rust-project-setup

Rust プロジェクトのセットアップ

適切な設定、リント、CI を備えた新しい Rust プロジェクトをセットアップするための手順ガイドです。

クイックリファレンス

トピック	リファレンス
Cargo.toml の設定、プロファイル、依存関係	references/cargo-config.md
ワークスペースの構成、メンバーの配置、共有依存関係	references/workspace-layout.md
GitHub Actions CI、キャッシュ、MSRV チェック	references/ci-setup.md
フィーチャーフラグ、条件付きコンパイル、ビルドスクリプト	references/features-conditional.md
no_std 開発、組み込みターゲット、クロスコンパイル	references/no-std.md

新規プロジェクトのチェックリスト

1. プロジェクトを作成する

# Binary
cargo init my-app

# Library
cargo init --lib my-lib

# Workspace (create Cargo.toml manually)
mkdir my-workspace && cd my-workspace

2. Cargo.toml を設定する

edition、rust-version（MSRV）、メタデータを設定します。

[package]
name = "my-app"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"

3. リントを設定する

clippy と rustfmt の設定を追加します。

# Cargo.toml
[lints.clippy]
all = { level = "deny", priority = 10 }
pedantic = { level = "warn", priority = 3 }

[lints.rust]
future-incompatible = "warn"
nonstandard_style = "deny"
# unsafe_op_in_unsafe_fn is deny-by-default in edition 2024 — no need to set it

Edition 2024 のリントのデフォルト設定：unsafe_op_in_unsafe_fn はデフォルトで deny です。unsafe fn 内の unsafe 操作には、明示的な unsafe {} ブロックが必要です。gen キーワードは予約されています。識別子として必要な場合は r#gen を使用してください。

# rustfmt.toml
edition = "2024"
reorder_imports = true
imports_granularity = "Crate"
group_imports = "StdExternalCrate"

4. プロファイルを設定する

[profile.release]
lto = true
codegen-units = 1
strip = true

5. CI を設定する

check、clippy、test、fmt 用の GitHub Actions ワークフローを追加します。references/ci-setup.md を参照してください。

6. Cargo.lock のポリシー

• バイナリ：Cargo.lock をコミットします（再現可能なビルドのため）
• ライブラリ：Cargo.lock はコミットしないでください（利用者が自身のバージョンを解決します）
• ライブラリの場合は .gitignore に追加します：Cargo.lock

7. ドキュメントを設定する

ライブラリクレートでは、ドキュメント用リントを有効にします。

// src/lib.rs
#![deny(missing_docs)]

一時的な抑制には #[allow(lint)] より #[expect(lint)] を優先してください。抑制が不要になったときに警告が表示されます。

#[expect(dead_code, reason = "used in next PR")]
fn upcoming_feature() {}

ワークスペースと単一クレート

用途	使用する場面
単一クレート	小規模なプロジェクト、CLI ツール、シンプルなライブラリ
ワークスペース	関連する複数のクレート、共有依存関係、個別のコンパイルターゲット

ワークスペースでは、メンバー間で依存関係とビルド成果物を共有することで、コンパイル時間を短縮できます。

プロジェクト構成

バイナリ

my-app/
  Cargo.toml
  rustfmt.toml
  src/
    main.rs
    lib.rs      # separate logic from entry point
  tests/
    integration_test.rs

ライブラリ

my-lib/
  Cargo.toml
  rustfmt.toml
  src/
    lib.rs
    module_a.rs
    module_b/
      mod.rs
      types.rs
  tests/
    api_test.rs
  examples/
    basic_usage.rs

ワークスペース

my-workspace/
  Cargo.toml          # [workspace] definition
  rustfmt.toml        # shared formatting
  crates/
    core/             # shared types and logic
    api/              # HTTP server
    cli/              # command-line interface

依存関係のベストプラクティス

• バイナリでは正確なバージョンを固定します：serde = "=1.0.210"
• ライブラリではバージョン範囲を使用します：serde = "1"
• フィーチャーを明示的にグループ化します：tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
• テスト専用のクレートには [dev-dependencies] を使用します
• cargo tree で重複するバージョンを確認します
• セキュリティ上の脆弱性について cargo audit を実行します
• once_cell／lazy_static を std::sync::LazyLock に置き換えます（Rust 1.80 以降で安定版）

Edition 2024 への移行に関する注意事項

既存のプロジェクトを edition 2024 に移行する場合：

• unsafe fn の本体では、unsafe 操作を明示的な unsafe {} ブロックで囲む必要があります
• extern "C" {} ブロックは unsafe extern "C" {} と記述する必要があります
• #[no_mangle] と #[export_name] には、#[unsafe(no_mangle)] と #[unsafe(export_name)] が必要です
• gen は予約キーワードです。gen 識別子はすべて r#gen に変更するか、別の名前を選んでください
• -> impl Trait はデフォルトですべてのスコープ内ライフタイムをキャプチャします。正確に制御するには + use<'a> を使用してください
• !（never 型）は () ではなく ! にフォールバックします。match アームと発散式を確認してください
• if let および末尾式内の一時値は、より早くドロップされます。これらの位置でロックやガードを保持するコードを確認してください

機械的に変更できる項目の多くは、cargo fix --edition を実行すると自動修正できます。

セットアップ完了の判定条件

チェックリストの後に、非公式な「完了したように見える」ではなく、客観的な合格条件として次を使用してください。

1. マニフェストの読み込み — プロジェクトまたはワークスペースのルートから、cargo metadata --format-version 1 を実行します。**合格条件：**終了コードが 0 で、出力に想定どおりのクレート（パッケージの name が期待する名前と一致）が列挙されます。
2. Lint とフォーマット — cargo clippy --all-targets（警告を失敗扱いにする必要がある場合は -- -D warnings を追加）と cargo fmt --check を実行します。**合格条件：**CI を確かな基準として扱う前に、どちらも終了コード 0 になります。
3. CI の設定 — 実行する予定のワークフローをコミットしてあります（references/ci-setup.md を参照）。**合格条件：**少なくとも 1 回のパイプライン実行が、check、clippy、tests、fmt（または定義した対象の一部）について成功します。
4. ロックファイルの方針 — バイナリークレート：Cargo.lock がコミットされています（git ls-files Cargo.lock の出力が Cargo.lock になります）。ライブラリークレート：Cargo.lock は追跡されていません（git ls-files Cargo.lock の出力が空、またはファイルが Git の対象外に設定され、一度も追加されていません）。**合格条件：**予期しない Cargo.lock の変更がなく、インデックスがこの方針に一致しています。

関連スキル

• rust-best-practices — イディオムに沿ったパターンと Edition 2024 のコーディング指針
• rust-code-review — 所有権、unsafe、トレイト設計を対象としたコードレビュー