gtk-rs / gir-files

gtk3-rs

This project is UNMAINTAINED. Please take a look at gtk4-rs instead!

The gtk-rs organization aims to provide safe Rust binding over GObject-based libraries. You can find more about it on https://gtk-rs.org.

This repository contains all the "core" crates of the gtk-rs organization. For more information about each crate, please refer to their README.md file in their directory.

Minimum supported Rust version

Currently, the minimum supported Rust version is 1.70.0.

Documentation

• Examples
• The Rust API Stable / Development

Ecosystem

The gtk3-rs repository contains Rust crates for GTK 3. However there is a large ecosystem of GObject libraries and many of these libraries have Rust bindings based on the tooling included in gtk-rs. Of particular note:

• gtk-rs-core - bindings for some of the core libraries such as glib, gio, pango, graphene
• gstreamer-rs - bindings for the GStreamer media framework

Additionally, Rust bindings for various libraries are hosted on GNOME's GitLab instance and can be found at https://gitlab.gnome.org/World/Rust.

When using crates that are not part of the gtk-rs repository, you will need to be careful and ensure that they do not pull in incompatible versions of core crates like glib-rs.

Regenerating

To regenerate crates using gir, please use the generator.py file as follows:

$ python3 generator.py

If you didn't do so yet, please check out all the submodules before via

$ git submodule update --checkout

Development

This repository is mostly split into two branches: master and crate. master contains the not yet released code and is where new developments are happening. crate contains the last release source code and isn't supposed to be updated.

This repository is structured as follows:

- crate/
   |
   |-- README.md
   |-- Gir.toml
   |-- Cargo.toml
   |-- src/
   |-- sys/

The crate is a "top" directory (so "atk" or "gdk" in here for example). Each crate contains:

• README.md: explanations about the crate itself and eventually some details.
• Cargo.toml: descriptor of the crate, used by cargo and Rust.
• Gir.toml: configuration used by gir to generate most of the crates' code.
• src: the source code of the crate.
• sys: the 1:1 bindings of the C API.

The gir and gir-files top folders are not crates, but are git submodules which respectively contain the gir tool and the gir files used by the generator.

When running generator.py the tool will automatically update these git submodules and run the gir tool on the gir files to regenerate the code.

During development, it is useful to execute the generator with a different version of the gir tool or of the gir files, for instance to test if the code generation is successful before submitting a pull request to update one of the submodules. This can be done by specifying arguments to the generator script, for instance, to run the generator on a local copy of the gir files:

$ python3 generator.py --gir-files-directory ../gir-files/

See python3 generator.py --help for more details.

gir-files's Issues

PangoCairo FcFontMap

In PangoCairo-1.0.gir, in class FcFontMap, the type of field parent_instance
should actually be Pango.FcFontMap. Patch applied by fix.py is incorrect.

Though, simply replacing it with Pango.FcFontMap is not correct either,
as this type is not defined anywhere in gir. Removing all fields to make type
opaque would be one possible workaround.

Soup-2.4.gir has gconstpointer instead of the actual type for a couple functions

For example:

• soup_address_equal_by_ip
• soup_address_equal_by_name

Switch to the MIT license

As there is no license on this repo, it's hard to reuse the code as part of another project.

Here is thus a suggestion to relicense into MIT.

Please answer with a sentence like “I hereby accept to license all my contributions to this repository under the MIT license” if you agree.

Note I am not a lawyer and cannot assert that this will be enough to be legally allowed to relicense the repository, but it's the best I can do :)

• @GuillaumeGomez
• @EPashkin
• @sfanxiang
• @moggiesir
• @vhdirk
• @fengalin
• @sdroege
• @bvinc
• @tmiasko
• @antoyo
• @gkoz

Upgrading to Gtk 3.22

I tried update gir-files with ubuntu's latest (like http://packages.ubuntu.com/zesty/amd64/libgtk-3-dev).
Examples with feature gtk_3_18 build fine, but I can't build version depends on gtk/v3_18 as no package with these features published.
So I starting make PRs for prepare these packages, not sure that it time for publish new crates (maybe we need solve other needed problem).
@GuillaumeGomez, how you think?

