diff --git a/src/Ch01_Getting_Started.md b/src/Ch01_Getting_Started.md index b83012a..435f84e 100644 --- a/src/Ch01_Getting_Started.md +++ b/src/Ch01_Getting_Started.md @@ -3,5 +3,7 @@ 现在就开始 Rust 之旅！有很多要掌握的东西，不过千里之行，始于足下。本章将讨论： - 在 Linux、macOS 及 Windows 上安装 Rust; -- 编写一个打印出 `Hello, world!` 的程序来； -- Rust 的包管理器和构建系统 Cargo 的使用。 + +- 编写一个打印出 `Hello, world!` 的程序； + +- 使用 Rust 的包管理器与构建系统 Cargo 。 diff --git a/src/getting_started/hello_world.md b/src/getting_started/hello_world.md index 63f7823..5e3fd56 100644 --- a/src/getting_started/hello_world.md +++ b/src/getting_started/hello_world.md @@ -1,20 +1,26 @@ # `Hello, World!` -既然已经安装好了 Rust, 那么就来编写第一个 Rust 程序吧。在掌握一门新语言时，传统就是要编写一个小的、打印出文字 `Hello, World!` 到屏幕上的程序，因此这里也会干这同样的事情！ +现在咱们已经安装了 Rust，那么就是时候编写第一个 Rust 程序了。学习一门新语言的传统做法，是编写一个在屏幕上打印出 `Hello, world!` 的小程序，所以咱们在这里，也要做同样的事情。 -> 注意：本书假定读者对命令行有着基本的熟悉。Rust 对代码在何处编辑和使用何种工具编辑没有特别要求，因此若优先选择某种集成开发环境，而非命令行，那么使用喜好的 IDE 即可。许多 IDE 都有某种程度的 Rust 支持；请查看 IDE 文档了解有关细节信息。近来，Rust 团队已着手启动良好的IDE支持，且此方面已取得极大进展！ +> **注意**：本书假定读者基本熟悉命令行。Rust 对编辑、工具或代码的存放位置，没有特别的要求，因此如果咱们喜欢使用集成开发环境（IDE），而不是命令行，请随意使用咱们喜欢的集成开发环境。许多集成开发环境，现在都在一定程度上有着 Rust 的支持；详情请查看集成开发环境的文档。Rust 团队一直致力于通过 `rust-analyzer`，实现对集成开发环境的强大支持。详情请参见 [附录 D](../appendix/dev_tools.md)。 -## 创建一个项目目录 + +## 创建项目的目录 + +**Creating a Project Directory** + + +首先，咱们将创建一个存储咱们 Rust 代码的目录。对于 Rust 来说，代码存放在哪里并不重要，但对于本书中的练习和项目，我们建议在咱们的主目录下，创建一个 `projects` 目录，并将咱们的所有项目，都放在那里。 这里是以构造一个保存 Rust 代码的目录开始的。对于 Rust 来说，代码位居何处并不重要，不过对于本书中的练习与项目，是建议在主目录下构造一个 `projects` 目录，并把全部项目放在那里的。 -请打开一个终端，并输入下面的这些命令来构造一个 `projects` 的目录，和一个在 `projects` 下用于 "Hello, World!" 项目的目录。 +请打开某个终端，并输入以下命令，创建 `projects` 目录，并在 `projects` 目录下，创建出这个 "Hello, world!" 的项目目录。 对于 Linux、macOS 和 Windows 上的 `PowerShell`, 请输入： ```console -$ mkdir ~/rust-lang/projects -$ cd ~/rust-lang/projects +$ mkdir ~/projects +$ cd ~/projects $ mkdir hello_world $ cd hello_world ``` @@ -22,17 +28,18 @@ $ cd hello_world 而对于 Windows 的 CMD， 请输入： ```console -> mkdir "%USERPROFILE%\rust-lang\projects" -> cd /d "%USERPROFILE%\rust-lang\projects" +> mkdir "%USERPROFILE%\projects" +> cd /d "%USERPROFILE%\projects" > mkdir hello_world > cd hello_world ``` -## 编写及运行 Rust 程序 +## 编写并运行一个 Rust 程序 -接下来，就要构造一个源代码文件，并命名为 `main.rs`。Rust 文件总是以 `.rs` 扩展名结束。若要在文件名中是一多个单词，那么请使用下划线来将这些单词隔开。比如，请使用 `hello_world.rs` 而不是 `helloworld.rs`。 -现在就要打开这个刚创建出的 `main.rs` 文件，并敲入清单 1-1 中的代码。 +接下来，请创建一个新的源文件，并将其命名为 `main.rs`。Rust 文件总是以 `.rs` 扩展名结尾。如果咱们在文件名中，使用了多个单词，惯例是要使用下划线，分隔这些单词。例如，请使用 `hello_world.rs`，而不是 `helloworld.rs`。 + +现在请打开咱们刚刚创建的 `main.rs` 文件，输入下面清单 1-1 中的代码。 文件名：`main.rs` @@ -42,9 +49,9 @@ fn main() { } ``` -*清单 1-1：打印`Hello, World!` 的程序* +*清单 1-1：打印出`Hello, World!` 的一个程序* -保存这个文件并回到终端窗口。在 Linux 或 macOS 上，请输入下面的命令来编译和运行这个文件： +请保存该文件，并返回到 `~/projects/hello_world` 目录下，咱们的终端窗口。在 Linux 或 macOS 上，请输入以下命令，编译并运行该文件： ```console $ rustc main.rs @@ -52,7 +59,7 @@ $ ./main Hello, World! ``` -在 Windows 上，就要输入命令 `.\main.exe` 而不是 `./main`： +在 Windows 上，请输入命令 `.\main.exe` 而不是 `./main`： ```console > rustc main.rs @@ -60,7 +67,18 @@ Hello, World! Hello, World! ``` -而不论所在操作系统为何，字符串 `Hello, World!` 都应打印到终端。而若没有看到这个输出，那么请回到安装小节的 [“问题排除”](#问题排除) 部分获取帮助。 +> **注意**：在 Windows 上使用 ZSH 的 MSYS2 环境下，上述命令的输出： + +```console +➜ hello_word rustc main.rs +➜ hello_word ls +main.exe main.pdb main.rs +➜ hello_word ./main.exe +Hello, World! +``` + +不论咱们的操作系统如何，`Hello, world!` 这个字符串都应打印到终端。如果咱们看不到此输出，请参阅安装部分的 [故障排除]() 部分，了解获得帮助的方法。 + 如确实打印出了 `Hello, World!`，那么恭喜你！你已正式编写除了一个 Rust 程序了。那就让你成为了一名 Rust 程序员了 -- 欢迎！ @@ -135,4 +153,4 @@ $ ./main # 或在 Windows 上的 .\main.exe 若你对某门动态语言，诸如 Ruby、Python 或者 JavaScript 更为熟悉，那么可能就不习惯于将编译和运行某个程序作为分开的步骤。Rust 是门 *提前编译* 语言（an *ahead-of-time compiled* language），这意味着可对程序进行编译，而将可执行文件交给他人，他们可在未安装 Rust 的情况下运行编译好的可执行文件。而若将某个 `.rb`、`.py`，或者 `.js` 文件交给某人时，他们就需要安装好相应的 Ruby、Python 或 JavaScript 实现。不过在这些语言中，仅需一个命令来编译和运行他们的程序。在编程语言设计中，每件事都有所取舍。 -对于简单的程序来说，用 `rustc` 编译就足够了，但随着项目的成长，就希望对所有选项进行管理，并令到代码分享更为简便。接下来，就要介绍 Cargo 工具了，这工具将帮助我们编写出实用的 Rust 程序。 + 对于简单的程序来说，用 `rustc` 编译就足够了，但随着项目的成长，就希望对所有选项进行管理，并令到代码分享更为简便。接下来，就要介绍 Cargo 工具了，这工具将帮助我们编写出实用的 Rust 程序。 diff --git a/src/getting_started/installation.md b/src/getting_started/installation.md index a23c019..b87412a 100644 --- a/src/getting_started/installation.md +++ b/src/getting_started/installation.md @@ -1,64 +1,70 @@ # 安装 -第一步即是安装 Rust。这里将通过 `rustup` 这个用于管理 Rust 版本及相关工具的命令行工具，来下载 Rust。要下载 Rust，就需要互联网连接。 +第一步是安装 Rust。我们将通过一个管理 Rust 版本与相关工具的命令行工具 `rustup`，下载 Rust。下载时咱们将需要互联网连接。 > 注意：若由于某些原因而不愿使用 `rustup`，那么请参考 [其他 Rust 安装方式页面](https://forge.rust-lang.org/infra/other-installation-methods.html) 了解更多选项。 -接下来就是要按照最新的稳定版 Rust 编译器。Rust 的稳定性保证了本书中所有示例都将在较新的 Rust 版本下可持续编译。由于 Rust 经常会改进错误消息和告警，因此在不同版本之间，输出可能会略有不同。也就是说，任何使用以下步骤所安装的较新、稳定版 Rust，都将如本书内容中所期望的那样工作。 +以下步骤将安装最新稳定版本的 Rust 编译器。Rust 的稳定性，保证了本书中所有编译成功的示例，都能继续在较新的 Rust 版本中编译。不同版本的输出，可能略有不同，因为 Rust 经常会改进错误信息和告警。换句话说，使用这些步骤安装的任何较新的、稳定的 Rust 版本，都应能与本书内容所预期的一样运行。 -> 关于**命令行注释** -> 在本章及全书中，都会给出一些在终端中用到的命令。他们是一些应在以 `$` 开始的终端中输入的行。至于这个 `$` 字符，是无需输入的；这个字符表示每条命令的开头。那些不以 `$` 开头的行，通常给出的是上一命令的输出。此外，那些特定于 `PowerShell` 的示例中，将使用 `>` 而不是 `$`。 + +> 关于 **命令行注解** +> +> 在本章和全书中，我们将介绍一些在终端中使用的命令。咱们要敲入到某个终端中的那些行，都以 `$` 开头。咱们无需键入那个 `$`；他属于命令行提示符，用于表示每条命令的开始。不以 `$` 开头的行，通常会显示前一条命令的输出。此外，特定于 `PowerShell` 的示例，会使用 `>` 而不是 `$`。 ## 在 Linux 与 macOS 上安装 `rustup` -若使用的是 Linux 或 macOS，那么请打开一个终端，然后输入下面的命令： + +如果咱们使用的是 Linux 或 macOS，请打开终端并输入以下命令： + ```console -curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh +$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh ``` -此命令会下载一个脚本并开始 `rustup` 工具的安装，而 `rustup` 将安装最新的稳定版 Rust。可能会提示输入 `sudo` 密码。在安装成功后，就会出现下面这行！ +这条命令会下载一个脚本，并启动 `rustup` 这个工具的安装，而 `rustup` 就会安装最新的 Rust 稳定版本。可能会提示输入密码。如果安装成功，会出现下面一行： + ```console Rust is isntalled now. Great! ``` -这里还将需要一个连接器（linker），这是个Rust要用来将其编译好的输出，组合起来形成一个文件的程序。似乎你的电脑上以及有了一个这样的连接器了。若收到连接器错误信息，那么就应安装一个 C 语言编译器，C 编译器通常会包含着连接器的。由于一些常用 Rust 包对 C 代码有依赖且需要 C 编译器，因此 C 编译器也是有用的。 +咱们还需要一个 Rust 用于将其编译输出，连接为一个文件的 *链接器，linker*，a program that Rust uses to join its compiled outputs into one file。咱们很可能已经有了这个链接器。如果出现链接器错误，那么咱们就应安装一个，通常包含了某个链接器的 C 编译器。C 编译器也很有用，因为一些常见的 Rust 软件包，均依赖于 C 代码，而因此需要 C 编译器。 + +在 macOS 上，咱们可以通过运行： -在 macOS 上，可通过运行下面的命令，获取到一个 C 编译器： ```console $ xcode-select --install ``` -Linux 用户一般都会安装 GCC 或 Clang，至于具体哪种 C 编译器，则是依据他们所用 Linux 分发版本的文档可以确定。比如若使用的是 Ubuntu，那么就可以安装 `build-essential` 软件包。 +获得一个 C 编译器。 + +Linux 用户一般应根据其发行版的文档，安装 GCC 或 Clang。例如，如果咱们使用 Ubuntu，则可以安装 `build-essential` 软件包。 ## 在 Windows 上安装 `rustup` -在 Windows 上，请前往 [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) 页面，并按照安装 Rust 的指令进行安装。在安装过程的某个时刻，将收到为何需要 Visual Studio 2013 或更新版本的 C++ 构建工具的说明。而最简单的获取到构建工具的方法，则是安装 [Visual Studio 2019 构建工具](https://visualstudio.microsoft.com/visual-cpp-build-tools/)。在询问将要安装何种工作负载（workloads）时，请确保 `C++ build tolls` 被选中，还要确保包含 Windows 10 SDK 及英语语言包。 -本书接下来用到的命令，在 `cmd.exe` 与 `PowerShell` 中都可工作。若其中有特定区别，本书将会解释要用哪个。 +在 Windows 上，请前往 https://www.rust-lang.org/tools/install 并按照说明安装 Rust。在安装过程中的某个时刻，咱们会收到一条信息，说明咱们还需要 Visual Studio 2013，或更高版本的 MSVC 构建工具。 + +而要获得构建工具，咱们需要安装 Visual Studio 2022。当被问及要安装哪些工作负载时，要包括下面这些： -## 更新与卸载 +- “使用 C++ 进行桌面开发” -在通过 `rustup` 安装了 Rust 后，更新到最新版本就容易了。在 `shell` 中运行下面的更新脚本： +- Windows 10 或 11 SDK -```console -$ rustup update -``` +- 英语语言包组件，以及咱们所选的任何其他语言包 -而要卸载 Rust 和 `rustup`，只需在 `shell` 中运行下面的卸载脚本： -```java -$ rustup self uninstall -``` +本书的其余部分使用了，可同时在 *cmd.exe* 和 PowerShell 中运行的命令。如果存在某些具体差异，我们将解释要使用哪个。 + ## 问题排除 -要检查当前是否安装了 Rust, 请开启一个 `shell` 并敲入这行命令： +要检查 Rust 安装是否正确，请打开 shell 并输入这一行： + ```console $ rustc --version @@ -70,11 +76,54 @@ $ rustc --version rustc x.y.z (abcabcadc yyyy-mm-dd) ``` -若看到这个信息，那么就已成功安装了 Rust！若看不到这个信息，且是在 Windows 上，那么就请在 `%PATH%` 系统变量中检查一下 Rust 在不在里面。若那一点问题都没有而 Rust 仍就不工作，那么可在数个地方需求帮助。其中最便利的就是 [Rust 官方 Discord](https://discord.gg/rust-lang) 上的 `#beginners` 频道了。在那里可与其他 Rust 公民（一种无厘头的自我称呼）聊天，他们可以帮助到你。其他不错的资源包括 [用户论坛](https://users.rust-lang.org/) 和 [Stack Overflow](https://stackoverflow.com/questions/tagged/rust)。 +> 在 Windows 上的 MSYS2 环境下的输出为： +```console +~ rustc --version +rustc 1.74.0 (79e9716c9 2023-11-13) +``` + +如果看到此信息，说明咱们已成功安装 Rust！如果没有看到此信息，请检查 Rust 是否在咱们的 `%PATH%` 系统变量中，如下所示。 + +在 Windows 的 CMD 中，请使用： + + +```cmd +> echo %PATH% +``` + +在 PowerShell 中，请使用： + +```powershell +> echo $env:Path +``` + +在 Linux 及 macOS 中，请使用： + +```console +$echo $PATH +``` + +如果这些都正确无误，而 Rust 仍无法正常工作，那么有很多咱们可以寻求帮助的地方。请访问 [社区页面](https://www.rust-lang.org/community)，了解如何与其他 Rustaceans（我们给自己起的昵称）取得联系。 + +## 更新与卸载 + +通过 `rustup` 安装 Rust 后，更新到新近发布的版本，就很容易了。请在 shell 中运行以下更新脚本： + + +```console +$ rustup update +``` + +要卸载 Rust 和 `rustup`，请在 shell 中运行以下卸载脚本： + + +```console +$ rustup self uninstall +``` ## 本地文档 -Rust 的安装，也包含了一份本地文档，因此可离线阅读到这本地文档。运行 `rustup doc` 即可在浏览器中打开这本地文档。 +Rust 的安装，还包含了一份本地文档，以便咱们离线阅读。请运行 `rustup doc`，在咱们的浏览器中打开本地文档。 -在任何时候遇到标准库所提供的类型或函数，而又确定他做些什么或该怎样使用这类型或函数时，就可以使用 API 文档来搞明白他是怎么回事！ +如果咱们不确定，某个标准库提供的类型或函数的作用，或使用方法，请使用应用程序编程接口（API）文档来搞清楚！