rust-cargo-build

Rust Cargo ビルドシステム

Cargo を、バージョン管理されたパッケージマネージャー、ビルドオーケストレーター、自動化インターフェースとして使用します。プロジェクトで実際に使われている Cargo のバージョン、MSRV、ワークスペースのルート、ターゲット、リリースモデルに基づいて判断してください。公式の Cargo Book を規範とし、このスキルではタスクの選択、実行、検証に焦点を当ててください。

事前確認

関連する最小限の範囲を実行します。

rustc --version --verbose
cargo --version
cargo locate-project --workspace
cargo metadata --no-deps --format-version 1

以下を確認します。

• ルートマニフェストがパッケージか仮想ワークスペースか；
• 宣言された edition、rust-version、resolver、ロックファイルのポリシー；
• 選択するパッケージ、ターゲット、機能、プロファイル、ターゲットトリプル；
• 依存関係のソース、レジストリ設定、オフライン時の制約；
• 要求された動作が、インストール済みの Cargo バージョンで安定しているか。

適切なリファレンスを選ぶ

現在のタスクに必要なリファレンスのみを読みます。

タスク	リファレンス
規範となる Cargo ガイド、リファレンス、コマンド、変更履歴のページを探す	公式ドキュメントの一覧
Cargo コマンドを選び、その副作用を把握する	Cargo コマンド一覧
パッケージの開始、ビルド、実行、テスト、ドキュメント作成、CI の追加を行う	Cargo ガイドのワークフロー
パッケージメタデータと lib/bin/example/test/bench ターゲットを設定する	マニフェストとターゲット
依存関係のソース、機能、オーバーライド、resolver を設定する	依存関係、機能、resolver
メンバーと継承するワークスペースフィールドを設定する	ワークスペース
.cargo/config.toml、環境変数、エイリアス、ネットワーク、ターゲット設定を行う	設定と環境
dev/release/カスタムプロファイルを調整する	プロファイル
コードを生成する、ネイティブ依存関係をコンパイルする、または build.rs から Cargo の指示を出力する	ビルドスクリプト
再ビルド、コンパイルの重複、キャッシュの配置、所要時間、将来的な非互換性を診断する	ビルドキャッシュと診断
リンカー、ランナー、またはホスト以外のターゲットを設定する	クロスコンパイル
レジストリ、ソースの置き換え、ベンダリング、認証情報、認証を設定する	レジストリと認証
パッケージの内容を確認する、公開する、所有者を管理する、またはバージョンを yank する	パッケージングと公開
安定版 Cargo の JSON やパッケージ ID を使ったビルドスクリプトやツールを作成する	メタデータと自動化
cargo-features、-Z、その他の nightly 専用動作を評価する	不安定な Cargo 機能

基本的なワークフロー

1. ルートを特定する — 編集する前に、ワークスペースのルートと有効なマニフェストを確認します。
2. 互換性を宣言する — edition、MSRV、サポート対象のターゲット、stable/nightly のポリシー、機能の契約を記録します。
3. 有効な状態を調べる — 1 つのマニフェストから推測するのではなく、cargo metadata、cargo tree、有効な設定を使用します。
4. 変更を最小限にする — 慣例に沿ったターゲット、追加的な機能、ワークスペースの継承、安定した Cargo の動作を優先します。
5. 要求されたマトリックスを実行する — パッケージ、ターゲット、機能、プロファイル、ターゲットトリプルを明示的に選択します。
6. 最適化の前に診断する — プロファイルやキャッシュを変更する前に、所要時間、依存関係のエッジ、詳細な出力、再ビルドの根拠を確認します。
7. 成果物と副作用を検証する — 生成されたファイル、パッケージの内容、ロックファイルの変更、レジストリの対象、認証情報の取り扱いを確認します。

判断ルール

マニフェスト、MSRV、リゾルバー

• エディションと MSRV を同一視せず、package.rust-version を宣言して、そのツールチェーンでテストしてください。
• リゾルバーはワークスペース全体に適用されるものとして扱ってください。仮想ワークスペースでは明示的に設定してください。
• リゾルバーのデフォルト値とバージョンによって利用可能になるフィールドは、インストール済みの Cargo ドキュメントまたは変更履歴で確認してください。
• Cargo の慣例的なパスでは不十分な場合に限り、明示的なターゲットテーブルを使用してください。

Cargo.lock と再現性

• 判断に迷ったら、Cargo.lock をコミットしてください。現行の Cargo ガイドでは、デフォルトでバージョン管理に含めることが推奨されています。
• 例外は、「アプリケーションなら含め、ライブラリなら含めない」という一律のルールではなく、リポジトリのリリース、CI、依存関係の検証ポリシーに基づいて判断してください。
• コミット済みのロックファイルを変更してはならない場合は、--locked を使用してください。
• ロックファイルの変更とネットワークアクセスの両方を禁止する必要がある場合に限り、--frozen を使用してください。
• ロックファイルの差分を確認してください。CI の失敗を回避するためだけにロックファイルを削除したり、広範囲な更新を実行したりしないでください。

