rsconstruct 0.9.146

Rust based fast build system
# Tool Lock (`rsconstruct.lock`)

`rsconstruct.toml` names the tools a project builds with by bare name: each
processor's tools, and the packages under `[dependencies]`. A bare name says
*which* tool, not *which release*, so on its own every CI runner would install
whatever release was newest the day it ran. `rsconstruct.lock` records the
release. It is to tools what `Cargo.lock` is to crates and `uv.lock` to Python
packages: generated by a command, committed next to `rsconstruct.toml`, and
installed from exactly.

The file is named after the tool that reads it. Commit it; do not edit it by
hand.

## What it locks

| Section | Installed by | Into | Pinned as |
|---------|--------------|------|-----------|
| `[cargo]` | `cargo install --locked --root` | the project ([below]#where-tools-are-installed) | `name@version` |
| `[pip]` | `pip` / `uv pip install` | the active Python environment | `name==version` (PEP 503-normalized keys) |
| `[npm]` | `npm install --global --prefix` | the project | `name@version` |
| `[gem]` | `gem install --install-dir` | the project | `name:version` |
| `[binary.<name>]` | the `binary` install method | the project; a `.deb` onto the machine | exact asset URL plus SHA-256 |

Entries come from two places:

- **Processor tools** of the enabled processors, by the install method `tool
  install` uses for them (the first one in the tool registry). A stanza with
  `enabled = false` contributes nothing: it exists to keep its config while
  its tool is absent, so `tool lock` drops its tool from the lock and `tool
  install`, `tool check` and `doctor` do not ask for it.
- **`[dependencies]`** entries for `cargo`, `pip`, `npm` and `gem`. An entry
  that already carries its own constraint (`ruff>=0.5`, `pkg@1.0`) is left as
  written and not locked.

These are not locked:

- **Packages a project lockfile already pins.** A processor tool that `uv.lock`
  or `package-lock.json` pins is installed from that file by `install-deps`,
  and a second pin here could only disagree with it. This holds only while
  that file is the configured source (`pip_source = "uv-lock"`, `npm_source =
  "package-lock"`, the defaults): with `pip_source = "pyproject"` or
  `npm_source = "package-json"` a lockfile on disk pins nothing, so the tool is
  locked here.
- **System packages** (`apt`, `dnf`, `pacman`, `brew`, `snap`) come with the OS
  image.
- **The Chrome `.deb`.** Its vendor URL always serves the current build, so
  there is no release to record.

A `binary` entry records the URL of one specific release asset (a
`releases/latest` recipe is resolved to the tag that was latest when the entry
was written) and the SHA-256 of the download. It also records how to recognize
the installed result: the SHA-256 of the executable, or, for a `.deb`, the
package name and version dpkg reports. Recipes whose URL is fixed in
rsconstruct's source (zola, checkpatch.pl, …) are recorded at that URL.

## Who reads it

| Command | Outside CI | In CI (`CI=true`) |
|---------|------------|-------------------|
| `tool lock` | add missing entries, drop unused ones, keep the rest | same (but run it outside CI) |
| `tool lock --upgrade` | re-resolve every entry to its latest release | same |
| `tool lock --upgrade <name>...` | like `tool lock`, plus re-resolve only the named tools; an unknown name is an error | same |
| `tool install`, `tool install-deps` | fill in missing entries, then bring the project's tools to their locked versions | the lock must match exactly, then the same |
| `tool check` | the lock must match and every locked tool must be installed at its version | same |
| `build` | not consulted (`--verify-tool-versions` runs the build check) | runs the build check before building |

"Match" means: every entry the project needs is present and no entry is
unused.

**The build check** is narrower than `tool check`. It runs after discovery and
the `-p`/`-x` selection, over the processors that have products in the build
graph — the same set whose tools the missing-tool preflight demands. For those
processors (and the `[dependencies]` packages) the lock must have an entry and
the installed tool must be the locked version; the lock must also exist.
Entries for other tools are not judged: a
disabled stanza, a processor excluded with `-x`, or one that matched no file in
this repo needs no tool installed, and an entry the selection does not need may
still be needed by a processor outside it. `tool check` is the exact,
whole-project test — a lock entry nothing needs any more fails it, not the
build.

**Every project runs its locked versions, in CI and on your machine alike.**
Crates, npm packages, gems and release binaries are installed into the project
itself (see [below](#where-tools-are-installed)), so a project at one version
of a tool and a project at another never get in each other's way, and an
install can always bring a project to exactly its lock. Python packages follow
the same rule inside the project's own virtualenv: when `python3` is a venv
under the project directory (or in CI), one at another version is reinstalled
at the locked one. A Python environment shared with other work, and `.deb`
binaries, which belong to the machine, are replaced only in CI; outside it a
mismatch there is reported as a warning naming both versions, and `tool check`
fails on it.

**In CI a lock problem is an error, never a rewrite.** A lock written on a
runner would never be committed, so each runner would resolve its own versions,
which is exactly the drift the lock exists to stop. The error lists what does
not match and tells you to run `rsconstruct tool lock` outside CI and commit the
result.

Moving entries to newer releases is `rsconstruct tool lock --upgrade` and
nothing else; give it names (`--upgrade ruff cargo-deny`) to move only those,
the way `cargo update -p` does. A name selects the tool under every install
method the project locks it for. A normal build, install or `tool lock` never moves an entry
that is already locked.

## Where tools are installed

A tool installed onto the machine is shared by every project there, so two
projects that lock different releases of it cannot both be right — whichever
was installed last wins for both, silently. rsconstruct therefore installs the
tools it gets from a registry into the project, the way uv installs a
project's Python packages into its `.venv`:

```text
.rsconstruct/tools/pkgs/<method>/<name>@<version>/   one install per package
.rsconstruct/tools/bin/<exe>                         the executables, first on PATH
```

At startup, in a project directory, rsconstruct puts `.rsconstruct/tools/bin`
first on `PATH` for itself and every tool it runs, so the project's copy wins
over anything installed elsewhere. `cargo <subcommand>` processors (`cargo
deny`, `cargo nextest`) run the project's `cargo-<subcommand>` directly,
because cargo itself looks in `$CARGO_HOME/bin` before `PATH`. A gem's entry in
`bin/` is a small launcher that runs it with `GEM_HOME` and `GEM_PATH` naming
only its own package, because rubygems activates the newest version of a gem
found anywhere on its path.

`tool install` and `tool install-deps` keep the directory in step with the
lock: they add what is missing, replace what moved, remove what the lock no
longer names, and print each package with `✓` (in place), `+` (added) or `-`
(removed). `cache clear` and `clean all` leave `.rsconstruct/tools` alone; it
holds tools, not build state.

**The tool store.** Each version is installed once per machine, into the store
— `$RSCONSTRUCT_TOOL_STORE`, else `$XDG_CACHE_HOME/rsconstruct/tools`, else
`~/.cache/rsconstruct/tools` — and every project that locks it gets a
hard-linked copy: no second download or compile, and no second copy on disk.
Where a hard link is impossible (the store on another filesystem) the files are
copied. Store files are read-only, since a hard link shares the file with every
other project.

What stays on the machine: system packages (`apt` and friends) and the `.deb`
binary recipes, which the OS package manager owns, and Python packages, which
go into the active environment — the project's virtualenv, set up before
rsconstruct runs. `tool install <name>` and `tool install --all` are machine
installs too: they install a named tool, or the whole registry, for the
machine, and do not touch any project's tool directory.

## rsconstruct itself is not locked

The fleet's `scripts/ci-install-tools.sh` (run by `ci.yml`) downloads the
latest rsconstruct release. Only the last few releases stay published, so a
pinned release would vanish from under CI, and pinning would also mean a
fleet-wide lock bump for every release. Locks written before 2026-10-26 carry
an `[rsconstruct]` table naming the release `tool lock` ran as; it is still
accepted, so those locks keep parsing, but it is ignored, and the next `tool
lock` drops it (and says so).

## Migrating from `.tools.versions`

`rsconstruct.lock` replaces `.tools.versions`. The old file recorded
machine-local tool paths and `--version` output, so it cannot be converted.
While one exists, `tool lock`, `tool install`, `tool install-deps`, `tool check`
and CI builds refuse to run: delete it and run `rsconstruct tool lock`.