Re: What are the gir1.2 package naming conventions?
On Wed, 10 Dec 2025 at 18:18:57 -0700, Soren Stoutner wrote:
One of the questions I have is about gir1.2 package naming.
Please see the GObject-Introspection mini-policy:
https://salsa.debian.org/gnome-team/gobject-introspection/-/blob/debian/latest/debian/policy.txt?ref_type=heads
However, [the numbers in the gir1.2- package name] do not usually
correspond to the current version number of the package.
Upstream chooses this number, indirectly. It's the same as the way they
indirectly choose the package name we use for shared libraries.
For example gir1.2-gee-0.8 contains a file named
/usr/lib/x86_64-linux-gnu/girepository-1.0/Gee-0.8.typelib (the
equivalent of a runtime shared library for GObject-Introspection
bindings), and libgee-0.8-dev contains the corresponding GIR XML file,
/usr/share/gir-1.0/Gee-0.8.gir (the equivalent of a C header file for
GObject-Introspection bindings).
Here the "0.8" is a major API version, chosen by upstream when they set
up their build system. Often it matches the "marketing" version number
of the oldest upstream release that had a compatible API/ABI, but there
is nothing that actually requires this (and you already found some
counterexamples). All that matters is that when upstream breaks the
API/ABI, they increase the version, and when they keep a
backwards-compatible API/ABI, they keep the same version - similar to
the common practice of putting a number in the pkg-config .pc filename
(an API version) and a number at the end of the SONAME (an ABI version).
The gir1.2- package name is mechanically derived from the name and major
API version (or the filename of the GIR XML and typelib, if you prefer
to think of it that way), in the same way that library package names are
mechanically derived from the SONAME of the shared library according to
the rules in Policy §8.1. Like Policy §8.1, there is a rule that you can
(and should) usually follow without applying any creativity or thought
to it.
The typelib (which is like a C shared library) should always be in its
own package.
For the GIR XML (which is like C headers), older packages normally put
it in the same -dev package as the C headers and shared library
development symlink, with a Provides on a systematic name like
gir1.2-gee-0.8-dev (the typelib package name + "-dev"). For new packages
that need to go through the NEW queue anyway, you can separate it out
into its own package with that same systematic name, which can be
helpful for cross-compiling and bootstrapping.
dh_girepository (dh-sequence-gir) will provide warnings at build time
for some common mistakes, and should be used for all typelibs and GIR
XML anyway, to auto-generate the dependencies - it's the GIR equivalent
of dh_shlibdeps.
This same number (or a similar one, sometimes dropping the .0) is also
included in the library package name.
Numbers in the library package name are major API and ABI versions for
the library's C API, which usually (but not always!) breaks at the same
time as the introspection API.
gir1.2-gee-0.8 is associated with libgee-0.8-2, with 2 being the SONAME.
No, the SONAME is libgee-0.8.so.2 (which you can think of as being API
version 0.8 and ABI version 2) and the name libgee-0.8-2 is mechanically
derived from that. (And so on for the other libraries you mentioned.)
You can confirm the machine-readable SONAME of a library with a command
like:
$ objdump -T -x /usr/lib/x86_64-linux-gnu/libgee-0.8.so.2.6.1 | grep SONAME
SONAME libgee-0.8.so.2
(it's the DT_SONAME ELF header).
The exception to this pattern is gir1.2-freedesktop, which does not end in a
version number, and also is not associated with a library package of the same
name.
This is a collection of typelibs for non-GNOME libraries that don't
provide their own GObject-Introspection data. If you inspect the package
you'll see that it has Provides for all the names it would have had if
the typelibs were in separate packages, for example:
$ dpkg -L gir1.2-freedesktop:amd64
...
/usr/lib/x86_64-linux-gnu/girepository-1.0/xfixes-4.0.typelib
...
$ dpkg -s gir1.2-freedesktop:amd64
...
Provides: ..., gir1.2-xfixes-4.0 (= 1.86.0-6), ...
...
It is valid to combine multiple typelibs like this, but doing so will
often result in excessive dependencies, so I would recommend sticking to
one binary package per typelib unless you know that combining them is
appropriate, the same way we normally put one shared library per package
unless there is a good reason to combine them.
smcv
Reply to: