1.. _Debugging_GtkAda_applications:
2
3*****************************
4Debugging GtkAda applications
5*****************************
6
7This chapter presents a number of technics that can be used when
8debugging GtkAda applications. First, the standard tools to debug
9Ada applications can be used:
10
11*Compile with -g*
12  You should almost always include debugging information when compiling and
13  linking your code. This gives you the possibility to use the debugger. See
14  below the variable GDK_DEBUG for how to disable grabs.
15
16*bind with -E*
17  Using this argument on the `gnatbind` or `gnatmake` command
18  line will force the compiler to include backtraces when an exception is
19  raised. These backtraces can be converted to symbolic backtraces by
20  using the `addr2line` tool.
21
22*Link with -lgmem*
23  Using this switch gives access to the `gnatmem` tool, that helps
24  you to detect memory leaks or doubly-deallocated memory. The latter
25  often results in hard-to-fix Storage_Error exceptions. See the GNAT
26  User's guide for more information.
27
28There are also a number of technics specific to GtkAda or gtk+
29applications. For most of them, you might need to recompile these
30libraries with the appropriate switches to get access to the extended
31debugging features.
32
33*Use the `--sync` switch*
34  Under unix systems, all applications compiled with gtk+ automatically
35  support this switch, which forces events to be processed synchronously,
36  thus making it easier to detect problems as soon as they happen.
37  This switch is not relevant to Windows systems.
38
39*break on g_log*
40  In the debugger, it is often useful to put a breakpoint on the glib
41  function `g_log`. When gtk+ is linked dynamically, you will need
42  to first start your application with `begin`, then put the
43  breakpoint and continue the application with `cont`. This helps
44  understand internal errors or warnings reported by gtk+ and glib
45
46*compile glib with `--disable-mem-pools`*
47  Glib, the underlying layer that provides system-independent services
48  to gtk+, has an extensive and optimized system for memory
49  allocation. Bigger chunks of Memory are allocated initially, and then
50  subdivided by glib itself. Although this is extremely performant, this
51  also make the debugging of memory-related problems (storage_error)
52  more difficult. Compiling with the above switch forces glib to use the
53  standard malloc() and free() system calls. On GNU/Linux systems, it might
54  be useful to set the variable `MALLOC_CHECK_` to 1 to use
55  error-detecting algorithms (see the man page for malloc()).
56
57*compile glib and gtk+ with `--enable-debug=yes`*
58  It is recommended that you specify this switch on the `configure`
59  command line when compiling these two libraries.
60  In addition to compiling the libraries with debugging information for
61  the debugger, additional runtime debug options (controllable via
62  environment variables) become available.
63  Specifying `--enable-debug=no` is not recommended for production
64  releases (see glib or gtk+ documentation for details).
65
66  For these three variables, the possible values are given below. These
67  are lists of colon-separated keywords. You can choose to remove any of
68  these value from the variable
69
70  *GOBJECT_DEBUG=objects:signals*
71    This sets up the debugging output for glib. The value @samp{objects}
72    is probably the most useful, and displays, on exit of the application,
73    the list of unfreed objects. This helps detect memory leaks. The
74    second value @samp{signals} will display all the signals emitted by
75    the objects. Note that this results in a significant amount of output.
76
77  *GDK_DEBUG=updates:nograbs:events:dnd:misc:@*xim:colormap:gdkrgb:gc:pixmap:image:input:cursor*
78    This sets up the debugging output for gdk. The most useful value is
79    @samp{nograbs}, which prevents the application from ever grabbing the
80    mouse or keyboards. If you don't set this, it might happen that the
81    debugger becomes unusable, since you don't have access to the mouse
82    when the debugger stops on a breakpoint. Another simpler solution is
83    to debug remotely from another machine, in which case the grabs
84    won't affect the terminal on which the debugger is running.
85
86  *GTK_DEBUG=misc:plugsocket:text:tree:updates:keybindings*
87    This sets up the debugging output for gtk. Almost all of these values
88    are mostly for internal use by gtk+ developpers, although
89    @samp{keybindings} might prove useful sometimes.
90
91.. highlight:: ada
92
93*Import the C function ada_gtk_debug_get_ref_count*
94  This function has the following Ada profile::
95
96    function Ref_Count (Add : System.Address) return Guint;
97    pragma Import (C, Ref_Count, "ada_gtk_debug_get_ref_count");
98
99  and should be called in a manner similar to::
100
101    declare
102       Widget : Gtk_Widget;
103       Count  : Guint;
104    begin
105       Count := Ref_Count (Get_Object (Widget));
106    end;
107
108  and returns the internal reference counter for the widget. When this
109  counter reaches 0, the memory allocated for the widget is
110  automatically freed.
111
112  This is mostly a debugging aid for people writting their own
113  containers, and shouldn't generally be needed. You shouldn't rely on
114  the internal reference counter in your actual code, which is why it
115  isn't exported by default in GtkAda.
116
117
118