Blame docs/reference/gobject/tut_tools.xml

Packit ae235b
Packit ae235b
Packit ae235b
               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
Packit ae235b
]>
Packit ae235b
<part label="V">
Packit ae235b
  <title>Related Tools</title>
Packit ae235b
  
Packit ae235b
  <partintro>
Packit ae235b
    <para>
Packit ae235b
      Several useful developer tools have been build around GObject
Packit ae235b
      technology.  The next sections briefly introduce them and link to
Packit ae235b
      the respective project pages.
Packit ae235b
    </para>
Packit ae235b
  
Packit ae235b
    <para>
Packit ae235b
      For example, writing GObjects is often seen as a tedious task. It
Packit ae235b
      requires a lot of typing and just doing a copy/paste requires a
Packit ae235b
      great deal of care. A lot of projects and scripts have been
Packit ae235b
      written to generate GObject skeleton form boilerplate code, or
Packit ae235b
      even translating higher-level language into plain C.
Packit ae235b
    </para>
Packit ae235b
  </partintro>
Packit ae235b
  
Packit ae235b
  <chapter id="tools-vala">
Packit ae235b
    <title>Vala</title>
Packit ae235b
    <para>
Packit ae235b
      From the <ulink url="https://wiki.gnome.org/Projects/Vala">Vala
Packit ae235b
      homepage</ulink> itself: <quote>Vala is a new programming language
Packit ae235b
      that aims to bring modern programming language features to GNOME
Packit ae235b
      developers without imposing any additional runtime requirements
Packit ae235b
      and without using a different ABI compared to applications and
Packit ae235b
      libraries written in C.</quote>
Packit ae235b
    </para>
Packit ae235b
  
Packit ae235b
    <para>
Packit ae235b
      The syntax of Vala is similar to C#. The available compiler
Packit ae235b
      translates Vala into GObject C code. It can also compile
Packit ae235b
      non-GObject C, using plain C API.
Packit ae235b
    </para>
Packit ae235b
  </chapter>
Packit ae235b
  
Packit ae235b
  <chapter id="tools-gob">
Packit ae235b
    <title>GObject builder</title>
Packit ae235b
  
Packit ae235b
    <para>
Packit ae235b
      In order to help a GObject class developer, one obvious idea is
Packit ae235b
      to use some sort of templates for the skeletons and then run
Packit ae235b
      them through a special tool to generate the real C files.  
Packit ae235b
      url="http://www.5z.com/jirka/gob.html">GOB</ulink> (or GOB2) is
Packit ae235b
      such a tool. It is a preprocessor which can be used to build
Packit ae235b
      GObjects with inline C code so that there is no need to edit the
Packit ae235b
      generated C code.  The syntax is inspired by Java and Yacc or
Packit ae235b
      Lex. The implementation is intentionally kept simple: the inline C
Packit ae235b
      code provided by the user is not parsed.
Packit ae235b
    </para>
Packit ae235b
  </chapter>
Packit ae235b
  
Packit ae235b
  <chapter id="tools-ginspector">
Packit ae235b
      <title>Graphical inspection of GObjects</title>
Packit ae235b
  
Packit ae235b
      <para>
Packit ae235b
        Yet another tool that you may find helpful when working with
Packit ae235b
        GObjects is 
Packit ae235b
        url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
Packit ae235b
        is able to display GLib/GTK+ objects and their properties.
Packit ae235b
      </para>
Packit ae235b
  </chapter>
Packit ae235b
  
Packit ae235b
  <chapter id="tools-refdb">
Packit ae235b
    <title>Debugging reference count problems</title>
Packit ae235b
  
Packit ae235b
    <para>
Packit ae235b
      The reference counting scheme used by GObject does solve quite 
Packit ae235b
      a few memory management problems but also introduces new sources of bugs.
Packit ae235b
      In large applications, finding the exact spot where the reference count
Packit ae235b
      of an Object is not properly handled can be very difficult.
Packit ae235b
    </para>
Packit ae235b
    <para>
Packit ae235b
      A useful tool in debugging reference counting problems is to
Packit ae235b
      set breakpoints in gdb on g_object_ref() and g_object_unref().
Packit ae235b
      Once you know the address of the object you are interested in,
Packit ae235b
      you can make the breakpoints conditional:
Packit ae235b
      <programlisting>
Packit ae235b
break g_object_ref if _object == 0xcafebabe
Packit ae235b
break g_object_unref if _object == 0xcafebabe
Packit ae235b
      </programlisting>
Packit ae235b
    </para>
Packit ae235b
  </chapter>
Packit ae235b
    
Packit ae235b
  <chapter id="tools-gtkdoc">
Packit ae235b
    <title>Writing API docs</title>
Packit ae235b
  
Packit ae235b
    <para>The API documentation for most of the GLib, GObject, GTK+ and GNOME
Packit ae235b
    libraries is built with a combination of complex tools. Typically, the part of 
Packit ae235b
    the documentation which describes the behavior of each function is extracted
Packit ae235b
    from the specially-formatted source code comments by a tool named gtk-doc which
Packit ae235b
    generates DocBook XML and merges this DocBook XML with a set of master XML 
Packit ae235b
    DocBook files. These XML DocBook files are finally processed with xsltproc
Packit ae235b
    (a small program part of the libxslt library) to generate the final HTML
Packit ae235b
    output. Other tools can be used to generate PDF output from the source XML.
Packit ae235b
    The following code excerpt shows what these comments look like.
Packit ae235b
      <informalexample><programlisting>
Packit ae235b
/**
Packit ae235b
 * gtk_widget_freeze_child_notify:
Packit ae235b
 * @widget: a #GtkWidget
Packit ae235b
 * 
Packit ae235b
 * Stops emission of "child-notify" signals on @widget. The signals are
Packit ae235b
 * queued until gtk_widget_thaw_child_notify() is called on @widget. 
Packit ae235b
 *
Packit ae235b
 * This is the analogue of g_object_freeze_notify() for child properties.
Packit ae235b
 **/
Packit ae235b
void
Packit ae235b
gtk_widget_freeze_child_notify (GtkWidget *widget)
Packit ae235b
{
Packit ae235b
...
Packit ae235b
      </programlisting></informalexample>
Packit ae235b
    </para>
Packit ae235b
    <para>
Packit ae235b
    Thorough
Packit ae235b
    <ulink url="https://developer.gnome.org/gtk-doc-manual/stable/">documentation</ulink>
Packit ae235b
    on how to set up and use gtk-doc in your project is provided on the
Packit ae235b
    <ulink url="https://developer.gnome.org/">GNOME developer website</ulink>.
Packit ae235b
    </para>
Packit ae235b
  </chapter>
Packit ae235b
</part>