第一个 crate：从 cargo new 到 Span

Pebble 长什么样#

先把整个系统的数据流摆出来，后面每一章都是其中一个方框：

实线是数据，虚线是错误报告。所有阶段都要说”第几行第几列出错了”，所以最底下还有两个被所有人依赖的小 crate：pebble-span（位置）和 pebble-diag（错误报告）。我们今天从 pebble-span 起步，因为它是整张依赖图的叶子。

这个系列怎么读#

我定了几条规矩，因为我自己踩过”看懂了但写不出来”的坑。

边写边建。 每一章你会写某几个 crate 的核心部分，从一个最小版本开始，逐步长成仓库里的样子。重复、冗长、和本章主题无关的部分（比如 30 个只是名字不同的 builtin 函数），我会指名道姓让你从仓库里复制，并告诉你为什么现在可以不读。

实验场。 每次我说”这段代码不会编译”，你都应该自己试一遍。所以现在就建一个 ~/rust-lab（下面马上建），所有实验都是里面的一个文件，文件名我会写出来：src/bin/ch01_bindings.rs，ch 后面是章节号。（整个系列的全部实验已经放在仓库的 lab/rust-lab 里，可以直接复制过来，不必一个文件一个文件地敲；我还是建议你至少手敲前几个，错误信息是自己撞出来才记得住的。）

真实输出。 本系列里所有的编译错误、命令输出、测试统计，都是我在这台机器上用 rustc 1.95.0 实际跑出来的。输出偶尔会被截断（用 ... 标出），但每一行都不会被我改写。路径里的 /tmp/rust-lab 是我机器上的位置，你的会是 ~/rust-lab。如果你的编译器版本不同，措辞可能略有出入。

固定的代码快照。 我的参考实现是仓库的 tutorial-v1 标签。每章末尾有一个检查点，列出”到这里为止哪些文件必须和标签完全一致”（可以用 diff 验证），以及哪些文件是还会继续变的中间版本。

下面是整个系列的地图：

没有哪一章是”选读”。顺序就是依赖顺序：每一章只会用到前面讲过的东西，偶尔需要提前露个脸的概念，我会写明”先当成 X，第 N 篇细讲”。

装环境#

我用的是 rustc 1.95.0。仓库里有一个 flake.nix，nix develop 进去就是这个版本；没有 Nix 的话，用 rustup 装 stable，仓库的 rust-toolchain.toml 要求的就是 stable 加 rustfmt、clippy 两个组件：

1
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
2
rustup component add rustfmt clippy

确认一下：

1
$ rustc --version
2
rustc 1.95.0 (59807616e 2026-04-14) (built from a source tarball)
3
$ cargo --version
4
cargo 1.95.0 (f2d3ce0bd 2026-03-21)

rustc 是编译器，对应 gcc/clang。cargo 是构建系统加包管理器，对应 CMake 加 vcpkg/Conan 的合体。绝大多数时候你只和 cargo 说话，它再去调用 rustc。

实验场：你的第一个 cargo 项目#

1
cd ~
2
cargo new rust-lab --edition 2024
3
cd rust-lab

cargo new 创建了这些东西：

1
rust-lab/
2
├── Cargo.toml
3
├── .gitignore
4
└── src/
5
    └── main.rs

Cargo.toml 是项目清单（对应 CMakeLists.txt，但是是声明式的，没有脚本）：

1
[package]
2
name = "rust-lab"
3
version = "0.1.0"
4
edition = "2024"
5

6
[dependencies]

edition 是 Rust 的”方言版本”，大约每三年一个（2015、2018、2021、2024）。不同 edition 的 crate 可以互相链接，所以语言可以做不兼容的改进而不分裂生态。本系列全部用 2024。

src/main.rs 是 cargo new 替你写好的：

1
fn main() {
2
    println!("Hello, world!");
3
}

运行：

1
$ cargo run --quiet --bin rust-lab
2
Hello, world!

这里有三件事值得停一下。

第一，println! 后面的 ! 不是装饰：它表示这是一个宏，不是函数。Rust 的宏在编译期展开，所以 println!("{}", x) 的格式字符串是在编译期检查的：占位符数量不对，直接编译失败，而不是像 C 的 printf 那样运行时读栈上的垃圾。第 6 篇和第 10 篇我们会自己写宏。

