Bug#1120310: What are the gir1.2 package naming conventions?
On Thursday, December 11, 2025 7:48:19 AM Mountain Standard Time Jeremy Bícha wrote: > On Thu, Dec 11, 2025 at 5:49 AM Simon McVittie wrote: > > 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/ late > > st/debian/policy.txt?ref_type=heads > There's more documentation at > https://salsa.debian.org/gnome-team/gobject-introspection/-/blob/debian/ latest > /debian/gobject-introspection.README.Debian Thanks to both of you. This is the type of information I was looking for. -- Soren Stoutner [email protected] signature.asc Description: This is a digitally signed message part.
Bug#1120310: What are the gir1.2 package naming conventions?
On Thu, Dec 11, 2025 at 5:49 AM Simon McVittie wrote: > 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 There's more documentation at https://salsa.debian.org/gnome-team/gobject-introspection/-/blob/debian/latest/debian/gobject-introspection.README.Debian Thank you, Jeremy Bícha
Bug#1120310: 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
Bug#1120310: What are the gir1.2 package naming conventions?
There are two types of ABI changes: ones that are backward-compatible and ones that are not. An ABI change is backward-compatible if any reasonable program or library that was linked with the previous version of the shared library will still work correctly with the new version of the shared library. 15 Adding new symbols to the shared library is a backward-compatible change. Removing symbols from the shared library is not. Changing the behavior of a symbol may or may not be backward-compatible depending on the change; for example, changing a function to accept a new enum constant not previously used by the library is generally backward-compatible, but changing the members of a struct that is passed into library functions is generally not unless the library takes special precautions to accept old versions of the data structure. ABI changes that are not backward-compatible normally require changing the SONAME of the library and therefore the shared library package name, which forces rebuilding all packages using that shared library to update their dependencies and allow them to use the new version of the shared library. For more information, see Run-time shared libraries. The run-time shared library must be placed in a package whose name changes whenever the SONAME of the shared library changes. This allows several versions of the shared library to be installed at the same time, allowing installation of the new version of the shared library without immediately breaking binaries that depend on the old version. 2 Normally, the run-time shared library and its SONAME symlink should be placed in a package named librarynamesoversion, where soversion is the version number in the SONAME of the shared library. Alternatively, if it would be confusing to directly append soversion to libraryname (if, for example, libraryname itself ends in a number), you should use libraryname-soversion instead. 3 https://www.debian.org/doc/debian-policy/ch-sharedlibs.html
Bug#1120310: What are the gir1.2 package naming conventions?
I am in the process of reviewing the gxml package for sponsorship. https://salsa.debian.org/amin_modaresi/gxml One of the questions I have is about gir1.2 package naming. As I have not previously packages a gir1.2 package, I thought it best to ask here instead of making a mistake and having to do a second trip through NEW. When shipping introspection data, which can be used by packages using the GIRepository format to generate dynamic bindings, most of the packages end in what appears to be a version number. For example: gir1.2-gee-0.8 gir1.2-pango-1.0 gir1.2-secret-1 gir1.2-vte-2.91 gir1.2-wnck-3.0 However, these number do not usually correspond to the current version number of the package. gir1.2-gee-0.8 is version 0.20.8-2 gir1.2-pango-1.0 is version 1.56.3-2 gir1.2-secret-1 is version 0.21.7-2 gir1.2-vte-2.91 is version 0.82.2-1 gir1.2-wnck-3.0 is version 43.3-1 This same number (or a similar one, sometimes dropping the .0) is also included in the library package name. gir1.2-gee-0.8 is associated with libgee-0.8-2, with 2 being the SONAME. gir1.2-pango-1.0 is associated with libpango-1.0-0, with 0 being the SONAME gir1.2-secret-1 is associated with libsecret-1-0, with 0 being the SONAME gir1.2-vte-2.91 is associated with libvte-2.91-0, with 0 being the SONAME gir1.2-wnck-3.0 is associated with libwnck-3-0, with 0 being the SONAME 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. So, my question is, where does this number come from (and how often does it change)? Any guidance from those with more familiarity packaging GNOME software would be appreciated. P.S. I am subscribed to debian-mentors, but not debian-gtk-gnome. -- Soren Stoutner [email protected] signature.asc Description: This is a digitally signed message part.
