cargo-workflows

Cargo ワークフロー

目的

Cargo ワークスペース、機能管理、ビルドスクリプト（build.rs）、CI 統合、インクリメンタルコンパイル、Cargo ツールエコシステムについて、エージェントを案内します。

トリガー

• 「複数のクレートを含む Cargo ワークスペースを設定するにはどうすればよいですか？」
• 「Cargo の機能はどのように動作しますか？」
• 「build.rs スクリプトを作成するにはどうすればよいですか？」
• 「CI で Cargo のビルドを高速化するにはどうすればよいですか？」
• 「Rust の依存関係を監査するにはどうすればよいですか？」
• 「cargo nextest とは何ですか？使うべきですか？」

ワークフロー

1. ワークスペースの設定

my-project/
├── Cargo.toml           # Workspace root
├── Cargo.lock           # Single lock file for all members
├── crates/
│   ├── core/
│   │   └── Cargo.toml
│   ├── cli/
│   │   └── Cargo.toml
│   └── server/
│       └── Cargo.toml
└── tools/
    └── codegen/
        └── Cargo.toml

# Workspace root Cargo.toml
[workspace]
members = [
    "crates/core",
    "crates/cli",
    "crates/server",
    "tools/codegen",
]
resolver = "2"   # Feature resolver v2 (required for edition 2021)

# Shared dependency versions (workspace.dependencies)
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
anyhow = "1"

# Shared profile settings
[profile.release]
lto = "thin"
codegen-units = 1

# Member Cargo.toml
[package]
name = "myapp-core"
version.workspace = true
edition.workspace = true

[dependencies]
serde.workspace = true    # Inherit from workspace
anyhow.workspace = true

2. 機能フラグ

[features]
default = ["std"]

# Simple flag
std = []

# Feature that enables another feature
full = ["std", "async", "serde-support"]

# Feature with optional dependency
async = ["dep:tokio"]
serde-support = ["dep:serde", "serde/derive"]

[dependencies]
tokio = { version = "1", optional = true }
serde = { version = "1", optional = true }

# Build with specific features
cargo build --features "async,serde-support"

# Build with no default features
cargo build --no-default-features

# Build with all features
cargo build --all-features

# Check feature combinations
cargo check --no-default-features
cargo check --all-features

機能に関する注意点：

• 機能は追加型です。依存関係グラフ内のどこかで一度有効になると、その後も有効なままです
• resolver = "2" により、開発用依存関係と通常の依存関係の間で機能が漏れるのを防げます
• 暗黙的な機能の作成を避けるには、dep:optional_dep 構文（edition 2021）を使用します

3. ビルドスクリプト（build.rs）

// build.rs (at crate root, runs before compilation)
use std::env;
use std::path::PathBuf;

fn main() {
    // Re-run if these files change
    println!("cargo:rerun-if-changed=build.rs");
    println!("cargo:rerun-if-changed=wrapper.h");
    println!("cargo:rerun-if-env-changed=MY_LIB_PATH");

    // Link a system library
    println!("cargo:rustc-link-lib=mylib");
    println!("cargo:rustc-link-search=/usr/local/lib");

    // Pass a cfg flag to Rust code
    let target = env::var("TARGET").unwrap();
    if target.contains("linux") {
        println!("cargo:rustc-cfg=target_os_linux");
    }

    // Set environment variable for downstream crates
    println!("cargo:rustc-env=MY_GENERATED_VAR=value");

    // Generate bindings with bindgen
    let bindings = bindgen::Builder::default()
        .header("wrapper.h")
        .generate()
        .expect("Unable to generate bindings");

    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings.write_to_file(out_path.join("bindings.rs")).unwrap();
}

println! ディレクティブ	効果
cargo:rerun-if-changed=FILE	ファイルが変更された場合、ビルドスクリプトを再実行します
cargo:rerun-if-env-changed=VAR	環境変数が変更された場合、再実行します
cargo:rustc-link-lib=NAME	ライブラリをリンクします
cargo:rustc-link-search=PATH	ライブラリ検索パスを追加します
cargo:rustc-cfg=FLAG	コード内で #[cfg(FLAG)] を有効にします
cargo:rustc-env=KEY=VAL	コンパイル時に env!("KEY") を設定します
cargo:warning=MSG	ビルド警告を出力します

4. インクリメンタルビルドと CI キャッシュ

# GitHub Actions with sccache
- uses: Swatinem/rust-cache@v2
  with:
    cache-on-failure: true
    shared-key: "release-build"

# Or manual cache
- uses: actions/cache@v3
  with:
    path: |
      ~/.cargo/registry/index/
      ~/.cargo/registry/cache/
      ~/.cargo/git/db/
      target/
    key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

# Warm cache locally
cargo fetch                    # Download all deps without building
cargo build --tests            # Build everything including test bins

# Check if incremental hurts release builds (it often does)
[profile.release]
incremental = false            # Default; leave false for release

5. cargo nextest（高速なテストランナー）

# Install
cargo install cargo-nextest

# Run tests (parallel by default, better output)
cargo nextest run

# Run with specific filter
cargo nextest run test_name_pattern

# List tests without running
cargo nextest list

# Use in CI (JUnit output)
cargo nextest run --profile ci

nextest.toml：

[profile.ci]
fail-fast = false
test-threads = "num-cpus"
retries = { backoff = "exponential", count = 2, delay = "1s" }

[profile.default]
test-threads = "num-cpus"

6. 依存関係の管理と監査

# Check for security advisories
cargo install cargo-audit
cargo audit

# Deny specific licenses, duplicates, advisories
cargo install cargo-deny
cargo deny check

# Check for unused dependencies
cargo install cargo-machete
cargo machete

# Update dependencies
cargo update                    # Update to compatible versions
cargo update -p serde           # Update single package
cargo upgrade                   # Update to latest (cargo-edit)

deny.toml：

[licenses]
allow = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause"]
deny = ["GPL-2.0", "AGPL-3.0"]

[bans]
multiple-versions = "warn"
deny = [{ name = "openssl", reason = "Use rustls instead" }]

[advisories]
ignore = []  # List advisory IDs to ignore

7. 便利な cargo コマンド

# Build only specific binary
cargo build --bin myapp

# Build only specific example
cargo build --example myexample

# Run with arguments
cargo run -- --flag arg1 arg2

# Expand macros (for debugging proc macros)
cargo install cargo-expand
cargo expand module::path

# Tree of dependencies
cargo tree
cargo tree --duplicates      # Show crates with multiple versions
cargo tree -i serde          # Who depends on serde?

# Cargo.toml metadata
cargo metadata --format-version 1 | jq '.packages[].name'

ワークスペースのパターンと依存関係の解決の詳細については、references/workspace-patterns.md を参照してください。

関連スキル

• コンパイラフラグとプロファイル設定については、skills/rust/rustc-basics を使用します
• Cargo でビルドしたバイナリのデバッグについては、skills/rust/rust-debugging を使用します
• C ライブラリのバインディングで build.rs を使用する場合は、skills/rust/rust-ffi を使用します
• Rust を CMake ビルドに統合する場合は、skills/build-systems/cmake を使用します