第二，没有头文件。Rust 的编译单元是整个 crate（后面会讲），编译器能看到 crate 里所有的项，谁用谁不需要先声明。可见性靠 pub 关键字显式标注，默认私有。

第三，多出来的 target/ 目录：编译产物都在这里，target/debug/ 是调试构建，cargo run --release 会用 target/release/。它是 .gitignore 里的第一行，对应 CMake 的 build/。

接下来我们会在这个项目里往 src/bin/ 下面放实验文件（完整的实验场在 lab/rust-lab，cp -r ~/pebble-tag/lab/rust-lab ~/rust-lab 就能得到所有章节的文件），每个文件自动成为一个独立的可执行程序，名字是文件名（不带 .rs）。运行某一个：cargo run --quiet --bin ch01_bindings。--quiet 去掉 cargo 自己的 “Compiling…” 噪音。注意，一旦 src/bin/ 里有多个程序，单独一个 cargo run 会因为不知道跑哪个而报错，所以以后总是带 --bin（不带的话，cargo 会报错 “could not determine which binary to run”，并让你用 --bin 指定，我试过）。

1
mkdir -p src/bin

搭一个 workspace#

Pebble 有 16 个 crate。这里先把三个词分清楚，因为 C/C++ 里没有一一对应的概念：

• crate：Rust 的编译单元，一个库或一个可执行文件，从一个根文件（lib.rs 或 main.rs）开始，整个模块树编译成一个产物。粗略对应”一个静态库/可执行文件”，但编译器是把整个 crate 当成一个翻译单元来处理的。
• package：一个带 Cargo.toml 的目录，可以包含一个库 crate 和若干个二进制 crate。cargo 管理的是 package。
• workspace：一组共享同一个 Cargo.lock 和同一个 target/ 的 package。对应 CMake 的顶层工程加 add_subdirectory。

还有第四个词 module（模块），是 crate 内部的命名空间，对应 C++ 的 namespace，但和文件系统绑定（第 7 篇会写 mod cli;）。

现在开始。建一个新目录，不是 rust-lab，而是我们真正的项目：

1
cd ~
2
mkdir pebble && cd pebble
3
git init

写根目录的 Cargo.toml。注意它没有 [package]，只有 [workspace]，这叫虚拟 workspace：

1
[workspace]
2
resolver = "3"
3
members = ["crates/*"]
4

5
[workspace.package]
6
version = "0.1.0"
7
edition = "2024"
8
rust-version = "1.88"
9
authors = ["bfmhno3"]
10
license = "MIT OR Apache-2.0"
11
repository = "https://github.com/bfmhno3/pebble"
12
description = "Pebble: a small scripting language and toolchain, built from scratch in Rust."
13
keywords = ["language", "interpreter", "compiler", "vm", "learning"]
14
categories = ["development-tools", "compilers"]
15

16
[workspace.dependencies]
17
pebble-span = { path = "crates/pebble-span", version = "0.1.0" }
18

19
[workspace.lints.rust]
20
rust_2018_idioms = "warn"
21
unsafe_op_in_unsafe_fn = "warn"
22

23
[workspace.lints.clippy]
24
all = "warn"

逐段看：

• members = ["crates/*"]：crates/ 下每个子目录都是成员，以后加 crate 不用改这一行。
• resolver = "3"：依赖解析算法的版本。虚拟 workspace 没有根 package，cargo 没法从 edition 推断，所以得显式写。我试过不写：

1
warning: virtual workspace defaulting to `resolver = "1"` despite one or more workspace members being on edition 2024 which implies `resolver = "3"`
2
  |
3
  = note: to keep the current resolver, specify `workspace.resolver = "1"` in the workspace root's manifest
4
  = note: to use the edition 2024 resolver, specify `workspace.resolver = "3"` in the workspace root's manifest
5
...

