Set up QuickRust: instructions for coding agents

QuickRust is a drop-in replacement for cargo: the same commands and flags, faster builds, and one central cache instead of target/. The programs it builds behave exactly the same.

Ask the user before sudo, before qrust setup edits their shell startup files, or before editing files they did not ask about. If a step fails, stop and report the command and its output.

1. Detect

Platform: uname -sm, or $env:PROCESSOR_ARCHITECTURE on Windows. Supported: macOS arm64 and x86_64, Linux x86_64 and arm64 (static builds, any distribution), Windows x86_64 (tested less than macOS and Linux).
Installed already: if qrust --version works, go to 3.
The project: a Cargo.toml at its root, a package or a workspace. A rust-toolchain.toml (or rust-toolchain) names its toolchain; QuickRust installs it on the first build. rustup is not needed.

2. Install

One of these, then check qrust --version:

System	Install
macOS, Linux with Homebrew	`brew install machinefabric/tap/quickrust`
Debian, Ubuntu (amd64, arm64)	apt, below
Fedora, RHEL (x86_64, aarch64)	dnf, below
Windows	PowerShell, below
any, with a recent stable Rust	from source, below

# apt
curl -fsSL https://release.machinefabric.com/packages/keys/repo-signing-prod.asc \
  | sudo gpg --dearmor -o /usr/share/keyrings/machinefabric.gpg
echo "deb [signed-by=/usr/share/keyrings/machinefabric.gpg] https://release.machinefabric.com/packages/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/machinefabric.list
sudo apt update && sudo apt install quickrust

# dnf
sudo tee /etc/yum.repos.d/machinefabric.repo >/dev/null <<'EOF'
[machinefabric]
name=MachineFabric
baseurl=https://release.machinefabric.com/packages/rpm/$basearch
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://release.machinefabric.com/packages/keys/repo-signing-prod.asc
EOF
sudo dnf install quickrust

# Windows: latest release from the manifest, digest checked, then set up from the archive
$ProgressPreference = 'SilentlyContinue'   # Windows PowerShell 5.1's progress bar slows the download
$manifest = Invoke-RestMethod https://release.machinefabric.com/quickrust/manifest
$version = $manifest.channels.release.latestVersion
$archive = $manifest.channels.release.versions.$version.platforms.'windows-x86_64'.installers[0]
Invoke-WebRequest $archive.path -OutFile $archive.name -UseBasicParsing
if ((Get-FileHash $archive.name -Algorithm SHA256).Hash -ne $archive.sha256) { throw "the archive does not match the manifest's digest" }
Expand-Archive $archive.name -DestinationPath .
.\quickrust\qrust.exe setup

# from source
git clone https://github.com/machinefabric/quickrust
cd quickrust && cargo build --release --locked
target/release/qrust setup

The same manifest (https://release.machinefabric.com/quickrust/manifest) lists a .tar.gz with its sha256 for darwin-arm64, darwin-x86_64, linux-x86_64 and linux-arm64; it holds quickrust/qrust, and quickrust/qrust setup installs it.

3. Set up

Run qrust setup; a package manager’s install needs it too. From an archive or a source build it copies qrust into ~/.qrust/bin; from Homebrew, apt or dnf it links ~/.qrust/bin to the package’s qrust, which that package manager then upgrades. It installs stable Rust and puts ~/.qrust/bin first on PATH through the shell startup files (on Windows, the user’s PATH), so cargo, rustc, rustfmt, cargo-clippy and rust-analyzer are QuickRust’s. rustup and ~/.cargo are left alone.

To leave the startup files alone (CI, containers, dotfiles): qrust setup --no-modify-path, and put ~/.qrust/bin first on PATH yourself.
In the current shell: . "$HOME/.qrust/env"; in PowerShell, $env:Path = "$HOME\.qrust\bin;$env:Path".
Check: qrust doctor ends with OK. If it says cargo on PATH is not QuickRust’s, another directory (often ~/.cargo/bin) comes before ~/.qrust/bin.
To try it without making it cargo: qrust setup --no-modify-path, then qrust build, qrust test and so on in place of cargo.

4. Build

Use cargo as before: cargo build, cargo test, cargo run, cargo clippy. Nothing in Cargo.toml, Cargo.lock or .cargo/config.toml changes.

Output: run from a tool or a pipe, as an agent runs it, cargo prints Cargo’s own output unchanged: every warning and error, in full. QuickRust’s summary (errors in full, warnings counted; qrust warnings [--crate C] [--lint L], qrust errors and qrust log to read them again) applies only to builds run in a terminal. --message-format=json passes through untouched.
There is no target/. qrust path prints the build directory; qrust path bin <name> [--release] a binary. In scripts, replace target/release/app with "$(qrust path bin app --release)". Under Cargo, CARGO_TARGET_DIR and cargo metadata’s target_directory give it.
A fixed build directory: --target-dir or CARGO_TARGET_DIR. build.target-dir in .cargo/config.toml is overridden.
A target/ already in the project is never used or touched: it can be deleted. cargo clean empties QuickRust’s build directory. The members of a workspace share one build directory.
cargo install (or qrust install) builds through QuickRust’s cache and installs into ~/.qrust/bin, not ~/.cargo/bin.
Development builds keep line tables only (backtraces, breakpoints and stepping work), and dependencies get no debug information. To inspect variables, set debug = true under [profile.dev] in Cargo.toml; QuickRust then leaves both alone.
Editors: after setup, the rust-analyzer, cargo and rustfmt on PATH are QuickRust’s. An editor started before setup, or a GUI app that does not read the shell’s startup files (common on macOS), still has the old PATH: restart it from a new shell.

5. CI (optional)

Pin a version and check its archive against the manifest’s sha256:

version=<version>
curl -fLO "https://release.machinefabric.com/quickrust/release/$version/qrust-$version-linux-x86_64.tar.gz"
echo "<sha256>  qrust-$version-linux-x86_64.tar.gz" | sha256sum -c
tar xzf "qrust-$version-linux-x86_64.tar.gz"
quickrust/qrust setup --no-modify-path
echo "$HOME/.qrust/bin" >> "$GITHUB_PATH"   # elsewhere: export PATH="$HOME/.qrust/bin:$PATH"

Cache ~/.qrust/toolchains, keyed by the toolchain file. QRUST_REPORT="$RUNNER_TEMP/qrust/{session}.json" cargo build keeps a report of each build; budgets that fail a slower build: run QuickRust in CI.

6. When a build fails

qrust upstream build runs the toolchain’s own Cargo with nothing added. If it fails too, the problem is not QuickRust’s.
QRUST_MODE=compat cargo build builds exactly what Cargo builds. If it passes, a fast-mode setting is the cause: build exactly like Cargo.
qrust analyze rebuilds: why each crate rebuilt.
Exit status: Cargo’s own whenever Cargo ran. 2 means QuickRust could not run the command (no usable toolchain, invalid configuration or arguments); its FAIL line says why.
Otherwise report to the user with the full output. Community: https://discord.gg/Q7ga2graWW.

Reference

All docs, indexed: https://machinefabric.com/quickrust/llms.txt
Commands · configuration · environment · fast mode · compatibility · platforms
Build outputs without target/ · warnings and errors · adopt gradually