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 set-up the development environment, how to build and how to test
   5 Clippy. For a more in depth description on the codebase take a look at [Adding
   6 Lints] or [Common Tools].
   7
   8 [Adding Lints]: https://github.com/rust-lang/rust-clippy/blob/master/doc/adding_lints.md
   9 [Common Tools]: https://github.com/rust-lang/rust-clippy/blob/master/doc/common_tools_writing_lints.md
  10
  11 - [Basics for hacking on Clippy](#basics-for-hacking-on-clippy)
  12   - [Get the code](#get-the-code)
  13   - [Setup](#setup)
  14   - [Building and Testing](#building-and-testing)
  15   - [`cargo dev`](#cargo-dev)
  16
  17 ## Get the Code
  18
  19 First, make sure you have checked out the latest version of Clippy. If this is
  20 your first time working on Clippy, create a fork of the repository and clone it
  21 afterwards with the following command:
  22
  23 ```bash
  24 git clone git@github.com:<your-username>/rust-clippy
  25 ```
  26
  27 If you've already cloned Clippy in the past, update it to the latest version:
  28
  29 ```bash
  30 # upstream has to be the remote of the rust-lang/rust-clippy repo
  31 git fetch upstream
  32 # make sure that you are on the master branch
  33 git checkout master
  34 # rebase your master branch on the upstream master
  35 git rebase upstream/master
  36 # push to the master branch of your fork
  37 git push
  38 ```
  39
  40 ## Setup
  41
  42 Next we need to setup the toolchain to compile Clippy. Since Clippy heavily
  43 relies on compiler internals it is build with the latest rustc master. To get
  44 this toolchain, you can just use the `setup-toolchain.sh` script or use
  45 `rustup-toolchain-install-master`:
  46
  47 ```bash
  48 sh setup-toolchain.sh
  49 # OR
  50 cargo install rustup-toolchain-install-master
  51 # For better IDE integration also add `-c rustfmt -c rust-src` (optional)
  52 rustup-toolchain-install-master -f -n master -c rustc-dev -c llvm-tools
  53 rustup override set master
  54 ```
  55
  56 _Note:_ Sometimes you may get compiler errors when building Clippy, even if you
  57 didn't change anything. Normally those will be fixed by a maintainer in a few hours.
  58
  59 ## Building and Testing
  60
  61 Once the `master` toolchain is installed, you can build and test Clippy like
  62 every other Rust project:
  63
  64 ```bash
  65 cargo build  # builds Clippy
  66 cargo test   # tests Clippy
  67 ```
  68
  69 Since Clippy's test suite is pretty big, there are some commands that only run a
  70 subset of Clippy's tests:
  71
  72 ```bash
  73 # only run UI tests
  74 cargo uitest
  75 # only run UI tests starting with `test_`
  76 TESTNAME="test_" cargo uitest
  77 # only run dogfood tests
  78 cargo test --test dogfood
  79 ```
  80
  81 If the output of a [UI test] differs from the expected output, you can update the
  82 reference file with:
  83
  84 ```bash
  85 sh tests/ui/update-all-references.sh
  86 ```
  87
  88 For example, this is necessary, if you fix a typo in an error message of a lint
  89 or if you modify a test file to add a test case.
  90
  91 _Note:_ This command may update more files than you intended. In that case only
  92 commit the files you wanted to update.
  93
  94 [UI test]: https://rustc-dev-guide.rust-lang.org/tests/adding.html#guide-to-the-ui-tests
  95
  96 ## `cargo dev`
  97
  98 Clippy has some dev tools to make working on Clippy more convenient. These tools
  99 can be accessed through the `cargo dev` command. Available tools are listed
 100 below. To get more information about these commands, just call them with
 101 `--help`.
 102
 103 ```bash
 104 # formats the whole Clippy codebase and all tests
 105 cargo dev fmt
 106 # register or update lint names/groups/...
 107 cargo dev update_lints
 108 # create a new lint and register it
 109 cargo dev new_lint
 110 # (experimental) Setup Clippy to work with rust-analyzer
 111 cargo dev ra-setup
 112 ```