• [workspace.package]：所有成员共享的元数据，一处定义，各 crate 用 version.workspace = true 引用，类似 CMake 里的顶层变量。rust-version = "1.88" 是我承诺支持的最低编译器版本（MSRV）。
• [workspace.dependencies]：统一管理依赖的版本，成员写 pebble-span.workspace = true 就行。现在只有一行，随着章节推进会长到 16 个内部 crate 加十几个外部依赖。path 指向本地目录，version 在将来发布到 crates.io 时才有用。
• [workspace.lints]：lint 是编译器和 clippy（官方的 linter）的警告开关。rust_2018_idioms 要求你写 2018 以来的惯用法；unsafe_op_in_unsafe_fn 第 11 篇讲；clippy::all 打开 clippy 的默认检查组。所有成员通过 [lints] workspace = true 继承它们。

再建 .gitignore，一行就够：

1
/target

现在让 cargo 创建第一个 crate。--lib 表示这是库，不是可执行文件：

1
$ cargo new --lib crates/pebble-span
2
    Creating library `pebble-span` package
3
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

因为目录在 workspace 里，cargo 已经替我们写好了继承行和 [lints]，crates/pebble-span/Cargo.toml 是这样的：

1
[package]
2
name = "pebble-span"
3
version.workspace = true
4
edition.workspace = true
5
rust-version.workspace = true
6
authors.workspace = true
7
license.workspace = true
8
repository.workspace = true
9
description.workspace = true
10
keywords.workspace = true
11
categories.workspace = true
12

13
[dependencies]
14

15
[lints]
16
workspace = true

我们只改两处：description 换成这个 crate 自己的一句话，keywords 和 categories 两行删掉（它们继承的是整个项目的描述，不适合单个 crate），空的 [dependencies] 也不需要。整个文件变成（文件 crates/pebble-span/Cargo.toml）：

1
[package]
2
name = "pebble-span"
3
description = "Source offsets, spans, and source maps for the Pebble toolchain."
4
version.workspace = true
5
edition.workspace = true
6
rust-version.workspace = true
7
authors.workspace = true
8
license.workspace = true
9
repository.workspace = true
10

11
[lints]
12
workspace = true

version.workspace = true 这种点号写法是 TOML 的普通语法，等价于 [package.version] 表里写 workspace = true。这个文件和仓库标签里的完全一致，以后不会再改。

cargo new 还生成了一个 lib.rs，里面有一个 add 函数和一个叫 it_works 的测试。这是它的模板，我们要整个换掉。先把这个文件清空，下面开始写真正的内容。

写 SourceId：一个零开销的 newtype#

编译器每个阶段都要说”出错在哪”。最朴素的做法是传两个整数：文件号和字节偏移。C 程序员这时候会写：

1
struct span { unsigned source; unsigned start; unsigned end; };

Rust 里可以写得几乎一样。但我想在这上面再加一点编译期的保护：文件号不是随便一个整数，不应该能和”偏移量”混着用。做法是把它包进一个只有一个字段的元组结构体，叫 newtype：

1
/// Identifies one source file.
2
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
3
pub struct SourceId(pub u32);

先把每个词过一遍：

• pub struct SourceId(pub u32);：struct 定义结构体；这种圆括号形式叫元组结构体，字段没有名字，按位置访问：id.0。里面的 pub 说明这个字段对外可见（默认私有）；u32 是 32 位无符号整数。
• /// 是文档注释，会进 cargo doc 生成的文档。仓库的规则是每个公开项都要有。
• #[derive(...)] 让编译器按字段自动生成 trait 的实现。trait 是第 2 篇才正式讲的东西，现在把它理解成”接口”，对应 C++ 的 concept 或抽象基类就够了。这里一口气派生了七个：
  • Copy 和 Clone：复制。Copy 的意思是”按位复制就是完整的复制”，和 C 里 struct 赋值一样（memcpy）。后面会看到，有些类型（比如拥有堆内存的 String）不能 Copy，第 2 篇解释为什么。
  • PartialEq 和 Eq：== 和 !=。
  • PartialOrd 和 Ord：<、> 和排序。
  • Hash：可以做哈希表的键。

这些在 C++ 里你需要手写 operator==（或者 C++20 的 = default），而 Rust 里一行 derive 搞定。

newtype 的价值我们实际看一下。下面是实验 src/bin/ch01_newtype.rs，里面有一个故意写错的调用：

