# QuickRust

> Cargo, faster: nothing to configure, one cache that minds your disk, and answers about where the time went.

## For agents

- [Set up QuickRust: instructions for coding agents](https://machinefabric.com/quickrust/agents.md): How an AI coding agent installs QuickRust on macOS, Linux or Windows, makes it the project's cargo, and works with its build output.

## Start

- [Overview](https://machinefabric.com/quickrust/docs/index.html): QuickRust is a drop-in replacement for the cargo command that makes Rust builds faster, manages the Rust toolchains itself, and records every build so that it can explain where the time and the disk space went.

## Tutorials

- [Your first build with QuickRust](https://machinefabric.com/quickrust/docs/tutorials/first-build.html): In this tutorial we will create a small Rust program, build and run it through QuickRust, break it and mend it, give it a dependency and a test. Along the way we will meet QuickRust's build output, the build directory it keeps for every project, its record of every warning, and its cache.
- [Finding where a build's time goes](https://machinefabric.com/quickrust/docs/tutorials/where-the-time-goes.html): In this tutorial we will build a small program that uses serde, then ask QuickRust where the build spent its time: which crates the build had to wait for, what the procedural macros and build scripts cost, and why a rebuild compiled what it did. At the end we will compare two builds and write a report we can open in a browser.

## How-to guides

- [How to install, update and uninstall QuickRust](https://machinefabric.com/quickrust/docs/how-to/install.html): This guide shows you how to put QuickRust on a machine, keep it current, check that it works, and remove it again.
- [How to try QuickRust before making it your cargo](https://machinefabric.com/quickrust/docs/how-to/adopt-gradually.html): This guide shows you how to adopt QuickRust in stages, each one reversible, and how to go back to plain Cargo.
- [How to choose and manage toolchains](https://machinefabric.com/quickrust/docs/how-to/choose-a-toolchain.html): This guide shows you how to decide which Rust toolchain a build uses, add components and targets to it, use a toolchain you built yourself, and control updates.
- [How to install programs with qrust install](https://machinefabric.com/quickrust/docs/how-to/install-programs.html): This guide shows you how to install Rust programs from crates.io, another registry, a Git repository or a local directory, and how to list, update and remove them.
- [How to find build outputs without target/](https://machinefabric.com/quickrust/docs/how-to/find-build-outputs.html): This guide shows you how to find the binaries and other files a build produced, now that there is no target/ directory in your project, and how to make a script or tool that expects one work.
- [How to see the warnings, errors and full log of a build](https://machinefabric.com/quickrust/docs/how-to/read-warnings-and-errors.html): This guide shows you how to read everything a build printed, after QuickRust has summed it up in a terminal.
- [How to build exactly as Cargo does](https://machinefabric.com/quickrust/docs/how-to/build-exactly-like-cargo.html): This guide shows you how to turn off what QuickRust changes about a build, all of it or one setting at a time, for example to rule QuickRust out while you chase a problem.
- [How to keep QuickRust's cache within your disk](https://machinefabric.com/quickrust/docs/how-to/free-disk-space.html): This guide shows you how to see how much space QuickRust uses, free space now, and set the limits QuickRust keeps to by itself.
- [How to use sccache with QuickRust](https://machinefabric.com/quickrust/docs/how-to/use-sccache.html): This guide shows you how to build with sccache through QuickRust, either with the sccache setup you already have or by letting QuickRust add it, and how to read what it did.
- [How to find out why crates rebuilt](https://machinefabric.com/quickrust/docs/how-to/find-why-crates-rebuilt.html): This guide shows you how to find out why a build compiled crates you expected to be fresh, and what to do about the usual causes.
- [How to measure the effect of a build setting](https://machinefabric.com/quickrust/docs/how-to/measure-a-change.html): This guide shows you how to measure how long your project takes to build in a given situation, and whether a change of build settings (codegen units, debug information, a linker, an environment variable) makes it faster without breaking it.
- [How to review and apply QuickRust's recommendations](https://machinefabric.com/quickrust/docs/how-to/apply-a-recommendation.html): This guide shows you how to see what QuickRust recommends for a build, preview the change each recommendation implies, and apply or undo it.
- [How to export a build report](https://machinefabric.com/quickrust/docs/how-to/export-a-report.html): This guide shows you how to get a build's report out of QuickRust, as JSON for tools or as HTML for people, either as part of the build or afterwards.
- [How to run QuickRust in CI and gate on build time](https://machinefabric.com/quickrust/docs/how-to/set-up-ci.html): This guide shows you how to build with QuickRust in a CI job, keep a report of every build, and fail (or warn) when a change makes the build slower or bigger than you allow.

## Reference

- [Commands](https://machinefabric.com/quickrust/docs/reference/commands.html): Every command the qrust binary accepts, the toolchain programs it stands in for, and the exit statuses it returns.
- [Configuration](https://machinefabric.com/quickrust/docs/reference/configuration.html): QuickRust's own settings, where they are read from, every key with its values and default, and how a command's toolchain is selected.
- [Environment variables](https://machinefabric.com/quickrust/docs/reference/environment.html): The environment variables QuickRust reads, the ones it sets for the Cargo it runs and for the programs Cargo starts, and the ones that are internal to it.
- [Fast mode](https://machinefabric.com/quickrust/docs/reference/fast-mode.html): The build settings QuickRust applies in its default mode = "fast", when each one applies, and the key that turns it off.
- [Output](https://machinefabric.com/quickrust/docs/reference/output.html): What QuickRust writes to a terminal: the line forms, which commands it presents, when Cargo's own output passes through untouched, and what it stores.
- [Files and directories](https://machinefabric.com/quickrust/docs/reference/files.html): Everything QuickRust keeps on disk: its home directory, its cache, what it writes into a repository, and how long records are kept.
- [Budgets](https://machinefabric.com/quickrust/docs/reference/budgets.html): The budget file, its policy and thresholds, the metrics a budget can name, and how a budget is evaluated against a baseline.
- [Benchmarks](https://machinefabric.com/quickrust/docs/reference/benchmarks.html): The scenarios of qrust benchmark, the options and verdicts of qrust experiment, how runs are taken and discarded, and where results are stored.
- [Compatibility with Cargo](https://machinefabric.com/quickrust/docs/reference/compatibility.html): What QuickRust passes to and from Cargo unchanged, what it adds or changes, and how nested invocations, target directories and Cargo's configuration are handled.
- [Platforms](https://machinefabric.com/quickrust/docs/reference/platforms.html): Where QuickRust runs and is tested, what differs between platforms, and what cannot be observed on a stable toolchain.
- [Run report schema, version 1.0](https://machinefabric.com/quickrust/docs/reference/report-schema.html): One JSON document per recorded run, produced by QRUST_REPORT=<path> cargo …, measurement.report, or qrust report --format json.
- [Conformance to the specification](https://machinefabric.com/quickrust/docs/reference/conformance.html): Status of the specification in this implementation. "Tested" names where the behaviour is asserted.

## Explanation

- [How QuickRust works](https://machinefabric.com/quickrust/docs/explanation/architecture.html): QuickRust stands where cargo stands, yet the builds it runs are still made by the toolchain's own Cargo and rustc. This page explains how both can be true: what QuickRust puts around the toolchain, how it sees every compilation without changing how Cargo works, and why it is built this way rather than as a Cargo fork or a plugin.
- [Why QuickRust is fast by default](https://machinefabric.com/quickrust/docs/explanation/fast-by-default.html): QuickRust changes how your project is built without being asked, and the changes go further than a tool that merely runs Cargo might be expected to make. This page explains why it makes them, what limits it puts on itself, how a change earns its place as a default, and what each one costs.
- [About the artifact cache](https://machinefabric.com/quickrust/docs/explanation/artifact-cache.html): Cargo compiles a crate again in every target directory, even when the same version of the same crate, with the same features and flags, was compiled a minute ago for another project or another checkout. QuickRust's artifact cache is the answer to that waste: a unit compiled once is restored instead of compiled again. This page explains what is cached, how a cached result is known to be the right one, and why the cache is shaped as it is.
- [About early cut-off and QuickRust's compiler driver](https://machinefabric.com/quickrust/docs/explanation/early-cutoff.html): Change one line inside a function in a library crate, and Cargo recompiles that crate, then every crate that depends on it, then every binary and test above them, even when nothing those crates can see has changed. Early cut-off is QuickRust's way of stopping that cascade at the crate that was edited. This page explains why the cascade happens, what QuickRust changes in the compiler to stop it, which edits benefit, and what it costs.
- [How QuickRust knows a build is up to date](https://machinefabric.com/quickrust/docs/explanation/up-to-date-checks.html): Run cargo build twice in a terminal through QuickRust and the second time it answers at once:
- [Why QuickRust owns its environment](https://machinefabric.com/quickrust/docs/explanation/owning-the-environment.html): A Rust developer usually installs rustup, which installs toolchains, whose Cargo builds into a target/ directory in every project and keeps downloads in ~/.cargo, none of which ever shrinks on its own. QuickRust replaces all of that around the build engine: it installs and selects toolchains itself, keeps its own Cargo home, builds every workspace into a directory of its own cache, and keeps that cache within a size it chooses. This page explains why it goes that far, what the decisions were, and what they cost.
- [About QuickRust's build output](https://machinefabric.com/quickrust/docs/explanation/build-output.html): In a terminal, a QuickRust build does not look like a Cargo build. There is no Compiling line per crate; there is one status line, errors in full, warnings counted rather than printed, and a one-line verdict. This page explains why QuickRust takes over the terminal, how its way of speaking is designed, and where it deliberately leaves Cargo's output alone.
- [About measuring builds](https://machinefabric.com/quickrust/docs/explanation/measurement.html): QuickRust reports numbers about builds (durations, critical paths, rebuild causes, cache hits, bytes on disk) and lets CI fail on them. Numbers that drive decisions have to be trustworthy, and build measurements are easy to get wrong in quiet ways. This page explains the principles QuickRust measures by and why each one is there.
- [Security and privacy](https://machinefabric.com/quickrust/docs/explanation/security.html): QuickRust sits in front of Cargo and rustc, on every build, with the permissions of the user who runs it. That position deserves scrutiny: what does it add to what a user already trusts, what does it keep about builds, and what can it delete? This page explains the trust model and the reasoning behind each boundary. Where things live on disk is listed in the files reference.