[!info] Related notes

• 所属 MOC：工具链与工程结构 · 学习路线 · 语言基础
• 后续概念：程序结构、Cargo、Rustup
• 哲学入口：起源与设计哲学
• 命令速查：Cargo 命令速查

安装 Rust 并运行第一个程序

这个概念为什么出现

学语法之前，必须先有一条可验证的工具链路径：

• rustc / cargo / rustup 在 PATH 中
• 版本与默认工具链可知
• 能 cargo new 创建项目
• 能 cargo run / cargo test / cargo check

否则后续所有“报错”都分不清是代码问题还是环境问题。本篇是 howto：目标不是讲完语言，而是装好、跑通、知道坏了怎么查。

[!abstract] 一句话理解 用官方 rustup 安装稳定工具链 → 用 rustc -V/cargo -V/rustup show 验收 → cargo new 建项目 → cargo run 证明环境可用。

目标

完成后应满足：

1. rustc/cargo 能运行，并通过 rustup 确认当前目录实际使用的工具链
2. rustup show 能看到 default toolchain
3. 新建二进制项目 cargo run 打印预期输出
4. 理解默认二进制模板可能没有任何测试；成功退出不代表已有业务覆盖
5. 能区分“环境坏了”与“代码错了”

最小可运行示例

场景：新同事第一天要在笔记本上跑通订单服务脚手架

不必接数据库。先证明：本机能编译、能跑、能测。
官方推荐用 rustup 安装，用 Cargo 管理项目，而不是手工东拼西凑编译器路径。

// src/main.rs —— cargo new hello_rust 默认会生成类似入口
// 业务意图：进程启动时打印就绪信息，证明二进制可执行。
// 教学点：二进制 crate 的入口是 main；cargo run 负责编译并执行。

fn main() {
    // 订单脚手架就绪日志（示例文案）
    println!("hello, Rust");
}

建议运行：

# 1) 安装（Linux/macOS 官方脚本；Windows 见 rustup 官网）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 按提示加载环境，例如：
# . "$HOME/.cargo/env"

# 2) 验收
rustc --version
cargo --version
rustup show
rustup show active-toolchain

# 3) 创建项目（选择不存在的目录）
cargo new hello_rust
cd hello_rust
# 将上面的 Rust 代码写入 src/main.rs，替换默认内容后再运行
cargo run
cargo test
cargo check

期望输出（cargo run 关键行）：

hello, Rust

如果未替换 src/main.rs，默认模板通常打印 Hello, world!，不是上面的文案。默认二进制模板通常报告 0 tests；它只验证测试构建流程可运行。

结合场景再看三个关注点

1. rustup 管工具链，cargo 管项目：装错成“只有某个 IDE 插件”会导致命令行不可复现。
2. cargo check 快于完整链接：日常改代码先 check，再 run/test。
3. 测试数量也要看：cargo test 成功且 0 tests 不代表代码行为已验证，后续需为实际逻辑添加测试。

核心步骤与准确模型

1. 安装受支持版本

• 首选：Install Rust 的 rustup
• 组件默认通常包含：rustc、cargo、rust-std 等
• rustfmt、clippy 常由 default profile 安装；minimal profile 不一定包含，可按需添加（见 Clippy 与 rustfmt）
• 编译还需要平台链接工具：Linux 通常需 C 链接工具链（Debian/Ubuntu 可用 build-essential）；macOS 需 Xcode Command Line Tools；Windows MSVC 路线需相应 Visual Studio C++ Build Tools 与 Windows SDK，按 rustup 提示安装

rustup component add rustfmt clippy

2. 验收环境

命令	你在确认什么
rustc --version	编译器在 PATH
cargo --version	构建工具在 PATH
rustup show / rustup show active-toolchain	已装工具链与当前目录的实际选择；项目覆盖可不同于默认工具链
rustup update stable	更新 stable 通道，会改变编译器版本；不是只读验收命令

3. 项目闭环

cargo new hello_rust
├── Cargo.toml    # 包清单
└── src/main.rs   # 二进制入口

常用命令：

命令	作用
cargo run	编译（debug）并运行
cargo build	只构建
cargo build --release	优化构建
cargo test	跑测试
cargo check	检查代码，通常省略最终二进制链接；仍可能构建/运行构建脚本和过程宏

4. 排错心智

现象	优先怀疑
command not found: cargo	PATH / 未 source env / 安装未完成
能 rustc 不能 cargo	核对是否混用了系统包、rustup 或不同 PATH，再修复安装
linker cc not found / MSVC 链接失败	平台链接器、开发工具或 SDK 缺失，不能仅靠 cargo check 成功判断可执行文件已可用
网络失败拉依赖	代理/镜像/防火墙（crates.io）
编辑器红、命令行绿	IDE 组件/工具链指向不一致

边界情况与反直觉行为

• 系统包管理器的 rustc 可能过旧：学习与现代 edition 建议 rustup 主路径。
• sudo 安装通常不推荐：用户级 rustup 更易管理多工具链。
• 企业代理环境：Cargo 依赖下载与 rustup 工具链下载的配置不同；Cargo 的 config.toml 不能统一控制两者，应按组织的代理/镜像说明分别配置。

常见误区

[!warning] 常见误区：只装 IDE 插件不装工具链 错误理解：装了编辑器扩展就能学 Rust。
正确模型：扩展依赖本机 rust-analyzer + 工具链。
为何易错：其他语言有时“插件自带 runtime”的错觉。

工程实践

1. stable 是滚动通道，不是固定版本；需要复现时在 rust-toolchain.toml 固定具体工具链版本。edition 由 Cargo.toml 声明，2024 edition 至少需要 Rust 1.85。
2. CI 使用与项目一致的工具链和依赖锁定策略，运行 cargo fmt --check、cargo clippy、cargo test；仅“同一 major”无法固定 Rust 1.x 各版本的行为。
3. 学会读 rustc 错误索引与 cargo 输出的文件:行号。

验证记录：在已有 Linux / Rust 1.90.0 工具链下，新建临时项目并写入本文源码，run 输出 hello, Rust，test 报告 0 tests，check 成功。为避免创建额外 Git 仓库，验证时使用 cargo new 的 --vcs none；本轮未重新执行安装脚本或 Windows/macOS 安装。

本节总结

• 安装用 rustup，项目用 cargo。
• 验收三件套：rustc / cargo / rustup show。
• 第一天目标是 run/test/check 闭环，不是背完语法。

自测题

概念题

1. rustup 与 cargo 各解决什么问题？

操作题

2. 如何验证 clippy 已安装？

参考答案

1. rustup：工具链/组件/target；cargo：构建、依赖、测试、运行。
2. rustup component list --installed | rg clippy 或直接 cargo clippy -V。

延伸阅读与资料来源

资料	类型	支撑内容
Install Rust	官方	安装入口
rustup book	官方	工具链管理
Cargo Book	官方	项目与命令
The Book ch01	官方书	入门闭环