1
let ok = Span::new(SourceId(0), 2, 9);
2
let bad = Span::new(0, 2, 9);

编译：

1
$ cargo build --bin ch01_newtype
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
error[E0308]: mismatched types
4
  --> src/bin/ch01_newtype.rs:21:25
5
   |
6
21 |     let bad = Span::new(0, 2, 9);
7
   |               --------- ^ expected `SourceId`, found integer
8
   |               |
9
   |               arguments to this function are incorrect
10
   |
11
...
12
help: try wrapping the expression in `SourceId`
13
   |
14
21 |     let bad = Span::new(SourceId(0), 2, 9);
15
   |                         +++++++++ +
16

17
For more information about this error, try `rustc --explain E0308`.
18
error: could not compile `rust-lab` (bin "ch01_newtype") due to 1 previous error

（完整文件在 lab 的实验清单 里说明；Span 的完整定义在下一节，先照抄下一节的 struct Span 与 Span::new 即可，外加上面的 SourceId。）这条错误里最重要的是编码 E0308：以后你会无数次见到它。rustc --explain E0308 会打印一段详细解释。

那它有运行时代价吗？没有。实验 ch01_sizes.rs：

1
$ cargo run -q --bin ch01_sizes
2
size_of::<SourceId>() = 4
3
size_of::<Span>()     = 12
4
size_of::<usize>()    = 8
5
0 2 9

SourceId 就是 4 个字节，和 unsigned 一模一样；Span 是 12 个字节，和上面那个 C 的 struct span 一样。类型安全完全是编译期的东西，编译完就蒸发了。顺便注意 usize：它是”指针宽度的无符号整数”，对应 C 的 size_t，在这台机器上是 8 个字节，用来做索引和长度。

1
impl fmt::Debug for SourceId {
2
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3
        write!(f, "source#{}", self.0)
4
    }
5
}

1
//! Source offsets and spans.
2
//!
3
//! Everything in the front end of the compiler talks about positions in terms
4
//! of *byte offsets into a source file*. Those offsets are grouped into
5
//! [`Span`]s.
6

7
use core::fmt;

写 Span：值、方法和表达式#

把 SourceId 的代码放在 use 的后面，紧接着写 Span：

1
/// A half-open byte range `[start, end)` inside a single source file.
2
///
3
/// `Span` is `Copy`: it is three small integers, so passing it around is free
4
/// and never moves any source text.
5
#[derive(Copy, Clone, PartialEq, Eq, Hash)]
6
pub struct Span {
7
    pub source: SourceId,
8
    pub start: u32,
9
    pub end: u32,
10
}

这是普通的带名字段结构体。半开区间 [start, end) 是我和你都应该熟悉的惯例（C++ 迭代器区间、Python 切片都是这样）：长度是 end - start，空区间是 start == end，相邻两个区间首尾相接不重叠。

Span 没有派生 PartialOrd：两个 span 比大小没有意义，我就不给它这个能力。另外它也没有派生 Debug，因为我想要紧凑的 2..9，一会儿手写。

