Files and directories

QuickRust creates its directories with mode 0700. Paths below use the default home, ~/.qrust; QRUST_HOME moves all of it.

QuickRust’s home

<id> is the first 16 hexadecimal digits of the SHA-256 of the workspace root’s canonical path.

QuickRust’s cache

Everything under ~/.qrust/cache/ can be rebuilt or downloaded again. QuickRust keeps it within cache.max-size and leaves cache.min-free of the disk free (Configuration), removing what was used least recently.

Collection

A collection removes, in this order:

1. whatever nothing can use any more: build directories of workspaces that are gone, drivers of toolchains that are gone, week-old unfinished downloads, month-old memos, leftovers in tmp/;
2. while the cache is above cache.max-size or the disk below cache.min-free: build directories, artifact entries and sources of installed programs, least recently used first, until the cache is under 90% of cache.max-size and the disk has 125% of cache.min-free free;
3. crates and git checkouts downloaded into QuickRust’s Cargo home, removed by Cargo itself (cargo -Zgc clean gc): by Cargo’s usual ages at every collection and, while the bounds are still exceeded, those unused for a month, a week, a day, an hour, 15 minutes in turn. Only while no QuickRust command is running a Cargo (~/.qrust/cargo-runs/). Otherwise they are left for the next collection, which qrust gc and qrust cache status report. Cargo’s clean deletes its records of registries it does not find in the Cargo home, such as the temporary one cargo package builds against, and a running Cargo that holds one of those records stops with an internal error. A command that starts while Cargo’s clean runs waits for it and says so.

A collection counts what it frees itself and does not measure the disk again until it ends, because the disk may not show what it frees. A snapshot (Time Machine’s hourly local snapshots on macOS, btrfs or ZFS snapshots) keeps the blocks of every file older than itself, and what was used least recently always is. What the disk does not show at the end is recorded in usage.json and counted as free, before and after commands and by the next collection, until the disk shows it. That lasts a day at most, the life of a Time Machine local snapshot. After a day, the disk’s own figure counts again.

Never removed: anything used in the last 15 minutes; a build directory a QuickRust command holds or a Cargo holds a lock in; a source an install holds; an artifact entry whose files a build directory in use links. Sizes are blocks allocated; a file with several hard links counts once and is freed with its last link.

qrust cache status shows the last count and recent collections; qrust gc --dry-run lists what a collection would remove.

Toolchain programs inside a toolchain

In a build directory

They go with the rest of the directory (cargo clean).

In a repository

QuickRust writes into a repository only on request.

No target/ directory is created in a project.

Setup

qrust setup writes:

• ~/.qrust/bin/ with qrust, qrust-rustc-wrapper and the program links; it refuses to replace a file there that is not QuickRust’s;
• ~/.qrust/env and ~/.qrust/env.fish;
• one line marked # Added by qrust setup: QuickRust's bin first on PATH in ~/.profile, and in ~/.bash_profile, ~/.bashrc and ~/.zshenv where they exist (~/.zshenv also when zsh is on PATH); ~/.config/fish/conf.d/qrust.fish when ~/.config/fish exists; on Windows, the user’s PATH through PowerShell (none of this with --no-modify-path);
• once, from $CARGO_HOME or ~/.cargo: credentials.toml, and the [registries], [registry], [source], [net] and [http] tables of config.toml, into ~/.qrust/cargo/ (the tables it did not import are listed);
• ~/.qrust/setup.json.

qrust self uninstall --yes removes ~/.qrust and the lines and files above that qrust setup added. rustup and ~/.cargo are never changed.

Retention

Pruning runs on about one command in 32. Prebuilt stamps: at most 32 per workspace. Collection log: the last 200 entries.