# 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 |

```sh
# 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
```

```sh
# 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
```

```powershell
# 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
```

```sh
# 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`:

```sh
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](https://machinefabric.com/quickrust/docs/how-to/set-up-ci.html).

## 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](https://machinefabric.com/quickrust/docs/how-to/build-exactly-like-cargo.html).
- `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](https://machinefabric.com/quickrust/docs/reference/commands.html) ·
  [configuration](https://machinefabric.com/quickrust/docs/reference/configuration.html) ·
  [environment](https://machinefabric.com/quickrust/docs/reference/environment.html) ·
  [fast mode](https://machinefabric.com/quickrust/docs/reference/fast-mode.html) ·
  [compatibility](https://machinefabric.com/quickrust/docs/reference/compatibility.html) ·
  [platforms](https://machinefabric.com/quickrust/docs/reference/platforms.html)
- [Build outputs without target/](https://machinefabric.com/quickrust/docs/how-to/find-build-outputs.html) ·
  [warnings and errors](https://machinefabric.com/quickrust/docs/how-to/read-warnings-and-errors.html) ·
  [adopt gradually](https://machinefabric.com/quickrust/docs/how-to/adopt-gradually.html)