1
impl Span {
2
    /// A span that points at nothing; useful as a placeholder.
3
    pub const DUMMY: Span = Span {
4
        source: SourceId(0),
5
        start: 0,
6
        end: 0,
7
    };
8

9
    /// Builds a span from a source id and a byte range.
10
    #[must_use]
11
    pub const fn new(source: SourceId, start: u32, end: u32) -> Self {
12
        Self { source, start, end }
13
    }

1
const fn double(x: u32) -> u32 { x * 2 }
2
fn triple(x: u32) -> u32 { x * 3 }
3

4
const A: u32 = double(21);
5
const B: u32 = triple(14);

1
$ cargo build --bin ch01_const_fn
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
error[E0015]: cannot call non-const function `triple` in constants
4
  --> src/bin/ch01_const_fn.rs:10:16
5
   |
6
10 | const B: u32 = triple(14);
7
   |                ^^^^^^^^^^
8
   |
9
note: function `triple` is not const
10
...

1
$ cargo build --bin ch01_must_use
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
warning: unused return value of `Span::len` that must be used
4
  --> src/bin/ch01_must_use.rs:15:5
5
   |
6
15 |     s.len();
7
   |     ^^^^^^^
8
   |
9
   = note: `#[warn(unused_must_use)]` (part of `#[warn(unused)]`) on by default
10
help: use `let _ = ...` to ignore the resulting value
11
...

1
    /// An empty span located at `at`.
2
    #[must_use]
3
    pub const fn empty(source: SourceId, at: u32) -> Self {
4
        Self {
5
            source,
6
            start: at,
7
            end: at,
8
        }
9
    }
10

11
    /// Number of bytes covered by the span.
12
    #[must_use]
13
    pub const fn len(self) -> u32 {
14
        self.end.saturating_sub(self.start)
15
    }
16

17
    /// Whether the span covers zero bytes.
18
    #[must_use]
19
    pub const fn is_empty(self) -> bool {
20
        self.start >= self.end
21
    }

1
fn main() {
2
    let a: u32 = 7;
3
    let b: usize = 3;
4
    let sum = a + b;
5
    println!("{sum}");
6
}

1
$ cargo build --bin ch01_casts
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
error[E0308]: mismatched types
4
 --> src/bin/ch01_casts.rs:4:19
5
  |
6
4 |     let sum = a + b;
7
  |                   ^ expected `u32`, found `usize`
8

9
error[E0277]: cannot add `usize` to `u32`
10
 --> src/bin/ch01_casts.rs:4:17
11
  |
12
4 |     let sum = a + b;
13
  |                 ^ no implementation for `u32 + usize`
14
  |
15
  = help: the trait `Add<usize>` is not implemented for `u32`
16
help: the following other types implement trait `Add<Rhs>`
17
...
18
error: could not compile `rust-lab` (bin "ch01_casts") due to 2 previous errors

1
println!("{}", a as usize + b);
2
println!("{}", a + b as u32);
3
println!("{}", 300_i32 as u8);
4
println!("{}", -1_i32 as u32);
5
println!("{}", 3.9_f64 as i32);
6
println!("{}", -1.0_f64 as u8);
7
println!("{}", u32::try_from(300_i64).unwrap());
8
println!("{:?}", u8::try_from(300_i32));

1
$ cargo run --quiet --bin ch01_casts_ok
2
10
3
10
4
44
5
4294967295
6
3
7
0
8
300
9
Err(TryFromIntError(()))

1
let big: u8 = std::hint::black_box(255);
2
println!("wrapping_add   = {}", big.wrapping_add(1));
3
println!("saturating_add = {}", big.saturating_add(1));
4
println!("checked_add    = {:?}", big.checked_add(1));
5
println!("overflowing    = {:?}", big.overflowing_add(1));
6
let plain = big + 1;
7
println!("big + 1        = {plain}");

1
$ cargo run --quiet --bin ch01_overflow
2
wrapping_add   = 0
3
saturating_add = 255
4
checked_add    = None
5
overflowing    = (0, true)
6

7
thread 'main' (51943) panicked at src/bin/ch01_overflow.rs:11:17:
8
attempt to add with overflow
9
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

1
$ cargo run --quiet --release --bin ch01_overflow
2
wrapping_add   = 0
3
saturating_add = 255
4
checked_add    = None
5
overflowing    = (0, true)
6
big + 1        = 0

1
fn add_one(x: u32) -> u32 {
2
    x + 1;
3
}

1
$ cargo build --bin ch01_tail_expr
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
error[E0308]: mismatched types
4
 --> src/bin/ch01_tail_expr.rs:1:23
5
  |
6
1 | fn add_one(x: u32) -> u32 {
7
  |    -------            ^^^ expected `u32`, found `()`
8
  |    |
9
  |    implicitly returns `()` as its body has no tail or `return` expression
10
2 |     x + 1;
11
  |          - help: remove this semicolon to return this value
12

13
For more information about this error, try `rustc --explain E0308`.
14
error: could not compile `rust-lab` (bin "ch01_tail_expr") due to 1 previous error

1
let block_value = {
2
    let a = 2;
3
    a * 10 // no semicolon: the block evaluates to this
4
};
5
let unit = {
6
    let a = 2;
7
    a * 10;
8
};
9
println!("{}", add_one(1));
10
println!("{block_value}");
11
println!("{unit:?}");

1
$ cargo run --quiet --bin ch01_tail_expr_ok
2
warning: unused arithmetic operation that must be used
3
  --> src/bin/ch01_tail_expr_ok.rs:12:9
4
   |
5
12 |         a * 10;
6
   |         ^^^^^^ the arithmetic operation produces a value
7
   |
8
   = note: `#[warn(unused_must_use)]` (part of `#[warn(unused)]`) on by default
9
help: use `let _ = ...` to ignore the resulting value
10
   |
11
12 |         let _ = a * 10;
12
   |         +++++++
13

14
2
15
20
16
()

1
let x = 5;
2
let x = x * 2; // shadowing: a brand new variable that reuses the name
3
{
4
    let x = "inner"; // shadowing may even change the type
5
    println!("inner x = {x}");
6
}
7
println!("outer x = {x}");
8

9
let mut count = 0;
10
count += 1;
11
count += 1;
12
println!("count = {count}");

1
$ cargo run --quiet --bin ch01_bindings
2
inner x = inner
3
outer x = 10
4
count = 2

1
$ cargo build --bin ch01_immutable
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
error[E0384]: cannot assign twice to immutable variable `y`
4
 --> src/bin/ch01_immutable.rs:3:5
5
  |
6
2 |     let y = 1;
7
  |         - first assignment to `y`
8
3 |     y = 2;
9
  |     ^^^^^ cannot assign twice to immutable variable
10
  |
11
help: consider making this binding mutable
12
  |
13
2 |     let mut y = 1;
14
  |         +++
15

16
warning: value assigned to `y` is never read
17
...

1
let n = 7;
2
let kind = if n % 2 == 0 { "even" } else { "odd" };
3
println!("{n} is {kind}");
4

5
let mut tries = 0;
6
let first_square_over_50 = loop {
7
    tries += 1;
8
    if tries * tries > 50 {
9
        break tries * tries;
10
    }
11
};
12
println!("first square over 50: {first_square_over_50}");

1
7 is odd
2
first square over 50: 64

1
let mut i = 0;
2
while i < 3 {
3
    print!("{i} ");
4
    i += 1;
5
}
6
println!();
7
for j in 0..3 {
8
    print!("{j} ");
9
}
10
println!();
11
for j in 0..=3 {
12
    print!("{j} ");
13
}
14
println!();

1
0 1 2
2
0 1 2
3
0 1 2 3

1
'outer: for row in 0..5 {
2
    for col in 0..5 {
3
        if row * col == 6 {
4
            println!("found {row} * {col} == 6");
5
            break 'outer;
6
        }
7
    }
8
}

1
found 2 * 3 == 6

1
    /// The smallest span covering both `self` and `other`.
2
    ///
3
    /// Both spans must belong to the same source file; the compiler guarantees
4
    /// this, and a debug build will panic if it is ever violated.
5
    #[must_use]
6
    pub fn merge(self, other: Span) -> Span {
7
        debug_assert_eq!(
8
            self.source, other.source,
9
            "tried to merge spans from different files"
10
        );
11
        Span {
12
            source: self.source,
13
            start: self.start.min(other.start),
14
            end: self.end.max(other.end),
15
        }
16
    }
17

18
    /// Whether `offset` falls inside the half-open range.
19
    #[must_use]
20
    pub const fn contains(self, offset: u32) -> bool {
21
        self.start <= offset && offset < self.end
22
    }
23
}

