# 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
| `[cargo]` | `cargo install --locked` | `name@version` |
| `[pip]` | `pip` / `uv pip install` | `name==version` (PEP 503-normalized keys) |
| `[npm]` | `npm install -g` | `name@version` |
| `[gem]` | `gem install` | `name:version` |
| `[binary.<name>]` | the `binary` install method | 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
| `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 install missing tools at their locked versions | the lock must match exactly; a tool installed at a different version is reinstalled at the locked one |
| `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.
**Outside CI, rsconstruct never replaces a tool you already have.** It installs
what is missing at the locked version, and `tool check` reports drift, but a
tool already on your machine at another version is left alone.
**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.
## 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`.