lintcheck/README.md

   1 ## `cargo lintcheck`
   2
   3 Runs clippy on a fixed set of crates read from
   4 `lintcheck/lintcheck_crates.toml` and saves logs of the lint warnings into the
   5 repo.  We can then check the diff and spot new or disappearing warnings.
   6
   7 From the repo root, run:
   8
   9 ```
  10 cargo run --target-dir lintcheck/target --manifest-path lintcheck/Cargo.toml
  11 ```
  12
  13 or
  14
  15 ```
  16 cargo lintcheck
  17 ```
  18
  19 By default the logs will be saved into
  20 `lintcheck-logs/lintcheck_crates_logs.txt`.
  21
  22 You can set a custom sources.toml by adding `--crates-toml custom.toml` or using
  23 `LINTCHECK_TOML="custom.toml"` where `custom.toml` must be a relative path from
  24 the repo root.
  25
  26 The results will then be saved to `lintcheck-logs/custom_logs.toml`.
  27
  28 ### Configuring the Crate Sources
  29
  30 The sources to check are saved in a `toml` file. There are three types of
  31 sources.
  32
  33 1. Crates-io Source
  34
  35    ```toml
  36    bitflags = {name = "bitflags", versions = ['1.2.1']}
  37    ```
  38    Requires a "name" and one or multiple "versions" to be checked.
  39
  40 2. `git` Source
  41    ````toml
  42    puffin = {name = "puffin", git_url = "https://github.com/EmbarkStudios/puffin", git_hash = "02dd4a3"}
  43    ````
  44    Requires a name, the url to the repo and unique identifier of a commit,
  45    branch or tag which is checked out before linting.  There is no way to always
  46    check `HEAD` because that would lead to changing lint-results as the repo
  47    would get updated.  If `git_url` or `git_hash` is missing, an error will be
  48    thrown.
  49
  50 3. Local Dependency
  51    ```toml
  52    clippy = {name = "clippy", path = "/home/user/clippy"}
  53    ```
  54    For when you want to add a repository that is not published yet.
  55
  56 #### Command Line Options (optional)
  57
  58 ```toml
  59 bitflags = {name = "bitflags", versions = ['1.2.1'], options = ['-Wclippy::pedantic', '-Wclippy::cargo']}
  60 ```
  61
  62 It is possible to specify command line options for each crate. This makes it
  63 possible to only check a crate for certain lint groups. If no options are
  64 specified, the lint groups `clippy::all`, `clippy::pedantic`, and
  65 `clippy::cargo` are checked. If an empty array is specified only `clippy::all`
  66 is checked.
  67
  68 **Note:** `-Wclippy::all` is always enabled by default, unless `-Aclippy::all`
  69 is explicitly specified in the options.
  70
  71 ### Fix mode
  72 You can run `cargo lintcheck --fix` which will run Clippy with `--fix` and
  73 print a warning if Clippy's suggestions fail to apply (if the resulting code does not build).
  74 This lets us spot bad suggestions or false positives automatically in some cases.
  75
  76 Please note that the target dir should be cleaned afterwards since clippy will modify
  77 the downloaded sources which can lead to unexpected results when running lintcheck again afterwards.
  78
  79 ### Recursive mode
  80 You can run `cargo lintcheck --recursive` to also run Clippy on the dependencies
  81 of the crates listed in the crates source `.toml`. e.g. adding `rand 0.8.5`
  82 would also lint `rand_core`, `rand_chacha`, etc.
  83
  84 Particularly slow crates in the dependency graph can be ignored using
  85 `recursive.ignore`:
  86
  87 ```toml
  88 [crates]
  89 cargo = {name = "cargo", versions = ['0.64.0']}
  90
  91 [recursive]
  92 ignore = [
  93     "unicode-normalization",
  94 ]
  95 ```