gtk-rs-core

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.83.0.

Documentation

• Examples
• The Rust API Stable / Development

Ecosystem

The gtk-rs-core repository contains Rust crates for the foundational GObject-based libraries. 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:

• gtk3-rs - bindings for GTK 3
• gtk4-rs - bindings for GTK 4
• 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.

AI Contribution Policy

gtk-rs is a project by humans for humans. We prefer contributions that are produced by human creativity, we expect a human to take full responsibility for each contribution, and we will take more joy in reviewing contributions when there's people at the other end of the line to stand by their changes.

If you use LLM/GenAI tools for your contributions, here are the rules you must follow:

Requirements

1. Use AI as a tool. Verify behavior, correctness, and compatibility yourself prior to submitting your contribution. Do not ask the maintainers to do this for you.
2. Keep changes narrow and limited. Do NOT use LLM/GenAI tools to generate broad rewrites, large refactorings, or style changes.
3. Do NOT submit generated code, documentation, or tests that you don’t understand.
4. Do NOT fabricate benchmarks, bug reports, test results, code samples, or reproducers.
5. Do NOT include private code, credentials, tokens, or any other confidential material.
6. Respect the licensing and attribution requirements.

Disclosure

Always disclose the use of LLM/GenAI tools when creating an issue or a merge request. Do not include trailers like “Co-authored-by:” or “Assisted-by:” in commit messages, since they serve as free advertising for AI companies.

Reviews

1. Describe your changes, and the verification steps.
2. Be prepared to explain all the changes yourself.
3. Do NOT feed the review feedback to an LLM/GenAI tool.

Maintainers expectations

1. Review LLM/GenAI-assisted contributions more strictly than any other contribution.
2. Require reproducibility in fixes and tests.
3. Reject changes that appear to be unverified LLM/GenAI output.
4. Reject comments and feedback that appear to be LLM/GenAI output.

A COMPUTER CAN NEVER BE HELD ACCOUNTABLE. THEREFORE A COMPUTER MUST NEVER MAKE A MAINTENANCE DECISION.

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: main and versioned branches, e.g. 0.20. main contains the not yet released code and is where new developments are happening. 0.20 contains the last release source code of the 0.20 release branch.

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.