some autogenerated enums are not valid in rust

When an enum symbol, its last element starts with a number, the auto-generated rust symbol is not valid

For example, GstGLVersion:

GST_GLSL_VERSION_100 will generate an enum symbol named 100, which is not valid

Another example is GstGLTextureTarget

GST_GL_TEXTURE_TARGET_2D is generated as 2D, which isn't valid either.

An option could be, in those cases, to prepend a '_'.

Update to newer versions

At least GLib, GObject, but probably also GTK/Pango/GDK. The ones here are quite old by now :)

Add `webkit2gtk5-rs` files

To help aid development on webkit2gtk5-rs, I propose that the following files be included in this repository (by including them within dl.py):

• WebKit2-5.0.gir
• JavaScriptCore-5.0.gir
• Soup-3.0.gir
• WebKit2WebExtension-5.0.gir

Additionally, to properly patch JavaScriptCore-5.0.gir, two more files will be needed:

• JavaScriptCore-5.0-patch.gir
• JavaScriptCore-5.0.xsl

To patch JavaScriptCore-5.0.gir, fix.sh should have the following appended to it:

# change int to uint to prevent overflow
xmlstarlet ed -L \
	-u '//_:constant[@name="DOM_NODE_FILTER_SHOW_ALL"]/_:type[@name="gint"]/@c:type' -v "guint" \
	-u '//_:constant[@name="DOM_NODE_FILTER_SHOW_ALL"]/_:type[@name="gint"]/@name' -v "guint" \
	WebKit2WebExtension-5.0.gir

xmlstarlet tr JavaScriptCore-5.0.xsl JavaScriptCore-5.0.gir | xmlstarlet fo >JavaScriptCore-5.0.gir.tmp
mv JavaScriptCore-5.0.gir.tmp JavaScriptCore-5.0.gir

# fill in types from JavaScriptCore
xmlstarlet ed -L \
	-i '///_:type[not(@name) and @c:type="JSGlobalContextRef"]' -t 'attr' -n 'name' -v "JavaScriptCore.GlobalContextRef" \
	-i '///_:type[not(@name) and @c:type="JSValueRef"]' -t 'attr' -n 'name' -v "JavaScriptCore.ValueRef" \
	WebKit2WebExtension-5.0.gir WebKit2-5.0.gir

xmlstarlet ed -L \
	-u '//_:constant[@name="DOM_NODE_FILTER_SHOW_ALL"]/_:type/@name' -v "guint" \
	-u '//_:constant[@name="DOM_NODE_FILTER_SHOW_ALL"]/_:type/@c:type' -v "guint" \
	WebKit2WebExtension-5.0.gir

---

With all this in mind, would it make sense to add the webkit2gtk-5.0 .GIR files to this repository? Would it be beyond the scope of this repository to do so? If not, should this repository go so far as to simply contain all the .GIR files included within the GNOME SDK (as this repository does)?

[Feature request] Create release for 0.16 and 0.17

Like discussed on #rust:gnome.org, please release the gir files used to generate the bindings for 0.16 under a 0.16 tag (and likewise for 0.17).
Enabling this by default for future releases would tremendously help.

Thanks,

werdahias

gir files are Linux-only

These .gir files only work on Linux systems! For instance g_desktop_app_info_get_type is not available in macOS systems (g_osx_app_info_get_type is instead). Perhaps these files could be generated on the fly for each platform?

libadwaita.gir

Hey all, i'm really interested in getting the new adwaita project into Rust. I thought i'd open this issue as a place to kickstart the effort. Maybe folks have thoughts about this library and a strategy for inclusion.

How to generate a GIR file?

I am not sure where I should open this issue, but I cannot see any documentation about how to create a new GIR file.

I would like to create a Rust binding of libgoa and I was told that using GIR is a good first step. But I only saw some documentation about using a GIR file, not generating it.

BTW, does the GIR format handle the asynchronous methods? In my binding, I wrap the asynchronous Rust methods in a fn foobar() -> impl Future<Output = FooBar>, but I wonder if GIR does that as well.