working-with-mbx

mbx を使う

概要

mbx（Mr. Boxington）は、Cargo 用の共有コンパイラーキャッシュで、target/ ディレクトリも自動管理します。Cargo は引き続き依存関係を解決し、ビルドが必要なものを判断します。mbx は一致するコンパイル結果を復元し、それ以外はコンパイラーを実行します。

次の場合にこのスキルを使用します：

• mbx をインストールする、または通常の cargo コマンドで有効にする
• ビルドのキャッシュヒットが少なく、その理由を知りたい
• mbx の結果（ヒット／ミス／バイパス）が想定どおりか判断する
• キャッシュストアや管理対象のターゲットディレクトリからディスク領域を回収する
• CI に mbx のキャッシュを追加する、または sccache／rust-cache から移行する

厳守事項

1. mbx と sccache を併用しないでください。どちらも RUSTC_WRAPPER を介して rustc をラップします。RUSTC_WRAPPER がすでに設定されている場合、mbx はそれに処理を委ねるため、ビルドはキャッシュされません。
2. mbx doctor だけでなく、Cargo のパスで有効化を確認してください。doctor は mise のネイティブな Rust ツールオプションを認識しないため、セットアップに関する警告が出ても、それだけでラップが無効とは限りません。
3. 削除する前に診断してください。ビルドに対して mbx explain を実行します。キャッシュを消すと証拠が失われ、次のビルドはキャッシュなしで実行されます。
4. 新しいターゲットディレクトリを2つ使って再利用を測定してください。同じターゲットで同じコマンドを再実行すると、mbx ではなく Cargo の鮮度チェックを測定することになります。

インストール

mise を使用する場合（推奨）

mise use --global --tool-option mr_boxington=true rust mr-boxington

mise 2026.9.2 以降が必要です。これにより Rust と mbx がインストールされ、mise を介した Cargo のラップが有効になります。mbx setup は不要です。--tool-option は次のツールに適用されるため、rust より前に指定する必要があります。現在のプロジェクトだけで有効にするには、--global を省略します。

プロジェクトで共有するには、両方のツールを mise.toml にコミットします。

[tools]
rust = { version = "stable", mr_boxington = true }
mr-boxington = "latest"

両方のエントリーが必要です。mr_boxington = true を追加する際は、プロジェクトで既存の Rust バージョンを維持してください。mise install を実行してから、ビルドします。

mise を使用しない場合

cargo install mbx --locked
mbx --version

Linux（x86-64／ARM64、glibc および musl）、macOS Apple Silicon、Windows（x86-64／ARM64）用のリリースアーカイブは、SHA256SUMS とともに GitHub Releases で公開されています。references/installation.md を参照してください。

単独でインストールした mbx を通常の cargo で使うには、次のようにします。

mbx setup
mbx setup --status

mbx setup は rust-analyzer のバックグラウンドチェックも設定しますが、mise のネイティブオプションでは設定されません。--global または --local で適用範囲を指定します。--yes を指定すると推奨設定が受け入れられます。

mbx が実際に使われていることを確認する

これは最もよくある失敗です。ビルドは成功しても、何もキャッシュされません。

command -v cargo     # Unix
mbx doctor

Windows では (Get-Command cargo).Path または where.exe cargo を使用します。

cargo の解決先は、次のいずれかである必要があります。

• mise のコマンドラッパー（例：~/.local/share/mise/command-wrappers/bin/cargo）
• mise のシム
• mbx setup による安定版 mbx シム

~/.cargo/bin/cargo を直接呼び出すと、mise の統合が完全にバイパスされます。

非対話型の環境（コーディングエージェント、SSH、デスクトップアプリ）

これらの環境では、対話型ターミナルとは異なる PATH が引き継がれることがよくあります。次のいずれかを使用してください。

mise exec -- cargo build      # explicit, always works