1
impl fmt::Debug for Span {
2
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3
        write!(f, "{}..{}", self.start, self.end)
4
    }
5
}
6

7
impl fmt::Display for Span {
8
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
9
        write!(f, "{}..{}", self.start, self.end)
10
    }
11
}

写测试#

Rust 的测试是语言内置的，没有 gtest，没有 CMake 的 add_test。在文件底部加：

1
#[cfg(test)]
2
mod tests {
3
    use super::*;
4

5
    #[test]
6
    fn merge_covers_both() {
7
        let a = Span::new(SourceId(0), 2, 5);
8
        let b = Span::new(SourceId(0), 7, 9);
9
        assert_eq!(a.merge(b), Span::new(SourceId(0), 2, 9));
10
    }
11

12
    #[test]
13
    #[should_panic(expected = "different files")]
14
    fn merge_across_files_is_a_bug() {
15
        let a = Span::new(SourceId(0), 0, 1);
16
        let b = Span::new(SourceId(1), 0, 1);
17
        let _ = a.merge(b);
18
    }
19
}

• #[cfg(test)]：条件编译，只有在 cargo test 下这个模块才存在，对应 #ifdef TESTING。发布版本里这些代码完全不存在。
• mod tests { ... }：一个内联的模块（命名空间）。use super::*; 把父模块的所有名字带进来，所以测试可以直接写 Span。单元测试住在被测代码的同一个文件里，因此它甚至可以访问私有项，第 2 篇你会用到。
• #[test] 标记一个测试函数。它不接收参数，正常返回就是通过，panic 就是失败。
• assert_eq!(left, right)：失败时打印两边的值，这要求类型实现了 Debug，这就是为什么前面我们给 SourceId 和 Span 都实现了它。
• #[should_panic(expected = "different files")]：这个测试期望发生 panic，并且 panic 消息必须包含这个子串。它验证的是 merge 里 debug_assert_eq! 的那条消息。

