Rust Cargo パッケージ管理の完全ガイド：依存解決・ワークスペース・CI/CD対策

Cargo の概要と crates.io との連携

Cargo は Rust 標準のビルドツール兼パッケージマネージャです。コードコンパイルだけでなく、依存クレートの取得・バージョン解決・ロックファイル管理までを一貫して行うため、個人開発でもチーム開発でも必須となります。このセクションでは Cargo の全体像と、デフォルトで利用される公式レジストリ crates.io への接続方法を確認します。

Cargo が担う主な役割

Cargo は以下の３つの大きな機能を提供します。

1. ビルドとテストの自動化
   cargo build, cargo test などの単一コマンドでコンパイル・ユニットテスト・ベンチマークが実行できます。
2. 依存解決とキャッシュ
   Cargo.toml に記載されたバージョン範囲から最適なクレートを自動的に選択し、取得したソースはローカルの ~/.cargo/registry と ~/.cargo/git に保存されます。キャッシュはプロジェクト間で共有できるため、同一バージョンの再取得が不要です（詳しくは Qiita の解説記事を参照: https://qiita.com/takashi/items/4c0b9a5d1e6f2b8e7b3a）。
3. レジストリとの安全な通信
   Cargo は TLS 経由で crates.io とやり取りし、Git リポジトリ形式のインデックスからメタ情報を取得します。インデックス自体は ~/.cargo/git にクローンされ、ローカルで高速に検索できます。

crates.io との接続方法

crates.io は Cargo のデフォルトレジストリです。特別な設定を行わなくても以下の流れで利用可能です。

公式ドキュメント: https://doc.rust-lang.org/cargo/reference/registry.html

Cargo.toml の基本構造とバージョン指定

Cargo.toml はプロジェクトのメタ情報と依存関係を記述する中心ファイルです。ここでは主要セクションと、実務で頻繁に使うバージョン演算子の正しい意味を解説します。

主要セクションの概要

Cargo.toml はテーブル形式で項目が区分けされており、目的別に依存を管理できます。以下は代表的なテーブルとそのキー例です。

バージョン演算子の正しい意味

バージョン指定は SemVer（セマンティック・バージョニング）に基づく互換性保証と、更新頻度のバランスを取るために重要です。各演算子の挙動は次の通りです。

参考: Rust 官方文档「Dependency Specification」https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html

実務シナリオ別：依存関係の追加・更新・削除

プロジェクトのライフサイクルに応じて、依存管理のベストプラクティスは変わります。この章では「新規追加」「手動編集と cargo add の使い分け」「バージョン固定と cargo update」の３つのシナリオを具体例とともに示します。

新規プロジェクトで依存クレートを追加する手順

まずは Cargo が提供するサブコマンド cargo add（cargo-edit クレート）を利用した流れです。

1. プロジェクト作成
   bash
cargo new my_project
cd my_project
2. 依存クレートの追加（例: serde と tokio）
   bash
cargo add serde --features derive
cargo add tokio --features full
3. 生成された Cargo.toml の確認
4. 期待したバージョン範囲が設定されているか。
5. 必要に応じて ^ や ~ に手動で書き換える。

手動編集と cargo add/remove の使い分け

Aetheria の実務記事では、cargo add --optional, --default-features false など高度なオプションの使い方が詳しく解説されています（参照: https://aetheria.jp/articles/cargo-add-options）。

バージョン固定と cargo update の活用

安定運用では Cargo.lock と組み合わせてバージョンをロックし、必要に応じて計画的に更新します。

ローカルパス・Git リポジトリからの依存設定と Workspace の活用

社内クレートや開発中ブランチを直接参照したいケースは多くあります。また、複数クレートを統合的に管理できる Workspace は大規模プロジェクトで必須です。

ローカルディレクトリ依存の記述例

ローカルパスを使うと、ビルドが高速になるだけでなく、変更が即座に反映されます。

• ポイント
• 相対パスでも絶対パスでも指定可。
• Cargo.lock にハッシュが保存されるため、CI 上でも同一ソースが再現できます。

Git リポジトリ依存の記述例

Git URL とブランチ・タグ・コミットハッシュを組み合わせて柔軟に指定できます。

• 注意点
• rev（コミットハッシュ）で固定すると、再現性が完全に保証されます。
• branch 指定は開発ブランチの最新を取得するため、cargo update が必要になるケースがあります。

Workspace によるクレート階層管理

Workspace はルート Cargo.toml にメンバーリストを列挙し、全体で単一の Cargo.lock を共有します。これによりビルド時間が短縮され、依存バージョンの衝突も防げます。

