# 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 --root` | the project ([below](#where-tools-are-installed)) | `name@version` |
| `[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 one in the slot of the tool's preferred
target; see [Install targets](commands.md#install-targets)). 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`, `npm` and `gem`. An entry that
already carries its own constraint (`pkg@1.0`, `rake:13.0`) is left as
written and not locked.
These are not locked:
- **Python packages.** A project's Python packages, the Python tools its
processors run included, are pinned by `uv.lock` and installed by `uv sync`
into the repo's `.venv` (see [Python packages live in the repo's
`.venv`](configuration.md#python-packages-live-in-the-repos-venv-owned-by-uv)).
A Python tool `uv.lock` does not pin is an error, not an entry here.
- **Packages `package-lock.json` already pins.** A processor tool it pins is
installed from that file by `tool install project`, and a second pin here
could only disagree with it. This holds only while that file is the
configured source (`npm_source = "package-lock"`, the default): with
`npm_source = "package-json"` it 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 project`, `tool install machine` | 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 repo's `.venv`, which `uv sync` brings to
exactly `uv.lock`. `.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 project` keeps 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.
A release binary is usually one executable. Some need the directories beside
it: protoc reads the well-known `.proto` files from its `include/`, qpdf loads
its libraries from its `lib/`, node's `npm` lives in its `lib/node_modules/`,
and lilypond runs the Guile, Ghostscript and Python bundled in its tree. Their
release (a zip or a tarball, ffmpeg's too) is unpacked whole into the
package's directory and every executable in its `bin/` is linked: such a
recipe installs only into a project, never onto the machine. A tool a
project's own scripts run, like lilypond or ffmpeg, is named in the generic
processor's `required_tools`, which is what makes the project lock it.
`uv` and `node` are the installers `tool install project` runs. Every project
with Python dependencies locks uv, and every project with Node packages
(package.json or `[dependencies] npm`) locks node; each is linked in ahead of
the `uv sync` or npm steps that need it.
The language toolchains are pinned by their own managers' files rather than
by `rsconstruct.lock`: `.python-version` names the Python that `uv sync`
builds the `.venv` with (uv downloads that exact build where the machine
lacks it), and `rust-toolchain.toml` names the rustc, clippy and rustfmt that
rustup runs for `cargo`. That is why the machine install for `cargo` and
`rustc` is rustup, whose proxies read the file, and never a distro package
that would ignore it.
What stays on the machine: system packages (`apt` and friends) and the `.deb`
binary recipes, which the OS package manager owns. They come from `tool install
machine`, which never touches any project's tool directory; `tool install
machine <name>` and `tool install machine --all` install a named tool, or the
whole registry, for the machine.
## 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 check`
and CI builds refuse to run: delete it and run `rsconstruct tool lock`.