check to appendix-05

src/appendix-04-useful-development-tools.md

@@ -1,5 +1,168 @@
-## 附录 E：实用开发工具
+## 附录 D：实用开发工具
 
 > [appendix-04-useful-development-tools.md](https://github.com/rust-lang/book/blob/master/src/appendix-04-useful-development-tools.md)
 > <br />
-> commit 1fedfc4b96c2017f64ecfcf41a0a07e2e815f24f
+> commit 1fedfc4b96c2017f64ecfcf41a0a07e2e815f24f
+
+本附录，我们将讨论 Rust 项目提供的用于开发 Rust 代码的工具。
+
+## 通过 `rustfmt` 自动格式化
+
+`rustfmt` 工具根据社区代码风格格式化代码。很多项目使用 `rustfmt` 来避免编写 Rust 风格的争论：所有人都用这个工具格式化代码！
+
+`rustfmt` 工具的质量还未达到发布 1.0 版本的水平，不过目前有一个可用的预览版。请尝试使用并告诉我们它如何！
+
+安装 `rustfmt`：
+
+```text
+$ rustup component add rustfmt-preview
+```
+
+这会提供 `rustfmt` 和 `cargo-fmt`，类似于 Rust 同时安装 `rustc` 和 `cargo`。为了格式化整个 Cargo 项目：
+
+```text
+$ cargo fmt
+```
+
+运行此命令会格式化当前 crate 中所有的 Rust 代码。这应该只会改变代码风格，而不是代码语义。请查看 [该文档][rustfmt] 了解 `rustfmt` 的更多信息。
+
+[rustfmt]: https://github.com/rust-lang-nursery/rustfmt
+
+## 通过 `rustfix` 修复代码
+
+如果你编写过 Rust 代码，那么你可能见过编译器警告。例如，考虑如下代码：
+
+<span class="filename">文件名: src/main.rs</span>
+
+```rust
+fn do_something() {}
+
+fn main() {
+    for i in 0..100 {
+        do_something();
+    }
+}
+```
+
+这里调用了 `do_something` 函数 100 次，不过从未在 `for` 循环体中使用变量 `i`。Rust 会警告说：
+
+```text
+$ cargo build
+   Compiling myprogram v0.1.0 (file:///projects/myprogram)
+warning: unused variable: `i`
+ --> src/main.rs:4:9
+  |
+4 |     for i in 1..100 {
+  |         ^ help: consider using `_i` instead
+  |
+  = note: #[warn(unused_variables)] on by default
+
+    Finished dev [unoptimized + debuginfo] target(s) in 0.50s
+```
+
+警告中建议使用 `_i` 名称：下划线表明该变量有意不使用。我们可以通过 `cargo fix` 命令使用 `rustfix` 工具来自动采用该建议：
+
+```text
+$ cargo fix
+    Checking myprogram v0.1.0 (file:///projects/myprogram)
+      Fixing src/main.rs (1 fix)
+    Finished dev [unoptimized + debuginfo] target(s) in 0.59s
+```
+
+如果再次查看 *src/main.rs*，会发现 `cargo fix` 修改了代码：
+
+<span class="filename">文件名: src/main.rs</span>
+
+```rust
+fn do_something() {}
+
+fn main() {
+    for _i in 0..100 {
+        do_something();
+    }
+}
+```
+
+现在 `for` 循环变量变为 `_i`，警告也不再出现。
+
+`cargo fix` 命令可以用于在不同 Rust 版本间迁移代码。版本在附录 E 中介绍。
+
+## 通过 `clippy` 提供更多 lint 功能
+
+`clippy` 工具是一系列 lint 的集合，用于捕捉常见错误和改进 Rust 代码。
+
+`clippy` 工具的质量还未达到发布 1.0 版本的水平，不过目前有一个可用的预览版。请尝试使用并告诉我们它如何！
+
+安装 `clippy`：
+
+```text
+$ rustup component add clippy-preview
+```
+
+对任何 Cargo 项目运行 clippy 的 lint：
+
+```text
+$ cargo clippy
+```
+
+例如，如果程序使用了如 pi 这样数学常数的近似值，如下：
+
+<span class="filename">文件名: src/main.rs</span>
+
+```rust
+fn main() {
+    let x = 3.1415;
+    let r = 8.0;
+    println!("the area of the circle is {}", x * r * r);
+}
+```
+
+在此项目上运行 `cargo clippy` 会导致这个错误：
+
+```text
+error: approximate value of `f{32, 64}::consts::PI` found. Consider using it directly
+ --> src/main.rs:2:13
+  |
+2 |     let x = 3.1415;
+  |             ^^^^^^
+  |
+  = note: #[deny(clippy::approx_constant)] on by default
+  = help: for further information visit https://rust-lang-nursery.github.io/rust-clippy/v0.0.212/index.html#approx_constant
+```
+
+这告诉我们 Rust 定义了更为精确的常量，而如果使用了这些常量程序将更加准确。如下代码就不会导致 `clippy` 产生任何错误或警告：
+
+<span class="filename">文件名: src/main.rs</span>
+
+```rust
+fn main() {
+    let x = std::f64::consts::PI;
+    let r = 8.0;
+    println!("the area of the circle is {}", x * r * r);
+}
+```
+
+请查看 [其文档][clippy] 来了解 `clippy` 的更多信息。
+
+[clippy]: https://github.com/rust-lang-nursery/rust-clippy
+
+## 使用 Rust Language Server 的 IDE 集成
+
+为了帮助 IDE 集成，Rust 项目分发了 `rls`，其为 Rust Language Server 的缩写。这个工具采用 [Language Server Protocol][lsp]，这是一个 IDE 与编程语言沟通的规格说明。`rls` 可以用于不同的客户端，比如 [Visual Studio: Code 的 Rust 插件][vscode]。
+
+[lsp]: http://langserver.org/
+[vscode]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust
+
+`rls` 工具的质量还未达到发布 1.0 版本的水平，不过目前有一个可用的预览版。请尝试使用并告诉我们它如何！
+
+安装 `rls`：
+
+```text
+$ rustup component add rls-preview
+```
+
+接着为特定的 IDE 安装 language server 支持，如比便会获得如自动补全、跳转到定义和 inline error 之类的功能。
+
+请查看 [其文档][rls] 来了解 `rls` 的更多信息。
+
+[rls]: https://github.com/rust-lang-nursery/rls

src/appendix-05-editions.md

@@ -2,4 +2,26 @@
 
 > [appendix-05-editions.md](https://github.com/rust-lang/book/blob/master/src/appendix-05-editions.md)
 > <br />
-> commit 1fedfc4b96c2017f64ecfcf41a0a07e2e815f24f
+> commit 1fedfc4b96c2017f64ecfcf41a0a07e2e815f24f
+
+早在第一章，我们见过 `cargo new` 在 *Cargo.toml* 中增加了一些有关 `edition` 的元数据。本附录将解释其意义！
+
+Rust 语言和编译器有一个为期 6 周的发布循环。这意味着用户会稳定得到新功能的更新。其他编程语言发布大更新但不甚频繁；Rust 选择更为频繁的发布小更新。一段时间之后，所有这些小更新会日积月累。不过随着版本的发布，很难回顾说 “哇，从 Rust 1.10 到 Rust 1.31，Rust 的变化真大！”
+
+每两到三年，Rust 团队会生成一个新的 Rust **版本**（*edition*）。每一个版本会结合已经落地的功能，并提供一个清晰的带有完整更新文档和工具的功能包。新版本会作为常规的 6 周发布过程的一部分发布。
+
+这为不同的人群提供了不同的功能：
+
+* 对于活跃的 Rust 用户，其将增量的修改与易于理解的功能包相结合。
+* 对于非用户，它表明发布了一些重大进展，这意味着 Rust 可能变得值得一试。
+* 对于 Rust 自身开发者，其提供了项目整体的集合点。
+
+在本文档编写时，Rust 有两个版本：Rust 2015 和 Rust 2018。本书基于 Rust 2018 edition 编写。
+
+*Cargo.toml* 中的 `edition` 字段表明代码应该使用哪个版本编译。如果该字段不存在，其默认为 `2015` 以提供后向兼容性。
+
+每个项目都可以选择不同于默认的 2015 edition 的版本。这样，版本可能会包含不兼容的修改，比如新增关键字可能会与代码中的标识符冲突并导致错误。不过除非选择兼容这些修改，（旧）代码仍将能够编译，即便升级了 Rust 编译器的版本。所有 Rust 编译器都支持任何之前存在的编译器版本，并可以链接人恶化支持版本的 crate。编译器修改只影响最初的解析代码的过程。因此，如果你使用 Rust 2015 而某个依赖使用 Rust 2018，你的项目仍旧能够编译并使用该依赖。反之，若项目使用 Rust 2018 而依赖使用 Rust 2015 亦可工作。
+
+有一点需要明确：大部分功能在所有版本中都能使用。开发者使用任何 Rust 版本将能继续接收最新稳定版的改进。然而在一些情况，主要是增加了新关键字的时候，则可能出现了只能用于新版本的功能。只需切换版本即可利用新版本的功能。
+
+请查看 [Edition Guide](https://rust-lang-nursery.github.io/edition-guide/) 了解更多细节，这是一个完全介绍版本的书籍，包括如何通过 `cargo fix` 自动将代码迁移到新版本。