Introduction

This book aims to provide complete documentation on how to use gir to generate bindings for GObject based libraries based on the GObject introspection data.

gir consists of a library and at the same time a binary you can use to generate the bindings.

gir requires both a Gir.toml configuration file and a .gir file containing the GObject introspection data.

• The *.gir you need will correspond to the project you want to generate bindings for. You can get them from here or directly on ubuntu website (for example: http://packages.ubuntu.com/zesty/amd64/libgtk-3-dev).

• The *.toml is what is used to pass various settings and options to gir for use when generating the bindings - you will need to write one to suit your needs, for an example you can take a look to gtk-rs/sys/gir-gtk.toml.

It operates on 4 different modes:

• sys: is what creates the low-level FFI bindings from the supplied *.gir file - these are essentially direct calls in to the related C library and are typically unsafe. The resulting crate is typically appended with -sys.

• normal: generates another crate for a layer on top of these unsafe (sys) bindings which makes them safe for use in general Rust.

• not_bound: allows you to see the detected types/methods that will not be generated for whatever reasons.

• doc: used for documentation generation

Helpers

gir includes a wrapper script ./generator.py that detects Gir.toml configurations in the current directory (or the path(s) passed on the command-line) and generates "normal" or "sys" crates for it. Alternatively --embed-docs can be passed to prepare source-code for a documentation build by moving all documentation into it. For a complete overview of available options, pass --help.

GIR format reference

It can always be useful to look at the reference or schema.