• メリット（KumaROOT ドキュメント参照: https://kumaroot.com/docs/workspace）
• 複数クレートが同一 Cargo.lock を共有し、全体の依存バージョンが統一される。
• cargo test --workspace や cargo build --workspace で一括操作が可能になる。

Cargo.lock の扱いと CI/CD における再現性確保

ロックファイルは「同一の依存ツリーでビルドできる」ことを保証する重要なアーティファクトです。プロジェクト種別（バイナリ vs ライブラリ）に応じた取り扱いと、CI でのキャッシュ戦略について詳しく解説します。

Cargo.lock の基本的な役割

• バイナリ（実行可能ファイル）プロジェクト
• Cargo.lock を 必ずコミット。これによりローカル開発者・CI 環境が同一依存ツリーでビルドでき、予期せぬアップデートによるビルドエラーを防止します。
• ライブラリ（crate）プロジェクト
• 基本的に Cargo.lock は コミットしない。利用側のアプリケーションがロックファイルを生成するため、上位プロジェクトでバージョン統一が可能です。ただし、以下の例外があります。

CI では cargo build --locked や cargo test --locked を使用すると、ロックファイルと乖離した依存取得がブロックされます。

CI パイプラインでのキャッシュ活用例（GitHub Actions）

以下は Cargo のレジストリと Git リポジトリをキャッシュし、ビルド時間を短縮するテンプレートです。

• ポイント
• hashFiles('Cargo.lock') をキーに入れることで、依存が変わったときだけキャッシュが再生成されます。
• --locked オプションはロックファイルと不整合がある場合にビルドを失敗させるため、CI の再現性が保証されます。

crates.io への公開手順と運用ベストプラクティス

社外向けのクレートを公開する際は、正しい手順とトラブル時の対処法を把握しておくことが重要です。ここでは cargo publish の流れ、事前チェック項目、そしてバージョニング・yank の活用方法をまとめます。

公開前の準備チェックリスト

1. 認証トークンの設定
   bash
cargo login <your-token>
2. ローカルでビルドとテスト（全機能が通ることを確認）
   bash
cargo test --all
cargo clippy -- -D warnings
3. パッケージ内容の検証 (Cargo.toml の exclude/include を活用)
   bash
cargo package --list # 何が含まれるか一覧表示
cargo package --allow-dirty # 未コミットでも確認できる（CI 用）
4. ドキュメントと例のビルド
5. cargo doc --no-deps が成功すること。
6. README が Markdown で正しくレンダリングされるかをプレビュー。

詳細な手順は issoh の実践記事にまとめられています（参照: https://issoh.dev/blog/cargo-publish-yank）。

cargo publish 実行と失敗時の対処

• 失敗例：バージョンがすでに存在する、または依存解決エラー。
• バージョンをインクリメント（パッチアップデート）して再挑戦。
• cargo yank <version> で問題のあるバージョンだけ非表示にし、次のバージョンで再公開。

SemVer に基づくバージョン管理

緊急で問題が見つかった場合は次のコマンドでバージョンを非表示にできます。

社内プライベートレジストリの設定例

社内向けクレートは GitHub Packages や Azure Artifacts などのプライベートレジストリに公開します。以下は実際に使える ~/.cargo/config.toml のサンプルです。

• ポイント
• index はレジストリの Git インデックス URL。実際に運用しているサーバーのパスを記述してください（例: https://registry.mycorp.com/git/crates-index）。
• CI では同じ設定ファイルをプロジェクトルートかホームディレクトリに配置し、認証情報は GitHub Actions の secrets.CARGO_REGISTRY_TOKEN 等で安全に供給します。

まとめ

本稿では Cargo の全体像から実務的な依存管理手法、CI/CD における再現性確保、そして crates.io / プライベートレジストリへの公開までを網羅的に解説しました。以下のポイントを押さえておけば、ビルドエラーやバージョン衝突に悩まされることが格段に減少します。

1. Cargo の役割と crates.io へのデフォルト接続は把握しているか
2. Cargo.toml のバージョン演算子の意味を正しく使い分けているか（特に * は避ける）
3. ロックファイルの扱いをプロジェクト種別に合わせて管理できているか（バイナリは必ずコミット、ライブラリは状況次第）
4. CI でキャッシュと --locked オプションを活用し、ビルドの再現性を保証しているか
5. 公開前チェックリストと SemVer に基づくバージョニング手順を実践できているか

これらを日常的に意識すれば、Rust 開発チーム全体の生産性が向上し、安定したデリバリーが可能になります。ぜひ本ガイドを手元に置き、プロジェクトごとに適用してみてください。