Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
gobject-introspection and gir-repository
1.2. Name of Document Author/Supplier:
Author: Brian Cameron
1.3 Date of This Document:
13 August, 2009
4. Technical Description
1. Introduction
1.1. Project/Component Working Name:
gobject-introspection and gir-repostiory
1.2. Name of Document Author/Supplier:
Brian Cameron
1.3. Date of This Document:
08/07/2009
1.4. Name of Major Document Customer(s)/Consumer(s):
1.4.1. The PAC or CPT you expect to review your project:
Solaris PAC
1.4.2. The ARC(s) you expect to review your project:
LSARC
1.4.3. The Director/VP who is "Sponsoring" this project:
Robert O'Dea
1.4.4. The name of your business unit:
Software - OPG
1.5. Email Aliases:
1.5.1. Responsible Manager:
leo.binchy at sun.com
1.5.2. Responsible Engineer:
brian.cameron at sun.com
1.5.3 Marketing Manager:
glynn.foster at sun.com
1.5.4. Interest List:
desktop-discuss at opensolaris.org
2. Project Summary
2.1. Project Description:
The goal of gobject-introspection is to describe the APIs and collect
them in a uniform, machine readable format.
Historically in GNOME, the core platform has been relatively binding
friendly, but there are several details not captured in the C+GObject
layer that bindings have needed. For example, reference counting
semantics and the item type inside GLists. Up until now various
language bindings such as Python, Mono, java-gnome etc. had duplicated
copies of hand-maintained metadata, and this led to a situation where
bindings tended to lag behind until these manual fixups were done, or
were simply wrong, and your application would crash when calling a more
obscure function.
The introspection project solves this by putting all of the metadata
inside the GObject library itself, using annotations in the comments.
This will lead to less duplicate work from binding authors, and a more
reliable experience for binding consumers.
Additionally, because the introspection build process will occur inside
the GObject libraries themselves, a goal is to encourage GObject
authors to consider shaping their APIs to be more binding friendly from
the start, rather than as an afterthought.
4. Technical Description:
4.1. Details:
Note that gobject-introspection and gir-repository are not currently
used by the GNOME 2.28 stack. They are used by clutter version 1.0,
but nothing in the GNOME 2.28 stack currently uses clutter. Providing
these libraries in a GNOME 2.28 timeframe is useful only for making
it possible for developers to build and test programs like GNOME Shell
and libchamplain which are expected to be introduced in the next
release of GNOME.
gobject-introspection provides:
* 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
* 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
The gobject-introspection module installs:
* typelib files to /usr/lib/girepository-1.0
* GIR files to /usr/share/gir-1.0
for the following modules:
* OpenGL
* Glib
* cairo
* fontconfig
* freetype2
* libxml2
* xfixes
* xft
* xlib
Note that only the glib GIR and typelib files are built by the
gobject-introspection module. The other modules are supported with
static files.
4.1.1 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. The purpose
of it is to provide a common structure to access the complete available
API that a library or other unit of code exports. It is meant to be
language agnostic using namespaces to separate core, language or
library specific functionality. There are currently only C based tools
that work on the format, but it's meant to be usable to use in other
situations, for instance to/from another set of languages.
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.
4.1.2 Typelib
The typelib is a to disk version of the GIR designed to be fast, memory
efficient and complete enough so that language bindings can be written
on top of it without other sources of information. It is normally
compiled from a GIR when a library/program is installed and accessed
from the language binding or another application who wishes to use the
information.
4.1.3 Tools
* g-ir-compiler - A typelib compiler. It converts one or more GIR
files into one or more typelib files. It can emit
either raw typelib files (default) or C code if the
--code argument is used.
* g-ir-generate - A GIR generator, using the repository API. It
generates GIR files from a raw typlib or a shared
library.
* g-ir-scanner - Generates GIR XML files by parsing headers and
introspecting GObject based libraries. It is
usually invoked during the normal build step for a
project and the information is saved to disk and
later installed so language bindings and other
applications can use it. Header files and source
files are passed in arguments on the command line.
Currently only C-based libraries are supported by
the scanner.
4.1.4 API Library
gobject-introspection also includes a C based library called
libgirepository which provides an API to access to the typelib
metadata. It also contains an API to invoke functions, given the
function info object. The implementation is based on libffi.
4.1.5 API Library
A separate module called gir-repository provides typelib and GIR files
for many libraries available in the GNOME stack which library bindings
can depend upon. This module is temporary, since these .gir files will
eventually migrate to their respective upstream modules.
4.1.6 gir-repostiory
The gir-repository module installs:
* typelib files to /usr/lib/girepository-1.0
* GIR files to /usr/share/gir-1.0
for the following modules:
* ATK
* avahi
* babl
* clutter, clutter-gtk, clutter-cairo, clutter-json
* D-Bus
* GConf
* GDK, GDK-pixbuf, GTK
* gnio (not currently available on Solaris)
* gnome-keyring
* gnome-menu
* goocanvas (not currently available on Solaris)
* GStreamer
* gssdp (not currently available on Solaris)
* gtksourceview
* libnautilus-extension
* libnotify
* libunique
* libwnck
* pango
* poppler
* libsoup
* VTE
* webkit (LSARC 2009/409)
It only installs the files for the modules which are available on the
system.
gir-repostitory also installs a handful of helper libraries to build
and use typelibs.
4.2. Interfaces:
Exported Interfaces Stability Comments
---------------------------------- ---------------- -------------
The gobject-introspection module exports these interfaces:
/usr/bin/g-ir-compiler Uncommitted Compiler
/usr/bin/g-ir-generate Uncommitted GIR Generator
/usr/bin/g-ir-scanner Uncommitted GIR XML Generator
/usr/lib/libgirepository-1.0.so Uncommitted Library API
/usr/lib/libgirepository-everything-1.0.so
Uncommitted Library used for
testing bindings
for completeness.
/usr/lib/girepository-1.0 Uncommitted Repository of
typelib files for
libraries
/usr/lib/gobject-introspection/giscanner
Project Private Implementation of
g-ir-scanner
/usr/lib/pkgconfig/gobject-introspection-1.0.pc
Uncommitted object-introspection
pc file
/usr/include/object-introspection/girepository.h
Uncommitted header file
/usr/include/object-introspection/girffi.h
Uncommitted header file
/usr/share/gir-1.0/ Uncommitted Repository of GIR
files for libraries.
/usr/share/man/man1/g-ir-compiler.1 Uncommitted Man page
/usr/share/man/man1/g-ir-generate.1 Uncommitted Man page
/usr/share/man/man1/g-ir-scanner.1 Uncommitted Man page
The gir-repository module exports these additional interfaces:
/usr/lib/libgirepo-Clutter-custom.so
Volatile Helper library
for building
typelibs
/usr/lib/libgirepo-DBus-custom.so Volatile ""
/usr/lib/libgirepo-Gdk-custom.so Volatile ""
/usr/lib/libgirepo-Gtk-custom.so Volatile ""
Imported Interfaces Stability Comments
-------------------- --------------- -----------------------
gobject-introspection imports:
glib Committed LSARC 2006/202
libffi Volatile PSARC 2008/542
gir-repository imports:
ATK Committed LSARC 2006/202
avahi Volatile LSARC 2006/455
babl Volatile LSARC 2008/702
clutter Volatile LSARC 2008/426
D-Bus Volatile LSARC 2006/368
GConf Volatile LSARC 2006/202
GDK, GDK-pixbuf, GTK Committed LSARC 2006/202
gnome-keyring Volatile LSARC 2008/430
gnome-menu Volatile LSARC 2007/146
GStreamer Volatile LSARC 2006/202
gtksourceview Volatile LSARC 2007/146
libnautilus-extension Volatile LSARC 2006/202
libnotify Volatile LSARC 2007/137
libunique Volatile LSARC 2009/142
libwnck Volatile LSARC 2006/202
pango Committed LSARC 2006/202
poppler Volatile LSARC 2007/146
libsoup Project Private LSARC 2003/298
VTE Volatile LSARC 2006/202
webkit Uncommitted LSARC 2009/409
4.3. Doc Impact:
Man pages are provided with gobject-introspection
4.4. Packaging & Delivery:
SUNWgobject-introspection, SUNWgobject-introspection-devel,
SUNWgir-repository
4.5. Dependencies:
None.
4.6. L10N Impact:
The Desktop team and the G11N team are working together to evaluate and
provide I18N/L10N support.
4.7. Security Impact:
None
5. Reference Documents:
GObject Introspection Website
http://live.gnome.org/GObjectIntrospection/
GObject Introspection Tutorial
http://live.gnome.org/GObjectIntrospection/FromHereToThere
GObject Introspection Annotations
http://live.gnome.org/GObjectIntrospection/Annotations
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
Desktop
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
