docs/reference/gobject/tut_tools.xml

   1 <partintro>
   2         <para>
   3                 Several useful developer tools have been build around GObject technology.
   4                 The next sections briefly introduce them and link to the respective project pages.
   5         </para>
   6 </partintro>
   7
   8 <chapter id="tools-gob">
   9   <title>GObject builder</title>
  10
  11   <para>
  12                 Writing gobjects can be a tedious task. It requires a lot of typing and just
  13                 doing a copy/paste requires a great deal of care.
  14                 One obvious idea is to use some sort of templates for the class skeletons.
  15                 and then run them through a special tool to generate the real C files.
  16                 <ulink url="http://www.5z.com/jirka/gob.html">GOB/</ulink> (or GOB2) is such
  17                 a tool. It is a preprocessor which can be used to build GObjects
  18                 with inline C code so that there is no need to edit the generated C code.
  19                 The syntax is inspired by Java and Yacc or Lex. The implementation is
  20                 intentionally kept simple: the inline C code provided by the user
  21                 is not parsed.
  22   </para>
  23 </chapter>
  24
  25 <chapter id="tools-ginspector">
  26     <title>Graphical inspection of Gobjects</title>
  27
  28     <para>
  29       Yet another tool that you may find helpful when working with
  30       GObjects is <ulink
  31       url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
  32       is able to display Glib/Gtk+ objects and their properties.
  33     </para>
  34 </chapter>
  35
  36
  37 <chapter id="tools-refdb">
  38   <title>Debugging reference count problems</title>
  39
  40   <para>
  41     The reference counting scheme used by GObject does solve quite
  42     a few memory management problems but also introduces new sources of bugs.
  43     In large applications, finding the exact spot where the reference count
  44     of an Object is not properly handled can be very difficult. Hopefully,
  45     there exist a tool named <ulink url="http://refdbg.sf.net/">refdbg/</ulink>
  46     which can be used to automate the task of tracking down the location
  47     of invalid code with regard to reference counting. This application
  48     intercepts the reference counting calls and tries to detect invalid behavior.
  49     It suports a filter-rule mechanism to let you trace only the objects you are
  50     interested in and it can be used together with gdb.
  51   </para>
  52 </chapter>
  53
  54 <chapter id="tools-gtkdoc">
  55   <title>Writing API docs</title>
  56
  57   <para>The API documentation for most of the Glib, GObject, GTK+ and GNOME
  58   libraries is built with a combination of complex tools. Typically, the part of
  59   the documentation which describes the behavior of each function is extracted
  60   from the specially-formatted source code comments by a tool named gtk-doc which
  61   generates docbook xml and merges this docbook xml with a set of master xml
  62   docbook files. These xml docbook files are finally processed with xsltproc
  63   (a small program part of the libxslt library) to generate the final html
  64   output. Other tools can be used to generate pdf output from the source xml.
  65   The following code excerpt shows what these comments look like.
  66 <programlisting>
  67 /**
  68  * gtk_widget_freeze_child_notify:
  69  * @widget: a #GtkWidget
  70  *
  71  * Stops emission of "child-notify" signals on @widget. The signals are
  72  * queued until gtk_widget_thaw_child_notify() is called on @widget.
  73  *
  74  * This is the analogue of g_object_freeze_notify() for child properties.
  75  **/
  76 void
  77 gtk_widget_freeze_child_notify (GtkWidget *widget)
  78 {
  79 ...
  80 </programlisting>
  81   </para>
  82   <para>
  83   The great thoroughful
  84   <ulink url="http://developer.gnome.org/arch/doc/authors.html">documentation</ulink>
  85   on how to setup and use gtk-doc in your
  86   project is provided on the gnome developer website.
  87   </para>
  88 </chapter>