Decompile a GObject Typelib into GIR XML Safely

You will turn an installed compiled GObject typelib into GIR XML, save it without overwriting the original, and compare it with the source GIR when one is available. Allow about ten minutes. You need a shell, a readable typelib, and the GObject Introspection tools. The examples use the Ubuntu package version 2.80.0 installed on this machine.

This is an inspection and recovery workflow. It does not alter the typelib, the installed GIR files, or a service. The generated XML is a reconstruction, not a complete replacement for GIR generated from source code, headers and shared libraries.

1. Select the binary you intend to run

First check the command and its version:

$ command -v gi-decompile-typelib
/home/linuxbrew/.linuxbrew/bin/gi-decompile-typelib
$ /usr/bin/gi-decompile-typelib --version
gi-decompile-typelib 2.80.0

Use the absolute path when reproducing a package result. A different copy earlier in PATH can have a different version and different library search behaviour. On Debian-derived systems, the package also installs the architecture-qualified name:

$ /usr/bin/x86_64-linux-gnu-gi-decompile-typelib --version
x86_64-linux-gnu-gi-decompile-typelib 2.80.0

Use that form for cross-compiling when the target architecture requires its search paths. Do not assume that a similarly named executable from another package is interchangeable.

2. Locate a typelib and keep the original safe

A typelib normally lives below a girepository-1.0 directory. This example uses Gio, which is installed with GLib:

$ test -r /usr/lib/x86_64-linux-gnu/girepository-1.0/Gio-2.0.typelib && echo readable
readable
$ ls -lh /usr/lib/x86_64-linux-gnu/girepository-1.0/Gio-2.0.typelib
-rw-r--r-- 1 root root 362K ... Gio-2.0.typelib

Replace the path with the typelib you need. Keep the input path explicit while testing. The program reads the binary and writes GIR XML; it does not edit the input, but a careless output path can overwrite an existing report.

3. Write the decompiled XML to a new file

Pass the typelib as the final argument and use -o or --output for the destination:

$ /usr/bin/gi-decompile-typelib \
    --output Gio-2.0-decompiled.gir \
    /usr/lib/x86_64-linux-gnu/girepository-1.0/Gio-2.0.typelib
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ head -n 5 Gio-2.0-decompiled.gir
<?xml version="1.0"?>
<repository version="1.0"
            xmlns="http://www.gtk.org/introspection/core/1.0"
            xmlns:c="http://www.gtk.org/introspection/c/1.0"
            xmlns:glib="http://www.gtk.org/introspection/glib/1.0">

The destination is ordinary user-owned output, so sudo is not needed. If it already exists, choose a new name or move it aside first. That prevents a failed run from destroying a report you still need.

4. Use standard output for a pipeline

Without --output, the GIR document is written to standard output. Redirect it to a new file when you want a saved result:

$ /usr/bin/gi-decompile-typelib \
    /usr/lib/x86_64-linux-gnu/girepository-1.0/Gio-2.0.typelib \
    > Gio-2.0-decompiled.gir
$ test -s Gio-2.0-decompiled.gir && echo 'non-empty GIR output'
non-empty GIR output

Use --output when shell redirection would make a longer command harder to review. Both forms produce the same kind of XML. Do not pipe the XML through a tool that expects a complete source GIR and silently fills in missing data.

5. Add dependency search directories deliberately

--includedir adds a directory to the search path used while resolving typelibs referenced by the input. It may be specified more than once, and the first directory listed has the highest precedence:

$ /usr/bin/gi-decompile-typelib \
    --includedir /usr/lib/x86_64-linux-gnu/girepository-1.0 \
    --output Gio-2.0-decompiled.gir \
    /usr/lib/x86_64-linux-gnu/girepository-1.0/Gio-2.0.typelib

The option is not a general-purpose rename or input-directory argument. Give the input a real path, especially in scripts. If you need to test precedence, list the preferred directory first and verify the resulting includes rather than trusting the command to report which copy it chose.

6. Decide whether --all is appropriate

The default output contains the normal available information. --all asks the repository API to show all available information:

$ /usr/bin/gi-decompile-typelib --all \
    --output Gio-2.0-all.gir \
    /usr/lib/x86_64-linux-gnu/girepository-1.0/Gio-2.0.typelib
$ wc -c Gio-2.0-decompiled.gir Gio-2.0-all.gir
1696567 Gio-2.0-decompiled.gir
1711428 Gio-2.0-all.gir

The exact size depends on the installed GLib release and typelib. Treat --all as a diagnostic or comparison choice, not as a promise that the binary contains every detail from the original GIR.

7. Compare with the source GIR without expecting equality

If the package provides the original GIR, compare it as evidence of what was lost during compilation:

$ diff -u /usr/share/gir-1.0/Gio-2.0.gir Gio-2.0-decompiled.gir | less

It is normal to see different repository metadata, fewer annotations and fewer source-level details in the decompiled file. The manpage specifically warns that the binary format stores only a subset of GIR information. Use the source GIR when you need authoritative annotations or build metadata. Use the decompiled file when the binary typelib is what you have and a readable inspection artefact is useful.

Common failure traps

A missing input path is not fixed by --includedir; check the exact file with test -r. A command that reports an unexpected version may be a different executable earlier in PATH. If a decompilation fails, keep any existing report, check the binary and dependencies, then rerun with the intended system or architecture-qualified executable. Do not replace installed typelibs or GIR files as an experiment, and do not run this read-only workflow as root.