または、そのプロセスの PATH に mise のシムディレクトリを追加します。アプリケーション自身から command -v cargo を実行して確認し、環境を変更した後はアプリを再起動してください。mbx を前置する方法も常に使えます。例：mbx build。

ビルドを実行する

mbx は Cargo の引数を変更せずに渡します。

mbx build
mbx test --workspace --all-features
mbx clippy --workspace --all-targets -- -D warnings
mbx +stable check --workspace          # rustup-style toolchain selection

キャッシュされた作業を再利用するには、ビルド間で同じツールチェーン、機能、プロファイルを使用してください。

結果の読み方

ビルド結果には、次のような概要が表示されます。

mbx[cache]: 139 hits, 8 misses, 4 not looked up, 147 prefetched, 7 bypassed; 312.4 MiB downloaded, 0 B uploaded, 280.1 MiB stored locally

結果	発生した内容
ヒット	mbx が一致するコンパイル結果を復元しました
ミス	キーに一致する結果がありませんでした。コンパイルに成功すると、キャッシュが作成されます
検索対象外	mbx には利用可能な入力予測がなく、先にコンパイルする必要がありました
バイパス	呼び出しは共有キャッシュを使わずに実行されました

件数は、mbx が認識したコンパイラーの処理を示します。出力がすでに最新であるため Cargo がスキップした処理は含まれません。そのため、再実行時にヒット数がゼロになることがあります。

mbx explain --last              # inspect the last recorded build, without running Cargo
mbx explain build --workspace   # run a build with diagnostics (preserves Cargo's exit status)
MBX_SUMMARY=full mbx build      # detailed breakdown
mbx tui                         # watch a build live, one row per compilation

実際のキャッシュ再利用を測定する

mbx build --target-dir target/cache-demo-first
mbx build --target-dir target/cache-demo-second

2 回目のビルドでは、1 回目に記録された処理を復元できます。ビルド出力がまだ 含まれていないディレクトリ名を使用し、後で削除してください。明示的なターゲットは 管理対象外です。必ず実時間も比較してください。「回避したコンパイル時間」は アクションごとの合計であり、短縮された経過時間ではありません。

ヒット率が低い場合のトラブルシューティング

まず mbx explain build --workspace を実行してください。同じ原因をまとめ、 カテゴリごとにガイダンスを表示します。よくある原因は、概ね表示される順に次のとおりです。

• ストアが空です。 初回ビルドにはキーの導出に使える dep-info がないため、 「could not look up」が大半を占める場合があります。
• インクリメンタルビルドが有効です。 MBX_INCREMENTAL=1 の場合、ワークスペースのメンバーは インクリメンタルにコンパイルされ、これらのコンパイルはキャッシュを迂回し、 それらに依存するクレートもキャッシュにヒットしません。
• リンクを記述できませんでした。 ネイティブ実行ファイル、テスト、proc macro は Linux、macOS、Windows でキャッシュされますが、カスタム入力またはモデル化されていない入力を 含むリンクは引き続き実行されます。
• 入力が異なります。 チェックアウト間でツールチェーン、フィーチャーセット、プロファイル、 または RUSTFLAGS が異なると、別のキーとなり、通常のキャッシュミスとして報告されます。
• ビルドスクリプトの出力が異なります。 チェックアウトのパスを出力に埋め込むビルドスクリプトは、 チェックアウト間での再利用を妨げます。
• ビルドが独自の C コンパイラーを選択しました。 CC、HOST_CC、CXX、または HOST_CXX を設定すると、ホストでのコンパイルは mbx の管理対象外になります。
• Rust を更新しました。 コンパイラーはすべてのキーに含まれるため、ツールチェーンの更新により すべての rustc アクションが一度に無効になります。これは想定された動作であり、バグではありません。

コンパイルごとの記録を取得するには、MBX_BYPASS_LOG=bypass.log mbx build を実行します。

想定されるキャッシュ迂回

