src/tools/clippy/doc/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
   5 the codebase take a look at [Adding Lints] or [Common Tools].
   6
   7 [Adding Lints]: https://github.com/rust-lang/rust-clippy/blob/master/doc/adding_lints.md
   8 [Common Tools]: https://github.com/rust-lang/rust-clippy/blob/master/doc/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
  18 ## Get the Code
  19
  20 First, make sure you have checked out the latest version of Clippy. If this is
  21 your first time working on Clippy, create a fork of the repository and clone it
  22 afterwards with the following command:
  23
  24 ```bash
  25 git clone git@github.com:<your-username>/rust-clippy
  26 ```
  27
  28 If you've already cloned Clippy in the past, update it to the latest version:
  29
  30 ```bash
  31 # If the upstream remote has not been added yet
  32 git remote add upstream https://github.com/rust-lang/rust-clippy
  33 # upstream has to be the remote of the rust-lang/rust-clippy repo
  34 git fetch upstream
  35 # make sure that you are on the master branch
  36 git checkout master
  37 # rebase your master branch on the upstream master
  38 git rebase upstream/master
  39 # push to the master branch of your fork
  40 git push
  41 ```
  42
  43 ## Building and Testing
  44
  45 You can build and test Clippy like every other Rust project:
  46
  47 ```bash
  48 cargo build  # builds Clippy
  49 cargo test   # tests Clippy
  50 ```
  51
  52 Since Clippy's test suite is pretty big, there are some commands that only run a
  53 subset of Clippy's tests:
  54
  55 ```bash
  56 # only run UI tests
  57 cargo uitest
  58 # only run UI tests starting with `test_`
  59 TESTNAME="test_" cargo uitest
  60 # only run dogfood tests
  61 cargo test --test dogfood
  62 ```
  63
  64 If the output of a [UI test] differs from the expected output, you can update the
  65 reference file with:
  66
  67 ```bash
  68 cargo dev bless
  69 ```
  70
  71 For example, this is necessary, if you fix a typo in an error message of a lint
  72 or if you modify a test file to add a test case.
  73
  74 _Note:_ This command may update more files than you intended. In that case only
  75 commit the files you wanted to update.
  76
  77 [UI test]: https://rustc-dev-guide.rust-lang.org/tests/adding.html#guide-to-the-ui-tests
  78
  79 ## `cargo dev`
  80
  81 Clippy has some dev tools to make working on Clippy more convenient. These tools
  82 can be accessed through the `cargo dev` command. Available tools are listed
  83 below. To get more information about these commands, just call them with
  84 `--help`.
  85
  86 ```bash
  87 # formats the whole Clippy codebase and all tests
  88 cargo dev fmt
  89 # register or update lint names/groups/...
  90 cargo dev update_lints
  91 # create a new lint and register it
  92 cargo dev new_lint
  93 # (experimental) Setup Clippy to work with IntelliJ-Rust
  94 cargo dev ide_setup
  95 ```
  96
  97 ## lintcheck
  98 `cargo lintcheck` will build and run clippy on a fixed set of crates and generate a log of the results.
  99 You can `git diff` the updated log against its previous version and
 100 see what impact your lint made on a small set of crates.
 101 If you add a new lint, please audit the resulting warnings and make sure
 102 there are no false positives and that the suggestions are valid.
 103
 104 Refer to the tools [README] for more details.
 105
 106 [README]: https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/README.md
 107 ## PR
 108
 109 We follow a rustc no merge-commit policy.
 110 See <https://rustc-dev-guide.rust-lang.org/contributing.html#opening-a-pr>.
 111
 112 ## Common Abbreviations
 113
 114 | Abbreviation | Meaning                                |
 115 | ------------ | -------------------------------------- |
 116 | UB           | Undefined Behavior                     |
 117 | FP           | False Positive                         |
 118 | FN           | False Negative                         |
 119 | ICE          | Internal Compiler Error                |
 120 | AST          | Abstract Syntax Tree                   |
 121 | MIR          | Mid-Level Intermediate Representation  |
 122 | HIR          | High-Level Intermediate Representation |
 123 | TCX          | Type context                           |
 124
 125 This is a concise list of abbreviations that can come up during Clippy development. An extensive
 126 general list can be found in the [rustc-dev-guide glossary][glossary]. Always feel free to ask if
 127 an abbreviation or meaning is unclear to you.
 128
 129 [glossary]: https://rustc-dev-guide.rust-lang.org/appendix/glossary.html