依存関係と機能

• 機能は追加的なものとして扱い、cargo tree -e features で機能の統合を検証してください。
• プラットフォームの選択にはターゲット固有の依存関係を使用してください。ターゲット依存関係テーブルに cfg(feature = "...") を記述しないでください。
• 再現性の確保に必要な場合は、Git 依存関係をリビジョンに固定してください。
• [patch]、ソース置換、ベンダリングは、それぞれ文書化された目的にのみ使用してください。互いに置き換え可能なものとして扱わないでください。

設定と環境

• マニフェスト設定と階層的な Cargo 設定を区別してください。
• コマンドの作業ディレクトリから .cargo/config.toml が検出されることを確認してください。
• シークレットをコミット済みの設定やコマンド履歴に残さないでください。
• ビルドスクリプトや proc マクロ向けのホスト設定と、最終成果物に使用するターゲット設定を分けてください。

ビルドスクリプト

• 生成した成果物は OUT_DIR にのみ書き込んでください。
• 正確な cargo::rerun-if-changed と cargo::rerun-if-env-changed の指示を出力してください。
• 出力の再現性を保ち、ビルド中のネットワークアクセスを避けてください。
• ネイティブリンクの指示と links メタデータは、公開された統合契約として扱ってください。

プロファイル、キャッシュ、診断

• 最適化対象のワークフローを計測してください。対象には check、インクリメンタル開発、テスト、CI、リリース時のリンク、実行時の動作、バイナリサイズがあります。
• プロファイル定義はワークスペースのルートに置いてください。
• Reference に出力場所の記載がない限り、ビルドディレクトリの構成は Cargo 内部の実装として扱ってください。
• 推測に基づくキャッシュ削除よりも、cargo build --timings、cargo tree -d、将来の互換性に関するレポートを優先してください。

レジストリと公開

• レジストリ、ソース置換、ディレクトリソース、ベンダリングを区別してください。
• ログインや公開の操作を行う前に、認証情報プロバイダーとレジストリの識別情報を確認してください。
• 公開前に cargo package --list とパッケージ検証を実行してください。
• ログイン、オーナーの変更、公開、取り下げ、認証情報の変更には、明示的な許可を必須としてください。

Stable と Nightly

• Stable の Cargo の動作を優先してください。
• Nightly を推奨する前に、該当する不安定機能、呼び出し形式、追跡 issue、代替手段、削除条件を特定してください。
• cargo-features、-Z、[unstable] 設定を Stable の機能として提示しないでください。
• 不安定なインターフェースは安定化、変更、廃止される可能性があるため、変更履歴を再確認してください。

検証

サポートされていない組み合わせをむやみに実行せず、マトリックスを適宜調整してください。

cargo metadata --format-version 1
cargo fmt --all --check
cargo check --workspace --all-targets --all-features
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo package --list

リポジトリがロックファイルをコミットしている、または必須としている場合は、対応する Cargo コマンドに --locked を追加してください。ワークスペースで一部の機能やターゲットを意図的に対象外としている場合は、明示的なマトリックスを定義し、その理由を記録してください。

対象範囲

• クレートの選定、勧告、ライセンス、禁止事項、サプライチェーンポリシー → rust-dependencies
• ワークスペースとクレートの構成 → rust-workspace
• テストアーキテクチャ、フィクスチャ、プロパティテスト、カバレッジ → rust-testing
• rustdoc の内容とドキュメントアーキテクチャ → rust-documentation
• rustfmt、Clippy ポリシー、エディションの移行 → rust-style-clippy
• 実行時のパフォーマンスとアロケーションの動作 → rust-performance
• API の互換性とバージョン更新の判断 → rust-semver
• 組み込みターゲットの実行環境とハードウェア統合 → rust-embedded

上位レベルの判断が別のスキルに属する場合でも、Cargo コマンドの仕組みに関する内容はここに含めてかまいません。

完了基準

• 実効ワークスペース、Cargo のバージョン、MSRV、ターゲット、フィーチャー、プロファイルのコンテキストを特定します。
• バージョンによって動作が異なる場合は、関連する公式 Cargo ページへのリンクを記載します。
• 安定した動作と nightly の実験的な機能を区別します。
• 実効依存関係グラフと設定を検証します。
• 再現性と認証情報の安全性を保ちます。
• 成功を宣言する前に、アーティファクト、パッケージ、レジストリへの影響を確認します。

データプライバシー

このスキルはユーザーデータを収集、保存、送信しません。レジストリトークン、Git 認証情報、環境変数、生成されたアーティファクト、パッケージの内容は、機密情報として扱ってください。