Techniques to Debug Scheme GIMP Plug-ins

This describes several techniques for debugging Scheme plugins for the GIMP app.

The techniques are:

• view logs of the ScriptFu system
• harness your plugin with “print” statements
• use a debugger on the plugin process
• harness the ScriptFu code itself

The first are quicker, but give less information.

View Logs

By viewing logs, you can see what the GIMP app and ScriptFu system were doing at the time of some exception.

You should start the GIMP app from a terminal, ideally with --verbose --console-messages as parameter for gimp executable. See: The Basics.

Set an environment variable before starting the GIMP app:

export G_MESSAGES_DEBUG=scriptfu #on Linux/macOS
$env:G_MESSAGES_DEBUG='scriptfu' #on Windows
path_to_gimp --verbose --console-messages

This “turns on” printing of messages for the DEBUG level of logging for the domain “scriptfu”, since the ScriptFu system uses the logging feature of GLib.

The last logged message is usually most pertinent to any exception. But logs are not easy to understand unless you are familiar with internals of ScriptFu.

Harness your plugin

“Harnessing” is putting special code for debugging (or performance monitoring) in a program’s source. Sometimes you leave the special code in the source, or you remove it when you are done debugging.

You can sprinkle your code with calls to Scheme functions that print messages:

display or displayln

This is the recommended way to print messages for debugging on Script-Fu. To not repeat ourselves, see: The display function.

write

The write function writes to the currently opened port (a Scheme concept.) You can open a port to a file and log to the file, which might be easier to read. (No example given here.)

gimp-message

To get anywhere with a script, it’s useful to keep all those debug messages in the final script with gimp-message. However seeing all those messages can be annoying when you’re not debugging but working since they can appear on UI.

So, how can we set up a script so that you can gain more control over those helpful messages? It’s possible to use a function to define a global variable in Script-Fu.

(define debug #t)

With this defined in your plugin, you can use an if true statement to control the message activation.

(if debug (gimp-message " This is a debug flag controlled message "))

Another useful technique for pinning down an error is performing a binary search (this half, this quarter, this eighth… …this line.) with message statements. The following procedure definition provides a shortcut, to help this method.

(define (here x)(gimp-message(string-append " >>> " (number->string x) " <<<")))

Having the line (here 1) in your script would call the above procedure and print out the message;

>>> 1 <<<

Because the numbers after the error will not get printed, you can find the problem line with the code.

Sometimes, however, you may want to stop the script. It is possible to force a stop with another small function definition and the ‘quit’ keyword as per the recommendations of The quit function.

Use a debugger

This is about using a debugger tool such as gdb. First, see Debugging Plugins, which applies to plugins written in any language. Then, read this specifics for Scheme plugins.

Instead, generally you wait for a fatal condition and then get a backtrace. See below:

Old-style scripts installed to /scripts

You must debug the process extension-script-fu, which serves all old-style scripts. The name of the executable file is script-fu which will be set as <domain>. See: To use a debugger on a plug-in (alternative)

New-style scripts installed to /plug-ins

You must debug the process of the independently interpreted plugin. You must specify the name of the executable file (e.g. test-sphere-v3.scm will be the <domain>), the text file that has a shebang (in the first line “#!…”). See: To use a debugger on a plug-in (alternative)

Harnessing ScriptFu or GIMP or TinyScheme itself

You might suspect a bug in ScriptFu or TinyScheme or GIMP. Then you might involve GIMP developers. Or you can build GIMP yourself, and harness its code.

The TinyScheme interpreter embedded in ScriptFu has a trace facility. In other words, built-in logging. But it is rarely used. It reveals the very deep, internal workings of the “S expression” virtual machine in the innermost interpreter.