【2026年3月】Cargoの新しいビルドディレクトリ構成（Layout v2）に向けたテスト協力のお願い

Rustエコシステムの発展に伴い、ビルドツールであるCargoもまた、より高度な機能の実現に向けて進化を続けています。

2026年3月、Cargoチームはビルドプロセスの効率化と将来的な拡張性を目的に、ビルドディレクトリの新しいレイアウト（Layout v2）のテスト協力を呼びかけました。

この変更は、普段私たちが意識することの少ない「target」ディレクトリ内部の構造に踏み込むものであり、開発ツールやビルドスクリプトの作成者にとって重要な転換点となります。

本記事では、このアップデートの背景から、具体的な変更点、そしてテストへの参加方法について詳しく解説します。

なぜ今、ビルドディレクトリの再構成が必要なのか

Cargoのビルドディレクトリ（通常は target ディレクトリ）の構造は、これまで長らく内部実装として扱われてきました。

しかし、多くのプロジェクトやツールがCargoの不足している機能を補うために、この仕様として明文化されていない内部構造に依存しているのが現状です。

今回の「Layout v2」への移行は、単なる整理整頓ではありません。

コミュニティの有志であるranger-ross氏の尽力により、以下のようなCargoの次世代機能を実現するための布石として進められています。

ワークスペースを跨いだキャッシュの共有

現在のCargoは、ワークスペースごとにビルドキャッシュを保持しますが、これをプロジェクト間で共有できるようにする「クロスワークスペース・キャッシング」の実現が期待されています。

新しいレイアウトでは、ビルドの最小単位が自己完結したディレクトリに格納されるため、キャッシュの追跡と再利用が容易になります。

ディスク容量の効率的な管理

長期間の開発によりビルドディレクトリが肥大化することは、Rust開発者にとって共通の悩みでした。

新しい構造では、古くなったビルド成果物を自動的にクリーンアップする機能の実装が進められており、ディスク使用量を一定に保つことが可能になります。

並列処理の改善とパフォーマンス向上

これまで、Cargoとrust-analyzerが互いの処理をブロックしてしまうことがありましたが、より細かい粒度でのファイルロック（Granular locking）を導入することで、この問題の解消を目指しています。

また、Windows環境において中間生成物が PATH を汚染し、ビルド性能に悪影響を与える問題の修正も含まれています。

新しいレイアウト（Layout v2）の詳細

今回の変更で最も大きな点は、ファイルの整理基準が「コンテンツの種類」から「パッケージ名とビルドユニットのハッシュ」によるスコープ管理へと切り替わることです。

従来のレイアウト構造

これまでは、deps や build といったディレクトリに、複数のパッケージの生成物が混在して配置されていました。

build-dir/
└── debug/
    ├── .fingerprint/         # ビルドキャッシュの追跡
    │   ├── bin-[HASH]/*
    │   └── lib-[HASH]/*
    ├── build/                # ビルドスクリプトの成果物
    │   ├── bin-[HASH]/out/
    │   └── lib-[HASH]/out/
    └── deps/                 # コンパイルされたバイナリやライブラリ
        ├── bin-[HASH]
        └── lib-[HASH]

提案されている新しいレイアウト（Layout v2）

Layout v2では、以下のようにパッケージごとにディレクトリが分かれ、その中にハッシュ化されたビルド単位が格納されます。

build-dir/
└── debug/
    └── build/
        ├── bin/              # パッケージ名
        │   └── [HASH]/       # ビルド単位ごとの独立したディレクトリ
        │       ├── fingerprint/*
        │       └── out/*     # バイナリ、ライブラリ、デバッグ情報がここに集約される
        └── lib/
            └── [HASH]/
                ├── fingerprint/*
                └── out/*

この変更により、特定のパッケージに関連するファイルが1つの場所に集約されるため、管理の透明性が飛躍的に向上します。

なお、最終的な成果物（バイナリなど）が配置されるディレクトリ構造については、今回の変更対象には含まれていません。

テスト方法と実施手順

Cargoチームは、この変更による既存ツールへの影響を最小限に抑えるため、開発者による実環境でのテストを必要としています。

テストの準備

テストを実施するには、2026-03-10 以降の nightly ツールチェーンが必要です。

以下のコマンドで、新しいレイアウトを有効にしてテストを実行できます。

# 新しいディレクトリレイアウトを強制的に適用してテストを実行
cargo test -Zbuild-dir-new-layout

通常の開発プロセス、リリースプロセス、あるいはビルドディレクトリを直接操作するような独自スクリプトに対しても、このフラグを付与して動作を確認してください。

Cargo 1.91からのビルドディレクトリ分離機能

なお、2025年10月にリリースされた Cargo 1.91 以降、中間生成物の保存先（build-dir）と最終成果物の保存先（target-dir）を分離できるようになっています。

# 中間生成物の場所を環境変数で指定して実行
CARGO_BUILD_BUILD_DIR=build cargo build

もし -Zbuild-dir-new-layout で問題が発生した場合、この分離機能自体の影響なのか、新しいレイアウト特有の問題なのかを切り分けることが重要です。

既知の課題とライブラリの対応状況

一部のビルドスクリプトやテスト用ライブラリでは、target ディレクトリの構造を直接推測しているものがあり、修正が必要なケースが報告されています。

推奨される修正方法

バイナリのパスを推測する処理を書く場合は、直接パスを結合するのではなく、Cargoが提供する環境変数の使用を検討してください。

• std::env::var_os("CARGO_BIN_EXE_*") （Cargo 1.94以降）
• env!("CARGO_BIN_EXE_*")

主要ライブラリのサポート状況

2026年3月現在、主要なテスト支援ライブラリの対応状況は以下の通りです。

独自のツールでビルドディレクトリの内部構造に依存している場合は、上記のリポジトリでの修正内容を参考に、Layout v2への対応を進めることが推奨されます。

今後の展望

今回の変更は、Cargoのパフォーマンスと利便性を次なるステージへ引き上げるための大きな一歩です。

Layout v2の導入によってファイルロックの粒度が細かくなれば、開発ワークフローの並列性がさらに高まることでしょう。

将来的には、Windows環境でのパス長制限を回避するためのパス短縮化や、プロファイルやターゲットの枠を超えて生成物を共有する試みも予定されています。

Cargoチームは今回のテスト結果を慎重に評価し、将来の安定版リリースにおいてデフォルトの挙動とするかどうかを判断するとしています。

まとめ

今回のCargoビルドディレクトリ構成の変更は、一見すると地味な内部アップデートに見えるかもしれません。

しかし、その実態は「クロスワークスペース・キャッシュ」や「自動クリーンアップ」といった、Rustの開発体験を劇的に変える新機能を支える重要な基盤づくりです。

2026年3月現在、この機能はnightlyでのテスト段階にあります。

もしあなたが複雑なビルドスクリプトを持つプロジェクトや、Cargoの内部構造に触れるツールを開発しているなら、ぜひ -Zbuild-dir-new-layout フラグを試してみてください。

見つかった問題やフィードバックをトラッキングIssueへ報告することが、次世代のCargoをより堅牢なものにする助けとなります。

Rustのさらなる進化に向けて、コミュニティ全体でこの大きな転換期をサポートしていきましょう。