DEB-GIR-TOOL(1)

NAME
deb-gir-tool - Debian packaging helper for GObject-Introspection GIR XML

SYNOPSIS
deb-gir-tool COMMAND [--upstream-paths] [--verbose] [--zero-terminated] [OPTION...]

deb-gir-tool print-search-path [COMMON_OPTION...]

deb-gir-tool find [--if-exists] [--target-directory=DIR] [--with-dependencies] [COMMON_OPTION...] NAMESPACE-VER [NAMESPACE-VER...]

DESCRIPTION
deb-gir-tool manipulates GObject-Introspection GIR XML files (.gir files) in various ways that can be helpful during Debian packaging.

This tool is Debian-specific and should not be assumed to be present on non-Debian-derived operating systems.

On Debian and Debian derivatives, depend or build-depend on "gobject-introspection (>= 1.86.0-3~)" for access to this tool.

COMMON OPTIONS
These options are accepted by all commands.

--upstream-paths
    By default, deb-gir-tool only shows or searches paths that are appropriate for GIR XML packaged in .deb packages, currently /usr/share/gir-1.0 and /usr/lib/${DEB_HOST_MULTIARCH}/gir-1.0. With the --upstream-paths option, instead deb-gir-tool mimics the behaviour of upstream tools like gi-compile-repository(1) and g-ir-scanner(1), showing or searching all search paths including those configured locally by the user or the sysadmin.

--verbose, -v
    Show more informational output on standard error. "deb-gir-tool find --verbose --with-dependencies" shows which dependencies were a result of which modules, and "deb-gir-tool find --verbose --target-directory=DIR" shows which files it has copied.

    If repeated, enable debug-level logging on standard error.

--zero-terminated, -z
    For commands that normally output a series of items one per line, terminate each item with a zero byte instead of a newline, like "sed -z".

COMMANDS

  find
Locate GIR XML and act on each file found. By default, each filename found is printed on standard output followed by a newline, or a zero byte if the --zero-terminated option was used. Each namespace/version pair found is only shown or copied once, even if it appears on the command-line more than once.

This command requires one or more non-option arguments, each consisting of a namespace, a dash and an API version number, for example GLib-2.0, Gtk-4.0 or Adw-1.

ADDITIONAL OPTIONS

--if-exists
    Silently ignore any nonexistent namespaces or versions specified.

--keep
    If the destination for copying already exists, skip copying instead of failing with an error. This is only useful in conjunction with --target-directory.

--overwrite
    Overwrite files instead of failing with an error. This is only useful in conjunction with --target-directory.

--target-directory DIR
    Instead of printing XML files' names on standard output, copy the XML files to the given DIR.

--with-dependencies
    In addition to the modules given on the command-line, load each GIR XML file to find its dependencies, and show or copy those too. This is done recursively: the dependencies of dependencies are included.

  print-search-path
Output the directories that would be searched for GIR XML on standard output. Each directory name is followed by a newline, or a zero byte if the --zero-terminated option was used.

This command does not accept any non-option arguments or additional options.

ENVIRONMENT

DEB_HOST_MULTIARCH
    If set, search paths that would be appropriate for the given architecture, instead of the architecture for which deb-gir-tool was compiled. If it is run from debian/rules this will typically happen automatically.

DEBUG_INVOCATION
    If set to a non-empty value, show verbose log messages on standard error, similar to "-v -v".

G_MESSAGES_DEBUG
    If set to a non-empty list of space-separated log domains, show verbose log messages on standard error for the given log domains (see GLib documentation for details). A value of all is typical.

GI_GIR_PATH
    Colon-separated list of paths to prepend to the search path if the --upstream-paths option was used.

XDG_DATA_HOME, XDG_DATA_DIRS
    Used to form the search path according to the freedesktop.org Base Directory specification if the --upstream-paths option was used.

OUTPUT
Machine-readable output is emitted on standard output. See the description of each command for details of the format.

Human-readable diagnostic information may be emitted on standard error. It should not be parsed.

EXIT STATUS

0   The tool ran successfully.

1   An error occurred.

2   The command-line arguments were invalid or not understood.

EXAMPLES
Show the absolute path where gi-compile-repository(1) would find GLib-2.0.gir if referenced as a dependency:

    deb-gir-tool find --upstream-paths GLib-2.0

Show where arm-linux-gnueabi-gi-compile-repository(1), the version of gi-compile-repository(1) for the armel architecture, would find GLib-2.0.gir, ignoring local configuration and using only standard OS paths:

    dpkg-architecture -aarmel -c deb-gir-tool find GLib-2.0

Copy Adw-1.gir and all of its recursive dependencies such as Gtk-4.0.gir and GLib-2.0.gir to the current working directory:

    deb-gir-tool find -v --with-dependencies --target-directory=. Adw-1

SEE ALSO
gi-compile-repository(1), g-ir-compile(1), g-ir-scanner(1)