Cargo and Package Management

Reproducible Builds

A reproducible build guarantees that compiling the same source commit with the same configuration produces predictable, verifiable build behavior—and with path remapping and pinned toolchains, even bit-for-bit identical binaries across different developer machines and CI servers.

Ingredients of a Reproducible Rust Build:
  1. Pinned Toolchain       (`rust-toolchain.toml` -> exact `rustc` version)
  2. Pinned Dependencies    (`Cargo.lock` + `cargo build --locked`)
  3. Hermetic Source Cache  (`cargo vendor` + `--frozen` / `--offline`)
  4. Path Normalization     (`--remap-path-prefix` strips `/Users/alice/...`)

1. Pinning the Exact Compiler Toolchain (rust-toolchain.toml)

Placing a rust-toolchain.toml file at the root of your repository instructs rustup to automatically download and use that exact Rust compiler release, components, and target triples whenever anyone runs cargo inside the repository:

# File: rust-toolchain.toml
[toolchain]
channel = "1.85.0"
components = ["rustfmt", "clippy"]
targets = ["x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu"]
profile = "minimal"

2. Enforcing Cargo.lock with --locked and --frozen

Running bare cargo build or cargo test in CI is dangerous because Cargo will silently update or regenerate Cargo.lock if Cargo.toml changed without a matching lockfile update. Always pass --locked (or --frozen in air-gapped environments):

Flag Network Access Allowed? Cargo.lock Updates Allowed? Recommended Environment
(None) Yes Yes (updates silently if needed) Local interactive editing
--locked Yes (downloads cached crates) No (errors if Cargo.lock is stale or missing) Standard CI / CD pipelines, cargo install --locked
--offline No (uses local cache only) Yes (if cache satisfies) Local development without internet
--frozen No No Air-gapped release builders and vendored builds

3. Vendoring Dependencies for Hermetic Offline Builds (cargo vendor)

For high-assurance or air-gapped production builds that must not depend on crates.io availability at build time, cargo vendor unpacks the exact source code of every dependency in Cargo.lock into a local vendor/ directory:

# Unpack all dependencies into ./vendor/ and print .cargo/config.toml snippet
cargo vendor vendor/

Adding the generated source replacement to .cargo/config.toml allows cargo build --frozen to compile the entire project with zero network access:

# File: .cargo/config.toml
[source.crates-io]
replace-with = "vendored-sources"

[source.vendored-sources]
directory = "vendor"

4. Stripping Host Paths for Bit-for-Bit Identical Binaries

Even with the exact same rustc version and Cargo.lock, compiling a binary in /Users/alice/app and /home/ci/app embeds different absolute file paths inside panic location strings (file!()) and DWARF debug symbols. Passing --remap-path-prefix via RUSTFLAGS normalizes absolute paths so both machines produce identical binary hashes:

RUSTFLAGS="--remap-path-prefix=$(pwd)=/workspace" cargo build --release --locked

fn main() {
    // `file!()` expands to a relative path within the package (e.g., "src/main.rs")
    // while dependency panic strings can be normalized via `--remap-path-prefix`.
    println!("Current source file path is relative: {}", !file!().starts_with('/'));
}

Current source file path is relative: true