← Back to branch summary

~ubuntu-branches/ubuntu/maverick/gimp/maverick-updates

« back to all changes in this revision

Viewing changes to devel-docs/debug-plug-ins.txt

  • Committer: Bazaar Package Importer
  • Author(s): Daniel Holbach
  • Date: 2005-12-09 19:44:52 UTC
  • Revision ID: james.westby@ubuntu.com-20051209194452-yggpemjlofpjqyf4
Tags: upstream-2.2.9
Import upstream version 2.2.9

Show diffs side-by-side

added added

removed removed

Lines of Context:
devel-docs/debug-plug-ins.txt
 
1
Debugging Plug-ins
 
2
==================
 
3
 
 
4
Eeek! The plug-in you're working on has a bug in it! And the fix isn't
 
5
completely obvious, so you want to use debugger to see what is going on.
 
6
But hmm, how does one start a plug-in under a debugger if GIMP is the one
 
7
who is starting the plug-in...
 
8
 
 
9
To address this issue, libgimp has some hooks controlled by the
 
10
GIMP_PLUGIN_DEBUG environment variable. The idea is that you can attach
 
11
a debugger to the pid of the plug-in you want to debug. The format is as
 
12
follows:
 
13
 
 
14
 
 
15
GIMP_PLUGIN_DEBUG=name<,options>
 
16
 
 
17
"name" refers to the name of the plug-in binary that you wish to debug.
 
18
 
 
19
"options" is one or more of the following options, separated by :'s
 
20
 
 
21
    run:            suspend the plug-in when its run_proc is called.
 
22
    query:          suspend the plug-in when its query_proc is called.
 
23
    init:           suspend the plug-in when its init_proc is called.
 
24
    pid:            just print the pid of the plug-in on run_proc.
 
25
    fatal-warnings: emulate passing --g-fatal-warnings on the command line.
 
26
    fw:             shorthand for above.
 
27
    on:             shorthand for run:fatal-warnings. This is also the default
 
28
                    in the absence of an options string.
 
29
 
 
30
Examples:
 
31
 
 
32
GIMP_PLUGIN_DEBUG=blur
 
33
 
 
34
    When the blur plug-in is called to perform an action, it is suspended
 
35
    and the following is printed to the console:
 
36
 
 
37
    (blur:9000): LibGimp-DEBUG: Waiting for debugger...
 
38
 
 
39
    9000 is the pid of the new plug-in process. You can start your debugger,
 
40
    attach to it, set breakpoints/watches/etc. and continue from there.
 
41
 
 
42
GIMP_PLUGIN_DEBUG=blur,on
 
43
 
 
44
    Same effect as above.
 
45
 
 
46
GIMP_PLUGIN_DEBUG=blur,run:fatal-warnings
 
47
 
 
48
    Same effect as above.
 
49
 
 
50
GIMP_PLUGIN_DEBUG=blur,pid
 
51
 
 
52
    Prints:
 
53
 
 
54
    (blur:9000): LibGimp-DEBUG: Here I am!
 
55
 
 
56
    This simply prints the pid but doesn't halt the plug-in. It is simply
 
57
    convenience, since if your plug-in has a GUI, the GUI can start up
 
58
    and you can attach to it there while it is waiting for user input.
 
59
 
 
60
GIMP_PLUGIN_DEBUG=blur,query
 
61
 
 
62
    Same effect as if you did run, but instead suspends when the plug-in
 
63
    is queried on GIMP startup.
 
64
 
 
65
GIMP_PLUGIN_DEBUG=blur,init
 
66
 
 
67
    Same as above, but in the init phase of startup.
 
68
 
 
69
 
 
70
Hmm, but what about memory debuggers such as valgrind or purify? For those
 
71
you can set the following:
 
72
 
 
73
GIMP_PLUGIN_DEBUG_WRAP=name<,options>
 
74
 
 
75
    This is similar to GIMP_PLUGIN_DEBUG. Only "query", "init", and "run"
 
76
    are valid, and "on" defaults to simply "run"
 
77
 
 
78
GIMP_PLUGIN_DEBUG_WRAPPER=debugger
 
79
 
 
80
    debugger refers to the debugger program, such as valgrind. You can
 
81
    put command line options here too, they will be parsed like they do
 
82
    in the shell.