rsconstruct 0.9.140

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 | Pinned as |
|---------|--------------|-----------|
| `[rsconstruct]` | the CI workflows | the rsconstruct release CI downloads |
| `[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**, by the install method `tool install` uses for them (the
  first one in the tool registry).
- **`[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.
- **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; pin the running rsconstruct | same |
| `tool lock --upgrade <name>...` | like `tool lock`, plus re-resolve only the named tools (`rsconstruct` names the rsconstruct pin); 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 `tool check` test) | runs the `tool check` test before building |

"Match" means: every entry the project needs is present, no entry is unused,
and there is an `[rsconstruct]` pin. The running rsconstruct is not compared
with the pin: in the fleet the workflow downloads exactly the pinned release,
and rsconstruct's own CI deliberately runs a binary built from the commit under
test, whose version a release commit bumps past any pin.

**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]`

`tool lock` pins the rsconstruct that runs it, and keeps that pin until
`--upgrade`. The CI workflows read this table and download that release, so CI
builds with the rsconstruct you locked with:

```toml
[rsconstruct]
version = "0.9.138"
```

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