Introduction to GObject Introspection

This was also sent to gtk-devel today:

== Introduction ==

GObject-introspection is a package which will collect and extend the API
metadata for GObject based libraries. The main motivation of this work is to
centralize all introspection information required to write a language binding.

There are many other use cases as well, some of them are described at:

   http://live.gnome.org/GObjectIntrospection/

== Current status ==

The GObject-Introspection module/tarball contains the following:

     * An XML format called GIR containing introspection information
     * python package to create and parse the GIR format
     * scanner to generate GIR format from C source and headers

These components are also included, but needs to be ported to the GIR format:

     * a typelib similar to xpcom/msole which stores the information
       on disk in a binary format
     * a compiler to compile the typelib from a xml format (and vice versa)
     * C library to read the typelib

A separate SVN module called gir-repository has been created.
The idea is to create .gir files of all libraries available in the
the whole stack which language bindings can depend on.
Eventually the plan is to move the .gir files into the upstream projects
themselves, but that's likely to be a long process.

== GIR XML Format ==

The core of the GObject-introspection is an XML format which is called GIR (
GObject Introspection Repository) which contains the API introspection
metadata for a library or interface entity.

GIR currently contains three different XML namespaces:

• core: contains features available in popular programming languages: classes, methods, functions, interfaces, properties, strings, enums etc.
• c: contains features specific to the C language: identifiers, symbol names, C types
• glib: contains features specific to GLib/GObject: signal, GType, flags, paramspec

The separation of different data in different namespaces allow you
to reuse it allows you to arbitrarily extend the metadata available
in different languages.

== Scanner ==

To be able to bootstrap the effort and make something which will be
available in a reasonable timeframe we've been working on a scanner
which parsers C sources and headers and extracts the metadata and
generates a GIR file.

This is likely to be used by most of the Gtk/GNOME stack, as it would
require the least amount of work, however it's not the only way to
use the GIR format nor GObject-Introspection.
In the future we might use something similar to CORBA IDL to define
the interface, as GIR is not meant to human editable.

In addition to the parsing the C headers, additional metadata will
be provided, likely by using source annotations in gtk-doc comments.

== Typelib ==

To be able to create efficient read introspection data we need a typelib, eg
an efficent disk format with a C API to access the internal data.
Matthias wrote one based on the XPCOM typelib which has not yet been
updated to the GIR format, it's instead the tools to compile it are still
using an older XML format.

The work on finishing the typelib is depending on having the GIR format
somewhat stable and at that point updating the existing tools to understand it.

== How can I help? ==

At this point I'd like to get more eyes at the current GIR format to make
sure that it contains the necessary information and in a way which will
be easy to parse/access.
I am currently working mainly on the scanner to be able to quickly get
a large amount API expressed in GIR files.

For more information, check out the wiki page:

   http://live.gnome.org/GObjectIntrospection/

And the gobject-introspection and gir-repository modules in GNOME SVN.