compiler-query と standard-input は、キャッシュする出力のない通常のコンパイラープローブです。 簡易サマリーでは、これらはキャッシュ迂回の件数に含まれません。原因を追究する必要はありません。

その他のよくある症状

症状	最初に確認すること
通常の Cargo が mbx を使用しない	command -v cargo。スタンドアロン設定の場合は mbx setup --status も確認
Cargo がターゲットのロックを待機する	同時に実行するビルドには、それぞれ別のターゲットディレクトリを指定
ビルド前に Cargo のメタデータ取得が失敗する	cargo metadata --no-deps --format-version 1
ビルドストレージが NFS 上にある	cache_dir / target.root をローカルストレージに移動（mbx は NFS を拒否します）
リモートリクエストが失敗する	mbx doctor を実行し、続けて認証を確認
ストレージが想定より大きい	mbx cache stats を実行し、続けて mbx gc --dry-run を実行

1 回のコマンドで mbx を迂回する

MBX_DISABLE=1 cargo build

問題を報告する

mbx doctor --json
MBX_LOG=debug mbx build
MBX_BYPASS_LOG=bypass.log mbx build

これらの出力には、絶対パスのキャッシュパス、設定されているリモート、およびビルドするクレートが含まれます。 認証情報が出力されることはありません。

管理対象のターゲットディレクトリ

管理対象のターゲットはデフォルトで有効です。既存の target/ がないチェックアウトでは、 mbx はターゲットをキャッシュルートの下に配置し、シンボリックリンクを残します。

target -> <cache root>/targets/v1/<checkout digest>

Git のチェックアウトでは、必要に応じて mbx がリンクパスを .git/info/exclude に追加するため、 プロジェクトの .gitignore に変更を加えなくても git status はクリーンな状態を保ちます。

--target-dir、CARGO_TARGET_DIR、または Cargo の build.target-dir で指定されている場合、 mbx はそのターゲットを変更しません。

内容を削除せずに、既存のディレクトリを管理対象にします。

mbx adopt                            # the current checkout
mbx adopt --recursive --dry-run ~/src  # preview

MBX_TARGET_VIEWS=0 または [target] views = false で配置を無効にできます。

ディスク管理

mbx cache stats     # action store, managed targets, learned incremental state
mbx cache dir       # where the store lives
mbx gc --dry-run    # preview collection under the configured budgets
mbx gc              # collect
mbx clean           # this workspace's managed target, link, and incremental state
mbx cache remove /path/to/workspace   # the above, plus forget its cache claims
mbx stats           # lifetime savings

ビルド後に自動でガベージコレクションが実行され、実行頻度は最短でも 1 時間に 1 回です。 上限はデータを保存しているディスクの容量に応じて変わります。

上限	デフォルト	範囲
gc.max_size（アクションストア）	ディスクの 5%	5 GiB ～ 500 GiB
target.max_size（管理対象ターゲット）	ディスクの 10%	10 GiB ～ 100 GiB
gc.incremental_max_size（学習済みインクリメンタルデータ）	ディスクの 5%	10 GiB ～ 100 GiB

管理対象のターゲットは、target.max_age（30 日）にわたって未使用の場合と、対応する チェックアウトがなくなった場合にも回収されます。キャッシュは破棄可能で、いつでも再構築できます。 cargo clean では mbx のプライベートなインクリメンタル状態は削除されませんが、 mbx clean では削除される点に注意してください。

設定

3 つの情報源があり、最初に見つかった値が優先されます。

1. 環境変数（MBX_*）
2. Cargo ワークスペースのルートにある .mbx.toml - ビルドポリシーとスケジューラー設定のみ
3. プラットフォームの設定ディレクトリにある mbx/config.toml：
   • Linux：~/.config/mbx/config.toml
   • macOS：~/Library/Application Support/mbx/config.toml
   • Windows：%APPDATA%\mbx\config.toml

