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 or
/usr/lib/$(DEB_HOST_MULTIARCH)/girepository-1.0/Foo-X.Y.typelib
Using the multiarch paths for typelib files is recommended nowadays.
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,
replacing any underscores in the namespace with hyphen/minus, and
case-folding it to lower-case.
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.
If you use multiarch paths for the typelib files, the resulting gir
package can be marked as Multi-Arch: same.
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), as long as their versions are
expected to change in lockstep. If this is done, the package should have
versioned Provides for all the names that would have been used if the
typelibs had been packaged separately.
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)
/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
Generated by dwww version 1.15 on Sun Jun 16 11:59:25 CEST 2024.