| <?xml version='1.0' encoding="ISO-8859-1"?> |
| <partintro> |
| <para> |
| Several useful developer tools have been build around GObject technology. |
| The next sections briefly introduce them and link to the respective project pages. |
| </para> |
| </partintro> |
| |
| <chapter id="tools-gob"> |
| <title>GObject builder</title> |
| |
| <para> |
| Writing GObjects can be a tedious task. It requires a lot of typing and just |
| doing a copy/paste requires a great deal of care. |
| One obvious idea is to use some sort of templates for the class skeletons. |
| and then run them through a special tool to generate the real C files. |
| <ulink url="http://www.5z.com/jirka/gob.html">GOB/</ulink> (or GOB2) is such |
| a tool. It is a preprocessor which can be used to build GObjects |
| with inline C code so that there is no need to edit the generated C code. |
| The syntax is inspired by Java and Yacc or Lex. The implementation is |
| intentionally kept simple: the inline C code provided by the user |
| is not parsed. |
| </para> |
| </chapter> |
| |
| <chapter id="tools-ginspector"> |
| <title>Graphical inspection of GObjects</title> |
| |
| <para> |
| Yet another tool that you may find helpful when working with |
| GObjects is <ulink |
| url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It |
| is able to display GLib/GTK+ objects and their properties. |
| </para> |
| </chapter> |
| |
| |
| <chapter id="tools-refdb"> |
| <title>Debugging reference count problems</title> |
| |
| <para> |
| The reference counting scheme used by GObject does solve quite |
| a few memory management problems but also introduces new sources of bugs. |
| In large applications, finding the exact spot where the reference count |
| of an Object is not properly handled can be very difficult. Hopefully, |
| there exist a tool named <ulink url="http://refdbg.sf.net/">refdbg/</ulink> |
| which can be used to automate the task of tracking down the location |
| of invalid code with regard to reference counting. This application |
| intercepts the reference counting calls and tries to detect invalid behavior. |
| It supports a filter-rule mechanism to let you trace only the objects you are |
| interested in and it can be used together with GDB. |
| </para> |
| <para> |
| <indexterm><primary>g_trap_object_ref</primary></indexterm> |
| Note that if GObject has been compiled with <option>--enable-debug=yes</option>, |
| it exports a trap variable |
| <programlisting> |
| static volatile GObject *g_trap_object_ref; |
| </programlisting> |
| If set to a non-NULL value, <link linkend="g-object-ref">g_object_ref</link>() |
| and <link linkend="g-object-unref">g_object_unref</link>() will be intercepted |
| when called with that value. |
| </para> |
| </chapter> |
| |
| <chapter id="tools-gtkdoc"> |
| <title>Writing API docs</title> |
| |
| <para>The API documentation for most of the GLib, GObject, GTK+ and GNOME |
| libraries is built with a combination of complex tools. Typically, the part of |
| the documentation which describes the behavior of each function is extracted |
| from the specially-formatted source code comments by a tool named gtk-doc which |
| generates DocBook XML and merges this DocBook XML with a set of master XML |
| DocBook files. These XML DocBook files are finally processed with xsltproc |
| (a small program part of the libxslt library) to generate the final HTML |
| output. Other tools can be used to generate PDF output from the source XML. |
| The following code excerpt shows what these comments look like. |
| <programlisting> |
| /** |
| * gtk_widget_freeze_child_notify: |
| * @widget: a #GtkWidget |
| * |
| * Stops emission of "child-notify" signals on @widget. The signals are |
| * queued until gtk_widget_thaw_child_notify() is called on @widget. |
| * |
| * This is the analogue of g_object_freeze_notify() for child properties. |
| **/ |
| void |
| gtk_widget_freeze_child_notify (GtkWidget *widget) |
| { |
| ... |
| </programlisting> |
| </para> |
| <para> |
| Thorough |
| <ulink url="http://developer.gnome.org/arch/doc/authors.html">documentation</ulink> |
| on how to set up and use gtk-doc in your |
| project is provided on the GNOME developer website. |
| </para> |
| </chapter> |