summaryrefslogtreecommitdiffstats
path: root/src/doc/book/nostarch/appendix_d.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/doc/book/nostarch/appendix_d.md175
1 files changed, 175 insertions, 0 deletions
diff --git a/src/doc/book/nostarch/appendix_d.md b/src/doc/book/nostarch/appendix_d.md
new file mode 100644
index 000000000..96b73e954
--- /dev/null
+++ b/src/doc/book/nostarch/appendix_d.md
@@ -0,0 +1,175 @@
+<!-- DO NOT EDIT THIS FILE.
+
+This file is periodically generated from the content in the `/src/`
+directory, so all fixes need to be made in `/src/`.
+-->
+
+[TOC]
+
+## Appendix D: Useful Development Tools
+
+In this appendix, we talk about some useful development tools that the Rust
+project provides. We’ll look at automatic formatting, quick ways to apply
+warning fixes, a linter, and integrating with IDEs.
+
+## Automatic Formatting with rustfmt
+
+The `rustfmt` tool reformats your code according to the community code style.
+Many collaborative projects use `rustfmt` to prevent arguments about which
+style to use when writing Rust: everyone formats their code using the tool.
+
+Rust installations include `rustfmt` by default, so you should already have the
+programs `rustfmt` and `cargo-fmt` on your system. These two commands are
+analagous to `rustc` and `cargo` in that `rustfmt` allows finer-grained control
+and `cargo-fmt` understands conventions of a project that uses Cargo. To format
+any Cargo project, enter the following:
+
+```
+$ cargo fmt
+```
+
+Running this command reformats all the Rust code in the current crate. This
+should only change the code style, not the code semantics. For more information
+on `rustfmt`, see its documentation at *https://github.com/rust-lang/rustfmt*.
+
+## Fix Your Code with rustfix
+
+The `rustfix` tool is included with Rust installations and can automatically
+fix compiler warnings that have a clear way to correct the problem that’s
+likely what you want. You’ve probably seen compiler warnings before. For
+example, consider this code:
+
+Filename: src/main.rs
+
+```
+fn do_something() {}
+
+fn main() {
+ for i in 0..100 {
+ do_something();
+ }
+}
+```
+
+Here, we’re calling the `do_something` function 100 times, but we never use the
+variable `i` in the body of the `for` loop. Rust warns us about that:
+
+```
+$ cargo build
+ Compiling myprogram v0.1.0 (file:///projects/myprogram)
+warning: unused variable: `i`
+ --> src/main.rs:4:9
+ |
+4 | for i in 0..100 {
+ | ^ help: consider using `_i` instead
+ |
+ = note: #[warn(unused_variables)] on by default
+
+ Finished dev [unoptimized + debuginfo] target(s) in 0.50s
+```
+
+The warning suggests that we use `_i` as a name instead: the underscore
+indicates that we intend for this variable to be unused. We can automatically
+apply that suggestion using the `rustfix` tool by running the command `cargo
+fix`:
+
+```
+$ 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
+```
+
+When we look at *src/main.rs* again, we’ll see that `cargo fix` has changed the
+code:
+
+Filename: src/main.rs
+
+```
+fn do_something() {}
+
+fn main() {
+ for _i in 0..100 {
+ do_something();
+ }
+}
+```
+
+The `for` loop variable is now named `_i`, and the warning no longer appears.
+
+You can also use the `cargo fix` command to transition your code between
+different Rust editions. Editions are covered in Appendix E.
+
+## More Lints with Clippy
+
+The Clippy tool is a collection of lints to analyze your code so you can catch
+common mistakes and improve your Rust code. Clippy is included with standard
+Rust installations.
+
+To run Clippy’s lints on any Cargo project, enter the following:
+
+```
+$ cargo clippy
+```
+
+For example, say you write a program that uses an approximation of a
+mathematical constant, such as pi, as this program does:
+
+Filename: src/main.rs
+
+```
+fn main() {
+ let x = 3.1415;
+ let r = 8.0;
+ println!("the area of the circle is {}", x * r * r);
+}
+```
+
+Running `cargo clippy` on this project results in this error:
+
+```
+error: approximate value of `f{32, 64}::consts::PI` found
+ --> src/main.rs:2:13
+ |
+2 | let x = 3.1415;
+ | ^^^^^^
+ |
+ = note: `#[deny(clippy::approx_constant)]` on by default
+ = help: consider using the constant directly
+ = help: for further information visit https://rust-lang.github.io/rust-
+clippy/master/index.html#approx_constant
+```
+
+This error lets you know that Rust already has a more precise `PI` constant
+defined, and that your program would be more correct if you used the constant
+instead. You would then change your code to use the `PI` constant.
+
+The following code doesn’t result in any errors or warnings from Clippy:
+
+Filename: src/main.rs
+
+```
+fn main() {
+ let x = std::f64::consts::PI;
+ let r = 8.0;
+ println!("the area of the circle is {}", x * r * r);
+}
+```
+
+For more information on Clippy, see its documentation at
+*https://github.com/rust-lang/rust-clippy**.*
+
+## IDE Integration Using rust-analyzer
+
+To help with IDE integration, the Rust community recommends using
+`rust-analyzer`. This tool is a set of compiler-centric utilities that speak
+Language Server Protocol, which is a specification for IDEs and programming
+languages to communicate with each other. Different clients can use
+`rust-analyzer`, such as the Rust analyzer plug-in for Visual Studio Code at
+*https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer*.
+
+Visit the `rust-analyzer` project’s home page at
+*https://rust-analyzer.github.io* for installation instructions, then install
+the language server support in your particular IDE. Your IDE will gain
+capabilities such as autocompletion, jump to definition, and inline errors
+