Inspect the GLib Type Tree with gobject-query

gobject-query walks GLib's registered type information from a shell, and it will happily tell you almost nothing if you query the wrong process. This guide covers the two query modes, focusing on one root type, readable tree formatting, and why a short result is not automatically a failure.

Allow about ten minutes. You need the gobject-query executable from the GLib development tools. The examples are read-only and do not need sudo. This guide was checked with the command resolved as GLib 2.86.4. On this machine, dpkg also reports libglib2.0-dev-bin version 2.80.0-6ubuntu3.9, because the shell resolves a Linuxbrew executable first. Check your own path before comparing output.

1. Confirm which executable you are running

Start with the path and version. This stops you comparing a distribution package against a different GLib installation:

$ command -v gobject-query
/home/linuxbrew/.linuxbrew/bin/gobject-query
$ gobject-query --version
2.86.4
$ dpkg-query -W -f='${Package} ${Version}\n' libglib2.0-dev-bin
libglib2.0-dev-bin 2.80.0-6ubuntu3.9

The package query is useful on Debian or Ubuntu, but it does not prove that binary is first on your PATH. If command -v finds nothing, install the development-bin package through your normal package manager, then open a new shell.

Checkpoint: record the path and version you will use for the rest of the guide.

2. List the fundamental roots

The mandatory first argument selects a query mode. froots iterates over fundamental roots, which gives a useful overview even when no application-specific types have been registered:

$ gobject-query froots
├void
├GInterface
│ └GTypePlugin
├gchar
├guchar
├gboolean
├gint
├guint
├glong
├gulong
├gint64
├guint64
├GEnum
├GFlags

Your list will likely run longer than this excerpt. The branch characters show relationships in the type hierarchy: GInterface, GEnum and GFlags are type roots here, not shell commands or files to go looking for.

Save the complete listing for later comparison by redirecting it to a file you own:

$ gobject-query froots > /tmp/gobject-fundamental-roots.txt
$ test -s /tmp/gobject-fundamental-roots.txt && echo 'listing written'
listing written

This only touches that one temporary file. Repeat the command with the same path and shell redirection truncates it first, so pick a new name whenever an earlier capture is worth keeping.

3. Print a type tree

Use tree to print the registered type tree:

$ gobject-query tree
 GObject

A short result is not automatically an error. gobject-query is a small process examining whatever type information it can see; it does not load every library in your desktop session, so the set of registered types varies with the executable, libraries and process state. On this host, running it standalone prints only the root shown above.

Choose a root explicitly when you want to investigate one branch:

$ gobject-query tree -r GObject
 GObject
$ gobject-query tree -r GObject -n
 GObject

-r supplies the root type. -n stops descent into child types, handy when you only need to confirm a named root is recognised, or when a large tree would bury the point of the check.

If a supplied root is not known, the command can print nothing at all and still exit successfully:

$ gobject-query tree -r DefinitelyNotAType
$ printf 'exit status: %s\n' "$?"
exit status: 0

Treat empty output as a lookup result, not proof that the type exists. Check the spelling against a known listing or the library's documentation before drawing conclusions.

4. Make a larger listing easier to read

The tree formatter has separate controls for the prefix before each line, the incremental prefix for deeper levels, and the blank lines between entries. This example changes indentation on the fundamental-root listing:

$ gobject-query froots -b '..' -i '++' -s 2 | head -n 12
..├void
..├GInterface
..++ └GTypePlugin
..├gchar
..├guchar
..├gboolean
..├gint
..├guint
..├glong
..├gulong
..├gint64
..├guint64

-b sets the base indent string, -i sets the incremental indent string, and -s sets line spacing. Quote strings containing spaces or shell metacharacters. Start with the defaults when comparing output from two machines, then customise the display for a report or a narrow terminal.

Use -h when you need the installed command's compact option summary. The manpage calls the same two modes froots and tree; the qualifier is mandatory, so gobject-query --help is not a substitute for choosing a mode.

Keep the investigation safe

There is no configuration file to edit and no service to restart for any of this. Skip sudo: elevated privileges will not make an unknown type appear, and they can hide a path or environment difference that is actually useful to see.

When output differs between shells, compare command -v gobject-query, gobject-query --version and the environment each one starts in. If you need a type tree from a running application, query from inside that application's own context or use its diagnostic support; a standalone query cannot report types that were never registered in its process.

If you created the temporary capture in this guide and no longer need it, remove only that known file:

$ rm -- /tmp/gobject-fundamental-roots.txt

Warning: that deletion is irreversible. It is optional, and it does not affect GLib or the type registry either way.

Done means