Building from source and contributing

On Debian or Ubuntu, these are the packages the project's own builds install:

sudo apt install pkg-config cmake clang libxkbcommon-dev libxkbcommon-x11-dev \
  libwayland-dev libvulkan-dev libx11-xcb-dev libxcb1-dev libfontconfig-dev \
  libfreetype-dev libasound2-dev libzstd-dev

On other distributions, install the same libraries under their names there: a C toolchain with clang and cmake, pkg-config, and the development files of xkbcommon (with its X11 part), Wayland, Vulkan, xcb, fontconfig, freetype, ALSA and zstd.

The checks (task check:ci) also need Python 3 with PyYAML (python3-yaml).

A built Revue links only libc, libxcb and libxkbcommon. Wayland, Vulkan and fontconfig are loaded when it runs, so the computer that runs Revue needs a working Vulkan driver.

• macOS: the Xcode Command Line Tools (xcode-select --install). Revue compiles its Metal shaders when it runs, so the full Xcode isn't needed.
• Windows: the Rust MSVC toolchain, which needs the Visual Studio Build Tools with the C++ workload and a Windows SDK. Revue's shaders come precompiled with the source, so no shader compiler is needed.

If another cargo build (a second task dev, your editor's rust-analyzer) holds the build lock, task dev starts the last build instead of waiting, and says it may be out of date.

• Settings, data and the credential store are copied; the copy of the credentials is kept in memory only.
• It doesn't install updates and doesn't register itself for revue:// links.
• Sign-in tokens that a service renews are still saved for real, because the service stops accepting the old ones.
• revue --immutable does the same with any build (see Command line and environment variables).

task check runs the same checks as task check:ci plus the release build (slow: it's optimized with LTO). task check:quick leaves the release build out. Unlike check:ci, both build with the normal dev profile.

They work in two ways:

• With Nix installed, they run in the Nix dev shell (nix develop), which brings the Rust toolchain, the system libraries and Python. Nothing else is needed.
• Without Nix (or with task check NIX=0), they use the tools on your PATH, on Linux, macOS and Windows: Rust from rustup (it installs the pinned toolchain with clippy and rustfmt), your system's libraries (see What you need) and Python 3 with PyYAML (pip install pyyaml, or python3-yaml). Without Python and PyYAML, the workflow YAML check is skipped with a note; CI still runs it.

• task icons regenerates every icon format from assets/revue-icon.png, including the green dev icons.
• task file-icons -- <downloads folder> vendors the file-type icon themes and regenerates src/file_icons_table.rs.
• task windows-shaders precompiles GPUI's Windows shaders (with fxc.exe under Wine). Only needed after updating the patched GPUI Windows crate.
• task package PLATFORM=linux|windows|macos BIN=<path> packages a built binary into target/release-dist.
• task build and task release:build:linux|windows|macos build the release files in Docker images (see Releasing).
• task agent-cargo -- … is cargo for AI coding sessions working in the repository at once: it runs one cargo at a time in a shared build folder.
• task mcp:forgejo and task mcp:github start MCP servers for the repository, for coding assistants (from .mcp.json).

task shoot runs Revue in a headless sway session, drives it with keystrokes and saves screenshots, without touching your desktop or your Revue data. It needs sway, grim, wtype and wlrctl.

task shoot -- OUTDIR [--size WxH] [--light] [--clean] [--cache] [--settings JSON] [--demo] [--] [revue args] ::: STEP...

• It signs in with REVUE_GITHUB_TOKEN, or else the gh CLI's token, and starts from an empty cache. It never reads your Revue settings, sign-ins or cache.
• --size sets the window size (default 1920x1200), --light uses the light theme, --clean signs in only with a REVUE_GITHUB_TOKEN you pass explicitly, --cache starts from a copy of your HTTP cache (faster, but it holds your pull requests; not with --clean), --settings passes settings as JSON, and --demo runs the demo on made-up data.
• Each STEP is one of shot:NAME, key:KEYS, press:KEY, combo:MOD+KEY (e.g. combo:ctrl+shift+f), sleep:SECONDS, type:TEXT, click:X,Y, hover:X,Y or drag:X1,Y1,X2,Y2.
• It runs target/release/revue, or the binary in REVUE_BIN.

The Linux release archive comes with its own small Taskfile. After extracting it, task install installs Revue to ~/.local (the program, a desktop entry and icons), or system-wide with PREFIX=/usr/local task install as root.

revue-server is a separate program with its own Cargo.toml in server/. Run its tests there: cd server && cargo test. Building its Docker image runs them too.

The account pages run the app's encryption (crates/revue-vault) in the browser, compiled to WebAssembly from crates/revue-vault-wasm, a workspace of its own with its own Cargo.lock (a test in crates/revue-vault checks it locks the same versions as the app's). It isn't committed: the server's Docker image builds it, and task server:wasm builds it into server/assets/revue-vault.wasm (ignored by git) for task server:dev and task server:js-test, which run it first. That needs the wasm32-unknown-unknown target, which the task adds with rustup. Without the module the server still builds and passes its tests, but the account pages can't run (their wasm answers 503), and a release build with accounts stops with an error.

Project-wide settings that aren't secret live in global.env, which is checked in and compiled into every build: the server address (REVUE_SERVER_URL) and the crash-report address (REVUE_SENTRY_DSN). A variable of the same name set while building wins, and an empty one turns it off.

Only release builds send crash reports: the release builds set REVUE_RELEASE=1.

• Access tokens from Bitbucket (2 hours), Atlassian (1 hour) and Forgejo (1 hour) expire. Revue renews them with the refresh token 2 minutes before they run out, and saves the new pair on that computer only, never in the synced settings folder.
• GitHub OAuth apps registered since August 2026 expire their tokens after 8 hours by default, with a refresh token. Revue renews those the same way. An older app's tokens don't expire, unless you turn on Require token expiration in its settings.
• The browser has 10 minutes to come back to Revue.

• Revue asks for the scopes repo read:org, the same as a classic token.
• Organizations with OAuth app access restrictions show Revue as "requested". An organization owner has to approve it (organization Settings → Third-party access → OAuth application policy) before its private repositories appear.

Bitbucket accepts OAuth tokens only on api.bitbucket.org, not for the bitbucket.org source downloads that the Code tab and Find in Files use. When that download is refused, Revue fetches the commit's files through the API instead, one request per file (large files are left out, as with the download). Bitbucket allows about a thousand API requests an hour, so for repositories with more than 2000 files Revue asks you to sign that account in with an API token to browse its code. Reviewing diffs and comments works either way.

• Don't add offline_access in the console. Revue asks for it when signing in, to get a refresh token.
• For sharing, Atlassian asks for a vendor name, a privacy policy address and whether the app stores personal data. Revue stores tokens only on the user's own computer and has no server for them.
• At sign-in, Revue lists the Jira sites the account can reach. If there's more than one, type the site (your-company.atlassian.net) in the form first.

• Revue asks for the scopes read:user write:repository write:issue read:notification. Servers too old to know OAuth scopes grant full access instead.
• Server addresses in REVUE_FORGEJO_CLIENT_IDS are matched loosely: codeberg.org and https://codeberg.org/ are the same. Pairs may also be separated by ; or new lines.

• Slack lets a PKCE app come back to http://localhost, but only for user scopes, which is all Revue asks for.
• Without PKCE, Slack sends the browser only to an HTTPS address. Then also set REVUE_SLACK_CLIENT_SECRET, and REVUE_SLACK_REDIRECT_URL to an HTTPS page that forwards the browser to http://localhost:47392/callback with the same query.
• When the browser can't get back to Revue, users can paste the address it ended on into the sign-in page, under the box that waits for the browser.
• Settings → Accounts → Slack → Use your own Slack app lets each user override the built-in app (client ID, secret, redirect URL), and a pasted user token (xoxp-…) works without any app of Revue's.

A secret built into a desktop app can be extracted from the binary, as with any native OAuth client. It identifies the app but grants nothing without a user's consent. If it leaks, rotate it in the service's console and publish a new build.

• tr!("Sign out") for plain text.
• trf!("Sign out {name}?", name = login) with named placeholders. A translation may reorder them.
• trn!("{n} file", "{n} files", count) for counts.
• tr_mark!("Appearance") marks text in tables and constants; it's translated where it's shown, with i18n::tr.
• Plurals are an object of forms keyed by the English plural. Czech uses one for 1, few for 2 to 4 and other for the rest.
• The "//" entry in a language file holds notes and the glossary for translators.

1. Add assets/i18n/<code>.json.
2. In src/i18n.rs, add a variant to Language and Lang, with its plural rule in plural.
3. Add its code to Lang::from_code.

• Linux: built in rust:1-bookworm, so it runs on glibc 2.36 or newer (Debian 12, Ubuntu 22.04, and later).
• Windows: cross-compiled with cargo-xwin. GPUI's HLSL shaders come precompiled (regenerate them with task windows-shaders).
• macOS: cross-compiled as one universal binary (Apple Silicon and Intel) with cargo-zigbuild, packaged as Revue.app. Its Metal shaders are compiled when it runs.
• rust-toolchain.toml pins the toolchain the build containers use.
• A release from Forgejo pushes its commit and tag with the repository secret RELEASE_TOKEN, a personal access token (scope write:repository) of someone who may push to main.