apt install -y curl build-essential   # curl 下载脚本，build-essential 提供 gcc 链接器
export RUSTUP_DIST_SERVER=https://rsproxy.cn
export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
curl --proto '=https' --tlsv1.2 -sSf https://rsproxy.cn/rustup-init.sh | sh -s -- -y --profile minimal
source $HOME/.cargo/env

$ rustc --version
rustc 1.99.1 (58cf8f9c3 2026-10-13)
exit=0

$ cargo --version
cargo 1.99.1 (5f94df478 2026-08-27)

$ rustup toolchain list
stable-x86_64-unknown-linux-gnu (active, default)

$ which rustc && ls $HOME/.rustup/toolchains/
/root/.cargo/bin/rustc
stable-x86_64-unknown-linux-gnu

$ rustc -vV（详细版本：host/LLVM 后端）
rustc 1.99.1 (58cf8f9c3 2026-10-13)
binary: rustc
commit-hash: 58cf8f9c35b355199727627d07ae34a4e2846d67
commit-date: 2026-10-13
host: x86_64-unknown-linux-gnu
release: 1.99.1
LLVM version: 23.1.1

$ cat hello.rs
fn main() {
    println!("hello, rust");
}

$ rustc hello.rs（默认产出同名二进制）
exit=0

$ ls -l hello
-rwxr-xr-x 1 root root 4537856 Oct 17 03:12 hello

$ ./hello
hello, rust

$ rustc -O hello.rs -o hello-opt（-O 开优化，-o 改名）
-rwxr-xr-x 1 root root 4537048 Oct 17 03:12 hello-opt
hello, rust

$ rustc --edition=2021 hello.rs -o hello-2021（--edition 指定版本）
hello, rust

$ rustc --crate-type=lib hello.rs（编译成 rlib 库）
warning: function `main` is never used
 --> hello.rs:1:4
  |
