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

   1 ## Appendix D - Useful Development Tools
   2
   3 In this appendix, we talk about some useful development tools that the Rust
   4 project provides. We’ll look at automatic formatting, quick ways to apply
   5 warning fixes, a linter, and integrating with IDEs.
   6
   7 ### Automatic Formatting with `rustfmt`
   8
   9 The `rustfmt` tool reformats your code according to the community code style.
  10 Many collaborative projects use `rustfmt` to prevent arguments about which
  11 style to use when writing Rust: everyone formats their code using the tool.
  12
  13 To install `rustfmt`, enter the following:
  14
  15 ```console
  16 $ rustup component add rustfmt
  17 ```
  18
  19 This command gives you `rustfmt` and `cargo-fmt`, similar to how Rust gives you
  20 both `rustc` and `cargo`. To format any Cargo project, enter the following:
  21
  22 ```console
  23 $ cargo fmt
  24 ```
  25
  26 Running this command reformats all the Rust code in the current crate. This
  27 should only change the code style, not the code semantics. For more information
  28 on `rustfmt`, see [its documentation][rustfmt].
  29
  30 [rustfmt]: https://github.com/rust-lang/rustfmt
  31
  32 ### Fix Your Code with `rustfix`
  33
  34 The rustfix tool is included with Rust installations and can automatically fix
  35 compiler warnings that have a clear way to correct the problem that’s likely
  36 what you want. It’s likely you’ve seen compiler warnings before. For example,
  37 consider this code:
  38
  39 <span class="filename">Filename: src/main.rs</span>
  40
  41 ```rust
  42 fn do_something() {}
  43
  44 fn main() {
  45     for i in 0..100 {
  46         do_something();
  47     }
  48 }
  49 ```
  50
  51 Here, we’re calling the `do_something` function 100 times, but we never use the
  52 variable `i` in the body of the `for` loop. Rust warns us about that:
  53
  54 ```console
  55 $ cargo build
  56    Compiling myprogram v0.1.0 (file:///projects/myprogram)
  57 warning: unused variable: `i`
  58  --> src/main.rs:4:9
  59   |
  60 4 |     for i in 0..100 {
  61   |         ^ help: consider using `_i` instead
  62   |
  63   = note: #[warn(unused_variables)] on by default
  64
  65     Finished dev [unoptimized + debuginfo] target(s) in 0.50s
  66 ```
  67
  68 The warning suggests that we use `_i` as a name instead: the underscore
  69 indicates that we intend for this variable to be unused. We can automatically
  70 apply that suggestion using the `rustfix` tool by running the command `cargo
  71 fix`:
  72
  73 ```console
  74 $ cargo fix
  75     Checking myprogram v0.1.0 (file:///projects/myprogram)
  76       Fixing src/main.rs (1 fix)
  77     Finished dev [unoptimized + debuginfo] target(s) in 0.59s
  78 ```
  79
  80 When we look at *src/main.rs* again, we’ll see that `cargo fix` has changed the
  81 code:
  82
  83 <span class="filename">Filename: src/main.rs</span>
  84
  85 ```rust
  86 fn do_something() {}
  87
  88 fn main() {
  89     for _i in 0..100 {
  90         do_something();
  91     }
  92 }
  93 ```
  94
  95 The `for` loop variable is now named `_i`, and the warning no longer appears.
  96
  97 You can also use the `cargo fix` command to transition your code between
  98 different Rust editions. Editions are covered in Appendix E.
  99
 100 ### More Lints with Clippy
 101
 102 The Clippy tool is a collection of lints to analyze your code so you can catch
 103 common mistakes and improve your Rust code.
 104
 105 To install Clippy, enter the following:
 106
 107 ```console
 108 $ rustup component add clippy
 109 ```
 110
 111 To run Clippy’s lints on any Cargo project, enter the following:
 112
 113 ```console
 114 $ cargo clippy
 115 ```
 116
 117 For example, say you write a program that uses an approximation of a
 118 mathematical constant, such as pi, as this program does:
 119
 120 <span class="filename">Filename: src/main.rs</span>
 121
 122 ```rust
 123 fn main() {
 124     let x = 3.1415;
 125     let r = 8.0;
 126     println!("the area of the circle is {}", x * r * r);
 127 }
 128 ```
 129
 130 Running `cargo clippy` on this project results in this error:
 131
 132 ```text
 133 error: approximate value of `f{32, 64}::consts::PI` found
 134  --> src/main.rs:2:13
 135   |
 136 2 |     let x = 3.1415;
 137   |             ^^^^^^
 138   |
 139   = note: `#[deny(clippy::approx_constant)]` on by default
 140   = help: consider using the constant directly
 141   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#approx_constant
 142 ```
 143
 144 This error lets you know that Rust already has a more precise `PI` constant
 145 defined, and that your program would be more correct if you used the constant
 146 instead. You would then change your code to use the `PI` constant. The
 147 following code doesn’t result in any errors or warnings from Clippy:
 148
 149 <span class="filename">Filename: src/main.rs</span>
 150
 151 ```rust
 152 fn main() {
 153     let x = std::f64::consts::PI;
 154     let r = 8.0;
 155     println!("the area of the circle is {}", x * r * r);
 156 }
 157 ```
 158
 159 For more information on Clippy, see [its documentation][clippy].
 160
 161 [clippy]: https://github.com/rust-lang/rust-clippy
 162
 163 ### IDE Integration Using `rust-analyzer`
 164
 165 To help IDE integration, the Rust community recommends using
 166 [`rust-analyzer`][rust-analyzer]<!-- ignore -->. This tool is a set of
 167 compiler-centric utilities that speaks the [Language Server Protocol][lsp]<!--
 168 ignore -->, which is a specification for IDEs and programming languages to
 169 communicate with each other. Different clients can use `rust-analyzer`, such as
 170 [the Rust analyzer plug-in for Visual Studio Code][vscode].
 171
 172 [lsp]: http://langserver.org/
 173 [vscode]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer
 174
 175 Visit the `rust-analyzer` project’s [home page][rust-analyzer]<!-- ignore -->
 176 for installation instructions, then install the language server support in your
 177 particular IDE. Your IDE will gain abilities such as autocompletion, jump to
 178 definition, and inline errors.
 179
 180 [rust-analyzer]: https://rust-analyzer.github.io