GObject introspection mini-policy
=================================

1. Directory layout

GObject-introspection data is generally provided in two formats:
      * XML format in /usr/share/gir-1.0/Foo-X.Y.gir
      * binary format in /usr/lib/girepository-1.0/Foo-X.Y.typelib


2. Binary introspection packages

The binary typelib file must be put in an architecture-dependent package
named after its namespace. The name must be girFORMAT-NAMESPACE-VERSION.
For example, the package containing WebKit-1.0.typelib will be named
gir1.0-webkit-1.0 for the gir 1.0 format and gir1.2-webkit-1.0 for the
gir 1.2 format. Note that the format is specified in the .gir file
itself and may not match the /usr/lib/girepository-1.0 and
/usr/share/gir-1.0 paths.

Giant repositories of unrelated introspection data should be avoided.
However, related libraries that are known to evolve together can live in
the same package (example: Gst*-0.10).

Introspection packages belong in section introspection.


3. XML introspection data

The XML format introspection must be shipped in another
architecture-dependent* package of the same source.

              * This is so that it is guaranteed to be accessible at
                build time by the tool that will compute the
                dependencies for the .typelib files. 

If the source package also contains the library itself, this data should
be in the development binary package. If the introspection data is split
from the library source (e.g. for gobject-instrospection-repository), a
separate package containing this XML data can be created, in section
libdevel.

The package containing the XML data must depend on each of the 
introspection packages that contain the corresponding binary files.

For example, a source package would generate libfoo2.0-0, libfoo2.0-dev 
and gir1.2-foo-2.0.
 - gir1.2-foo-2.0 Depends: libfoo2.0-0 through the ${gir:Depends}
 - libfoo2.0-dev Depends: gir1.2-foo-2.0 (= ${binary:Version})


4. Dependencies of introspection packages

Introspection packages must depend on the libraries they reference, with
a sufficient version for the symbols they reference.

For that effect, the dh_girepository helper, shipped in the 
gobject-introspection binary package, wraps dpkg-shlibdeps and adds all 
dependencies accordingly, in the ${gir:Depends} variable.

Introspection packages must depend on other introspection packages that
are referenced through <include> statements. The helper generates such 
dependencies as well. Build-dependencies on packages containing them 
must be set, with sufficient version information. The dependencies must
be in the same gir format as the source package.

Packages containing the XML data don’t need any specific new
dependencies.


5. Dependencies on introspection packages

Currently, there are only Seed (JavaScript) scripts to use these
introspection packages. In the future, there might also be Python or
other interpreted languages.

Generating dependencies automatically for interpreted languages is not
reliable. Therefore, these packages must depend by hand on the
appropriate gir* packages. The interpreters themselves don’t need to
depend on packages they don’t use directly.


6. Example

Suppose that libfoo-2.0 is an API built on libbar-3.0. The libfoo-2.0
source generates the following files, put in the following packages:
        libfoo-2.0-3 /usr/lib/libfoo-2.0.so.3*
        libfoo-2.0-dev /usr/lib/libfoo-2.0.so (and other usual stuff)
        libfoo-2.0-dev /usr/share/gir-1.0/Foo-2.0.gir
        gir1.2-foo-2.0 /usr/lib/girepository-1.0/Foo-2.0.typelib

libfoo-2.0-dev Depends: libfoo-2.0-3, libbar-3.0-dev, gir1.2-foo-2.0
gir1.2-foo-2.0 Depends: ${gir:Depends} which expands to:
libfoo-2.0-3, gir1.2-bar-3.0

If foobar is a package containing the following JS script:
        #! /usr/bin/seed
        Foo = imports.gi.Foo;
        // Stuff that uses the Foo 2.0 API

Then foobar Depends: gir1.2-foo-2.0
