Edit docs about macros

[rust.git] / doc / basics.md

diff --git a/doc/basics.md b/doc/basics.md
index 8f2a20bfe2468103c360059cf475f955bd18e028..57a90a924ec3cf9fd0a58ab6d3d969a2b1b91ef8 100644 (file)
--- a/doc/basics.md
+++ b/doc/basics.md
@@ -11,7 +11,10 @@ the codebase take a look at [Adding Lints] or [Common Tools].
   - [Get the Code](#get-the-code)
   - [Building and Testing](#building-and-testing)
   - [`cargo dev`](#cargo-dev)
+  - [lintcheck](#lintcheck)
   - [PR](#pr)
+  - [Common Abbreviations](#common-abbreviations)
+  - [Install from source](#install-from-source)
 
 ## Get the Code
 
@@ -26,6 +29,8 @@ git clone git@github.com:<your-username>/rust-clippy
 If you've already cloned Clippy in the past, update it to the latest version:
 
 ```bash
+# 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
@@ -86,10 +91,23 @@ cargo dev fmt
 cargo dev update_lints
 # create a new lint and register it
 cargo dev new_lint
-# (experimental) Setup Clippy to work with rust-analyzer
-cargo dev ra_setup
+# automatically formatting all code before each commit
+cargo dev setup git-hook
+# (experimental) Setup Clippy to work with IntelliJ-Rust
+cargo dev setup intellij
 ```
+More about intellij command usage and reasons [here](../CONTRIBUTING.md#intellij-rust)
 
+## 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.
+
+[README]: https://github.com/rust-lang/rust-clippy/blob/master/lintcheck/README.md
 ## PR
 
 We follow a rustc no merge-commit policy.
@@ -108,8 +126,49 @@ See <https://rustc-dev-guide.rust-lang.org/contributing.html#opening-a-pr>.
 | HIR          | High-Level Intermediate Representation |
 | TCX          | Type context                           |
 
-This is a concise list of abbreviations that can come up during clippy development. An extensive
-genal list can be found in the [rustc-dev-guide glossary][glossary]. Always feel free to ask if
+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][glossary]. Always feel free to ask if
 an abbreviation or meaning is unclear to you.
 
-[glossary]: https://rustc-dev-guide.rust-lang.org/appendix/glossary.html
\ No newline at end of file
+## Install from source
+
+If you are hacking on Clippy and want to install it from source, do the following:
+
+First, take note of the toolchain [override](https://rust-lang.github.io/rustup/overrides.html) in `/rust-toolchain`.
+We will use this override to install Clippy into the right toolchain.
+
+> Tip: You can view the active toolchain for the current directory with `rustup show active-toolchain`.
+
+From the Clippy project root, run the following command to build the Clippy binaries and copy them into the
+toolchain directory. This will override the currently installed Clippy component.
+
+```terminal
+cargo build --release --bin cargo-clippy --bin clippy-driver -Zunstable-options --out-dir "$(rustc --print=sysroot)/bin"
+```
+
+Now you may run `cargo clippy` in any project, using the toolchain where you just installed Clippy.
+
+```terminal
+cd my-project
+cargo +nightly-2021-07-01 clippy
+```
+
+...or `clippy-driver`
+
+```terminal
+clippy-driver +nightly-2021-07-01 <filename>
+```
+
+If you need to restore the default Clippy installation, run the following (from the Clippy project root).
+
+```terminal
+rustup component remove clippy
+rustup component add clippy
+```
+
+> **DO NOT** install using `cargo install --path . --force` since this will overwrite rustup
+> [proxies](https://rust-lang.github.io/rustup/concepts/proxies.html). 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`.
+
+[glossary]: https://rustc-dev-guide.rust-lang.org/appendix/glossary.html