rust-windows-setup

Windows で Rust ツールチェーンを安定してインストールする

このスキルで解決できること

Windows で Rust をセットアップするとき、本当の落とし穴は Rust 自体ではなく、次の3つであることがよくあります。

1. rustup の公式ミラーからのダウンロードが遅い／途中で切れやすい → インストールがタイムアウトで中断される → ツールチェーンが中途半端にしかインストールされない → 次のエラーが発生する error: Missing manifest in toolchain 'stable-x86_64-pc-windows-gnu'。
2. C コンパイラーが必要（rusqlite、openssl-sys などの bundled 機能では C コードがコンパイルされます）が、Windows では MinGW の gcc か MSVC の cl.exe を使う必要があり、どちらにも PATH／環境変数の落とし穴があります。
3. ミラーや PATH が「システム全体」に設定されていない（~/.bashrc にだけ記述されている）ため、PowerShell／cmd／VS Code ターミナルに切り替えると機能しなくなります。

このスキルでは、一度で正しくセットアップする方法を紹介し、何度も再インストールする事態を防ぎます。

使用するタイミング

• 新しいマシン（特に中国国内の Windows）に Rust を一からインストールするとき。
• ビルド時に Missing manifest が発生するとき。
• C 依存関係を含む crate のビルド時に dlltool.exe: program not found が発生する、またはリンカーが見つからないとき。
• Rust 環境を「どのターミナルでもすぐ使える」状態にしたいとき。

基本方針

• ミラーと環境変数は Windows のユーザーレベル（レジストリ）に設定し、~/.bashrc にだけ記述しないでください—— ~/.bashrc は git-bash でしか有効にならず、rustup.exe は Windows プログラムなので、PowerShell／cmd からは読み取れません。
• まず MSVC を使ってください（Rust の Windows におけるデフォルトの target）。最も手間がかかりません。MinGW は代替手段です。

---

ステップ1：rustup の中国国内ミラーを設定する（ダウンロードのタイムアウト対策として重要）

PowerShell を使って Windows のユーザー環境変数に書き込みます（.NET を使うことで、setx の1024文字での切り詰めや、git-bash が $ を変数として展開する問題を避けます）。

[Environment]::SetEnvironmentVariable("RUSTUP_DIST_SERVER", "https://rsproxy.cn", "User")
[Environment]::SetEnvironmentVariable("RUSTUP_UPDATE_ROOT", "https://rsproxy.cn/rustup", "User")

確認（新しいターミナルを開いてから実行します）：

(Get-ItemProperty 'HKCU:\Environment').RUSTUP_DIST_SERVER

https://rsproxy.cn が返されるはずです。

ステップ2：cargo の crates ミラーを設定する（依存関係のダウンロードを高速化）

~/.cargo/config.toml を新規作成／追記します（cargo はシェルに関係なく、このファイルを直接読み込みます）。

[source.crates-io]
replace-with = "rsproxy-sparse"
[source.rsproxy-sparse]
registry = "sparse+https://rsproxy.cn/index/"
[registries.rsproxy]
index = "https://rsproxy.cn/crates.io-index"

ステップ3：Rust をインストールする

# 用国内镜像后的 rustup-init（下载快）
# 推荐直接装 MSVC 默认 target，见步骤四
winget install -e --id Rust.Rustup
# 或手动：
#  curl -sSf https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe -o rustup-init.exe
#  ./rustup-init.exe -y

ステップ4：C ツールチェーンを選択する（2つの選択肢。A を推奨）

方法 A（推奨）：MSVC —— 最も手間がかかりません

Visual Studio Build Tools のインストーラー1つで、C コンパイラーの cl.exe とリンカーの link.exe をまとめてインストールできます。また、rustc は vswhere を使って link.exe を自動検出するため、手動で PATH を設定する必要はありません。

# 1. 装 VC++ Build Tools（含 MSVC v143 + Windows SDK，需管理员/UAC 弹窗）
winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
  --override "--add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.Windows11SDK.26100 --includeRecommended --passive"

# 2. 装并切到 msvc target
rustup toolchain install stable-x86_64-pc-windows-msvc
rustup default stable-x86_64-pc-windows-msvc

# 3.（可选）卸掉 gnu，避免以后混淆
rustup toolchain uninstall stable-x86_64-pc-windows-gnu