1 | fn main() {
  |    ^^^^
  |
  = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default

warning: 1 warning emitted

exit=0

$ ls -l libhello.rlib
-rw-r--r-- 1 root root 6944 Oct 17 03:12 libhello.rlib

$ rustc --emit=asm hello.rs -o hello.s（导出汇编中间产物）
-rw-r--r-- 1 root root 8603 Oct 17 03:12 hello.s

$ cat bad.rs
fn main() {
    let x = 1;
    println!("{}", y);
}

$ rustc bad.rs
error[E0425]: cannot find value `y` in this scope
 --> bad.rs:3:20
  |
3 |     println!("{}", y);
  |                    ^
  |
help: a local variable with a similar name exists
  |
3 -     println!("{}", y);
3 +     println!("{}", x);
  |

error: aborting due to 1 previous error

For more information about this error, try `rustc --explain E0425`.
exit=1

$ rustc --error-format=json bad.rs（机器可读错误，截取）
{"$message_type":"diagnostic","message":"cannot find value `y` in this scope","code":{"code":"E0425",...},"level":"error","spans":[{"file_name":"bad.rs","line_start":3,"column_start":20,...}],"children":[{"message":"a local variable with a similar name exists","level":"help",...}],"rendered":"error[E0425]: ..."}

$ rustc --explain E0425（错误码官方解释，截取）
An unresolved name was used.

Erroneous code examples:

> 💡 说明： rustc 的诊断是三段式——`error[错误码]` 定位、`help:` 给修复建议（甚至直接给出 diff）、`--explain` 补背景；编译失败退出码固定为 1，链接期 panic 类错误是 101。

## 五、cargo 工程：new / run / build / test

```text
$ cargo new rustdemo
    Creating binary (application) `rustdemo` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
exit=0

$ cat rustdemo/Cargo.toml
[package]
name = "rustdemo"
version = "0.1.0"
edition = "2024"

[dependencies]

$ cat rustdemo/src/main.rs
fn main() {
    println!("Hello, world!");
}

$ cargo run（首次编译并运行）
   Compiling rustdemo v0.1.0 (/opt/rustdemo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.10s
     Running `target/debug/rustdemo`
Hello, world!
exit=0

$ cargo build（debug 构建）
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
exit=0

$ ls -l target/debug/rustdemo
-rwxr-xr-x 2 root root 4545688 Oct 17 03:12 target/debug/rustdemo

$ cargo build --release（release 构建，开优化）
   Compiling rustdemo v0.1.0 (/opt/rustdemo)
    Finished `release` profile [optimized] target(s) in 0.05s
exit=0

$ ls -l target/release/rustdemo
-rwxr-xr-x 2 root root 444760 Oct 17 03:12 target/release/rustdemo

$ cargo check（只查类型不产码，最快）
    Checking rustdemo v0.1.0 (/opt/rustdemo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
exit=0

$ cargo test（真实用例回显，截取尾部）
     Running unittests src/main.rs (target/debug/deps/rustdemo-6dd8dc5b6cf4b1a9)

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

$ cargo fmt --check
error: 'cargo-fmt' is not installed for the toolchain 'stable-x86_64-unknown-linux-gnu'.
help: run `rustup component add rustfmt` to install it
exit=1

$ rustup component add rustfmt（minimal profile 默认缺该组件）
info: downloading component rustfmt
exit=0

$ cargo fmt --check（装组件后通过，无输出）
exit=0

$ cargo clean（清空 target）
     Removed 140 files, 49.2MiB total
exit=0

$ cargo add rand
    Updating crates.io index
      Adding rand v0.10.3 to dependencies
             Features:
             + alloc
             + std
             + std_rng
             ...
    Updating crates.io index
     Locking 8 packages to highest Rust 1.99.1 compatible versions
      Adding cfg-if v1.0.5
      Adding chacha20 v0.10.2
      Adding cpufeatures v0.3.1
      Adding getrandom v0.4.3
      Adding libc v0.2.191
      Adding r-efi v6.0.0
      Adding rand v0.10.3
      Adding rand_core v0.10.1
exit=0

$ cat Cargo.toml（依赖已写入）
[package]
name = "rustdemo"
version = "0.1.0"
edition = "2024"

[dependencies]
rand = "0.10.3"

$ cargo run（首次尝试，旧 API）
   Compiling rand v0.10.3
   Compiling rustdemo v0.1.0 (/opt/rustdemo)
error[E0425]: cannot find function `thread_rng` in crate `rand`
 --> src/main.rs:4:19
  |
4 |     let n = rand::thread_rng().gen_range(1..=100);
  |                   ^^^^^^^^^^ not found in `rand`

warning: unused import: `rand::Rng`
 --> src/main.rs:1:5
  |
  = note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default

error: could not compile `rustdemo` (bin "rustdemo") due to 1 previous error; 1 warning emitted
exit=101

error[E0599]: no method named `random_range` found for struct `ThreadRng` in the current scope
   --> src/main.rs:4:25
    |
  4 |     let n = rand::rng().random_range(1..=100);
    |                         ^^^^^^^^^^^^
    |
   ::: /root/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/rand-0.10.3/src/rng.rs:163:8
    |
163 |     fn random_range<T, R>(&mut self, range: R) -> T
    |        ------------ the method is available for `ThreadRng` here
    |
    = help: items from traits can only be used if the trait is in scope
help: trait `RngExt` which provides `random_range` is implemented but not in scope; perhaps you want to import it
    |
  1 + use rand::RngExt;
    |

error: could not compile `rustdemo` (bin "rustdemo") due to 1 previous error; 1 warning emitted

$ cat src/main.rs
use rand::RngExt;

fn main() {
    let n = rand::rng().random_range(1..=100);
    println!("lucky number = {n}");
}

$ cargo run
   Compiling rand v0.10.3
   Compiling rustdemo v0.1.0 (/opt/rustdemo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.00s
     Running `target/debug/rustdemo`
lucky number = 55
exit=0

$ cargo run（第二次：编译缓存命中，直接运行）
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/rustdemo`
lucky number = 51

$ head -22 Cargo.lock（锁文件记录精确版本与哈希）
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4

[[package]]
name = "cfg-if"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"

[[package]]
name = "chacha20"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
dependencies = [
 "cfg-if",
 "cpufeatures",
 "rand_core",
]

$ cargo update（按 semver 更新依赖）
    Updating crates.io index
     Locking 0 packages to highest Rust 1.99.1 compatible versions
exit=0

$ cargo remove rand（移除依赖）
    Removing rand from dependencies
exit=0

$ rustup show（活动工具链与默认设置）
Default host: x86_64-unknown-linux-gnu
rustup home:  /root/.rustup

installed toolchains
--------------------
stable-x86_64-unknown-linux-gnu (active, default)

active toolchain
----------------
name: stable-x86_64-unknown-linux-gnu
active because: it's the default toolchain
installed targets:
  x86_64-unknown-linux-gnu

$ rustup component list --installed
cargo-x86_64-unknown-linux-gnu
rust-std-x86_64-unknown-linux-gnu
rustc-x86_64-unknown-linux-gnu

$ rustup target list --installed
x86_64-unknown-linux-gnu

$ rustup check（检查工具链与 rustup 自身更新）
stable-x86_64-unknown-linux-gnu - up to date: 1.99.1 (58cf8f9c3 2026-10-13)
rustup - up to date : 1.29.1

$ rustup --version
rustup 1.29.1 (d95a37b6a 2026-08-13)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: the currently active `rustc` version is `rustc 1.99.1 (58cf8f9c3 2026-10-13)`

$ cargo --list（子命令总表，截取前 26 行）
Installed Commands:
    add                  Add dependencies to a Cargo.toml manifest file
    b                    alias: build
    bench                Execute all benchmarks of a local package
    build                Compile a local package and all of its dependencies
    c                    alias: check
    check                Check a local package and all of its dependencies for errors
    clean                Remove artifacts that cargo has generated in the past
    clippy               Checks a package to catch common mistakes and improve your Rust code.
    config               Inspect configuration values
    d                    alias: doc
    doc                  Build a package's documentation
    fetch                Fetch dependencies of a package from the network
    fix                  Automatically fix lint warnings reported by rustc
    fmt                  Formats all bin and lib files of the current crate using rustfmt.
    generate-lockfile    Generate the lockfile for a package
    ...