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.
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.
Pending refactoring in issue 10.
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.
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.
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.
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.
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.
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.
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.
The gobject-introspection
.gir and .typelib files can be used to autogenerate bindings for dozens of
different languages.