Basics - Clippy Documentation

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Basics for hacking on Clippy

This document explains the basics for hacking on Clippy. Besides others, this includes how to build and test Clippy. For a more in depth description on the codebase take a look at Adding Lints or Common Tools.

- Basics for hacking on Clippy
  - Get the Code
  - Building and Testing
  - `cargo dev`
  - lintcheck
  - PR
  - Common Abbreviations
  - Install from source

## Get the Code

First, make sure you have checked out the latest version of Clippy. If this is your first time working on Clippy, create a fork of the repository and clone it afterwards with the following command:

    git clone git@github.com:<your-username>/rust-clippy

If you’ve already cloned Clippy in the past, update it to the latest version:

    # If the upstream remote has not been added yet
    git remote add upstream https://github.com/rust-lang/rust-clippy
    # upstream has to be the remote of the rust-lang/rust-clippy repo
    git fetch upstream
    # make sure that you are on the master branch
    git checkout master
    # rebase your master branch on the upstream master
    git rebase upstream/master
    # push to the master branch of your fork
    git push

## Building and Testing

You can build and test Clippy like every other Rust project:

    cargo build  # builds Clippy
    cargo test   # tests Clippy

Since Clippy’s test suite is pretty big, there are some commands that only run a subset of Clippy’s tests:

    # only run UI tests
    cargo uitest
    # only run UI tests starting with `test_`
    TESTNAME="test_" cargo uitest
    # only run dogfood tests
    cargo dev dogfood

If the output of a UI test differs from the expected output, you can update the reference file with:

    cargo bless

For example, this is necessary if you fix a typo in an error message of a lint, or if you modify a test file to add a test case.

> Note: This command may update more files than you intended. In that case only commit the files you wanted to update.

## `cargo dev`

Clippy has some dev tools to make working on Clippy more convenient. These tools can be accessed through the `cargo dev` command. Available tools are listed below. To get more information about these commands, just call them with `--help`.

    # formats the whole Clippy codebase and all tests
    cargo dev fmt
    # register or update lint names/groups/...
    cargo dev update_lints
    # create a new lint and register it
    cargo dev new_lint
    # deprecate a lint and attempt to remove code relating to it
    cargo dev deprecate
    # automatically formatting all code before each commit
    cargo dev setup git-hook
    # (experimental) Setup Clippy to work with RustRover
    cargo dev setup intellij
    # runs the `dogfood` tests
    cargo dev dogfood

More about intellij command usage and reasons.

## lintcheck

`cargo lintcheck` will build and run Clippy on a fixed set of crates and generate a log of the results. You can `git diff` the updated log against its previous version and see what impact your lint made on a small set of crates. If you add a new lint, please audit the resulting warnings and make sure there are no false positives and that the suggestions are valid.

Refer to the tools README for more details.

## PR

We follow a rustc no merge-commit policy. See https://rustc-dev-guide.rust-lang.org/contributing.html#opening-a-pr.

## Common Abbreviations

Abbreviation | Meaning
--- | ---
UB | Undefined Behavior
FP | False Positive
FN | False Negative
ICE | Internal Compiler Error
AST | Abstract Syntax Tree
MIR | Mid-Level Intermediate Representation
HIR | High-Level Intermediate Representation
TCX | Type context

This is a concise list of abbreviations that can come up during Clippy development. An extensive general list can be found in the rustc-dev-guide glossary. Always feel free to ask if an abbreviation or meaning is unclear to you.

## Install from source

If you are hacking on Clippy and want to install it from source, do the following:

From the Clippy project root, run the following command to build the Clippy binaries and copy them into the toolchain directory. This will create a new toolchain called `clippy` by default, see `cargo dev setup toolchain --help` for other options.

    cargo dev setup toolchain

Now you may run `cargo +clippy clippy` in any project using the new toolchain.

    cd my-project
    cargo +clippy clippy

…or `clippy-driver`

    clippy-driver +clippy <filename>

If you no longer need the toolchain it can be uninstalled using `rustup`:

    rustup toolchain uninstall clippy

> DO NOT install using `cargo install --path . --force` since this will overwrite rustup proxies. That is, `~/.cargo/bin/cargo-clippy` and `~/.cargo/bin/clippy-driver` should be hard or soft links to `~/.cargo/bin/rustup`. You can repair these by running `rustup update`.