zig-gobject

Bindings for GObject-based libraries (such as GTK) generated using GObject introspection data.

Usage

To use the bindings, find the latest release of this project and add the desired bindings artifact as a dependency in build.zig.zon. Then, the exposed bindings can be used as modules. For example:

const gobject = b.dependency("gobject", .{});
exe.root_module.addImport("gtk", gobject.module("gtk-4.0"));
exe.root_module.addImport("adw", gobject.module("adw-1"));

The generated bindings are primarily tested with Zig 0.13.0, but should also work with 0.12.0 and master. The binding generator supports only Zig 0.13.0; other versions of Zig may or may not work.

Companion projects

zig-libintl - libintl bindings for Zig, which provide gettext functions for internationalization.
Nonograms - a full application written using these bindings.

Examples

There are several examples in the example directory, which is itself a runnable project (depending on the bindings directory as a dependency). After generating the bindings, the examples can be run using zig build run in the example directory.

Development environment

The bindings generated by this project cover a wide variety of libraries, and it can be annoying and inconvenient to install these libraries on a host system for testing purposes. The best way to get a consistent environment for testing is to use Flatpak:

Install flatpak.
Install the base SDK dependencies:
- flatpak install org.freedesktop.Sdk//23.08
- flatpak install org.gnome.Sdk//46
- flatpak install org.freedesktop.Sdk.Extension.ziglang//23.08

The steps above only need to be done once per GNOME SDK version. To enter a development environment:

Run flatpak run --filesystem=home --share=network --share=ipc --socket=fallback-x11 --socket=wayland --device=dri --socket=session-bus org.gnome.Sdk//46
- --filesystem=home - makes the user's home directory available within the container
- --share=network - allows network access (needed to fetch build.zig.zon dependencies)
- --share=ipc --socket=fallback-x11 --socket=wayland --device=dri - allows graphical display through X11 or Wayland

--socket=session-bus - allows access to the session bus
For convenience, this command is available as a script in this repository: flatpak-env.sh.

Within the spawned shell, run . /usr/lib/sdk/ziglang-master/enable.sh to add Zig to your PATH (don't forget the . at the beginning of that command).

Running the binding generator

The binding generator can be invoked using zig build codegen, which accepts several useful options and is described further below, or by building the zig-gobject binary using zig build and invoking it directly.

zig build codegen requires a set of modules to be used as input. The input modules can be specified using -Dmodules to provide an explicit list of root modules for codegen (the codegen process will also discover any necessary dependencies): for example, zig build codegen -Dmodules=Gtk-4.0 will generate bindings for GTK 4 and anything else it depends on (Gio, GObject, GLib, and many others).

Alternatively, if a Flatpak development environment is set up (see the section above), a predefined GIR profile can be selected using -Dgir-profile, which includes all the modules available in a specific GNOME SDK.

GIR files are assumed to be located in /usr/share/gir-1.0 unless this is overridden via -Dgir-files-path.

The bindings are generated to the bindings directory under the build prefix (by default, zig-out).

Fixing broken GIR files

Sometimes, there are errors in GIR files which result in incorrect or incomplete bindings. The codegen process handles this by allowing GIR files to be transformed at build time using XSLT: providing the -Dgir-fixes=module=transform.xslt will cause the GIR for module to be transformed using transform.xslt prior to codegen. This transformation is not destructive: it writes the transformed GIR to a temporary directory and prepends the directory to the GIR search path.

Fixes for known GIR issues are maintained in gir-fixes.

Writing bindings by hand

While the binding generator is capable of generating good bindings from GIR input, it is sometimes necessary or desirable to bypass GIR for everything except build-related metadata (library dependencies, etc.) and write Zig bindings by hand. This is the strategy taken for Cairo, using the Cairo bindings in binding-overrides.

Any manual binding files present in binding-overrides will cause codegen of bindings to be skipped for the corresponding modules, using the manual bindings instead.

Running tests

zig build test will run the binding generator's tests. If bindings have been generated, the test project directory contains a package depending on them which runs tests on the generated bindings. The zig build test command in the test project accepts the same modules and gir-profile options as the codegen command to specify which modules to test (unlike codegen, the modules option here specifies a complete list of modules to test: there is no discovery and testing of dependency modules).

License

This project is released under the Zero-Clause BSD License. The libraries exposed by the generated bindings are subject to their own licenses.

ianprime0509/zig-gobject