mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-08-02 07:23:41 +02:00
docs: switch to xi:inbclude for the content to save some more seconds
This commit is contained in:
Stefan Kost
@@ -1,106 +1,112 @@
|
||||
<?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>
|
||||
|
||||
<para>
|
||||
For example, writing GObjects is often seen as a tedious task. It
|
||||
requires a lot of typing and just doing a copy/paste requires a
|
||||
great deal of care. A lot of projects and scripts have been
|
||||
written to generate GObject skeleton form boilerplate code, or
|
||||
even translating higher-level language into plain C.
|
||||
</para>
|
||||
</partintro>
|
||||
|
||||
<chapter id="tools-vala">
|
||||
<title>Vala</title>
|
||||
<para>
|
||||
From the <ulink url="http://live.gnome.org/Vala">Vala
|
||||
homepage</ulink> itself: <quote>Vala is a new programming language
|
||||
that aims to bring modern programming language features to GNOME
|
||||
developers without imposing any additional runtime requirements
|
||||
and without using a different ABI compared to applications and
|
||||
libraries written in C.</quote>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The syntax of Vala is similar to C#. The available compiler
|
||||
translates Vala into GObject C code. It can also compile
|
||||
non-GObject C, using plain C API.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="tools-gob">
|
||||
<title>GObject builder</title>
|
||||
|
||||
<para>
|
||||
In order to help a GObject class developper, one obvious idea is
|
||||
to use some sort of templates for the 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>
|
||||
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||
]>
|
||||
<part label="V">
|
||||
<title>Related Tools</title>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<para>
|
||||
For example, writing GObjects is often seen as a tedious task. It
|
||||
requires a lot of typing and just doing a copy/paste requires a
|
||||
great deal of care. A lot of projects and scripts have been
|
||||
written to generate GObject skeleton form boilerplate code, or
|
||||
even translating higher-level language into plain C.
|
||||
</para>
|
||||
</partintro>
|
||||
|
||||
<chapter id="tools-vala">
|
||||
<title>Vala</title>
|
||||
<para>
|
||||
From the <ulink url="http://live.gnome.org/Vala">Vala
|
||||
homepage</ulink> itself: <quote>Vala is a new programming language
|
||||
that aims to bring modern programming language features to GNOME
|
||||
developers without imposing any additional runtime requirements
|
||||
and without using a different ABI compared to applications and
|
||||
libraries written in C.</quote>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The syntax of Vala is similar to C#. The available compiler
|
||||
translates Vala into GObject C code. It can also compile
|
||||
non-GObject C, using plain C API.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="tools-gob">
|
||||
<title>GObject builder</title>
|
||||
|
||||
<para>
|
||||
In order to help a GObject class developper, one obvious idea is
|
||||
to use some sort of templates for the 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
|
||||
@@ -114,12 +120,13 @@ 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>
|
||||
</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>
|
||||
</part>
|
||||
|
||||
Reference in New Issue
Block a user