注意这个 should_panic 测试依赖 debug_assert。我试了 cargo test --release -p pebble-span：

1
test tests::merge_covers_both ... ok
2
test tests::merge_across_files_is_a_bug - should panic ... FAILED
3
note: test did not panic as expected at crates/pebble-span/src/lib.rs:115:8
4
test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

发布构建里断言整行消失，函数不再 panic，测试就失败了。这不是 bug，是 debug_assert 的定义；你只需要记住：测试默认在调试构建下跑。

跑起来：

1
$ cargo test -p pebble-span
2
   Compiling pebble-span v0.1.0 (/tmp/pebble-rebuild-01/crates/pebble-span)
3
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.45s
4
     Running unittests src/lib.rs (target/debug/deps/pebble_span-3b8ae416ebb198e2)
5

6
running 2 tests
7
test tests::merge_covers_both ... ok
8
test tests::merge_across_files_is_a_bug - should panic ... ok
9

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

12
   Doc-tests pebble_span
13

14
running 0 tests
15

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

-p pebble-span 指定 package，在 workspace 里只测这一个。最后的 “Doc-tests” 是文档里的代码示例也会被当成测试编译运行，第 10 篇我们会写一个。

1
---- scratch::cross_file_without_should_panic stdout ----
2
thread 'scratch::cross_file_without_should_panic' (57352) panicked at crates/pebble-span/src/lib.rs:72:9:
3
assertion `left == right` failed: tried to merge spans from different files
4
  left: source#0
5
 right: source#1
6
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
7
---- scratch::wrong_on_purpose stdout ----
8
thread 'scratch::wrong_on_purpose' (57353) panicked at crates/pebble-span/src/lib.rs:130:9:
9
assertion `left == right` failed
10
  left: 2..9
11
 right: 2..8

