教程文档【免费下载链接】bookThe Rust Programming Language项目地址https://gitcode.com/gh_mirrors/bo/book点击查看免费下载导读本指南围绕《The Rust Programming Language》简称 TRPLRust 官方书籍的源码仓库展开系统讲解如何从源码构建出可在线阅读的 HTML 书籍、如何运行书中全部代码示例的自动化测试以及如何通过拼写检查、引用校验、预处理器定制等工程化手段保障书籍质量。读完本文你将掌握基于 mdBook 的书籍工程从安装构建工具 → 构建产物 → 运行测试 → 质量门禁 → 参与贡献的完整链路并理解该仓库中book.toml、packages/、ci/等目录的职责分工。一、仓库定位一本书的源码工程与大多数把 Markdown 文档当作内容而不是代码的仓库不同本仓库把整本《The Rust Programming Language》当作一个可构建、可测试、可验证的软件工程来维护。仓库根目录下的 README.md 明确指出This repository contains the source of The Rust Programming Language book——即这里存放的不是编译产物而是书籍的源文件与构建流水线。1.1 多版本目录历史快照与当前主线从仓库目录结构可以清晰地看到书籍的演进轨迹该结构属于可以从源码结构直接确认的事实first-edition/第一版《The Rust Programming Language》的完整内容快照仍保留着first-edition/src/下的 Markdown 源文件second-edition/第二版快照拥有独立的 book.toml 与 102 个 Markdown 章节文件2018-edition/2018 版快照同样自带 book.tomlsrc/当前主线内容即 README 所说的、随 Rust 最新 releasestable/beta/nightly发布的版本。主线目录 src/SUMMARY.md 定义了当前 21 章的完整目录骨架从 Getting Started、Ownership 一直延伸到异步编程ch17-00-async-await.md与最终实战项目 Web 服务器ch21-00-final-project-a-web-server.md。对比各版本快照可以发现章节编号发生过多次调整如 OOP 章节从 ch17 迁到 ch18、模式匹配从 ch18 迁到 ch19 等这正是下文book.toml中大量 redirect 规则存在的原因。1.2 纸质版与在线版的同一套源README 强调书籍同时有 No Starch Press 的纸质版dead-tree form与免费在线版而仓库中 nostarch/ 目录存放的是发送给出版社的章节快照chapter00.md~chapter21.md、各附录及独立的 nostarch/book.toml。CONTRIBUTING.md 对此有明确约束所有修改应提交到src目录nostarch目录只随发给出版社的编辑稿更新提交修改该目录的 Pull Request 会被直接关闭。这一在线源 出版社快照双轨模式是理解本仓库贡献流程的关键前提。二、构建环境准备锁定 mdBook 版本书籍使用 Rust 社区标准的 mdBook 工具链构建。README 给出了核心要求Building the book requiresmdBook, ideally the same version that rust-lang/rust uses.这意味着不仅需要安装 mdBook还建议锁定与 Rust 主仓库 rustbook 工具一致的版本以保证构建行为与官方发布链路完全一致。安装命令为cargo install mdbook --locked --version version_num其中version_num应替换为与 Rust 工具链配套的 mdBook 版本号--locked会按照Cargo.lock锁定依赖版本确保可复现安装。2.1 仓库自身的 Rust 工具链约束仓库根目录的 rust-toolchain 文件约束了本仓库开发环境使用的 Rust 工具链版本同时根目录 book.toml 中声明edition 2024说明当前主线内容与代码示例均面向 Rust 2024 edition 编写。若本地 Rust 工具链与仓库要求不一致构建或测试时可能出现编译差异这也是 README 强调尽量与 rust-lang/rust 使用相同 mdBook 版本的原因之一。三、构建书籍从源码到 HTML3.1 单条命令完成构建在仓库根目录执行mdbook buildmdBook 会依据 book.toml 读取src/SUMMARY.md目录结构将全部 Markdown 章节渲染为 HTML输出到仓库根目录下的book/子目录。构建过程会顺带执行两个自定义预处理器详见第五节它们负责对书中代码列表与语义化注释做二次加工因此构建产物是经过预处理的完整 HTML 书籍。3.2 在浏览器中查看构建产物README 给出了跨平台的打开方式。以book/index.html为入口Firefox# Linux firefox book/index.html # macOS open -a Firefox book/index.html # Windows PowerShell Start-Process firefox.exe .\book\index.html # Windows Cmd start firefox.exe .\book\index.htmlChrome# Linux google-chrome book/index.html # macOS open -a Google Chrome book/index.html # Windows PowerShell Start-Process chrome.exe .\book\index.html # Windows Cmd start chrome.exe .\book\index.html由于book/是构建产物目录仓库中的.gitignore类机制会将其排除在版本控制之外如需重新生成随时可再次执行mdbook build。四、运行书中代码示例的测试README 提供了官方测试命令这是本仓库最核心的工程质量保障手段之一cd packages/trpl mdbook test --library-path packages/trpl/target/debug/deps4.1 命令拆解测试的是什么mdbook test会扫描src/下所有 Markdown 中的 Rust 代码块将其编译并作为doctest运行——书中每个可执行示例如猜测游戏、所有权示例、并发示例等都会被真实执行验证--library-path packages/trpl/target/debug/deps指定依赖库搜索路径让代码块中use trpl::...的导入能够解析到trpl辅助 crate 的预编译产物因此在运行测试前需要先确保packages/trpl已被构建首次执行时可通过cargo build或直接运行上述命令前的cargo build完成否则target/debug/deps目录中可能缺少所需动态链接库。从仓库结构看packages/trpl/tests/integration/下还存放着针对辅助 crate 自身的集成测试main.rs它保证了trplcrate 对外提供的 API 在真实使用场景下可用。4.2 测试目录与代码列表的组织书中出现的所有代码示例并非散落在正文里而是被组织进 listings/ 目录按章节分组listings/ch02-guessing-game-tutorial/第 2 章猜数字游戏的listing-02-01~listing-02-06及多个no-listing-*变体每个子目录都是完整的 Cargo 项目含Cargo.toml、Cargo.lock与main.rslistings/ch03-common-programming-concepts/变量、函数、控制流等示例其中output-only-*目录专门保存仅用于展示输出、不参与编译的示例其余各章节ch04 所有权、ch05 结构体、ch08 集合、ch10 泛型、ch12 IO 项目……直至 ch21 Web 服务器均有对应的完整可编译项目。README 提到可以在 release 页面下载书中全部代码列表的打包其数据源正是listings/目录。命名规范上listing-XX-XX对应正文编号no-listing-*表示无编号的穿插示例output-only-*表示仅供展示输出结果的示例这一约定对检索与引用代码非常友好。五、构建体系源码剖析book.toml 的工程化配置根目录 book.toml 是整个构建体系的配置文件核心。与普通 mdBook 项目相比它额外承担了大量书籍工程化职责。5.1 书籍元信息与渲染增强[book] title The Rust Programming Language authors [Steve Klabnik, Carol Nichols, Chris Krycho, Contributions from the Rust Community] [output.html] additional-css [ferris.css, theme/2018-edition.css, theme/semantic-notes.css, theme/listing.css] additional-js [ferris.js]additional-css依次加载仓库根目录的 ferris.css、theme/2018-edition.css、theme/semantic-notes.css 与 theme/listing.css分别负责 Rusta 吉祥物 Ferris 插图样式、2018 版排版兼容、语义化注释样式与代码列表样式additional-js加载 ferris.js用于渲染书中与 Ferris 相关的交互提示[output.html.search]中use-boolean-and true开启搜索关键词的 AND 语义提升在线版全文搜索的精确度。5.2 章节重编号的 redirect 规则书籍经历多轮章节调整如异步章节插入、OOP/模式匹配/高级特性/Web 服务器章节整体后移为保证旧链接不失效book.toml 定义了完整的 HTML 重定向表例如[output.html.redirect] ch17-00-oop.html ch18-00-oop.html ch18-00-patterns.html ch19-00-patterns.html ch19-00-advanced-features.html ch20-00-advanced-features.html ch20-00-final-project-a-web-server.html ch21-00-final-project-a-web-server.html这些规则与 src/SUMMARY.md 中的章节编号一一对应也从侧面印证了当前主线已是包含异步ch17与 OOPch18在内的第二版布局。5.3 自定义预处理器语义化代码与注释book.toml 声明了两个由仓库自研实现的 mdBook 预处理器它们会在构建时通过cargo run启动[preprocessor.trpl-note] command cargo run --manifest-path packages/mdbook-trpl/Cargo.toml --bin mdbook-trpl-note [preprocessor.trpl-listing] command cargo run --manifest-path packages/mdbook-trpl/Cargo.toml --bin mdbook-trpl-listing output-mode default对应源码位于 packages/mdbook-trpl/。从 packages/mdbook-trpl/Cargo.toml 可以看到该包实际提供了四个二进制mdbook-trpl-note处理书中的语义化注释/警示块mdbook-trpl-listing处理代码列表的语义化标记mdbook-trpl-heading规范化标题层级mdbook-trpl-figure处理插图引用。以mdbook-trpl-listing的实现packages/mdbook-trpl/src/bin/listing.rs为例它严格遵循 mdBook 预处理器契约通过Listing.supports_renderer()声明支持全部渲染器从 stdin 读取 mdBook 传入的书籍上下文parse_input(io::stdin())执行Listing.run(ctx, book)完成转换再以serde_json::to_writer将处理后的书籍写回 stdout。此外[build]段中的extra-watch-dirs [packages/mdbook-trpl]让mdbook serve/mdbook watch在预处理器源码变更时也能触发重建。5.4 配套渲染主题theme/ 目录下还存放了listing.css代码列表排版、semantic-notes.css语义注释、2018-edition.css2018 版兼容样式等主题文件与 2018-edition/、second-edition/ 各历史版本的独立 book.toml 配合实现同一套 mdBook 引擎、多版本书籍并行构建的能力。六、辅助 cratetrpl 支持库为了让读者在异步编程等章节能以最小的依赖成本跟随书中的示例仓库维护了一个专门的辅助 cratetrpl。6.1 依赖与设计动机packages/trpl/Cargo.toml 声明其依赖为futures 0.3、reqwest 0.12仅启用rustls-tls、scraper 0.20、tokio 1.x启用fs/rt-multi-thread/sync/time特性、tokio-stream 0.1。该包被设计为独立发布到 crates.io同时也可作为路径依赖随 Rust 发行版分发因此在 Cargo.toml 末尾显式声明了空的[workspace]以脱离宿主 workspace。6.2 统一 API 的重新导出packages/trpl/src/lib.rs 的 doc 注释说明了它的两个设计目的读者只需添加trpl一个依赖、使用一组trpl::导入即可覆盖书中所需的大部分异步 API由于仓库完全控制该 crate 的内容与变更时机即使上游如 Tokio 做破坏性 2.0 升级也不会打断读者跟随书中示例编译。具体实现上它大量重新导出而非重新实现例如pub use futures::future::{join, join_all, join3, Either}、pub use tokio::runtime::Runtime、pub use tokio::sync::mpsc::{unbounded_channel as channel, UnboundedReceiver as Receiver, UnboundedSender as Sender}源码注释特别解释了为教学简化而用unbounded变体对齐std::sync::mpsc的 API 形状以及tokio::time::{interval, sleep}、tokio_stream::{Stream, StreamExt, iter as stream_from_iter}等。此外它还实现了block_on等辅助函数每次调用创建一个专属 Tokio Runtime让不带异步运行时经验的读者也能直接运行示例。这就是第四节中mdbook test --library-path packages/trpl/target/debug/deps之所以能工作的底层原因书中代码块里的use trpl::join、trpl::spawn_task等导入最终都解析到这个 crate 的预编译库文件。七、质量门禁拼写检查与引用校验书籍作为开源项目同样引入 CI 质量门禁仓库 ci/ 目录提供了可本地复用的校验脚本。7.1 拼写检查ci/spellcheck.shci/spellcheck.sh 基于aspell实现 Markdown 源文件的拼写扫描其关键行为包括字典文件项目专属有效词表位于 ci/dictionary.txt脚本默认复制到/tmp/dictionary.txt使用避免 aspell 反复修改个人词典两种运行模式默认交互模式check逐个扫描./src/*.mdaspell 弹出窗口提示修正出错文件会被备份为filename.md.bakCI 列表模式list作为第一个参数传入仅报告错误并依据结果返回退出码——1表示发现错误0表示全部通过该模式下若字典文件缺失会直接报错退出短词过滤跳过长度小于等于 3 的单词以减少误报README 中BTreeMap即文档提到的典型误报例子字典维护约定当脚本产生误报时应将新词以保持排序一致的方式追加到ci/dictionary.txt脚本自动生成的字典文件首行为personal_ws-1.1 en 0 utf-8。7.2 引用校验ci/validate.shci/validate.sh 逐文件遍历src/*.md对每个文件执行cargo run --quiet --bin link2print $file——即调用书中链接到印刷版格式转换的工具link2print检查 Markdown 中的链接与引用是否合法。该脚本服务于在线版尽量贴近印刷版的维护目标任何在正文中引入的无效内部链接都会在 CI 阶段被拦截。7.3 代码与格式规范CONTRIBUTING.md 明确了工程化规范Rust 代码使用rustfmt统一格式化缺失时可通过rustup component add rustfmt安装Markdown 及非 Rust 文件使用dprint格式化cargo install dprint或官网安装仓库根目录的 dprint.jsonc 提供了项目级配置单文件格式化命令分别为rustfmt path to file与dprint fmt path to file。八、参与贡献版本节奏与翻译工作8.1 与 Rust 发布列车同步的修订节奏README 与 CONTRIBUTING 共同说明了本仓库独特的贡献节奏书籍乘坐Rust 的 release 列车nightly → beta → stable在stable在线版看到的问题可能在仓库main分支已被修复、只是尚未走完发布链路由于书籍同时存在印刷版为保持在线版与印刷版尽可能一致常规修订窗口集中在 Rust Edition 大版本升级期间期间之外只修正错误非错误类的 issue/PR 可能需等待数月乃至数年README 明确请求贡献者保持耐心。8.2 提交前自查清单综合 README 与 CONTRIBUTING.md向仓库提交改动前的检查要点包括所有正文编辑放在src/目录不修改nostarch/快照改动前先在仓库main分支与历史记录中确认问题是否已被修复并搜索已存在/已关闭的 issue 与 PR遵循仓库的rustfmt与dprint格式规范本地跑通mdbook build、mdbook test以及ci/spellcheck.sh list、ci/validate.sh等校验遵守 Rust 项目的行为准则仓库许可证与 Rust 本身相同MIT/Apache-2.0全文见 LICENSE-MIT 与 LICENSE-APACHE。8.3 翻译等待 mdbook 多语言支持README 明确说明翻译工作是受欢迎的但仓库目前等待 mdBook 对多语言的原生支持在支持落地前不会合入翻译内容有兴趣者可以为正在进行的翻译 issue 贡献力量。因此当前主线src/仍为英文原文翻译版本需等待上游 mdBook 能力就绪。九、常见问题与排查思路结合构建体系可以给出如下排障路径现象排查方向mdbook build失败或产物样式异常检查 mdBook 版本是否与 rust-toolchain 及 Rust 主仓库配套版本一致确认 book.toml 中声明的 CSS/JS 路径ferris.css、theme/*.css、ferris.js均存在mdbook test报找不到trpl先进入 packages/trpl 执行cargo build确保target/debug/deps已生成库文件再执行 README 中的测试命令拼写检查误报专业词将单词以排序后的位置追加到 ci/dictionary.txt 后重跑ci/spellcheck.sh list章节链接失效核对目标章节是否因重编号迁移参考 book.toml 的 redirect 表映射关系历史版本构建各历史版本目录first-edition/、second-edition/、2018-edition/自带独立的book.toml进入对应目录执行mdbook build即可十、总结一套可复用的书籍工程范式《The Rust Programming Language》仓库展示了教科书级的技术书籍工程化实践以src/为唯一内容源book.toml承载渲染配置与重定向规则packages/mdbook-trpl提供四个自定义 mdBook 预处理器实现语义化代码列表与注释packages/trpl以单一依赖 统一重导出的方式支撑书中代码测试ci/目录的拼写与引用校验脚本构成 CI 质量门禁而nostarch/快照机制则平衡了在线版与印刷版的一致性维护。对于任何希望用 mdBook 维护大型技术文档、并引入自动化测试与质量校验的团队本仓库的目录划分与构建脚本都是可以直接借鉴的蓝本。赞分享教程文档【免费下载链接】bookThe Rust Programming Language项目地址https://gitcode.com/gh_mirrors/bo/book点击查看免费下载相关推荐mdBook 的 mdbook test 命令自动化测试书籍中的 Rust 代码示例mdBook 的 mdbook test 命令自动化测试书籍中的 Rust 代码示例 导读 写作书籍时文档中的代码示例很容易随着项目演进而过时失效手工维护开发工具文档mdBook 测试套件实战指南基于 BookTest 与 snapbox 快照测试驱动书籍构建验证mdBook 测试套件实战指南基于 BookTest 与 snapbox 快照测试驱动书籍构建验证 导读 本指南以 mdBook 仓库的集成测试套件文档 te开发工具文档mdBook 使用指南用 Rust 从 Markdown 构建现代在线书籍mdBook 使用指南用 Rust 从 Markdown 构建现代在线书籍 mdBook 是一个用 Rust 实现的命令行工具用于把 Markdown 文件开发工具文档上一篇UEFITool终极指南轻松解析和编辑UEFI固件的完整教程下一篇UEFITool终极指南5步掌握UEFI固件分析与编辑创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考