rustc Start in the Compiler’s Own Directory, With a Configuration the Compiler WritesStatus: Accepted
Date: October 6, 2026 (#480)
Answers: #480,
a project’s .cargo/config.toml runs any program at nikaia build, even for
a pure Nikaia project
Related:
ADR-002 (the CLI wraps Cargo);
ADR-321 D15 (nothing lets foreign code run while a program is built);
ADR-324 D1 (there is no build script);
ADR-305 (the Rust floor);
Part III 13.2b (the cache)
Which configuration do the tools Nikaia drives - Cargo, rustc, the linker -
obey while a Nikaia program is built?
nikaia build writes a Cargo project and starts cargo, which starts rustc
and the linker. Cargo reads .cargo/config.toml from the directory it is
started in and from every directory above it, and merges them; rustup chooses
a toolchain from rust-toolchain.toml the same way. The compiler started
Cargo in the user’s working directory, usually the project. So a file in a
project - one no Nikaia document mentions, and which nikaia.toml and the
.nika sources do not show - could name the program Cargo runs as its linker
or as a wrapper around rustc, and a pure Nikaia project could run a program
of its own while it was built, past ADR-321 D15 and
ADR-324 D1.
| Tool | Configuration of the tools below |
|---|---|
| Cargo itself | read from the working directory upward, plus CARGO_HOME; a project’s file applies to whoever builds it |
| VS Code, rust-analyzer | the same files, which is why opening a folder asks for Workspace Trust |
| Bazel, Nix | the build runs in a directory of the tool’s own, with inputs it declared |
From memory, not checked against a version. What transfers: the build in a place of the tool’s own, with a configuration the tool writes.
| Option | Why it lost |
|---|---|
Start Cargo under <project>/target/… with a generated file |
Cargo reads every directory above too and merges them; a generated file overrides only the keys it sets |
A CARGO_HOME of the compiler’s own |
hides the user’s own configuration and credentials - a mirror, a proxy, a registry token - which no project wrote |
Refuse a project that has .cargo/config.toml |
also refuses a directory above the project that belongs to the user, and still leaves the project’s file active for cargo started by hand |
Override each key that names a program with --config |
a list that is never complete and ages with every Cargo release |
rustc and every tool rustup starts are started in a directory of the compiler’s own, outside the project.The directory lies under the user’s cache directory (Part III 13.2b), never inside the project’s tree, so no file of the project is on the path the tools search. Where Cargo writes its results is named explicitly, as it is today, so the cache and its speed are unchanged.
nikaia.toml.nikaia.toml is the one source; a .cargo/config.toml the compiler needs is
generated beside the generated project, from data the compiler has read and
checked. A project carries no configuration for the tools below.
CARGO_HOME’s configuration, the environment, and the toolchain the user’s
rustup chooses outside the project hold as before: they are the user’s, and a
cloned project cannot write them. A rust-toolchain.toml or
.cargo/config.toml in the project is not read, because nothing is started
where it lies.
nikaia.toml and its sources.std’s fixed set.CARGO_HOME.rustc alone, without Cargo, against
the prebuilt std: a measurement of its own.nikaia.toml.