src/tools/clippy/book/src/development/basics.md

   1 # Basics for hacking on Clippy
   2
   3 This document explains the basics for hacking on Clippy. Besides others, this
   4 includes how to build and test Clippy. For a more in depth description on the
   5 codebase take a look at [Adding Lints] or [Common Tools].
   6
   7 [Adding Lints]: https://github.com/rust-lang/rust-clippy/blob/master/book/src/development/adding_lints.md
   8 [Common Tools]: https://github.com/rust-lang/rust-clippy/blob/master/book/src/development/common_tools_writing_lints.md
   9
  10 - [Basics for hacking on Clippy](#basics-for-hacking-on-clippy)
  11   - [Get the Code](#get-the-code)
  12   - [Building and Testing](#building-and-testing)
  13   - [`cargo dev`](#cargo-dev)
  14   - [lintcheck](#lintcheck)
  15   - [PR](#pr)
  16   - [Common Abbreviations](#common-abbreviations)
  17   - [Install from source](#install-from-source)
  18
  19 ## Get the Code
  20
  21 First, make sure you have checked out the latest version of Clippy. If this is
  22 your first time working on Clippy, create a fork of the repository and clone it
  23 afterwards with the following command:
  24
  25 ```bash
  26 git clone git@github.com:<your-username>/rust-clippy
  27 ```
  28
  29 If you've already cloned Clippy in the past, update it to the latest version:
  30
  31 ```bash
  32 # If the upstream remote has not been added yet
  33 git remote add upstream https://github.com/rust-lang/rust-clippy
  34 # upstream has to be the remote of the rust-lang/rust-clippy repo
  35 git fetch upstream
  36 # make sure that you are on the master branch
  37 git checkout master
  38 # rebase your master branch on the upstream master
  39 git rebase upstream/master
  40 # push to the master branch of your fork
  41 git push
  42 ```
  43
  44 ## Building and Testing
  45
  46 You can build and test Clippy like every other Rust project:
  47
  48 ```bash
  49 cargo build  # builds Clippy
  50 cargo test   # tests Clippy
  51 ```
  52
  53 Since Clippy's test suite is pretty big, there are some commands that only run a
  54 subset of Clippy's tests:
  55
  56 ```bash
  57 # only run UI tests
  58 cargo uitest
  59 # only run UI tests starting with `test_`
  60 TESTNAME="test_" cargo uitest
  61 # only run dogfood tests
  62 cargo dev dogfood
  63 ```
  64
  65 If the output of a [UI test] differs from the expected output, you can update
  66 the reference file with:
  67
  68 ```bash
  69 cargo dev bless
  70 ```
  71
  72 For example, this is necessary if you fix a typo in an error message of a lint,
  73 or if you modify a test file to add a test case.
  74
  75 > _Note:_ This command may update more files than you intended. In that case
  76 > only commit the files you wanted to update.
  77
  78 [UI test]: https://rustc-dev-guide.rust-lang.org/tests/adding.html#guide-to-the-ui-tests
  79
  80 ## `cargo dev`
  81
  82 Clippy has some dev tools to make working on Clippy more convenient. These tools
  83 can be accessed through the `cargo dev` command. Available tools are listed
  84 below. To get more information about these commands, just call them with
  85 `--help`.
  86
  87 ```bash
  88 # formats the whole Clippy codebase and all tests
  89 cargo dev fmt
  90 # register or update lint names/groups/...
  91 cargo dev update_lints
  92 # create a new lint and register it
  93 cargo dev new_lint
  94 # deprecate a lint and attempt to remove code relating to it
  95 cargo dev deprecate
  96 # automatically formatting all code before each commit
  97 cargo dev setup git-hook
  98 # (experimental) Setup Clippy to work with IntelliJ-Rust
  99 cargo dev setup intellij
 100 # runs the `dogfood` tests
 101 cargo dev dogfood
 102 ```
 103
 104 More about [intellij] command usage and reasons.
 105
 106 [intellij]: https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md#intellij-rust
 107
 108 ## lintcheck
 109
 110 `cargo lintcheck` will build and run clippy on a fixed set of crates and
 111 generate a log of the results.  You can `git diff` the updated log against its
 112 previous version and see what impact your lint made on a small set of crates.
 113 If you add a new lint, please audit the resulting warnings and make sure there
 114 are no false positives and that the suggestions are valid.
 115
 116 Refer to the tools [README] for more details.
 117
 118 [README]: https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/README.md
 119
 120 ## PR
 121
 122 We follow a rustc no merge-commit policy. See
 123 <https://rustc-dev-guide.rust-lang.org/contributing.html#opening-a-pr>.
 124
 125 ## Common Abbreviations
 126
 127 | Abbreviation | Meaning                                |
 128 | ------------ | -------------------------------------- |
 129 | UB           | Undefined Behavior                     |
 130 | FP           | False Positive                         |
 131 | FN           | False Negative                         |
 132 | ICE          | Internal Compiler Error                |
 133 | AST          | Abstract Syntax Tree                   |
 134 | MIR          | Mid-Level Intermediate Representation  |
 135 | HIR          | High-Level Intermediate Representation |
 136 | TCX          | Type context                           |
 137
 138 This is a concise list of abbreviations that can come up during Clippy
 139 development. An extensive general list can be found in the [rustc-dev-guide
 140 glossary][glossary]. Always feel free to ask if an abbreviation or meaning is
 141 unclear to you.
 142
 143 ## Install from source
 144
 145 If you are hacking on Clippy and want to install it from source, do the
 146 following:
 147
 148 First, take note of the toolchain
 149 [override](https://rust-lang.github.io/rustup/overrides.html) in
 150 `/rust-toolchain`. We will use this override to install Clippy into the right
 151 toolchain.
 152
 153 > Tip: You can view the active toolchain for the current directory with `rustup
 154 > show active-toolchain`.
 155
 156 From the Clippy project root, run the following command to build the Clippy
 157 binaries and copy them into the toolchain directory. This will override the
 158 currently installed Clippy component.
 159
 160 ```terminal
 161 cargo build --release --bin cargo-clippy --bin clippy-driver -Zunstable-options --out-dir "$(rustc --print=sysroot)/bin"
 162 ```
 163
 164 Now you may run `cargo clippy` in any project, using the toolchain where you
 165 just installed Clippy.
 166
 167 ```terminal
 168 cd my-project
 169 cargo +nightly-2021-07-01 clippy
 170 ```
 171
 172 ...or `clippy-driver`
 173
 174 ```terminal
 175 clippy-driver +nightly-2021-07-01 <filename>
 176 ```
 177
 178 If you need to restore the default Clippy installation, run the following (from
 179 the Clippy project root).
 180
 181 ```terminal
 182 rustup component remove clippy
 183 rustup component add clippy
 184 ```
 185
 186 > **DO NOT** install using `cargo install --path . --force` since this will
 187 > overwrite rustup
 188 > [proxies](https://rust-lang.github.io/rustup/concepts/proxies.html). That is,
 189 > `~/.cargo/bin/cargo-clippy` and `~/.cargo/bin/clippy-driver` should be hard or
 190 > soft links to `~/.cargo/bin/rustup`. You can repair these by running `rustup
 191 > update`.
 192
 193 [glossary]: https://rustc-dev-guide.rust-lang.org/appendix/glossary.html