Home | History | Annotate | Download | only in gobject 
      1 <?xml version='1.0' encoding="ISO-8859-1"?>
      2 <partintro>
      3   <para>
      4     Several useful developer tools have been build around GObject
      5     technology.  The next sections briefly introduce them and link to
      6     the respective project pages.
      7   </para>
      8 
      9   <para>
     10     For example, writing GObjects is often seen as a tedious task. It
     11     requires a lot of typing and just doing a copy/paste requires a
     12     great deal of care. A lot of projects and scripts have been
     13     written to generate GObject skeleton form boilerplate code, or
     14     even translating higher-level language into plain C.
     15   </para>
     16 </partintro>
     17 
     18 <chapter id="tools-vala">
     19   <title>Vala</title>
     20   <para>
     21     From the <ulink url="http://live.gnome.org/Vala">Vala
     22     homepage</ulink> itself: <quote>Vala is a new programming language
     23     that aims to bring modern programming language features to GNOME
     24     developers without imposing any additional runtime requirements
     25     and without using a different ABI compared to applications and
     26     libraries written in C.</quote>
     27   </para>
     28 
     29   <para>
     30     The syntax of Vala is similar to C#. The available compiler
     31     translates Vala into GObject C code. It can also compile
     32     non-GObject C, using plain C API.
     33   </para>
     34 </chapter>
     35 
     36 <chapter id="tools-gob">
     37   <title>GObject builder</title>
     38 
     39   <para>
     40     In order to help a GObject class developper, one obvious idea is
     41     to use some sort of templates for the skeletons.  and then run
     42     them through a special tool to generate the real C files.  <ulink
     43     url="http://www.5z.com/jirka/gob.html">GOB</ulink> (or GOB2) is
     44     such a tool. It is a preprocessor which can be used to build
     45     GObjects with inline C code so that there is no need to edit the
     46     generated C code.  The syntax is inspired by Java and Yacc or
     47     Lex. The implementation is intentionally kept simple: the inline C
     48     code provided by the user is not parsed.
     49   </para>
     50 </chapter>
     51 
     52 <chapter id="tools-ginspector">
     53     <title>Graphical inspection of GObjects</title>
     54 
     55     <para>
     56       Yet another tool that you may find helpful when working with
     57       GObjects is <ulink
     58       url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
     59       is able to display GLib/GTK+ objects and their properties.
     60     </para>
     61 </chapter>
     62 
     63 <chapter id="tools-refdb">
     64   <title>Debugging reference count problems</title>
     65 
     66   <para>
     67     The reference counting scheme used by GObject does solve quite 
     68     a few memory management problems but also introduces new sources of bugs.
     69     In large applications, finding the exact spot where the reference count
     70     of an Object is not properly handled can be very difficult. Hopefully, 
     71     there exist a tool named <ulink url="http://refdbg.sf.net/">refdbg</ulink>
     72     which can be used to automate the task of tracking down the location
     73     of invalid code with regard to reference counting. This application 
     74     intercepts the reference counting calls and tries to detect invalid behavior. 
     75     It supports a filter-rule mechanism to let you trace only the objects you are 
     76     interested in and it can be used together with GDB.
     77   </para>
     78   <para>
     79     <indexterm><primary>g_trap_object_ref</primary></indexterm>
     80     Note that if GObject has been compiled with <option>--enable-debug=yes</option>,
     81     it exports a trap variable 
     82     <programlisting>
     83 static volatile GObject *g_trap_object_ref;
     84     </programlisting>
     85     If set to a non-NULL value, <link linkend="g-object-ref">g_object_ref</link>()
     86     and <link linkend="g-object-unref">g_object_unref</link>() will be intercepted
     87     when called with that value. 
     88   </para>
     89 </chapter>
     90   
     91 <chapter id="tools-gtkdoc">
     92   <title>Writing API docs</title>
     93 
     94   <para>The API documentation for most of the GLib, GObject, GTK+ and GNOME
     95   libraries is built with a combination of complex tools. Typically, the part of 
     96   the documentation which describes the behavior of each function is extracted
     97   from the specially-formatted source code comments by a tool named gtk-doc which
     98   generates DocBook XML and merges this DocBook XML with a set of master XML 
     99   DocBook files. These XML DocBook files are finally processed with xsltproc
    100   (a small program part of the libxslt library) to generate the final HTML
    101   output. Other tools can be used to generate PDF output from the source XML.
    102   The following code excerpt shows what these comments look like.
    103 <programlisting>
    104 /**
    105  * gtk_widget_freeze_child_notify:
    106  * @widget: a #GtkWidget
    107  * 
    108  * Stops emission of "child-notify" signals on @widget. The signals are
    109  * queued until gtk_widget_thaw_child_notify() is called on @widget. 
    110  *
    111  * This is the analogue of g_object_freeze_notify() for child properties.
    112  **/
    113 void
    114 gtk_widget_freeze_child_notify (GtkWidget *widget)
    115 {
    116 ...
    117 </programlisting>
    118   </para>
    119   <para>
    120   Thorough
    121   <ulink url="http://developer.gnome.org/arch/doc/authors.html">documentation</ulink> 
    122   on how to set up and use gtk-doc in your
    123   project is provided on the GNOME developer website.
    124   </para>
    125 </chapter>
    126