メタデータを早期に発行することで、Rustのビルド/チェックが最大2倍高速になる
Emitting metadata early makes building/checking Rust up to twice as fast (github.com)
要約
Rustのコンパイラとビルドツールであるcargoの新しい機能「headstart」は、メタデータを早期に発行することで、コンパイル時間を大幅に短縮します。依存関係の型チェックが完了する前に、その依存関係のインターフェース情報(メタデータ)を利用してビルドを開始し、全体のビルド速度を向上させます。これにより、特に大規模なプロジェクトにおいて、`cargo check`で最大54%、`cargo build`で最大42%の高速化が報告されています。
全文翻訳
headstart
依存クレートを、その依存先が型チェックを終える前に開始する。
すべてのクレートは、型チェックに必要な依存先のクレートの関数本体が完全にチェックされるのを待ってから開始します。しかし、型チェック自体にその本体は必要ありません。依存先のインターフェース、つまり.rmetaファイル内のメタデータに対してコンパイルされます。
Headstartは、インターフェースがチェックされ次第、rustcに早期メタデータファイルを書き込ませ、cargoに依存先をそれを元に開始させます。各クレートの本体は、下流のクレートがすでにコンパイルされている間にチェックされます。
cargo check: 依存先は早期メタデータで完了まで実行されます。cargo build: 依存先は早期メタデータで全解析を行い、コード生成前に依存先の完全なメタデータを待ちます。待機中、ジョブスロットを解放します。
本体にエラーがある場合でも、ビルドは今日と同じ診断情報と終了ステータスで失敗します。違いは、進捗表示やクロスクレートでのJSONメッセージの順序だけです。Cargoは、依存先がすべて正常に完了した場合にのみクレートの出力を報告し、いずれかが失敗した場合は破棄します。コストとしては、破棄される下流の作業、わずかに遅れて報告されるエラー、そして同時に使用されるメモリの増加があります(docs/design.md参照)。
部品
rustc,-Zearly-metadata(6パッチ):- 新しい
analysis_interfacesクエリが、解析をアイテムインターフェースと関数本体に分割します。 - ドライバがその2つの間に
.early-rmetaを書き込みます。 - クレートローディングは早期メタデータを受け入れ、コード生成前に完全なメタデータと交換し、プロデューサが保持するロックが解除されるまで待機します。
- 新しい
cargo,-Zheadstart(3パッチ):- すべてのコンパイルに
-Zearly-metadataを渡します。 checkとbuildの両方で、早期メタデータ通知で依存先を開始します。- 一時停止したコンパイルのジョブスロットを他の作業に割り当てます。
- 依存先が成功した場合にのみ、クレートの出力を報告します。
- すべてのコンパイルに
パッチはコミットシリーズであり、それぞれにコミットメッセージとテストが含まれており、アップストリームのプルリクエストになることを意図しています。詳細はpatches/README.mdを参照してください。
rustcのデフォルトフロントエンドでは、Headstartは13の実際のプロジェクト(rust-analyzer、zed、bevy、lemmy、polarsなど)のクリーンビルドを、cargo checkで最大54%、cargo buildで最大42%高速化します。遅くなるものはありません。並列フロントエンド(-Zthreads=8)では、一部重複するものの、最大25%の追加効果があります。これらは16コアでの数値です。この利点は、ビルドがアイドル状態にするコアから得られるため、小規模なマシンでは効果が縮小します。4コアでは、rust-analyzerのチェックは24%、ビルドは13-15%高速化し、codex-rsのチェックは14%高速化し、広範なビルドは同等になります。
[画像: codex-rs clean cargo build, headstart off vs on]
16コアでのcodex-rsのクリーンcargo buildをcratebankで記録しました。Headstartなしでは、ワークスペース自身のクレートはマシンがほとんどアイドル状態のまま順次コンパイルされますが、Headstartありでは、各クレートは前のクレートの早期メタデータで開始され、ビルドは37%高速化します。
[画像: codex-rs, what waited for what, headstart off vs on]
同じ2つのビルドで、時間と依存関係の深さを示しています。各ユニットは、それを解放した依存関係の下に描かれ、コンパイラフェーズで色分けされています。Headstartなしでは、ワークスペースのクレートは長い階段を形成しますが、Headstartありではそれらが重複します。詳細はdocs/results.mdをご覧ください。
仕組み、早期メタデータが何を除外するか、リスクについてはdocs/design.mdをご覧ください。測定結果はdocs/results.mdにあります。コンパイラとcargoチームに提供する準備ができているかについてはdocs/readiness.mdをご覧ください。
試すには
scripts/setup.sh # rustc + cargo をチェックアウトし、パッチを適用して両方をビルド
その後、任意のRustプロジェクトで:
RUSTC=/path/to/headstart/rustc/build/host/stage1/bin/rustc \
/path/to/headstart/cargo/target/release/cargo check -Zheadstart # または build
CARGO_UNSTABLE_HEADSTART=trueや、.cargo/config.tomlの[unstable] headstart = trueでも有効になります。これらがない場合、パッチ適用済みのcargoはアップストリームと同様に動作するため、同じバイナリで公平なベースラインが得られます。
コンパイルキャッシュ(sccacheや、終了するまでrustcの出力を保持するrustc-wrapperなど)を無効にしてタイミングを取ってください。これらは早期メタデータを隠蔽し、Headstartを無効にします。RUSTC_WRAPPER=はグローバルな設定を上書きします。rustupのnightlyと比較するには、まずscripts/release.shでビルドしてください(nightlyとの比較参照)。
tests/smokeは、2つのクレートを持つワークスペースで、cargo checkでの効果を示します。slowライブラリは、チェック時間のほとんどを関数本体のチェックに費やします。Headstartがオンの場合、appはslowのインターフェースチェック完了を待つのではなく、それが完了次第開始されます。cargo buildでは効果は見られません。appは早期に開始する作業が少なすぎるため、コンパイラのみの時間を計測します。
scripts/check-errors.shは、tests/errorsでのエラーに関する主張を確認します。クリーンビルド、依存関係のエラー、バイナリのエラーの3つのシナリオを、Headstartオフとオンでcargo checkとcargo buildで実行します。その後、人間が読める出力、JSON出力、終了ステータス、ビルドされたバイナリの出力を比較します。
scripts/check-incremental.sh [check|build]は、一連のインクリメンタル編集で同様のことを行います。ステップには、依存先が呼び出すimpl Fnの追加、インターフェースの破壊と修正が含まれます。また、最終状態をクリーンビルドと比較します。
scripts/check-swap.shは、ライブラリが依存先の早期メタデータで開始し、一時停止中に完全なメタデータとスワップする様子を、すべての最適化レベルで確認します。それからビルドされたプログラムは、完全なメタデータからビルドされたプログラムと同じ出力を生成する必要があります。
scripts/sweep.shは、Headstartオフとオン、-Zearly-metadata-verify付きで、すべての53のrustc-perfコンパイルベンチマークをビルドします。すべてのビルドが両モードで同じ診断情報で成功し、verifyが何も報告しない場合にパスします。-c buildはcargo buildをスイープし、-rはリリースプロファイルを、-tは並列フロントエンド(-Zthreads=8)をスイープします。
ベンチマーク
scripts/bench.sh -n 5 [-c build] path/to/project ...
これはクリーンなcargo check(またはcargo build)ビルドの時間を計測し、Headstartオフとオンを交互に行い、中央値を表示します。プロジェクトは::の後にcargo引数を取ることができます(path/to/vaultwarden::--features=sqlite)。scripts/real-projects.shは、docs/results.mdから測定されたコミットの13の実際のプロジェクトをクローンし、その形式で出力します:
scripts/bench.sh -n 3 -c build $(scripts/real-projects.sh ~/hs-real)
scripts/setup-codex.sh <dir>は、パッチ適用済みの依存関係とcodexの事前ビルド済みV8を必要とするcodex-rsに対して同様のことを行います(スクリプト参照)。タイミングを取る前に、<dir>/codex/headstart.envをソースしてください。
-wは、ビルドスクリプトがtarget外で一度だけ実行する作業(helixがソースツリーにグラムマをコンパイルするなど)のために、プロジェクトごとにタイム計測しないウォームアップビルドを追加します。
scripts/bench-suite.sh <out-dir>は、現在のマシンでdocs/results.mdの全ベンチマークスイートを実行します:rust-analyzer、21のrustc-perfベンチマーク、その他の実際のプロジェクト、codex-rs、checkおよびbuild。各ベンチマークの結果を個別に保持し、完了したものはスキップするため、再開可能であり、最後に要約テーブルを書き込みます。これは、まだ測定されていないマシンサイズ(例: 8コア)の数値を取得する方法です。
scripts/bench-mem.shは、プロジェクトディレクトリ自体でビルド中のすべてのrustcプロセスの合計メモリをサンプリングします(アイドル状態のマシンで実行してください)。scripts/bench-incremental.shは、1つの関数本体を編集した後のインクリメンタル再チェックの時間を計測します。scripts/log-rustcは、各rustc実行がいつ開始および終了したかを記録し、スケジュールを確認できるようにします。rustc-perfベンチマークはrustc/src/tools/rustc-perf/collector/compile-benchmarksの下にあります(git -C rustc submodule update --init --depth 1 src/tools/rustc-perf)。
nightlyとの比較
setup.shは開発用rustcをビルドしますが、PGOとBOLTで最適化されたrustupのnightlyよりも約2倍遅いです。nightlyと比較すると、Headstartは遅く見えます。Headstartのrustcをnightlyと同様にビルドするには:
scripts/release.sh # setup.shの後。16コアで約1時間、ディスク25GBが必要
これにより、rustc/build-pgo/host/stage2/bin/rustcが生成されます。6コアでnightly-2026-10-12に対してクリーンなripgrepビルドを行った場合:
check | build | |
|---|---|---|
| nightly | 3.76 s | 7.28 s |
release.sh rustc, headstart off | 4.18 s | 7.76 s |
release.sh rustc, headstart on | 2.64 s | 5.85 s |
BOLTステップには、LLVM 19以降のllvm-boltとmerge-fdataが必要です。これらがない場合、release.shはPGO後に停止しますが、これは利点の大部分を提供します。