-# Clippy
+# The Rust Programming Language
-[/badge.svg?branch=auto&event=push)](https://github.com/rust-lang/rust-clippy/actions?query=workflow%3A%22Clippy+Test+(bors)%22+event%3Apush+branch%3Aauto)
-[](#license)
+This is the main source code repository for [Rust]. It contains the compiler,
+standard library, and documentation.
-A collection of lints to catch common mistakes and improve your [Rust](https://github.com/rust-lang/rust) code.
+[Rust]: https://www.rust-lang.org/
-[There are over 550 lints included in this crate!](https://rust-lang.github.io/rust-clippy/master/index.html)
+**Note: this README is for _users_ rather than _contributors_.**
+If you wish to _contribute_ to the compiler, you should read
+[CONTRIBUTING.md](CONTRIBUTING.md) instead.
-Lints are divided into categories, each with a default [lint level](https://doc.rust-lang.org/rustc/lints/levels.html).
-You can choose how much Clippy is supposed to ~~annoy~~ help you by changing the lint level by category.
+## Quick Start
-| Category | Description | Default level |
-| --------------------- | ----------------------------------------------------------------------------------- | ------------- |
-| `clippy::all` | all lints that are on by default (correctness, suspicious, style, complexity, perf) | **warn/deny** |
-| `clippy::correctness` | code that is outright wrong or useless | **deny** |
-| `clippy::suspicious` | code that is most likely wrong or useless | **warn** |
-| `clippy::style` | code that should be written in a more idiomatic way | **warn** |
-| `clippy::complexity` | code that does something simple but in a complex way | **warn** |
-| `clippy::perf` | code that can be written to run faster | **warn** |
-| `clippy::pedantic` | lints which are rather strict or have occasional false positives | allow |
-| `clippy::nursery` | new lints that are still under development | allow |
-| `clippy::cargo` | lints for the cargo manifest | allow |
+Read ["Installation"] from [The Book].
-More to come, please [file an issue](https://github.com/rust-lang/rust-clippy/issues) if you have ideas!
+["Installation"]: https://doc.rust-lang.org/book/ch01-01-installation.html
+[The Book]: https://doc.rust-lang.org/book/index.html
-The [lint list](https://rust-lang.github.io/rust-clippy/master/index.html) also contains "restriction lints", which are
-for things which are usually not considered "bad", but may be useful to turn on in specific cases. These should be used
-very selectively, if at all.
+## Installing from Source
-Table of contents:
+The Rust build system uses a Python script called `x.py` to build the compiler,
+which manages the bootstrapping process. It lives at the root of the project.
-* [Usage instructions](#usage)
-* [Configuration](#configuration)
-* [Contributing](#contributing)
-* [License](#license)
+The `x.py` command can be run directly on most Unix systems in the following
+format:
-## Usage
+```sh
+./x.py <subcommand> [flags]
+```
-Below are instructions on how to use Clippy as a cargo subcommand,
-in projects that do not use cargo, or in Travis CI.
+This is how the documentation and examples assume you are running `x.py`.
+Some alternative ways are:
-### As a cargo subcommand (`cargo clippy`)
+```sh
+# On a Unix shell if you don't have the necessary `python3` command
+./x <subcommand> [flags]
-One way to use Clippy is by installing Clippy through rustup as a cargo
-subcommand.
+# On the Windows Command Prompt (if .py files are configured to run Python)
+x.py <subcommand> [flags]
-#### Step 1: Install Rustup
+# You can also run Python yourself, e.g.:
+python x.py <subcommand> [flags]
+```
-You can install [Rustup](https://rustup.rs/) on supported platforms. This will help
-us install Clippy and its dependencies.
+More information about `x.py` can be found by running it with the `--help` flag
+or reading the [rustc dev guide][rustcguidebuild].
-If you already have Rustup installed, update to ensure you have the latest
-Rustup and compiler:
+[gettingstarted]: https://rustc-dev-guide.rust-lang.org/getting-started.html
+[rustcguidebuild]: https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html
-```terminal
-rustup update
-```
+### Dependencies
-#### Step 2: Install Clippy
+Make sure you have installed the dependencies:
-Once you have rustup and the latest stable release (at least Rust 1.29) installed, run the following command:
+* `python` 3 or 2.7
+* `git`
+* A C compiler (when building for the host, `cc` is enough; cross-compiling may
+ need additional compilers)
+* `curl` (not needed on Windows)
+* `pkg-config` if you are compiling on Linux and targeting Linux
+* `libiconv` (already included with glibc on Debian-based distros)
-```terminal
-rustup component add clippy
-```
-If it says that it can't find the `clippy` component, please run `rustup self update`.
+To build Cargo, you'll also need OpenSSL (`libssl-dev` or `openssl-devel` on
+most Unix distros).
-#### Step 3: Run Clippy
+If building LLVM from source, you'll need additional tools:
-Now you can run Clippy by invoking the following command:
+* `g++`, `clang++`, or MSVC with versions listed on
+ [LLVM's documentation](https://llvm.org/docs/GettingStarted.html#host-c-toolchain-both-compiler-and-standard-library)
+* `ninja`, or GNU `make` 3.81 or later (Ninja is recommended, especially on
+ Windows)
+* `cmake` 3.13.4 or later
+* `libstdc++-static` may be required on some Linux distributions such as Fedora
+ and Ubuntu
-```terminal
-cargo clippy
-```
+On tier 1 or tier 2 with host tools platforms, you can also choose to download
+LLVM by setting `llvm.download-ci-llvm = true`.
+Otherwise, you'll need LLVM installed and `llvm-config` in your path.
+See [the rustc-dev-guide for more info][sysllvm].
-#### Automatically applying Clippy suggestions
+[sysllvm]: https://rustc-dev-guide.rust-lang.org/building/new-target.html#using-pre-built-llvm
-Clippy can automatically apply some lint suggestions, just like the compiler.
-```terminal
-cargo clippy --fix
-```
+### Building on a Unix-like system
-#### Workspaces
+1. Clone the [source] with `git`:
-All the usual workspace options should work with Clippy. For example the following command
-will run Clippy on the `example` crate:
+ ```sh
+ git clone https://github.com/rust-lang/rust.git
+ cd rust
+ ```
-```terminal
-cargo clippy -p example
-```
+[source]: https://github.com/rust-lang/rust
-As with `cargo check`, this includes dependencies that are members of the workspace, like path dependencies.
-If you want to run Clippy **only** on the given crate, use the `--no-deps` option like this:
+2. Configure the build settings:
-```terminal
-cargo clippy -p example -- --no-deps
-```
+ The Rust build system uses a file named `config.toml` in the root of the
+ source tree to determine various configuration settings for the build.
+ Set up the defaults intended for distros to get started. You can see a full
+ list of options in `config.toml.example`.
-### Using `clippy-driver`
+ ```sh
+ printf 'profile = "user" \nchangelog-seen = 2 \n' > config.toml
+ ```
-Clippy can also be used in projects that do not use cargo. To do so, run `clippy-driver`
-with the same arguments you use for `rustc`. For example:
+ If you plan to use `x.py install` to create an installation, it is
+ recommended that you set the `prefix` value in the `[install]` section to a
+ directory.
-```terminal
-clippy-driver --edition 2018 -Cpanic=abort foo.rs
-```
+3. Build and install:
+
+ ```sh
+ ./x.py build && ./x.py install
+ ```
+
+ When complete, `./x.py install` will place several programs into
+ `$PREFIX/bin`: `rustc`, the Rust compiler, and `rustdoc`, the
+ API-documentation tool. If you've set `profile = "user"` or
+ `build.extended = true`, it will also include [Cargo], Rust's package
+ manager.
+
+[Cargo]: https://github.com/rust-lang/cargo
-Note that `clippy-driver` is designed for running Clippy only and should not be used as a general
-replacement for `rustc`. `clippy-driver` may produce artifacts that are not optimized as expected,
-for example.
-
-### Travis CI
-
-You can add Clippy to Travis CI in the same way you use it locally:
-
-```yml
-language: rust
-rust:
- - stable
- - beta
-before_script:
- - rustup component add clippy
-script:
- - cargo clippy
- # if you want the build job to fail when encountering warnings, use
- - cargo clippy -- -D warnings
- # in order to also check tests and non-default crate features, use
- - cargo clippy --all-targets --all-features -- -D warnings
- - cargo test
- # etc.
+### Building on Windows
+
+On Windows, we suggest using [winget] to install dependencies by running the
+following in a terminal:
+
+```powershell
+winget install -e Python.Python.3
+winget install -e Kitware.CMake
+winget install -e Git.Git
```
-Note that adding `-D warnings` will cause your build to fail if **any** warnings are found in your code.
-That includes warnings found by rustc (e.g. `dead_code`, etc.). If you want to avoid this and only cause
-an error for Clippy warnings, use `#![deny(clippy::all)]` in your code or `-D clippy::all` on the command
-line. (You can swap `clippy::all` with the specific lint category you are targeting.)
+Then edit your system's `PATH` variable and add: `C:\Program Files\CMake\bin`.
+See
+[this guide on editing the system `PATH`](https://www.java.com/en/download/help/path.html)
+from the Java documentation.
-## Configuration
+[winget]: https://github.com/microsoft/winget-cli
-### Allowing/denying lints
+There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by
+Visual Studio and the GNU ABI used by the GCC toolchain. Which version of Rust
+you need depends largely on what C/C++ libraries you want to interoperate with.
+Use the MSVC build of Rust to interop with software produced by Visual Studio
+and the GNU build to interop with GNU software built using the MinGW/MSYS2
+toolchain.
-You can add options to your code to `allow`/`warn`/`deny` Clippy lints:
+#### MinGW
-* the whole set of `Warn` lints using the `clippy` lint group (`#![deny(clippy::all)]`).
- Note that `rustc` has additional [lint groups](https://doc.rust-lang.org/rustc/lints/groups.html).
+[MSYS2][msys2] can be used to easily build Rust on Windows:
-* all lints using both the `clippy` and `clippy::pedantic` lint groups (`#![deny(clippy::all)]`,
- `#![deny(clippy::pedantic)]`). Note that `clippy::pedantic` contains some very aggressive
- lints prone to false positives.
+[msys2]: https://www.msys2.org/
-* only some lints (`#![deny(clippy::single_match, clippy::box_vec)]`, etc.)
+1. Download the latest [MSYS2 installer][msys2] and go through the installer.
-* `allow`/`warn`/`deny` can be limited to a single function or module using `#[allow(...)]`, etc.
+2. Run `mingw32_shell.bat` or `mingw64_shell.bat` from the MSYS2 installation
+ directory (e.g. `C:\msys64`), depending on whether you want 32-bit or 64-bit
+ Rust. (As of the latest version of MSYS2 you have to run `msys2_shell.cmd
+ -mingw32` or `msys2_shell.cmd -mingw64` from the command line instead.)
-Note: `allow` means to suppress the lint for your code. With `warn` the lint
-will only emit a warning, while with `deny` the lint will emit an error, when
-triggering for your code. An error causes clippy to exit with an error code, so
-is useful in scripts like CI/CD.
+3. From this terminal, install the required tools:
-If you do not want to include your lint levels in your code, you can globally
-enable/disable lints by passing extra flags to Clippy during the run:
+ ```sh
+ # Update package mirrors (may be needed if you have a fresh install of MSYS2)
+ pacman -Sy pacman-mirrors
-To allow `lint_name`, run
+ # Install build tools needed for Rust. If you're building a 32-bit compiler,
+ # then replace "x86_64" below with "i686". If you've already got Git, Python,
+ # or CMake installed and in PATH you can remove them from this list.
+ # Note that it is important that you do **not** use the 'python2', 'cmake',
+ # and 'ninja' packages from the 'msys2' subsystem.
+ # The build has historically been known to fail with these packages.
+ pacman -S git \
+ make \
+ diffutils \
+ tar \
+ mingw-w64-x86_64-python \
+ mingw-w64-x86_64-cmake \
+ mingw-w64-x86_64-gcc \
+ mingw-w64-x86_64-ninja
+ ```
-```terminal
-cargo clippy -- -A clippy::lint_name
-```
+4. Navigate to Rust's source code (or clone it), then build it:
-And to warn on `lint_name`, run
+ ```sh
+ ./x.py build && ./x.py install
+ ```
-```terminal
-cargo clippy -- -W clippy::lint_name
-```
+#### MSVC
-This also works with lint groups. For example, you
-can run Clippy with warnings for all lints enabled:
-```terminal
-cargo clippy -- -W clippy::pedantic
-```
+MSVC builds of Rust additionally require an installation of Visual Studio 2017
+(or later) so `rustc` can use its linker. The simplest way is to get
+[Visual Studio], check the "C++ build tools" and "Windows 10 SDK" workload.
-If you care only about a single lint, you can allow all others and then explicitly warn on
-the lint(s) you are interested in:
-```terminal
-cargo clippy -- -A clippy::all -W clippy::useless_format -W clippy::...
-```
+[Visual Studio]: https://visualstudio.microsoft.com/downloads/
-### Configure the behavior of some lints
+(If you're installing CMake yourself, be careful that "C++ CMake tools for
+Windows" doesn't get included under "Individual components".)
-Some lints can be configured in a TOML file named `clippy.toml` or `.clippy.toml`. It contains a basic `variable =
-value` mapping e.g.
+With these dependencies installed, you can build the compiler in a `cmd.exe`
+shell with:
-```toml
-avoid-breaking-exported-api = false
-disallowed-names = ["toto", "tata", "titi"]
+```sh
+python x.py build
```
-The [table of configurations](https://doc.rust-lang.org/nightly/clippy/lint_configuration.html)
-contains all config values, their default, and a list of lints they affect.
-Each [configurable lint](https://rust-lang.github.io/rust-clippy/master/index.html#Configuration)
-, also contains information about these values.
-
-For configurations that are a list type with default values such as
-[disallowed-names](https://rust-lang.github.io/rust-clippy/master/index.html#disallowed_names),
-you can use the unique value `".."` to extend the default values instead of replacing them.
+Right now, building Rust only works with some known versions of Visual Studio.
+If you have a more recent version installed and the build system doesn't
+understand, you may need to force rustbuild to use an older version.
+This can be done by manually calling the appropriate vcvars file before running
+the bootstrap.
-```toml
-# default of disallowed-names is ["foo", "baz", "quux"]
-disallowed-names = ["bar", ".."] # -> ["bar", "foo", "baz", "quux"]
+```batch
+CALL "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
+python x.py build
```
-> **Note**
->
-> `clippy.toml` or `.clippy.toml` cannot be used to allow/deny lints.
+#### Specifying an ABI
-To deactivate the “for further information visit *lint-link*” message you can
-define the `CLIPPY_DISABLE_DOCS_LINKS` environment variable.
+Each specific ABI can also be used from either environment (for example, using
+the GNU ABI in PowerShell) by using an explicit build triple. The available
+Windows build triples are:
+- GNU ABI (using GCC)
+ - `i686-pc-windows-gnu`
+ - `x86_64-pc-windows-gnu`
+- The MSVC ABI
+ - `i686-pc-windows-msvc`
+ - `x86_64-pc-windows-msvc`
-### Specifying the minimum supported Rust version
+The build triple can be specified by either specifying `--build=<triple>` when
+invoking `x.py` commands, or by creating a `config.toml` file (as described in
+[Installing from Source](#installing-from-source)), and modifying the `build`
+option under the `[build]` section.
-Projects that intend to support old versions of Rust can disable lints pertaining to newer features by
-specifying the minimum supported Rust version (MSRV) in the clippy configuration file.
+### Configure and Make
-```toml
-msrv = "1.30.0"
+While it's not the recommended build system, this project also provides a
+configure script and makefile (the latter of which just invokes `x.py`).
+
+```sh
+./configure
+make && sudo make install
```
-Alternatively, the [`rust-version` field](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field)
-in the `Cargo.toml` can be used.
+`configure` generates a `config.toml` which can also be used with normal `x.py`
+invocations.
+
+## Building Documentation
+
+If you'd like to build the documentation, it's almost the same:
-```toml
-# Cargo.toml
-rust-version = "1.30"
+```sh
+./x.py doc
```
-The MSRV can also be specified as an attribute, like below.
+The generated documentation will appear under `doc` in the `build` directory for
+the ABI used. That is, if the ABI was `x86_64-pc-windows-msvc`, the directory
+will be `build\x86_64-pc-windows-msvc\doc`.
-```rust
-#![feature(custom_inner_attributes)]
-#![clippy::msrv = "1.30.0"]
+## Notes
-fn main() {
- ...
-}
-```
+Since the Rust compiler is written in Rust, it must be built by a precompiled
+"snapshot" version of itself (made in an earlier stage of development).
+As such, source builds require an Internet connection to fetch snapshots, and an
+OS that can execute the available snapshot binaries.
+
+See https://doc.rust-lang.org/nightly/rustc/platform-support.html for a list of
+supported platforms.
+Only "host tools" platforms have a pre-compiled snapshot binary available; to
+compile for a platform without host tools you must cross-compile.
-You can also omit the patch version when specifying the MSRV, so `msrv = 1.30`
-is equivalent to `msrv = 1.30.0`.
+You may find that other platforms work, but these are our officially supported
+build environments that are most likely to work.
-Note: `custom_inner_attributes` is an unstable feature, so it has to be enabled explicitly.
+## Getting Help
-Lints that recognize this configuration option can be found [here](https://rust-lang.github.io/rust-clippy/master/index.html#msrv)
+See https://www.rust-lang.org/community for a list of chat platforms and forums.
## Contributing
-If you want to contribute to Clippy, you can find more information in [CONTRIBUTING.md](https://github.com/rust-lang/rust-clippy/blob/master/CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
-Copyright 2014-2022 The Rust Project Developers
+Rust is primarily distributed under the terms of both the MIT license and the
+Apache License (Version 2.0), with portions covered by various BSD-like
+licenses.
+
+See [LICENSE-APACHE](LICENSE-APACHE), [LICENSE-MIT](LICENSE-MIT), and
+[COPYRIGHT](COPYRIGHT) for details.
+
+## Trademark
+
+[The Rust Foundation][rust-foundation] owns and protects the Rust and Cargo
+trademarks and logos (the "Rust Trademarks").
+
+If you want to use these names or brands, please read the
+[media guide][media-guide].
+
+Third-party logos may be subject to third-party copyrights and trademarks. See
+[Licenses][policies-licenses] for details.
-Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-[https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)> or the MIT license
-<LICENSE-MIT or [https://opensource.org/licenses/MIT](https://opensource.org/licenses/MIT)>, at your
-option. Files in the project may not be
-copied, modified, or distributed except according to those terms.
+[rust-foundation]: https://foundation.rust-lang.org/
+[media-guide]: https://foundation.rust-lang.org/policies/logo-policy-and-media-guide/
+[policies-licenses]: https://www.rust-lang.org/policies/licenses
projects / rust.git / blobdiff