From 2c79387d0bbcfd5ce5e90cc81b22216cd6e6434d Mon Sep 17 00:00:00 2001 From: Brayn Lee Date: Sun, 8 Aug 2021 17:41:08 +0800 Subject: [PATCH] docs: update ch00 and ch01 sections --- src/ch00-00-introduction.md | 11 +- src/ch01-01-installation.md | 14 +- src/ch01-02-hello-world.md | 18 ++- src/ch01-03-hello-cargo.md | 35 +++-- src/img/ferris/unsafe.svg | 291 ------------------------------------ 5 files changed, 43 insertions(+), 326 deletions(-) delete mode 100644 src/img/ferris/unsafe.svg diff --git a/src/ch00-00-introduction.md b/src/ch00-00-introduction.md index c956870..5af1f27 100644 --- a/src/ch00-00-introduction.md +++ b/src/ch00-00-introduction.md @@ -2,7 +2,7 @@ > [ch00-00-introduction.md](https://github.com/rust-lang/book/blob/main/src/ch00-00-introduction.md) >
-> commit 0aa307c7d79d2cbf83cdf5d47780b2904e9cb03f +> commit 4921fde29ae8ccf67d5893d4e43d74284626fded > 注意：本书的版本与出版的 [The Rust Programming Language][nsprust] > 和电子版的 [No Starch Press][nsp] 一致 @@ -78,14 +78,13 @@ Rust 语言也希望能支持很多其他用户，这里提及的只是最大的 -学习 Rust 的过程中一个重要的部分是学习如何阅读编译器提供的错误信息：它们会指导你编写出能工作的代码。为此，我们会提供很多不能编译的示例代码，以及各个情况下编译器会展示的错误信息。请注意如果随便输入并运行随机的示例代码，它们可能无法编译！请确保阅读任何你尝试运行的示例周围的内容，检视他们是否有意写错。Ferris 也会帮助你区别那些有意无法工作的代码： +学习 Rust 的过程中一个重要的部分是学习如何阅读编译器提供的错误信息：它们会指导你编写出能工作的代码。为此，我们会提供很多不能编译的示例，以及各个情况下编译器会展示的错误信息。请注意如果随便输入并运行随机的示例代码，它们可能无法编译！请确保阅读任何你尝试运行的示例周围的内容，检视他们是否有意写错。Ferris 也会帮助你区别那些有意无法工作的代码： | Ferris | 意义 | |------------------------------------------------------------------------|--------------------------------------------------| -| | 这些代码不能编译！ | -| | 这些代码会 panic！ | -| | 这些代码块包含不安全（unsafe）代码。 | -| | 这些代码不会产生期望的行为。 | +| Ferris with a question mark | 这些代码不能编译！ | +| Ferris throwing up their hands | 这些代码会 panic！ | +| Ferris with one claw up, shrugging | 这些代码不会产生期望的行为。 | 在大部分情况，我们会指引你将任何不能编译的代码纠正为正确版本。 diff --git a/src/ch01-01-installation.md b/src/ch01-01-installation.md index 299e955..65033d2 100644 --- a/src/ch01-01-installation.md +++ b/src/ch01-01-installation.md @@ -1,11 +1,11 @@ ## 安装 > [ch01-01-installation.md](https://github.com/rust-lang/book/blob/main/src/ch01-01-installation.md)
-> commit bad683bb7dcd06ef7f5f83bad3a25b1706b7b230 +> commit a01b23fee4c76a7e0d8c8c3261bdcf3a9840ccd3 第一步是安装 Rust。我们会通过 `rustup` 下载 Rust，这是一个管理 Rust 版本和相关工具的命令行工具。下载时需要联网。 -> 注意：如果你出于某些理由倾向于不使用 `rustup`，请到 [Rust 安装页面](https://www.rust-lang.org/install.html) 查看其它安装选项。 +> 注意：如果你出于某些理由倾向于不使用 `rustup`，请参阅 [Rust 的其他安装方法页面](https://forge.rust-lang.org/infra/other-installation-methods.html) 了解更多选项。 接下来的步骤会安装最新的稳定版 Rust 编译器。Rust 的稳定性确保本书所有示例在最新版本的 Rust 中能够继续编译。不同版本的输出可能略有不同，因为 Rust 经常改进错误信息和警告。也就是说，任何通过这些步骤安装的最新稳定版 Rust，都应该能正常运行本书中的内容。 @@ -27,7 +27,15 @@ $ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh Rust is installed now. Great! ``` -另外，你需要一个某种类型的链接器（linker）。很有可能已经安装，不过当你尝试编译 Rust 程序时，却有错误指出无法执行链接器，这意味着你的系统上没有安装链接器，你需要自行安装一个。C 编译器通常带有正确的链接器。请查看你使用平台的文档，了解如何安装 C 编译器。并且，一些常用的 Rust 包依赖 C 代码，也需要安装 C 编译器。因此现在安装一个是值得的。 +另外，你还需要一个链接器（linker），这是 Rust 用来将其编译的输出连接到一个文件中的程序。很可能你已经有一个了。如果你遇到了链接器错误，请尝试安装一个 C 编译器，它通常包括一个链接器。C 编译器也很有用，因为一些常见的 Rust 包依赖于 C 代码，因此需要安装一个 C 编译器。 + +在 macOS 上，你可以通过运行以下命令获得 C 语言编译器： + +```console +$ xcode-select --install +``` + +根据发行版的文档，Linux 用户通常应该安装 GCC 或 Clang。例如，如果你使用 Ubuntu，则可以安装 则可以安装 `build-essential` 包。 ### 在 Windows 上安装 `rustup` diff --git a/src/ch01-02-hello-world.md b/src/ch01-02-hello-world.md index 9627d5d..e13bfff 100644 --- a/src/ch01-02-hello-world.md +++ b/src/ch01-02-hello-world.md @@ -2,7 +2,7 @@ > [ch01-02-hello-world.md](https://github.com/rust-lang/book/blob/main/src/ch01-02-hello-world.md) >
-> commit f63a103270ec8416899675a9cdb1c5cf6d77a498 +> commit ee7c5776a958353a2be0e3787fffa9523638d0fa 既然安装好了 Rust，我们来编写第一个 Rust 程序。当学习一门新语言的时候，使用该语言在屏幕上打印 `Hello, world!` 是一项传统，我们将沿用这一传统！ @@ -16,7 +16,7 @@ 对于 Linux、macOS 和 Windows PowerShell，输入： -```text +```console $ mkdir ~/projects $ cd ~/projects $ mkdir hello_world @@ -50,7 +50,7 @@ fn main() { 保存文件，并回到终端窗口。在 Linux 或 macOS 上，输入如下命令，编译并运行文件： -```text +```console $ rustc main.rs $ ./main Hello, world! @@ -82,7 +82,9 @@ fn main() { 还须注意，函数体被包裹在花括号中，`{}`。Rust 要求所有函数体都要用花括号包裹起来。一般来说，将左花括号与函数声明置于同一行并以空格分隔，是良好的代码风格。 -在编写本书的时候，一个叫做 `rustfmt` 的自动格式化工具正在开发中。如果你希望在 Rust 项目中保持一种标准风格，`rustfmt` 会将代码格式化为特定的风格。Rust 团队计划最终将该工具包含在标准 Rust 发行版中，就像 `rustc`。所以根据你阅读本书的时间，它可能已经安装到你的电脑中了！检查在线文档以了解更多细节。 +如果要在Rust项目中坚持使用标准样式，可以使用名为rustfmt的自动格式化工具将代码格式化为特定样式。Rust团队已经在标准的Rust发行版中包含了这个工具，比如rustc，所以它应该已经安装在您的计算机上了！有关更多详细信息，请查看在线文档。 + +如果你希望在 Rust 项目中保持一种标准风格，可以使用名为 `rustfmt` 的自动格式化工具将代码格式化为特定的风格。Rust 团队已经在标准的 Rust 发行版中包含了这个工具，就像 `rustc`。所以它应该已经安装在你的电脑中了！检查在线文档以了解更多细节。 在 `main()` 函数中是如下代码： @@ -92,7 +94,7 @@ fn main() { 这行代码完成这个简单程序的所有工作：在屏幕上打印文本。这里有四个重要的细节需要注意。首先 Rust 的缩进风格使用 4 个空格，而不是 1 个制表符（tab）。 -第二，`println!` 调用了一个 Rust 宏（macro）。如果是调用函数，则应输入 `println`（没有`!`）。我们将在第十九章详细讨论宏。现在你只需记住，当看到符号 `!` 的时候，就意味着调用的是宏而不是普通函数。 +第二，`println!` 调用了一个 Rust 宏（macro）。如果是调用函数，则应输入 `println`（没有`!`）。我们将在第十九章详细讨论宏。现在你只需记住，当看到符号 `!` 的时候，就意味着调用的是宏而不是普通函数，并且宏并不总是遵循与函数相同的规则。 第三，`"Hello, world!"` 是一个字符串。我们把这个字符串作为一个参数传递给 `println!`，字符串将被打印到屏幕上。 @@ -104,7 +106,7 @@ fn main() { 在运行 Rust 程序之前，必须先使用 Rust 编译器编译它，即输入 `rustc` 命令并传入源文件名称，如下： -```text +```console $ rustc main.rs ``` @@ -112,7 +114,7 @@ $ rustc main.rs 在 Linux、macOS 或 Windows 的 PowerShell 上，在 shell 中输入 `ls` 命令可以看见这个可执行文件。在 Linux 和 macOS，你会看到两个文件。在 Windows PowerShell 中，你会看到同使用 CMD 相同的三个文件。 -```text +```console $ ls main main.rs ``` @@ -128,7 +130,7 @@ main.rs 这展示了扩展名为 *.rs* 的源文件、可执行文件（在 Windows 下是 *main.exe*，其它平台是 *main*），以及当使用 CMD 时会有一个包含调试信息、扩展名为 *.pdb* 的文件。从这里开始运行 *main* 或 *main.exe* 文件，如下： -```text +```console $ ./main # Windows 是 .\main.exe ``` diff --git a/src/ch01-03-hello-cargo.md b/src/ch01-03-hello-cargo.md index 27b48db..e0453c9 100644 --- a/src/ch01-03-hello-cargo.md +++ b/src/ch01-03-hello-cargo.md @@ -2,7 +2,7 @@ > [ch01-03-hello-cargo.md](https://github.com/rust-lang/book/blob/main/src/ch01-03-hello-cargo.md) >
-> commit f63a103270ec8416899675a9cdb1c5cf6d77a498 +> commit c032e945406dd8ef2ce2062aa1f9d65dbf9020d6 Cargo 是 Rust 的构建系统和包管理器。大多数 Rustacean 们使用 Cargo 来管理他们的 Rust 项目，因为它可以为你处理很多任务，比如构建代码、下载依赖库并编译这些库。（我们把代码所需要的库叫做 **依赖**（*dependencies*））。 @@ -10,7 +10,7 @@ Cargo 是 Rust 的构建系统和包管理器。大多数 Rustacean 们使用 Ca 由于绝大多数 Rust 项目使用 Cargo，本书接下来的部分假设你也使用 Cargo。如果使用 [“安装”][installation] 部分介绍的官方安装包的话，则自带了 Cargo。如果通过其他方式安装的话，可以在终端输入如下命令检查是否安装了 Cargo： -```text +```console $ cargo --version ``` @@ -18,16 +18,16 @@ $ cargo --version ### 使用 Cargo 创建项目 -我们使用 Cargo 创建一个新项目，然后看看与上面的 Hello, world! 项目有什么不同。回到 *projects* 目录（或者你存放代码的目录）。接着，可在任何操作系统下运行以下命令： +我们使用 Cargo 创建一个新项目，然后看看与上面的 “Hello, world!” 项目有什么不同。回到 *projects* 目录（或者你存放代码的目录）。接着，可在任何操作系统下运行以下命令： -```text +```console $ cargo new hello_cargo $ cd hello_cargo ``` 第一行命令新建了名为 *hello_cargo* 的目录。我们将项目命名为 *hello_cargo*，同时 Cargo 在一个同名目录中创建项目文件。 -进入 *hello_cargo* 目录并列出文件。将会看到 Cargo 生成了两个文件和一个目录：一个 *Cargo.toml* 文件，一个 *src* 目录，以及位于 *src* 目录中的 *main.rs* 文件。它也在 *hello_cargo* 目录初始化了一个 git 仓库，以及一个 *.gitignore* 文件。 +进入 *hello_cargo* 目录并列出文件。将会看到 Cargo 生成了两个文件和一个目录：一个 *Cargo.toml* 文件，一个 *src* 目录，以及位于 *src* 目录中的 *main.rs* 文件。它也在 *hello_cargo* 目录初始化了一个 git 仓库，以及一个 *.gitignore* 文件。如果你在现有的 git 仓库中运行 `cargo new`，则不会生成 git 文件；你可以通过使用`cargo new --vcs=git` 来覆盖此行为。 > 注意：Git 是一个常用的版本控制系统（version control system， VCS）。可以通过 `--vcs` 参数使 `cargo new` 切换到其它版本控制系统（VCS），或者不使用 VCS。运行 `cargo new --help` 参看可用的选项。 @@ -39,7 +39,6 @@ $ cd hello_cargo [package] name = "hello_cargo" version = "0.1.0" -authors = ["Your Name "] edition = "2018" [dependencies] @@ -47,13 +46,11 @@ edition = "2018" 示例 1-2: *cargo new* 命令生成的 *Cargo.toml* 的内容 -这个文件使用 [*TOML*][toml] (*Tom's Obvious, Minimal Language*) 格式，这是 Cargo 配置文件的格式。 - -[toml]: https://github.com/toml-lang/toml +这个文件使用 [*TOML*](https://toml.io) (*Tom's Obvious, Minimal Language*) 格式，这是 Cargo 配置文件的格式。 第一行，`[package]`，是一个片段（section）标题，表明下面的语句用来配置一个包。随着我们在这个文件增加更多的信息，还将增加其他片段（section）。 -接下来的四行设置了 Cargo 编译程序所需的配置：项目的名称、版本、作者以及要使用的 Rust 版本。Cargo 从环境中获取你的名字和 email 信息，所以如果这些信息不正确，请修改并保存此文件。附录 E 会介绍 `edition` 的值。 +接下来的三行设置了 Cargo 编译程序所需的配置：项目的名称、版本以及要使用的 Rust 版本。[附录 E][appendix-e] 会介绍 `edition` 的值。 最后一行，`[dependencies]`，是罗列项目依赖的片段的开始。在 Rust 中，代码包被称为 *crates*。这个项目并不需要其他的 crate，不过在第二章的第一个项目会用到依赖，那时会用得上这个片段。 @@ -77,7 +74,7 @@ Cargo 期望源文件存放在 *src* 目录中。项目根目录只存放 README 现在让我们看看通过 Cargo 构建和运行 “Hello, world!” 程序有什么不同！在 *hello_cargo* 目录下，输入下面的命令来构建项目： -```text +```console $ cargo build Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs @@ -85,7 +82,7 @@ $ cargo build 这个命令会创建一个可执行文件 *target/debug/hello_cargo* （在 Windows 上是 *target\debug\hello_cargo.exe*），而不是放在目前目录下。可以通过这个命令运行可执行文件： -```text +```console $ ./target/debug/hello_cargo # 或者在 Windows 下为 .\target\debug\hello_cargo.exe Hello, world! ``` @@ -94,7 +91,7 @@ Hello, world! 我们刚刚使用 `cargo build` 构建了项目，并使用 `./target/debug/hello_cargo` 运行了程序，也可以使用 `cargo run` 在一个命令中同时编译并运行生成的可执行文件： -```text +```console $ cargo run Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs Running `target/debug/hello_cargo` @@ -103,7 +100,7 @@ Hello, world! 注意这一次并没有出现表明 Cargo 正在编译 `hello_cargo` 的输出。Cargo 发现文件并没有被改变，就直接运行了二进制文件。如果修改了源文件的话，Cargo 会在运行之前重新构建项目，并会出现像这样的输出： -```text +```console $ cargo run Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo) Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs @@ -113,7 +110,7 @@ Hello, world! Cargo 还提供了一个叫 `cargo check` 的命令。该命令快速检查代码确保其可以编译，但并不产生可执行文件： -```text +```console $ cargo check Checking hello_cargo v0.1.0 (file:///projects/hello_cargo) Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs @@ -123,8 +120,9 @@ $ cargo check 我们回顾下已学习的 Cargo 内容： -* 可以使用 `cargo build` 或 `cargo check` 构建项目。 +* 可以使用 `cargo build` 构建项目。 * 可以使用 `cargo run` 一步构建并运行项目。 +* 可以在不生成二进制文件的情况下构建项目并使用 `cargo check` 检查错误。 * 有别于将构建结果放在与源码相同的目录，Cargo 会将其放到 *target/debug* 目录。 使用 Cargo 的一个额外的优点是，不管你使用什么操作系统，其命令都是一样的。所以从现在开始本书将不再为 Linux 和 macOS 以及 Windows 提供相应的命令。 @@ -139,8 +137,8 @@ $ cargo check 即便 `hello_cargo` 项目十分简单，它现在也使用了很多在你之后的 Rust 生涯将会用到的实用工具。其实，要在任何已存在的项目上工作时，可以使用如下命令通过 Git 检出代码，移动到该项目目录并构建： -```text -$ git clone someurl.com/someproject +```console +$ git clone example.org/someproject $ cd someproject $ cargo build ``` @@ -162,3 +160,4 @@ $ cargo build 是时候通过构建更实质性的程序来熟悉读写 Rust 代码了。所以在第二章我们会构建一个猜猜看游戏程序。如果你更愿意从学习 Rust 常用的编程概念开始，请阅读第三章，接着再回到第二章。 [installation]: ch01-01-installation.html#installation +[appendix-e]: appendix-05-editions.html \ No newline at end of file diff --git a/src/img/ferris/unsafe.svg b/src/img/ferris/unsafe.svg deleted file mode 100644 index d4fdc08..0000000 --- a/src/img/ferris/unsafe.svg +++ /dev/null @@ -1,291 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -