Contents
導入とこの記事の狙い（全体像）
この文書は Rust を学び始めた初心者が、短時間で実務向けの開発環境を構築できることを狙いとしています。toolchain 管理からエディタ設定、WASM・クロスコンパイル、CI／セキュリティまで一通り手を動かせる状態を目指します。
初心者向け：まずこれをやる（実行順）
最短で動く開発環境を手に入れるための順序を示します。順に実行すれば Hello World の作成から CI での品質チェックまで進められます。
セクションへのショートカット（主要項目へのリンク）
以下は本文中の主要セクションへのショートカットです。必要な箇所へすばやく移動してください。
- 前提条件と OS 別注意点 → #前提条件と準備
- Rust toolchain と開発ツール → #rust-toolchainと開発ツールの管理
- エディタ・デバッグ（VS Code） → #エディタとデバッグ環境（vs-code中心）
- ハンズオン（WASM / クロス） → #実践ハンズオンhello-world→wasm→クロスコンパイル
- CI と運用・セキュリティ → #ci・再現性・セキュリティgithub-actionsと運用ルール
実行順（初心者がまず行うこと）
まずは最低限これを順に実行してください。各手順は本文で詳述します。
- 共通前提（Git, ターミナル, ネットワーク）を満たす。
- rustup をインストールして stable を既定にする。
- cargo new でサンプルプロジェクトを作成してビルドする。
- VS Code に rust-analyzer とデバッガ拡張を入れ、launch.json を用意する。
- cargo fmt と cargo clippy を動かし、CI テンプレートを追加する。
- 必要に応じて wasm や musl ターゲットを追加し、クロスビルドを確認する。
Apple Silicon の PATH 例
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
|
1 2 3 4 5 6 7 8 9 |
### Linux（主要ディストリでの前提パッケージ） Linux ではビルドツールとヘッダが必要です。Debian/Ubuntu 系の例を示します。 ```bash sudo apt update sudo apt install -y build-essential curl pkg-config libssl-dev cmake git clang |
musl や aarch64 クロス用に QEMU や各種クロスツールが必要になる場合があります。ディストリ固有のパッケージ名や手順は各ディストリのドキュメントに従ってください。
rust-toolchain と開発ツールの管理
toolchain の管理と、フォーマッタ／リンタ等のツール導入は一か所で整理すると運用が楽になります。ここで再現性と安全性の方針を示します。
rustup の基本運用
rustup は公式の toolchain 管理ツールです。実務では stable を既定にして、プロジェクト単位で必要な場合に nightly をピンする運用が現実的です。代表的なコマンド例は以下です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# stable をインストールして既定にする rustup toolchain install stable rustup default stable # 必要なら nightly をプロジェクト単位でインストール rustup toolchain install nightly # 代表的なコンポーネント rustup component add rustfmt clippy rust-src llvm-tools-preview # WASM や musl 等のターゲット rustup target add wasm32-unknown-unknown rustup target add x86_64-unknown-linux-musl |
運用上のポイントは、チームで rust-toolchain.toml をリポジトリに置き、toolchain を明示的に共有することです。
rust-toolchain.toml の書き方と運用方針
プロジェクトのルートに rust-toolchain.toml を置くと、そのプロジェクトで使う toolchain を自動で選択できます。例:
|
1 2 3 4 5 |
[toolchain] channel = "stable" components = ["rustfmt", "clippy", "rust-src"] targets = ["wasm32-unknown-unknown"] |
- ファイルはリポジトリにコミットして再現性を高めてください。
- Nightly を利用する場合は原因と必要な機能を README に明記してください。
フォーマッタ／Clippy／ツール導入の方針（集中管理）
フォーマッタやリンタ、ビルド補助ツールはバージョン固定と導入方法を統一します。ローカル環境では rustup component（rustfmt, clippy）を使い、外部 CLI ツールは可能な限り OS のパッケージマネージャや公式インストーラを優先します。cargo install を使う場合は必ずバージョンを固定してください。
推奨例:
- rustfmt, clippy は rustup component から導入する
- wasm-pack や trunk を使う場合は、可能なら公式インストーラやリリースバイナリを利用する
- cargo install を CI 等で使う場合は --version で固定する（例: cargo install --version 0.10.1 wasm-pack）
セキュリティ上の注意点については CI セクションで詳述します。
エディタとデバッグ環境（VS Code中心）
VS Code は rust-analyzer と組み合わせると生産性が高まります。ここでは設定例と実運用での注意点を示します。設定キーや既定値は拡張のバージョンで変わることがあるため、公式ドキュメントを必ず確認してください。
VS Code の拡張と推奨設定例
まずは拡張を導入します。一般的には rust-analyzer と CodeLLDB を入れます。以下は推奨設定の例です。
|
1 2 3 4 5 6 7 8 9 10 |
{ "editor.formatOnSave": true, "files.watcherExclude": { "**/target/**": true }, "rust-analyzer.cargo.features": "all", "rust-analyzer.checkOnSave.command": "clippy", "rust-analyzer.procMacro.enable": true } |
この設定は一例です。rust-analyzer の設定名や既定値は変わることがあるため、公式ドキュメント（rust-analyzer の manual）を参照してください。
公式参照（主なもの）:
- rust-analyzer: https://rust-analyzer.github.io/
- CodeLLDB（拡張ページ）: 拡張の説明を参照
launch.json の具体例（バイナリ名の明示）
launch.json の program フィールドはビルドされた実行ファイルへのパスを指定します。プロジェクト名が hello_rust の場合、デバッグ用の program は target/debug/hello_rust になります。具体例:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
{ "version": "0.2.0", "configurations": [ { "name": "Debug (CodeLLDB)", "type": "codelldb", "request": "launch", "program": "${workspaceFolder}/target/debug/hello_rust", "args": [], "cwd": "${workspaceFolder}" } ] } |
手順:
1. cargo build を実行する。
2. target/debug に出力されたバイナリ名を確認する（Cargo.toml の package.name が使われます）。
3. launch.json の program をそのパスに合わせる。
代替 IDE と注意点
Neovim や IntelliJ Rust（JetBrains 製）は選択肢として有効です。Neovim は LSP と DAP の組み合わせで構成します。IntelliJ Rust は深い統合を提供しますがプラグインやバージョンによる挙動差を確認してください。
実践ハンズオン Hello World → WASM → クロスコンパイル
ここでは最短で動かすコマンド例と、WASM／musl に関する実務的な注意点を示します。各手順はコマンドを順に実行して確認してください。
最短コマンド一覧（Hello→ビルド→テスト）
導入後に以下を順に実行します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# toolchain を導入済みと仮定 rustup toolchain install stable rustup component add rustfmt clippy rust-src llvm-tools-preview # プロジェクト作成 cargo new hello_rust --bin cd hello_rust # ビルド・実行・テスト cargo build cargo run cargo test |
正常に実行できれば開発環境が基本的に整っています。
WASM の実務手順と wasm-bindgen に関する注意点
WASM 対応の基本はターゲット追加とビルド、必要なら wasm-bindgen / wasm-pack でバインディング生成です。代表例:
|
1 2 3 4 5 6 7 8 |
# ターゲット追加 rustup target add wasm32-unknown-unknown # ライブラリを npm 連携する場合の一例（ライブラリ向け） cargo install --version 0.10.1 wasm-pack wasm-pack build --target web |
wasm-bindgen-cli を使う場合:
|
1 2 3 4 5 6 7 8 |
# 例: バージョンを固定してインストール cargo install wasm-bindgen-cli --version 0.2.92 # ビルドして wasm-bindgen を使う例 cargo build --target wasm32-unknown-unknown --release wasm-bindgen target/wasm32-unknown-unknown/release/hello_rust.wasm --out-dir pkg --target web |
重要な注意点:
- wasm-bindgen の CLI と crate のバージョンは互換性が重要です。crate のバージョン（Cargo.toml）に合わせて CLI を選んでください。
- wasm-pack を使うと CLI 操作が簡素化される場合があります。用途（ライブラリ vs アプリ）に合わせて使い分けてください。
- wasm 関連ツールをインストールする際はバージョン固定をおすすめします。CI でも同じバージョンを使って再現性を確保してください。
- トラブル例: wasm-bindgen 実行時に "unsupported command" や "ABI mismatch" が出る場合は、wasm-bindgen のバージョン差異を疑ってください。
公式ドキュメント（参照）:
- wasm-bindgen: https://rustwasm.github.io/wasm-bindgen/
- wasm-pack: https://rustwasm.github.io/wasm-pack/
musl とクロスコンパイルの実務的注意点
musl ターゲットで静的バイナリを作る場合、ネイティブ依存やリンカの存在がカギになります。ローカルで試す場合は musl-tools 等をインストールし、必要に応じて linker を指定します。代表的な手順:
|
1 2 3 4 5 6 7 8 9 10 11 |
# ターゲット追加 rustup target add x86_64-unknown-linux-musl # Debian/Ubuntu の例（ローカルで試すとき） sudo apt install musl-tools # cross を使う例（Docker ベースで安定） cargo install cross cross build --target x86_64-unknown-linux-musl --release |
典型的な失敗例と解決策:
- エラー "linker x86_64-linux-musl-gcc not found"：musl-gcc や musl-tools がインストールされていない、または PATH にないことを疑います。cross を使うと多くのローカル設定問題を回避できます。
- ネイティブライブラリ（openssl 等）が glibc に依存する場合：静的リンクが失敗します。解決策は静的ビルド可能なバージョンを用意するか、glibc ベースのコンテナでビルドする、あるいは musl 対応版ライブラリを使うことです。
- .cargo/config.toml で linker を明示的に設定することが必要な場合があります。
CI・再現性・セキュリティ（GitHub Actions と運用ルール）
CI では toolchain 固定、キャッシュ、静的解析、脆弱性チェックを組み合わせると安全に素早く回せます。ここでは実務で使えるテンプレートと注意点を示します。
GitHub Actions の実務テンプレ例（キャッシュの扱いとフォールバック）
ライブラリプロジェクトでは Cargo.lock がない場合があります。Cargo.lock の有無に応じてキャッシュキーを切り替える例を示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
name: CI on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Rust toolchain uses: actions-rs/toolchain@v1 with: toolchain: stable components: rustfmt, clippy override: true - name: Cache cargo registry and target (when Cargo.lock exists) if: ${{ hashFiles('**/Cargo.lock') != '' }} uses: actions/cache@v3 with: path: | ~/.cargo/registry ~/.cargo/git target key: ${{ runner.os }}-cargo-lock-${{ hashFiles('**/Cargo.lock') }} - name: Cache cargo registry and target (fallback when no Cargo.lock) if: ${{ hashFiles('**/Cargo.lock') == '' }} uses: actions/cache@v3 with: path: | ~/.cargo/registry ~/.cargo/git target key: ${{ runner.os }}-cargo-toml-${{ hashFiles('**/Cargo.toml') }} - name: Format check run: cargo fmt -- --check - name: Lint run: cargo clippy --all-targets --all-features -- -D warnings - name: Test run: cargo test --all --verbose |
ポイント:
- Cargo.lock が存在するかでキャッシュキーを切り替えています。
- target ディレクトリのキャッシュは容量が大きくなるため整理とキー設計が重要です。
外部ツール導入のセキュリティとバージョン固定
CI/ローカルで cargo install を多用する場合は再現性と安全性に注意してください。
推奨事項:
- cargo install を使う場合は --version でバージョン固定を行う。
- 可能なら公式パッケージや OS のパッケージ管理、または GitHub Release の tarball を使う。
- 自動インストールスクリプトをパイプで実行する場合はソースの信頼性を確認し、CI では明示的にバージョン指定する。
- 外部ツールのインストールは最小限にし、DevContainer や Docker イメージに統合してチームで共有する。
脆弱性チェックと運用ルール
CI に cargo-audit や cargo-deny を組み込むと脆弱性検出が自動化できます。また運用ルールとして以下を推奨します。
- rust-toolchain.toml をリポジトリに必ずコミットする。
- バイナリプロジェクトは Cargo.lock をコミットする。ライブラリは通常コミットしない方針を確認する。
- Nightly を使う場合は README に理由と影響範囲を明記する。
- DevContainer や Docker イメージで開発環境を固定する。
よくあるトラブルと対処の優先順
代表的なトラブルとまず確認すべき点を列挙します。
- linker がない：必要な Build Tools（Windows）や build-essential（Linux）をインストールしてください。
- rustfmt / clippy が動かない：rustup component add rustfmt clippy を実行してください。
- デバッガが動かない：LLDB/GDB のインストール、拡張のバージョン、実行権限を確認してください。Windows では MSVC のデバッガや CodeLLDB を試してください。
- Proxy / オフライン環境：HTTP(S)_PROXY の設定や事前ダウンロードで対応します。
まとめ
要点を短く整理します。rustup で stable を既定にし、rust-toolchain.toml をリポジトリに置いて再現性を高めます。VS Code と rust-analyzer、CodeLLDB でエディタとデバッグを整え、cargo fmt と cargo clippy をローカルと CI で自動化します。WASM や musl のクロスコンパイルはターゲット追加と外部ネイティブ依存の取り扱いに注意し、CI では toolchain 固定・キャッシュ戦略・脆弱性チェックを組み合わせて安全に運用してください。
参考リンク（公式優先、第三者は補助として記載）
- Rust 公式入門: https://www.rust-lang.org/learn/get-started
- rustup: https://rust-lang.github.io/rustup/
- rust-analyzer: https://rust-analyzer.github.io/
- wasm-bindgen: https://rustwasm.github.io/wasm-bindgen/
- wasm-pack: https://rustwasm.github.io/wasm-pack/
- cross（クロスビルドツール）: https://github.com/rust-embedded/cross
補助的な実務解説（参考、公式を優先して参照してください）
- MSYS2（Windows + MinGW）: https://www.msys2.org/
- musl libc: https://musl.libc.org/