Example for exporting a GObject/C API from Rust

This repository contains an example Rust crate that can compile to a C-compatible shared library and that exports a GObject C API.

At the same time the API provided by this crate can be used directly from Rust by statically linking this crate as well as by dynamically linking against the C-compatible library. Both variants provide exactly the same Rust API.

In addition it provides a way to generate GObject-Introspection metadata that allows usage from other languages, like Python and JavaScript.

Implemented Example APIs

General Structure

Each type comes with 3 Rust modules

• mod.rs: Contains a Rust wrapper of the API. This is basically the same as what gir would autogenerate, and follows the same patterns as the GLib, GTK, etc. bindings.
• imp.rs: Contains the definition of the types together with the actual private implementation, plus an inline FFI module that exports C-compatible FFI functions.
• ffi.rs: Contains Rust FFI definitions of the exported C types. This is only used in combination with the bindings cargo feature (see below).

and a C header that is (for now, see issue 6) manually written.

Details

Pending refactoring in issue 10.

Usage

Usage from Rust

The API from the mod.rs can directly be used from Rust code and follows the same patterns as the GLib, GTK, etc. bindings.

There is example usage in the inline tests inside the mod.rs of each type.

Statically linked crate

The crate can be directly added as a dependency in some other projects Cargo.toml and then the API from the individual mod.rs is available.

This statically links the implementation into the application.

Running make check would run tests in this mode.

Dynamically linked C library (bindings feature)

When adding the crate as a dependency and enabling the bindings cargo feature then the actual implementation of all the types is omitted. Instead dynamic linking against the implementation from the C-compatible shared library will happen.

The API is otherwise exactly the same.

Running make check-bindings would run tests in this mode.

Usage from C

Running cargo build will create a C-compatible shared library in target/debug/libgobject_example.so. The corresponding headers for the API can be found in the include directory.

test.c contains some example usage of the API and make run-c compiles and runs this.

Usage from Python

Via gobject-introspection a Ex-0.1.typelib file is created. This can be used by pygobject to expose the API directly to Python.

test.py contains some example usage of the API and make run-python runs this.

Usage from JavaScript/GJS

Via gobject-introspection a Ex-0.1.typelib file is created. This can be used by gjs to expose the API directly to JavaScript. An alternative for node.js would be node-gtk.

test.js contains some example usage of the API and make run-gjs runs this.

Usage from Vala

Via gobject-introspection a Ex-0.1.gir file is created that contains an XML representation of the API. Vala can directly make use of this.

test.vala contains some example usage of the API and make run-vala runs this.

Usage from other languages

The gobject-introspection .gir and .typelib files can be used to autogenerate bindings for dozens of different languages.