Development

For contributors: build environment, releases and the project layout.

Documentation · Development

Build from source

You need a recent stable Rust toolchain and Git. The exact Rust version is pinned in rust-toolchain.toml; rustup picks it up automatically.

Linux

The GUI needs the development packages of fontconfig, xkbcommon, Wayland and ALSA:

# Fedora
sudo dnf install fontconfig-devel libxkbcommon-devel wayland-devel alsa-lib-devel
# Debian / Ubuntu
sudo apt install libfontconfig1-dev libxkbcommon-dev libwayland-dev libasound2-dev

Then clone and build:

git clone https://github.com/Two-Play/openrage.git
cd openrage
cargo build --release
./target/release/openrage-gui

For a reproducible environment, see the container image below.

Windows

Rust on Windows needs the Visual Studio Build Tools with Desktop development with C++; rustup-init.exe offers to install them. No other libraries are needed. Then, in PowerShell:

git clone https://github.com/Two-Play/openrage.git
cd openrage
cargo build --release
.\target\release\openrage-gui.exe

On Linux, dev/install-desktop-entry.sh adds the build to the application menu (~/.local/share), so the window and the task bar show OpenRAGE's icon: on Wayland a window gets its icon only from the desktop entry named like its app id (openrage). It points at target/release/openrage-gui, or at the program you pass it.

Measure speed with --release: a debug build optimises the dependencies but not OpenRAGE's own crates, so loading models, maps and textures is several times slower there.

Reproducible build environment

For the system libraries there is a container image based on Fedora's toolbx image, dev/Containerfile:

dev/toolbox.sh            # build the image and create the "openrage" toolbox
toolbox enter openrage
cargo run --release -p openrage-gui

Inside the toolbox the GUI runs as usual (Wayland/X11, GPU, audio and your home folder, including the game, are shared). Without toolbx the image works with plain Podman or Docker:

cp rust-toolchain.toml dev/ && podman build -t localhost/openrage-dev -f dev/Containerfile dev
podman run --rm -v "$PWD":/src:Z -w /src localhost/openrage-dev cargo build --release

CI builds the image and OpenRAGE inside it whenever the environment or the dependencies change.

Branches

  • develop is where work goes: every change is a pull request into develop (the default branch).
  • main holds what is released. It only takes pull requests from develop (a release) or from a hotfix/… branch (an urgent fix, merged back into develop afterwards); the Branch flow check refuses others.
  • Both branches are protected: no direct pushes, no force pushes, no deleting; changes need a pull request with the test and licenses checks passing. Pull requests that only touch the website or documentation skip those checks (CI ignores such changes), so a maintainer merges them as an admin.

A release: open a pull request from develop into main, merge it, then tag main (below).

Releases

Releases are made by pushing a version tag on main (git tag v0.2.0 && git push origin v0.2.0, matching the version in Cargo.toml); the Release workflow builds both systems and publishes the release. It can also be run by hand from the Actions tab to build the archives without publishing.

Once a release is published, the Release bundle workflow adds openrage-<tag>-linux-windows.zip: both versions in one download (linux/, windows/, a short README.txt and the license files), for mod sites that host one file per release. It reuses the release's archives instead of building again and adds its checksum to SHA256SUMS.txt. Run it by hand (Actions → Release bundle → Run workflow) with a tag to make the bundle for an older release; with upload off it is only kept as a workflow artifact.

Licenses

OpenRAGE is GPL-3.0-only, so every dependency must come under a license that can be combined with it. deny.toml lists the allowed licenses; CI runs cargo deny check licenses on every change. A new dependency with another license fails CI: check that it is GPL-3-compatible before adding it to the list.

THIRD_PARTY_LICENSES.md (shipped with every release) and crates/openrage-app/src/third_party_licenses.json (shown in Help → About OpenRAGE, by openrage licenses and on the licenses page) are generated from Cargo.lock with cargo-about (configured in about.toml). After changing dependencies, regenerate them:

cargo install --locked --features cli cargo-about
cargo fetch --locked
python3 dev/third_party_licenses.py

CI checks that both files are current (python3 dev/third_party_licenses.py --check). The licenses page copies the JSON into site/data/ when the website is built; do the same (mkdir -p site/data && cp crates/openrage-app/src/third_party_licenses.json site/data/) before zola serve.

Credits for format knowledge and ported code go into NOTICE.md by hand; the About dialog shows its sections.

Project layout

CratePurpose
rage-coreshared primitives: hashing (joaat), positional I/O
rage-cryptoAES / NG ciphers, Rockstar's XXTEA, key discovery in the user's executable, key cache
rage-rpfRPF7 reader and OpenIV-style writer, virtual file system over nested archives
rage-indexSQLite search index: names, hash dictionary, FTS5 full text, incremental updates
rage-resourceRSC7 resources: page layout, virtual pointers into system/graphics memory
rage-formatsgame formats: textures, models, audio, animations, metadata (meta/PSO/RBF → XML), text tables
rage-modsOpenIV mods folder: overlay resolution, folder comparison, change lists
openrage-appsettings, key setup, game detection, extraction, model and format logic shared by CLI and GUI
openrage-pluginsplugin host: manifests, discovery, permissions, the wasmtime sandbox; the plugin interface (wit/plugin.wit)
openrage-clithe openrage command-line tool
openrage-guithe Slint explorer (openrage-gui)

plugins/ is a separate Cargo workspace built for wasm32-wasip2: the plugin SDK, the example plugins and a test plugin. cargo test builds them and runs them in the host (crates/openrage-plugins/tests).

The UI language is English; the GUI is built with Slint's translation support so further languages can be added.