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 or
   /usr/lib/$(DEB_HOST_MULTIARCH)/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.

In the common case where Foo-X.Y.gir does not vary between architectures,
it should be installed into /usr/share/gir-1.0.

In the uncommon case where it varies between architectures, it may be
installed into /usr/lib/${DEB_HOST_MULTIARCH}/gir-1.0, but maintainers
should keep in mind that several packages are not yet able to consume
GIR XML from that location. A versioned dependency or a versioned Breaks
is required in this case (see below).

GObject-Introspection data for private libraries that are only suitable
for use within a single source package or a tightly-coupled group of source
packages should be installed into a directory that is not on the default
search path, for example
/usr/lib/$(DEB_HOST_MULTIARCH)/mypackage/Foo-X.Y.typelib or.
/usr/share/mypackage/Foo-X.Y.gir.


2. Binary introspection packages

A public 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. Since gobject-introspection 1.78.1-2,
this can be achieved by adding Provides: ${gir:Provides} to the package.

Introspection packages belong in section introspection.

Private binary typelib files do not usually need to be separated from a
larger package. Following the naming convention above is not required.


3. XML introspection data

Public XML format introspection must be shipped in another
architecture-dependent package of the same source. This is done for
two reasons:

    a. so that it is guaranteed to be accessible at build time by
       the tool that will compute the dependencies for the .typelib files;
    b. so that the package with the GIR XML can depend on a matching
       version of the package with the typelib.

If the source package also contains the library itself, this data may
be in the development binary package, or in a separate package in section
libdevel whose name is the same as the typelib package name followed by -dev.

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.

The package containing the XML data should have a versioned Provides on
the canonical package name for each GIR XML module that it contains, if
different from the package's name. Since gobject-introspection 1.78.1-2,
this can be achieved by adding Provides: ${gir:Provides} to the package.

If the source package is built using a build-profile that excludes
GObject-Introspection data, then it must not have this Provides.

For example, a source package that generates Foo-2.0.typelib and Foo-2.0.gir
might have binary packages 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}),
   and Provides: gir1.2-foo-2.0-dev (= ${binary:Version}) through the
   ${gir:Provides}

or it might have binary packages libfoo2.0-0, libfoo2.0-dev, gir1.2-foo-2.0
and gir1.2-foo-2.0-dev:

 - gir1.2-foo-2.0: Depends: libfoo2.0-0 through the ${gir:Depends}
 - libfoo2.0-dev:  Depends: gir1.2-foo-2.0 (= ${binary:Version}),
 - gir1.2-foo-2.0-dev: Depends: gir1.2-foo-2.0 (= ${binary:Version})

Private GIR XML files do not usually need to be separated from a
larger package. Following the naming convention above is not required.


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 public XML data must depend on the introspection package
containing the corresponding typelib.
This is not required for private XML data.

Packages containing public XML data should depend on the package containing
the XML data for each GIR XML module that they reference via <include>,
with the exception that no dependency is necessary for the modules
provided by gir1.2-glib-2.0 and gir1.2-freedesktop: GLib-2.0, GObject-2.0,
GModule-2.0, Gio-2.0, GIRepository-2.0, DBus-1.0, DBusGLib-1.0, GL-1.0,
Vulkan-1.0, cairo-1.0, fontconfig-2.0, freetype2-2.0, libxml2-2.0,
xfixes-4.0, xft-2.0, xlib-2.0, xrandr-1.3.
This is not required for private XML data.

If GIR XML data is installed in the multiarch directory, it must have a
versioned dependency on gir1.2-glib-2.0 (>= 1.78.1-3~), or some other
mechanism to ensure that it is not co-installed with older versions of
libgirepository-1.0-1.


5. Dependencies on introspection packages

Typelibs are typically loaded by an interpreted script written in a
language such as JavaScript (gjs, cjs or Seed), Python (PyGI) or Perl
(Glib::Object::Introspection).

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. Build-dependencies

Source packages that build GIR XML should build-depend on
libgirepository1.0-dev and gobject-introspection. It is OK for the
dependency on gobject-introspection to be implied by dh-sequence-gir.

Where possible, source packages that build GIR XML should have a
Build-Depends or Build-Depends-Arch on the canonicalized gir1.2-*-dev
package name of any GObject-Introspection modules referenced via
<include>, with the exception that no dependency is necessary for the
modules provided by gir1.2-glib-2.0: GLib-2.0, GObject-2.0, GModule-2.0,
Gio-2.0 and GIRepository-2.0. This build-dependency cannot be added if
the gir1.2-*-dev package name does not yet exist as a real or virtual
package.


7. 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 should have Build-Depends(-Arch) on libgirepository1.0-dev
and dh-sequence-gir.

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

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
