On this page you can learn how to contribute to Fractal by working on the code.
Here are a few links to help you get started with Rust and the GTK Rust bindings:
The Rust docs of our application and the GNOME Development Center might also be useful.
Don't hesitate to join our Matrix room to come talk to us and ask us any questions you might have. The “Rust ❤️ GNOME” room can also provide general help about using Rust in GNOME.
Fractal is written in Rust, so you will need to have at least Rust (the minimum required version is
available in the Cargo.toml file as package.rust-version) and Cargo available on your system.
You will also need to install the Rust nightly toolchain to be able to run our
pre-commit hook, which can be done with:
rustup toolchain install nightlyIf you are building Fractal with Flatpak (via GNOME Builder or the command line), you will need to manually add the necessary remotes and install the Rust freedesktop.org extension:
# Add Flathub and the gnome-nightly repo
flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak remote-add --user --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo
# Install the gnome-nightly Sdk and Platform runtime
flatpak install --user gnome-nightly org.gnome.Sdk//master org.gnome.Platform//master
# Install the required rust-stable extension from Flathub
flatpak install --user flathub org.freedesktop.Sdk.Extension.rust-stable//25.08If you are building the flatpak manually you will also need flatpak-builder on your system, or the
org.flatpak.Builder flatpak from Flathub.
Using GNOME Builder with Flatpak is the recommended way of building and installing Fractal.
You can find help on cloning and building a project in the docs of Builder.
To open a build terminal to run commands like Clippy, you can use the “+” button at
the left of the header bar of the editor and select “New build terminal”, or use its keyboard
shortcut Shift+Ctrl+Alt+T. The terminal should open in
the _build directory.
As an alternative, Foundry is a command line tool with
a lot of features similar to an IDE, which we can also use to develop in a Flatpak environment. It
should be available as the foundry package in your distribution.
First, set up the project:
foundry initThen, you can build and run the application directly:
foundry runNote that Foundry will use .foundry/cache/build as build directory.
To test changes you make to the code, re-run that last command.
To run commands like Clippy in the build environment, use:
foundry devenv -- {COMMAND}The command will run in the .foundry/cache/build directory by default.
Another command line alternative is fenv, which focuses only on developing with Flatpak.
First, install fenv:
cargo install --git https://gitlab.gnome.org/ZanderBrown/fenv fenvAfter that, set up the project:
# Set up the flatpak environment
fenv gen build-aux/org.gnome.Fractal.Devel.jsonFinally, build and run the application:
# Build the project
fenv build
# Launch Fractal
fenv runNote that fenv will use _build as build directory.
To test changes you make to the code, re-run these two last commands.
To run commands like Clippy in the build environment, use:
fenv exec -- {COMMAND}The command will run in the current directory by default.
Some features that interact with the system require the app to be installed to test them (i.e. notifications, command line arguments, etc.).
GNOME Builder can export a flatpak of the app after it has been successfully built.
Fractal can then be installed with:
flatpak install --user --bundle path/to/org.gnome.Fractal.Devel.flatpakAlternatively, it can be built and installed with flatpak-builder:
flatpak-builder --user --install app build-aux/org.gnome.Fractal.Devel.jsonNote that the flatpak-builder command can be replaced with flatpak run org.flatpak.Builder.
It can then be entirely removed from your system with:
flatpak remove --delete-data org.gnome.Fractal.DevelIf you decide to ignore our recommendation and build on your host system, outside of Flatpak, you will need Meson and Ninja.
meson setup --prefix=/usr/local _build
ninja -C _build
sudo ninja -C _build installWe expect all code contributions to be correctly formatted. To help with that, a pre-commit hook
should get installed as part of the building process. It runs the hooks/checks crate. It's a
quick script that makes sure that the code is correctly formatted with rustfmt, among other
things. Make sure that this script is effectively run before submitting your merge request,
otherwise CI will probably fail right away.
You should also run Clippy as that will catch common errors and improve the quality of your submissions and is once again checked by our CI. To reuse the same cache as when building Fractal, you should run the following command in a build environment:
meson compile -C {BUILD_DIRECTORY} src/cargo-clippy_ The -C {BUILD_DIRECTORY} option can be omitted when the command is run from the build
directory._
Please follow the GNOME commit message guidelines. We enforce the use of a tag as a prefix for the summary line. It should be the area of the app that is changed.
You must pass all the prerequisites of the Change Submission Guide.
Before submitting a merge request, make sure that your fork is available publicly, otherwise CI won't be able to run.
Use the title of your commit as the title of your MR if there's only one. Otherwise it should summarize all your commits. If your commits do several tasks that can be separated, open several merge requests.
In the details, write a more detailed description of what it does. If your changes include a change in the UI or the UX, provide screenshots in both light and dark mode, and/or a screencast of the new behavior.
Don't forget to mention the issue that this merge request solves or is related to, if applicable.
GitLab recognizes the syntax Closes #XXXX or Fixes #XXXX that will close the corresponding
issue accordingly when your change is merged.
We expect to always work with a clean commit history. When you apply fixes or suggestions, amend or fixup and squash your previous commits that you can then force push.
Contributions must not include content generated by large language models or other probabilistic tools like ChatGPT, Claude, and Copilot.
This policy exists due to
- ethical concerns about the data gathering for training these models
- the disproportionate use of electricity and water of building / running them
- the potential negative influence of LLM-generated content on quality
- potential copyright violations
This ban of LLM-generated content applies to all parts of the projects, including, but not limited to, code, documentation, issues, and artworks. Translating texts for issues and comments to English can be achieved with machine translation tools, without the use of generative AI (LLM), such as DeepL.
We heavily discourage the use of LLM chat bots as a replacement for reading Fractal's documentation and API reference.
Support requests referencing misleading or false LLM output relating to the project may be ignored, since it is a waste of time for us to "debug" where things went wrong based on this output before human support was sought.