不明な TOML キーは拒否されるため、設定名の誤記はエラーになります。マシンのパス、 リモートキャッシュの設定、認証情報、ターゲットの配置、ガベージコレクションは、 リポジトリの .mbx.toml では受け付けられません。

マシン全体のコンパイラープールに上限を設定し、ノート PC の応答性を保ちましょう （デフォルトでは論理 CPU の全数と物理メモリの 85% を使用します）。

[scheduler]
cpus = 4
memory = "8GiB"

機能ごとの無効化スイッチ：

スイッチ	無効にする機能
MBX_SCHEDULER=0	マシン全体のコンパイルスケジューリング
MBX_CC=0	ビルドスクリプトと mbx exec の C/C++ キャッシュ
MBX_TARGET_VIEWS=0	管理対象のターゲットディレクトリ
MBX_CACHE_LINKS=0	ネイティブリンクキャッシュ
MBX_LEARNED_INCREMENTAL=0	学習済みインクリメンタル再利用
MBX_SAVINGS=off	節約額の行

CI

steps:
  - uses: actions/checkout@v7
  - uses: jdx/mr-boxington-action@v1
  - run: mbx test --workspace

アクションの前にツールチェーンをインストールしてください。生成されるキーには、OS、アーキテクチャ、 および PATH 上の rustc の識別情報が含まれます。デフォルトブランチへのプッシュでアーカイブが 作成され、フォークからのものも含め、プルリクエストでは復元のみが行われます。CI または GITHUB_ACTIONS が設定されている場合、mbx は説明的な CI サマリーを自動的に使用します。

sccache からの移行では、削除が必要です。RUSTC_WRAPPER、~/.cargo/config.toml の build.rustc-wrapper、およびインストール手順から sccache を取り除き、その後 mbx doctor を実行してください。rust-cache からの移行では、アクションを置き換えます。 同じパスを対象に両方を実行すると、復元と保存の処理が重複します。

利用可能なリファレンス

• references/getting-started.md - インストールから最初のキャッシュ済みビルドまで
• references/setup.md - Cargo のラッピング、rust-analyzer、Cargo のパスの確認
• references/troubleshooting.md - 症状の一覧と診断
• references/cache-results.md - ヒット／ミス／バイパス、再利用の測定
• references/limits.md - mbx がキャッシュするものと、キャッシュしないもの
• references/managed-targets.md - ターゲットの配置、移行、予算
• references/configuration.md - 全設定のリファレンス
• references/incremental.md - 学習済みインクリメンタル再利用
• references/scheduling.md - 並列ビルド、マシン全体のプール
• references/github-action.md - CI の設定
• references/cookbook/migrate.md - sccache または rust-cache からの移行
• references/cookbook/local-development.md - エディター、監視ループ、デバッグ
• references/remote-cache.md - キャッシュサーバーと S3 バックエンド
• references/cli/ - コマンドごとのフラグと引数

上記すべてを更新するには、./update-docs.sh を実行してください。

注意事項 - 違反につながる操作

• 念のため sccache の設定を残す → mbx はキャッシュを黙って停止します
• 「mbx doctor でセットアップについて警告されたので、mbx は有効になっていない」→ まず command -v cargo を確認してください
• キャッシュが機能することを確かめるため、同じターゲットで同じビルドを 2 回実行する → Cargo の最新状態を測定することになります
• ヒット率の低さを解決するためにキャッシュを消去する → まず mbx explain --last を実行してください
• compiler-query／standard-input のバイパスを追いかける → 通常のプローブであり、キャッシュ対象はありません
• コーディングエージェントや CI スクリプトに ~/.cargo/bin/cargo を呼び出すよう指示する → mise との統合を迂回します
• チェックインする .mbx.toml に [remote] の認証情報を記述する → 拒否されます。環境変数を使用してください
• 監視ループに cargo clean を追加する → Cargo の最新状態に関する情報が失われます