docs/reference/gobject/tut_tools.xml

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