以降は、cargo build／cargo install に --target を付ける必要はなく、どのターミナルからでもそのまま使えます。

方法 B（代替）：MinGW gnu —— PATH の設定が必須です

# 1. 装 MSYS2
winget install -e --id MSYS2.MSYS2 --accept-package-agreements --accept-source-agreements --silent
# 2. 在 MSYS2 里装 mingw gcc + binutils（注意：第一次 pacman -Syu 会弹“关闭终端”确认，
#    非交互会杀掉进程；用 -Sy 只刷新再 -S 装，避开它）
#    C:\msys64\usr\bin\bash.exe -lc "pacman -Sy --noconfirm; pacman -S --needed --noconfirm mingw-w64-x86_64-gcc mingw-w64-x86_64-binutils"
# 3. 关键：把 C:\msys64\mingw64\bin 加进 Windows 用户 PATH（否则 dlltool/ld 找不到）

C:\msys64\mingw64\bin を Windows のユーザー PATH に追加します（PowerShell を使うことで、切り詰めを避けられます）。

$p = [Environment]::GetEnvironmentVariable("Path", "User")
if (-not $p.Contains("msys64\mingw64\bin")) {
  [Environment]::SetEnvironmentVariable("Path", ($p.TrimEnd(";") + ";C:\msys64\mingw64\bin"), "User")
  Write-Host "已添加 C:\msys64\mingw64\bin 到用户 PATH"
}

ワンステップスクリプト（任意）

このスキルには scripts/setup-rust-windows.ps1 が付属しており、管理者権限の PowerShell から実行すると、ミラーの設定、rustup のインストール、VC++ Build Tools のインストール、msvc target への切り替え、検証を一度に行えます。

powershell -ExecutionPolicy Bypass -File scripts/setup-rust-windows.ps1

VS Build Tools のインストール時には UAC が表示され、管理者権限が必要です。それ以外の手順は一般ユーザーで実行できます。

ステップ5：検証する

新しいターミナルを開き（環境変数を反映させます）、次を実行します。

rustc --version
cargo --version
cargo build        # 或 cargo build --target x86_64-pc-windows-gnu（方案 B）

---

トラブルシューティング早見表

エラー／現象	原因	解決方法
Missing manifest in toolchain 'stable-x86_64-pc-windows-gnu'	ツールチェーンのダウンロードがタイムアウト／中断され、半分しかインストールされていない	まず rustup ミラーを設定してから（ステップ1）、rustup toolchain uninstall <名字> → rustup toolchain install <名字> --profile minimal でクリーンインストールします
~ で cargo を実行するとヘルプが表示されるのに、プロジェクトディレクトリで cargo を実行すると Missing manifest が発生する	見かけ上の問題：引数なしの cargo はヘルプを表示するだけで、rustc を呼び出さないため、不正なツールチェーンが表面化しません。プロジェクトに入るとツールチェーンを実際に解析するため、エラーになります	rustc --version を直接確認します。不正な状態であれば、前の行の手順で再インストールします
error: error calling dlltool 'dlltool.exe': program not found	MinGW の dlltool が PATH にありません（cc のリンク段階で明示的に呼び出す必要があります）	方法 B の場合、C:\msys64\mingw64\bin が Windows のユーザー PATH に追加されていることを確認します（ステップ4、方法Bの3）
cargo build が downloading N components のまま長時間進まない	rustup の公式ミラーが遅い	ミラーが有効になっていません。ステップ1を再確認します（HKCU\Environment に rsproxy の値があるかどうか）
git-bash で reg query／powershell を実行すると構文エラーになる	git-bash がバックスラッシュや $ をエスケープ／展開しています	powershell -Command の引数をシングルクォートで囲みます。正規表現内の \m は無効なので、リテラルの部分文字列を判定する .Contains() に置き換えます

備考

• ミラー環境変数（ステップ1、2）は一度設定すれば十分です。レジストリに書き込むと、以降は新しいターミナルすべてに自動的に引き継がれます。
• マシンが海外にあり、公式ミラーの速度に問題がなければ、ミラーの手順は省略できます。ただし、PATH（方法Aでは設定不要／方法Bでは必須）は引き続き重要です。
• 動機となった事例：mco-org/squad（Rust + rusqlite bundled）に pi のサポートを追加した際、問題に直面しながら検証を通過した一連の手順は、このスキルに沿って実施しました。