1
assertion `left == right` failed
2
  left: Span { source: source#0, start: 2, end: 9 }
3
 right: Span { source: source#0, start: 2, end: 8 }

检查点#

在 ~/pebble 下：

1
cargo test -p pebble-span
2
cargo clippy --workspace --all-targets -- -D warnings
3
cargo fmt --all --check

测试输出就是上面那个：2 个通过，0 个失败。clippy 加 -D warnings（把所有警告当作错误）应当安静地结束：

1
    Checking pebble-span v0.1.0 (/tmp/pebble-rebuild-01/crates/pebble-span)
2
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.18s

cargo fmt --all --check 什么都不输出（退出码 0）就是格式正确。如果它打印了 diff，直接运行 cargo fmt --all 让 rustfmt 替你改。

先拿到标签的本地克隆，以后每一篇的 diff 都用它（只需要做一次）：

1
git clone --branch tutorial-v1 https://github.com/bfmhno3/pebble ~/pebble-tag

必须和标签一致的文件：

• crates/pebble-span/Cargo.toml：已经完成，以后不会再变。验证：

1
diff <(git -C ~/pebble-tag show tutorial-v1:crates/pebble-span/Cargo.toml) crates/pebble-span/Cargo.toml

中间版本（后面的章节会继续改）：

• 根 Cargo.toml：我们的 [workspace.dependencies] 目前只有 pebble-span 一行，之后每章添一个 crate。[workspace.package]、[workspace.lints] 和仓库一致，[profile.*] 段第 15 篇再加。
• .gitignore：目前只有 /target，仓库里的是更完整的版本。
• crates/pebble-span/src/lib.rs：目前只有 SourceId、Span 和它们的两个测试，120 行（wc -l 应当是 120）；没有 #![no_std]、没有 SourceFile、没有 SourceMap。第 2 篇会把它写成标签里的最终版本，届时 diff 要求一致。

练习#

1. 给 Span 加一个方法 intersect(self, other: Span) -> Option<Span>：两个 span 的交集，没有交集（或者不在同一个文件）时返回 None。Option<T> 是”要么有一个 T（写作 Some(x)），要么没有（None）“，第 2 篇会细讲，这里你只需要会构造它。提示：开头取 max，结尾取 min。

1
/// The overlap of two spans, or `None` when they do not share a byte.
2
#[must_use]
3
pub fn intersect(self, other: Span) -> Option<Span> {
4
    if self.source != other.source {
5
        return None;
6
    }
7
    let start = self.start.max(other.start);
8
    let end = self.end.min(other.end);
9
    if start < end {
10
        Some(Span::new(self.source, start, end))
11
    } else {
12
        None
13
    }
14
}

2. 下面三段代码，哪几段能编译？先预测，再到实验场验证（ch01_copy.rs、ch01_copy_string.rs）。

• A：#[derive(Copy, Clone)] struct Pt { x: u32 }，把一个 Pt 变量连续两次传给 fn show_pt(p: Pt)。
• B：struct Name { len: u32 }（没有 derive Copy），把一个 Name 变量连续两次传给 fn show_name(n: Name)。
• C：#[derive(Copy, Clone)] struct Label { name: String }。

1
$ cargo build --bin ch01_copy
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
error[E0382]: use of moved value: `n`
4
  --> src/bin/ch01_copy.rs:26:15
5
   |
6
24 |     let n = Name { len: 1 };
7
   |         - move occurs because `n` has type `Name`, which does not implement the `Copy` trait
8
25 |     show_name(n);
9
   |               - value moved here
10
26 |     show_name(n); // snippet B
11
   |               ^ value used here after move
12
...

1
$ cargo build --bin ch01_copy_string
2
   Compiling rust-lab v0.1.0 (/tmp/rust-lab)
3
error[E0204]: the trait `Copy` cannot be implemented for this type
4
 --> src/bin/ch01_copy_string.rs:2:8
5
  |
6
1 | #[derive(Copy, Clone)]
7
  |          ---- in this derive macro expansion
8
2 | struct Label {
9
  |        ^^^^^
10
3 |     name: String,
11
  |     ------------ this field does not implement `Copy`
12

13
For more information about this error, try `rustc --explain E0204`.
14
error: could not compile `rust-lab` (bin "ch01_copy_string") due to 1 previous error

3. 把下面的 while 循环改写成 loop { ... break value } 的形式，不改变结果：

1
fn first_power_of_two_over(limit: u32) -> u32 {
2
    let mut p = 1;
3
    while p <= limit {
4
        p *= 2;
5
    }
6
    p
7
}

1
fn first_power_of_two_over_loop(limit: u32) -> u32 {
2
    let mut p = 1;
3
    loop {
4
        if p > limit {
5
            break p;
6
        }
7
        p *= 2;
8
    }
9
}

下一篇#

Span 有一个特点：它是 Copy 的，所以我们一直回避了一个问题，谁拥有源码文本？一个编译器要把文件名和文件内容存在某处，还要能根据字节偏移反查”第几行第几列”，这时候 String 出场，所有权问题也会出场。C++ 程序员在这里的肌肉记忆是 std::string 和 const std::string&，还有”别返回指向局部变量的引用”这条纪律。Rust 的做法是把这条纪律写进编译器，而且不需要你背：它会在编译期告诉你哪一行违反了，并给出一个看得懂的错误。第 2 篇，所有权：SourceMap 里的 String 归谁，我们把 pebble-span 写完。