Build a GObject Introspection Typelib with gi-compile-repository

Turn a GObject Introspection .gir file into a binary .typelib with gi-compile-repository, so GObject Introspection consumers can load it. You will start from a GIR XML file and end with a verified typelib. The examples use the Debian executable from libglib2.0-dev-bin, version 2.80.0, installed here with the matching development package. Allow about ten minutes if you already have a GIR file.

This command compiles metadata only. It does not compile a shared library, install a package, or change a system typelib directory. You normally need no elevated privileges: write the result to a build directory you own. The input must already exist, and any GIR files it references must be discoverable.

1. Confirm the executable and its version

On Debian-derived systems, the architecture-prefixed name exists for cross-compilation. The unprefixed command is convenient for a native build. This machine also has another GLib installation earlier in its shell PATH, so the examples use the Debian path explicitly:

$ /usr/bin/gi-compile-repository --version
gi-compile-repository 2.80.0
$ dpkg-query -W -f='\${Package} \${Version}\n' libglib2.0-dev-bin libglib2.0-dev
libglib2.0-dev-bin 2.80.0-6ubuntu3.9
libglib2.0-dev:amd64 2.80.0-6ubuntu3.9

2. Find a GIR input

A GIR file is XML describing an introspected library. This system includes the Gio input:

$ test -r /usr/share/gir-1.0/Gio-2.0.gir && echo 'readable'
readable
$ head -n 3 /usr/share/gir-1.0/Gio-2.0.gir
<?xml version="1.0" encoding="UTF-8"?>
<repository version="1.2"
             xmlns="http://www.gtk.org/introspection/core/1.0">

Swap in the GIR file from your own build when you are compiling a project, and keep the input under source or build control. The compiler reads it and never edits it.

3. Write the typelib to a new build path

Give the output path with --output, or -o for short. Use a new filename while testing. You do not need shell redirection, because the option writes the binary result directly:

$ mkdir -p build/typelibs
$ /usr/bin/gi-compile-repository \
    --output build/typelibs/Gio-2.0.typelib \
    /usr/share/gir-1.0/Gio-2.0.gir

A successful compilation may be silent. Verify both the file type and the size:

$ file build/typelibs/Gio-2.0.typelib
build/typelibs/Gio-2.0.typelib: G-IR binary database, v4.0, 810 entries/774 local
$ test -s build/typelibs/Gio-2.0.typelib && echo 'non-empty typelib'
non-empty typelib

Entry counts differ with the input and GLib version. What matters is a non-empty G-IR binary database, not an exact byte count.

4. Keep output files safe

A safer pattern writes a temporary file in the same directory, verifies it, then replaces the old result:

$ /usr/bin/gi-compile-repository \
    --output build/typelibs/Gio-2.0.typelib.new \
    /usr/share/gir-1.0/Gio-2.0.gir
$ file build/typelibs/Gio-2.0.typelib.new
build/typelibs/Gio-2.0.typelib.new: G-IR binary database, v4.0, 810 entries/774 local
$ mv -- build/typelibs/Gio-2.0.typelib.new build/typelibs/Gio-2.0.typelib

The mv is the state-changing step. If compilation or verification fails, do not run it: the previous destination stays in place and you can inspect or remove the .new file deliberately.

5. Add directories for referenced GIR files

When the input refers to another GIR XML file outside the default search path, add its directory with --includedir. You can repeat the option. The first directory on the command line has the highest search precedence, so order matters when two directories hold the same namespace and version:

$ /usr/bin/gi-compile-repository \
    --includedir /path/to/project/gir \
    --includedir /path/to/dependency/gir \
    --output build/typelibs/Example-1.0.typelib \
    /path/to/project/gir/Example-1.0.gir

Use absolute or build-system-generated paths rather than relying on the current working directory. If compilation reports a missing namespace, check that the expected XML file exists and that its directory was supplied in the right order. An include directory only affects lookup; it does not copy dependencies into the output directory.

6. Record the library names in the metadata

If the typelib describes symbols from a shared library, pass its name with --shared-library, or -l. The value must not include the shared library suffix. Repeat the option when the metadata covers more than one library:

$ /usr/bin/gi-compile-repository \
    --shared-library example \
    --output build/typelibs/Example-1.0.typelib \
    /path/to/Example-1.0.gir

Here example is the library name without a suffix such as .so. This option records where introspected symbols can be found; it does not build, copy or install libexample.so. Take the intended library name from the GIR file and its build system, not from the typelib filename.

7. Use the prefixed command to cross-compile

Debian provides names such as x86_64-linux-gnu-gi-compile-repository. They select search paths suited to that architecture. Use the prefix that matches the target your cross-build reports, not whichever name autocompletes:

$ /usr/bin/x86_64-linux-gnu-gi-compile-repository --version
gi-compile-repository 2.80.0

For a native build, the two commands give the same version on this host. For another target, follow that target package's documented search paths and keep host and target GIR or typelib directories separate. A successful exit status alone does not prove the result suits the target runtime.

8. Turn on diagnostics when needed

Add --verbose for progress messages, or --debug for more detailed diagnostics:

$ /usr/bin/gi-compile-repository --verbose \
    --output build/typelibs/Gio-2.0.typelib \
    /usr/share/gir-1.0/Gio-2.0.gir
GLib-GIRepository-Message: ... entries ...

Counts and diagnostic wording vary with the input. If the command fails, rerun with --verbose, check the input path, then check every referenced GIR directory. A silent successful run is not an error: normal output is the file named by --output.