Debugging Plug-ins
==================

Eeek! The plug-in you're working on has a bug in it! And the fix isn't
completely obvious, so you want to use debugger to see what is going on.
But hmm, how does one start a plug-in under a debugger if GIMP is the one
who is starting the plug-in...

To address this issue, libgimp has some hooks controlled by the
GIMP_PLUGIN_DEBUG environment variable. The idea is that you can attach
a debugger to the pid of the plug-in you want to debug. The format is as
follows:


GIMP_PLUGIN_DEBUG=name<,options>

"name" refers to the name of the plug-in binary that you wish to debug.

"options" is one or more of the following options, separated by :'s

    run:            suspend the plug-in when its run_proc is called.
    query:          suspend the plug-in when its query_proc is called.
    init:           suspend the plug-in when its init_proc is called.
    pid:            just print the pid of the plug-in on run_proc.
    fatal-warnings: emulate passing --g-fatal-warnings on the command line.
    fw:             shorthand for above.
    on:             shorthand for run:fatal-warnings. This is also the default
                    in the absence of an options string.


The steps to debug a plug-in are as follows:

  0. Make sure GIMP is built with debugging information (gcc -g)

  1. Start GIMP with the appropriate debugging environment variables

  2. Load the standalone plug-in program in the debugger (gdb or
     the ddd frontend to gdb)

  3. Invoke the plug-in procedure in GIMP. GIMP will start the plug-in
     process, then send a STOP signal to it and then print a message with
     the pid of the plug-in process to the terminal.

  4. Attach to the pid of the plug-in process in the debugger

  5. Set breakpoints where you want the plug-in to stop in the debugger

  6. Send the CONT signal (kill -CONT <pid>) to the plug-in process
     (When compiled with Windows, resume the plug-in process with 
      gimp-debug-resume.exe <pid>)
      
  7. Enter "continue" in the debugger. The plug-in will then continue
     and break at the breakpoints.


Examples:

GIMP_PLUGIN_DEBUG=blur

    When the blur plug-in is called to perform an action, it is suspended
    and the following is printed to the console:

    (blur:9000): LibGimp-DEBUG: Waiting for debugger...

    9000 is the pid of the new plug-in process. You can start your debugger,
    attach to it, set breakpoints/watches/etc. and continue from there.
    In case of the gdb typing "continue" will start the plugin.

GIMP_PLUGIN_DEBUG=blur,on

    Same effect as above.

GIMP_PLUGIN_DEBUG=blur,run:fatal-warnings

    Same effect as above.

GIMP_PLUGIN_DEBUG=blur,pid

    Prints:

    (blur:9000): LibGimp-DEBUG: Here I am!

    This simply prints the pid but doesn't halt the plug-in. It is simply
    convenience, since if your plug-in has a GUI, the GUI can start up
    and you can attach to it there while it is waiting for user input.

GIMP_PLUGIN_DEBUG=blur,query

    Same effect as if you did run, but instead suspends when the plug-in
    is queried on GIMP startup.

GIMP_PLUGIN_DEBUG=blur,init

    Same as above, but in the init phase of startup.


Hmm, but what about memory debuggers such as valgrind or purify? For those
you can set the following:

GIMP_PLUGIN_DEBUG_WRAP=name<,options>

    This is similar to GIMP_PLUGIN_DEBUG. Only "query", "init", and "run"
    are valid, and "on" defaults to simply "run"

GIMP_PLUGIN_DEBUG_WRAPPER=debugger

    debugger refers to the debugger program, such as valgrind. You can
    put command line options here too, they will be parsed like they do
    in the shell.

When compiled with Windows, the plug-in process is halted by Windows functions.
It must be resumed externally by invoking gimp-debug-resume.exe <pid>
The plug-ins pid can be found out by invoking gimp-debug-resume.exe 
without parameters. It shows the pid of all running processes.