mbx-cache-rustc 0.7.1

mbx internals: conservative rustc action analysis and key construction. No API stability -- use the mbx CLI or mbx-cache-protocol.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

<p align="center">
  <img src="docs/public/logo.svg" alt="Mr Boxington, a friendly cache box wearing a monocle and bow tie" width="220">
</p>

<h1 align="center">mr boxington</h1>

<p align="center">
  <strong>fix <code>target/</code></strong><br>
  Put mbx in front of any cargo command. One cache warms every worktree and CI run, and prunes itself to a size budget.
</p>

<p align="center">
  <a href="https://mr-boxington.jdx.dev">Documentation</a>
  ·
  <a href="https://github.com/jdx/mr-boxington/releases">Releases</a>
</p>

`mbx` wraps ordinary Cargo commands with a content-addressed rustc cache. Cargo
still resolves dependencies, plans builds, and links outputs; mbx restores
supported compilations it has seen before. There is nothing to configure and
nothing to install into Cargo: put `mbx` in front of the command you already
run.

```sh
mbx build                  # cargo build, with caching
mbx test --all-features    # cargo test --all-features, with caching
mbx clippy --workspace     # cargo clippy --workspace, with caching
mbx tui                    # watch every build's cache activity live
mbx gc --dry-run           # preview what cleanup would reclaim
```

The first build prints what it set up — where the cache lives, the budget it
is pruned to, and when a `target/` directory becomes collectable.

## Why mbx?

- **Warm every worktree.** Cache keys contain no checkout-specific absolute
  paths, so building one checkout warms its siblings automatically without
  sharing a Cargo target lock.
- **Bounded disk, without a chore.** The action store prunes itself to a
  budget, and managed `target/` directories are deleted when their checkout is
  gone, unused for 30 days, or over their share of the disk. Both budgets
  scale with the disk rather than assuming every machine is the same size.
- **Warm CI safely.** GitHub Actions cache can warm fork pull requests from a
  cache built on `main`, while a self-hosted remote can serve trusted runners
  and teammates. Pull requests never publish remote objects.
- **See the whole result.** mbx reports hits, misses, actions it could not look
  up, and actions it deliberately bypassed. A high hit rate cannot hide work
  that never entered the cache. `mbx tui` shows the same outcomes as they
  happen, for every build on the machine at once.

## Install

With [mise](https://mise.jdx.dev):

```sh
mise use -g mr-boxington
```

With Cargo:

```sh
cargo install mbx
```

Or install the latest Linux x86-64 release archive:

```sh
mkdir -p ~/.local/bin
archive=mbx-x86_64-unknown-linux-musl.tar.gz
release=https://github.com/jdx/mr-boxington/releases/latest/download
curl -fsSLO "$release/$archive"
curl -fsSLO "$release/SHA256SUMS"
grep "  $archive$" SHA256SUMS | sha256sum --check --strict -
tar -xzf "$archive" -C ~/.local/bin
```

Release archives also cover Linux ARM64, Apple Silicon, and Windows x86-64 and
ARM64.
Every release includes `SHA256SUMS`.

[See all installation options →](https://mr-boxington.jdx.dev/getting-started)

## Automatic pruning

Collection runs after a build, at most once an hour, and needs no
configuration. Both size budgets default to a share of the disk holding the
cache — 5% for the action store and 10% for managed `target/` directories,
each from its floor (5 GiB and 10 GiB) up to 100 GiB and rounded down to a
whole 5 GiB — and a managed directory is also collected once its checkout is
gone or it has sat unused for 30 days.

mbx keeps a running total of what that has been worth and reports one line of
it after a build:

```text
mbx[savings]: 41.7 GiB of target/ had outlived its checkouts. it has been dealt with.
```

The line is drawn from a pool, so it does not repeat itself. `savings =
"plain"` states the same facts without the joke, and `savings = "off"` keeps
the totals without printing anything (`MBX_SAVINGS` from the environment). Inspect or collect the store explicitly with:

```sh
mbx cache stats
mbx cache projects
mbx cache largest --limit 10
mbx cache verify
mbx cache remove /path/to/workspace
mbx gc
mbx gc --max-size 3GB
mbx gc --dry-run
```

For a checkout without an existing `target/`, managed target directories are
enabled automatically:

```sh
mbx build
```

mbx places the target directory under its cache root and leaves `target` as a
symlink, so familiar paths still work — and the outputs of a checkout that is
deleted get collected rather than stranded.

For an existing real `target/`, an interactive `mbx` asks before removing the
old outputs and replacing the directory with a managed link. The safe default
is to keep it. Non-interactive runs never remove it. Set `MBX_TARGET_VIEWS=0`
to disable managed placement and the prompt.

[Learn about managed targets →](https://mr-boxington.jdx.dev/managed-targets)

## Worktree and CI warming

An equivalent rustc action keys the same across checkout paths. One worktree's
dependency build can therefore warm another while every checkout keeps its own
target directory.

For GitHub-hosted CI, [`jdx/mr-boxington-action`](https://github.com/jdx/mr-boxington-action)
can install mbx and use GitHub Actions cache, saving only from the default
branch and restoring in pull requests. Trusted environments can switch the
same action to a compatible remote such as the self-hostable
[cache server](https://mr-boxington.jdx.dev/cache-server).

[Configure GitHub Actions →](https://mr-boxington.jdx.dev/github-actions)

## How it works

An `mbx` Cargo command starts an in-process cache agent, points Cargo at a rustc shim with
`RUSTC_WRAPPER`, and exits the agent with the build—there is no daemon. The shim
derives an action key, restores cached outputs when possible, or runs the real
compiler and publishes a successful result.

Anything mbx cannot model exactly bypasses the cache. Native linking is not
cached; built-in WebAssembly targets with self-contained linkers are the narrow
exception because their linker, CRT, and libc inputs ship in the Rust toolchain.
Incremental compilations bypass the cache. Correctness comes before hit rate.

[Read the architecture and limits →](https://mr-boxington.jdx.dev/how-it-works)

## Documentation

- [Get started](https://mr-boxington.jdx.dev/getting-started)
- [Configuration](https://mr-boxington.jdx.dev/configuration)
- [GitHub Actions](https://mr-boxington.jdx.dev/github-actions)
- [Remote cache](https://mr-boxington.jdx.dev/remote-cache)
- [Protocol compatibility](https://mr-boxington.jdx.dev/protocol-compatibility)
- [Cache results](https://mr-boxington.jdx.dev/cache-results)
- [Watching builds](https://mr-boxington.jdx.dev/tui)
- [CLI reference](https://mr-boxington.jdx.dev/cli)
- [Current limits](https://mr-boxington.jdx.dev/limits)

## License

[MIT](LICENSE)