glib-compile-resources

Compile resources referenced in file.gresource.xml to a .gresource binary

$ glib-compile-resources [file.gresource.xml]

$ glib-compile-resources --generate-source [file.gresource.xml]

$ glib-compile-resources --generate --target=[file.ext] [file.gresource.xml]

$ glib-compile-resources --generate-dependencies [file.gresource.xml]

glib-compile-resources [OPTION...]

--target=FILE
    Specifies the output file name. The file extension often determines the output type (e.g., .c for C source, .h for C header, .gresource for binary).

--sourcedir=DIR
    Sets the base directory from which relative paths in the .gresource.xml file are resolved. This is crucial for locating the actual resource files.

--generate-header
    Instructs the command to generate a C header file (.h), typically containing declarations for accessing the compiled resources.

--generate-source
    Instructs the command to generate a C source file (.c) containing the compiled resource data and initialization functions.

--generate-gresource
    Instructs the command to generate a binary .gresource file, which can be loaded at runtime without being compiled into the application's executable.

--dependency-file=FILE
    Generates a file listing the dependencies of the compiled resources, useful for integration with build systems like Make.

--c-name=NAME
    Specifies the C identifier name for the generated resource variable, used when generating C source or header files.

--internal
    Makes the generated declarations internal (static) to the C source file, preventing symbol clashes if the resource is part of a library.

--external-data
    Causes data larger than 1MB to be stored externally in separate files rather than embedded directly. Useful for very large resources.

--disable-external-data
    Disables the external data feature, embedding all data directly regardless of size.

--compress
    Compresses resource data using zlib. This is the default behavior in modern GLib versions (since 2.70).

--disable-compress
    Disables resource data compression.

--compression-level=LEVEL
    Sets the zlib compression level (0-9, default 9).

--compression-type=TYPE
    Sets the compression algorithm (e.g., 'none', 'lz4', 'zlib').

--version
    Displays the version information of glib-compile-resources.

--help
    Shows a summary of command-line options.

The glib-compile-resources command is a utility provided by the GLib library, primarily used in the development of GTK+ and other GLib-based applications. Its core function is to take an XML description of application resources (such as images, UI definitions, CSS files, icons, or any other data) along with the actual resource files, and compile them into a C source file or a binary GResource file.

This process allows developers to bundle all necessary application assets directly into the executable, eliminating the need for separate resource files at runtime. This simplifies deployment, ensures resources are always available, and can improve startup performance by reducing file system lookups. The generated C source file can then be compiled and linked into the application's executable, where resources can be accessed programmatically using GLib's GResource API. Alternatively, a .gresource binary file can be generated and loaded at runtime. It's an essential tool for creating self-contained and easily distributable GLib applications.

• Build System Integration: While powerful, glib-compile-resources is typically integrated into build systems like Meson or Autotools rather than run manually by developers. Incorrect build script setup can lead to issues.
• XML Structure: The command relies heavily on a correctly formatted .gresource.xml file. Errors in this XML can lead to compilation failures.
• Path Resolution: Careful use of the --sourcedir option and relative paths in the XML is necessary to ensure all resources are found correctly.
• Large Resources: For very large resources, consider using --external-data to avoid excessive memory usage or long compilation times when embedding directly.

The input to glib-compile-resources is typically an XML file (e.g., myresources.gresource.xml) that describes the resources. It defines one or more <gresource> bundles, each with a prefix attribute (e.g., /org/example/app/ui/) under which resources are accessed. Within each bundle, individual resource files are listed using <file> tags. The path in the <file> tag is relative to the --sourcedir. Resources can also specify attributes like compressed="true". This structured XML allows the command to know which files to include and how they should be exposed within the application.

In most modern GLib/GTK+ projects, glib-compile-resources is not run manually. Instead, it's integrated into the project's build system. Tools like Meson or Autotools have built-in support or modules to automatically invoke glib-compile-resources during the build process. This ensures that resources are compiled and linked correctly, and dependencies are managed, simplifying the build workflow for developers.

The glib-compile-resources utility, and the GResource system it supports, was introduced with GLib 2.32, released in March 2012. Before this, developers often resorted to custom methods or external tools to embed resources into applications. The GResource system provided a standardized, efficient, and integrated way for GLib/GTK+ applications to manage and access their bundled assets, improving deployment simplicity and runtime performance. Its development reflects GLib's ongoing effort to provide comprehensive tooling for application development on Linux and other platforms.

gresource(1), pkg-config(1), gcc(1)