Module vault 

The vault: a durable store of Cargo unit groups, addressed by Cargo’s own fingerprint hashes.

A unit group is exactly what Cargo needs to consider one built unit fresh: the 16-hex fingerprint hash file, the serialized Fingerprint JSON, the binary dep-info, and the unit’s artifacts (deps/…, and the build/<anchor>/… tree for build-script units). The vault keeps one directory per generation, where a generation is one toolchain plus one flag environment (the parity key):

{cargo-cache-home}/epicenter/
  store/<parity-key>/
    manifest.json                file list, sizes, canonical stamps
    units/<pkg>-<unit-hash>/     one unit group
      <memo-file>                the authoritative 16-hex hash
      <memo-file>.json           the serialized Fingerprint
      dep-<memo-file>            EncodedDepInfo (mandatory for freshness)
      deps/…  build/…            artifacts, as the profile dir holds them
  build/…                        the shared working dir (a disposable view)

Timestamps are the only lever besides the hash in Cargo’s freshness check, so every file of a unit group carries ONE canonical second (stamp): the ceiling of the group’s metadata output (.rmeta) when it has one — the moment dependents can compile against it — else of its newest file, and always ≥ every dependency’s stamp (harvest clamps the store). Restore never stamps hard links: they share the store’s inode, and a touch on a restored file would rewrite the store itself.

Structs

FileEntry

One stored file.

GenerationInfo

One generation as the vault command shows it.

HarvestReport

What one harvest did.

Manifest

manifest.json of one generation.

RestoreReport

What one restore did.

StoredUnit

One unit as the vault holds it.

Toolchain

The rustc -vV facts that name a vault generation.

UnitEntry

One stored unit group.

VerifyReport

Result of auditing one generation.

Functions

drop_generation

Delete one whole generation under its lock: units, manifest and the lock file. Returns false when a live harvest holds the generation lock.

drop_units

Remove stored unit groups: their directories go, the manifest is pruned, and a generation left without units disappears entirely. Returns how many groups were dropped; groups that could not be removed stay recorded.

generation_names

Names of the store generations (directories under store/).

generation_unit_names

Unit dir names of one generation: the manifest when readable, else the units/ directory (so an orphan generation can still be fully deleted).

generations

Summarize every generation of the vault.

harvest

Store unit groups from a build dir into the vault.

harvest_with

Harvest for a specific toolchain and/or layout (exec with a +toolchain child). The plain harvest uses the default toolchain and derives the layout from cargo --version.

parity_key

One vault generation = toolchain + host + flag environment: 1.99.0-b940084d7-x86_64-unknown-linux-gnu-3f9a2c1b.

parity_key_of

Parity key for a rustup selector (exec with a +toolchain child).

restore

Link matching unit groups from the vault into a working dir.

restore_with

Restore for a specific toolchain/layout (exec with a +toolchain or a new-layout child). layout skips units stored in the other build-dir layout; the plain restore accepts every stored unit.

store_root

<build>/../store — the vault lives beside the shared build dir, so cargo clean can never touch it.

stored_unit_rustc

The rustc identity recorded in a stored unit’s Fingerprint JSON.

stored_units

Every stored unit across all generations, manifest-driven.

sweep_store_debris

Clean the debris a crash or a manual deletion leaves in the store root: .lock-* files whose generation is gone, and empty manifest-less generation directories. Existing generations and held locks are kept.

toolchain

Parse rustc -vV (first line + host:) for the default toolchain.

toolchain_install_time

Install time of the active toolchain: the real rustc binary in the sysroot (falling back to the sysroot directory). This is the reference for “was this unit built by the installed toolchain?”.

toolchain_install_time_of

Install time of selector’s toolchain (same shape as the default).

toolchain_of

Parse rustc -vV for a rustup selector (nightly, 1.98.0, …; None = the default toolchain). exec uses this for cargo +nightly.

units_dir

store/<parity-key>/units.

verify

Audit every generation in the vault: every manifest file present with the recorded size, the canonical stamp, and — for memo files — the recorded hash content; plus a count of unit groups the manifest doesn’t know.