bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #49707 - steveklabnik:rustc-book, r=QuietMisdreavus

Browse source 
Add "the Rustc book"

This PR introduces a new book into the documentation, "The rustc book". We already have books for Cargo, and for Rustdoc, rustc should have some too. This book is focused on *users* of rustc, and provides a nice place to write documentation for users.

I haven't put content here, but plan on scaffolding it out very soon, and wanted this PR open for a few discussions first. One of those is "what exactly should said TOC be?" I plan on having a proposed one up tomorrow, but figured I'd let people know to start thinking about it now.

The big one is that we also will want to put https://github.com/rust-lang-nursery/rustc-guide in-tree as well, and the naming is... tough. I'm proposing:

* doc.rust-lang.org/rustc is "The Rustc book", to mirror the other tools' books.
* doc.rust-lang.org/rustc-contribution is "The Rustc contribution guide", and contains that book

@nikomatsakis et al, any thoughts on this? I'm not attached to it in particular, but had to put something together to get this discussion going. I think mirroring the other tools is a good idea for this work, but am not sure where exactly that leaves yours.

Fixes https://github.com/rust-docs/team/issues/11
This commit is contained in:
kennytm 2018-04-27 14:16:42 +08:00 • committed by GitHub
commit d403d82b0a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
21 changed files with 2516 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

4
src/bootstrap/builder.rs
View file

@ -323,7 +323,7 @@ impl<'a> Builder<'a> {
test::Cargotest, test::Cargo, test::Rls, test::ErrorIndex, test::Distcheck,
test::RunMakeFullDeps,
test::Nomicon, test::Reference, test::RustdocBook, test::RustByExample,
test::TheBook, test::UnstableBook,
test::TheBook, test::UnstableBook, test::RustcBook,
test::Rustfmt, test::Miri, test::Clippy, test::RustdocJS, test::RustdocTheme,
// Run run-make last, since these won't pass without make on Windows
test::RunMake, test::RustdocUi),
@ -331,7 +331,7 @@ impl<'a> Builder<'a> {
Kind::Doc => describe!(doc::UnstableBook, doc::UnstableBookGen, doc::TheBook,
doc::Standalone, doc::Std, doc::Test, doc::WhitelistedRustc, doc::Rustc,
doc::ErrorIndex, doc::Nomicon, doc::Reference, doc::Rustdoc, doc::RustByExample,
doc::CargoBook),
doc::RustcBook, doc::CargoBook),
Kind::Dist => describe!(dist::Docs, dist::RustcDocs, dist::Mingw, dist::Rustc,
dist::DebuggerScripts, dist::Std, dist::Analysis, dist::Src,
dist::PlainSourceTarball, dist::Cargo, dist::Rls, dist::Rustfmt, dist::Extended,

1
src/bootstrap/doc.rs
View file

@ -71,6 +71,7 @@ book!(
Nomicon, "src/doc/nomicon", "nomicon";
Reference, "src/doc/reference", "reference";
Rustdoc, "src/doc/rustdoc", "rustdoc";
RustcBook, "src/doc/rustc", "rustc";
RustByExample, "src/doc/rust-by-example", "rust-by-example";
);

1
src/bootstrap/test.rs
View file

@ -1212,6 +1212,7 @@ test_book!(
Nomicon, "src/doc/nomicon", "nomicon", default=false;
Reference, "src/doc/reference", "reference", default=false;
RustdocBook, "src/doc/rustdoc", "rustdoc", default=true;
RustcBook, "src/doc/rustc", "rustc", default=true;
RustByExample, "src/doc/rust-by-example", "rust-by-example", default=false;
TheBook, "src/doc/book", "book", default=false;
UnstableBook, "src/doc/unstable-book", "unstable-book", default=true;

4
src/doc/index.md
View file

@ -43,6 +43,10 @@ Rust's standard library has [extensive API documentation](std/index.html),
with explanations of how to use various things, as well as example code for
accomplishing various tasks.
## The Rustc Book
[The Rustc Book](rustc/index.html) describes the Rust compiler, `rustc`.
## The Cargo Book
[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and dependency manager.

1
src/doc/rustc/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
book

5
src/doc/rustc/book.toml Normal file
View file

@ -0,0 +1,5 @@
[book]
authors = ["The Rust Project Developers"]
multilingual = false
src = "src"
title = "The rustc book"

16
src/doc/rustc/src/SUMMARY.md Normal file
View file

@ -0,0 +1,16 @@
# The Rustc Book
- [What is rustc?](what-is-rustc.md)
- [Command-line arguments](command-line-arguments.md)
- [Lints](lints/index.md)
- [Lint levels](lints/levels.md)
- [Lint Groups](lints/groups.md)
- [Lint listing](lints/listing/index.md)
- [Allowed-by-default lints](lints/listing/allowed-by-default.md)
- [Warn-by-default lints](lints/listing/warn-by-default.md)
- [Deny-by-default lints](lints/listing/deny-by-default.md)
- [Codegen options](codegen-options/index.md)
- [Targets](targets/index.md)
- [Built-in Targets](targets/built-in.md)
- [Custom Targets](targets/custom.md)
- [Contributing to `rustc`](contributing.md)

209
src/doc/rustc/src/codegen-options/index.md Normal file
View file

@ -0,0 +1,209 @@
# Codegen options
All of these options are passed to `rustc` via the `-C` flag, short for "codegen." You can see
a version of this list for your exact compiler by running `rustc -C help`.
## ar
This option is deprecated and does nothing.
## linker
This flag lets you control which linker `rustc` invokes to link your code.
## link-arg=val
This flag lets you append a single extra argument to the linker invocation.
"Append" is significant; you can pass this flag multiple times to add multiple arguments.
## link-args
This flag lets you append multiple extra arguments to the linker invocation. The
options should be separated by spaces.
## link-dead-code
Normally, the linker will remove dead code. This flag disables this behavior.
An example of when this flag might be useful is when trying to construct code coverage
metrics.
## lto
This flag instructs LLVM to use [link time
optimizations](https://llvm.org/docs/LinkTimeOptimization.html).
It takes one of two values, `thin` and `fat`. 'thin' LTO [is a new feature of
LLVM](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html),
'fat' referring to the classic version of LTO.
## target-cpu
This instructs `rustc` to generate code specifically for a particular processor.
You can run `rustc --print target-cpus` to see the valid options to pass
here. Additionally, `native` can be passed to use the processor of the host
machine.
## target-feature
Individual targets will support different features; this flag lets you control
enabling or disabling a feature.
To see the valid options and an example of use, run `rustc --print
target-features`.
## passes
This flag can be used to add extra LLVM passes to the compilation.
The list must be separated by spaces.
## llvm-args
This flag can be used to pass a list of arguments directly to LLVM.
The list must be separated by spaces.
## save-temps
`rustc` will generate temporary files during compilation; normally it will
delete them after it's done with its work. This option will cause them to be
preserved instead of removed.
## rpath
This option allows you to set the value of
[`rpath`](https://en.wikipedia.org/wiki/Rpath).
## overflow-checks
This flag allows you to control the behavior of integer overflow. This flag
can be passed many options:
* To turn overflow checks on: `y`, `yes`, or `on`.
* To turn overflow checks off: `n`, `no`, or `off`.
## no-prepopulate-passes
The pass manager comes pre-populated with a list of passes; this flag
ensures that list is empty.
## no-vectorize-loops
By default, `rustc` will attempt to [vectorize
loops](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer). This
flag will turn that behavior off.
## no-vectorize-slp
By default, `rustc` will attempt to vectorize loops using [superword-level
parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer). This
flag will turn that behavior off.
## soft-float
This option will make `rustc` generate code using "soft floats." By default,
a lot of hardware supports floating point instructions, and so the code generated
will take advantage of this. "soft floats" emulate floating point instructions
in software.
## prefer-dynamic
By default, `rustc` prefers to statically link dependencies. This option will
make it use dynamic linking instead.
## no-integrated-as
LLVM comes with an internal assembler; this option will let you use an
external assembler instead.
## no-redzone
This flag allows you to disable [the
red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). This flag can
be passed many options:
* To enable the red zone: `y`, `yes`, or `on`.
* To disable it: `n`, `no`, or `off`.
## relocation-model
This option lets you choose which relocation model to use.
To find the valid options for this flag, run `rustc --print relocation-models`.
## code-model=val
This option lets you choose which code model to use.
To find the valid options for this flag, run `rustc --print code-models`.
## metadata
This option allows you to control the metadata used for symbol mangling.
## extra-filename
This option allows you to put extra data in each output filename.
## codegen-units
This flag lets you control how many threads are used when doing
code generation.
Increasing paralellism may speed up compile times, but may also
produce slower code.
## remark
This flag lets you print remarks for these optimization passes.
The list of passes should be separated by spaces.
`all` will remark on every pass.
## no-stack-check
This option is deprecated and does nothing.
## debuginfo
This flag lets you control debug information:
* `0`: no debug info at all
* `1`: line tables only
* `2`: full debug info
## opt-level
This flag lets you control the optimization level.
* `0`: no optimizations
* `1`: basic optimizations
* `2`: some optimizations
* `3`: all optimizations
* `s`: optimize for binary size
* `z`: optimize for binary size, but also turn off loop vectorization.
## debug-assertions
This flag lets you turn `cfg(debug_assertions)` on or off.
## inline-threshold
This option lets you set the threshold for inlining a function.
The default is 225.
## panic
This option lets you control what happens when the code panics.
* `abort`: terminate the process upon panic
* `unwind`: unwind the stack upon panic
## incremental
This flag allows you to enable incremental compilation.

116
src/doc/rustc/src/command-line-arguments.md Normal file
View file

@ -0,0 +1,116 @@
# Command-line arguments
Here's a list of command-line arguments to `rustc` and what they do.
## `-h`/`--help`: get help
This flag will print out help information for `rustc`.
## `--cfg`: configure the compilation environment
This flag can turn on or off various `#[cfg]` settings.
## `-L`: add a directory to the library search path
When looking for external crates, a directory passed to this flag will be searched.
## `-l`: link the generated crate to a native library
This flag allows you to specify linking to a specific native library when building
a crate.
## `--crate-type`: a list of types of crates for the compiler to emit
This instructs `rustc` on which crate type to build.
## `--crate-name`: specify the name of the crate being built
This informs `rustc` of the name of your crate.
## `--emit`: emit output other than a crate
Instead of producing a crate, this flag can print out things like the assembly or LLVM-IR.
## `--print`: print compiler information
This flag prints out various information about the compiler.
## `-g`: include debug information
A synonym for `-C debug-level=2`.
## `-O`: optimize your code
A synonym for `-C opt-level=2`.
## `-o`: filename of the output
This flag controls the output filename.
## `--out-dir`: directory to write the output in
The outputted crate will be written to this directory.
## `--explain`: provide a detailed explanation of an error message
Each error of `rustc`'s comes with an error code; this will print
out a longer explanation of a given error.
## `--test`: build a test harness
When compiling this crate, `rustc` will ignore your `main` function
and instead produce a test harness.
## `--target`: select a target triple to build
This controls which [target](targets/index.html) to produce.
## `-W`: set lint warnings
This flag will set which lints should be set to the [warn level](lints/levels.html#warn).
## `-A`: set lint allowed
This flag will set which lints should be set to the [allow level](lints/levels.html#allow).
## `-D`: set lint denied
This flag will set which lints should be set to the [deny level](lints/levels.html#deny).
## `-F`: set lint forbidden
This flag will set which lints should be set to the [forbid level](lints/levels.html#forbid).
## `--cap-lints`: set the most restrictive lint level
This flag lets you 'cap' lints, for more, [see here](lints/levels.html#capping-lints).
## `-C`/`--codegen`: code generation options
This flag will allow you to set [codegen options](codegen-options/index.html).
## `-V`/`--version`: print a version
This flag will print out `rustc`'s version.
## `-v`/`--verbose`: use verbose output
This flag, when combined with other flags, makes them produce extra output.
## `--extern`: specify where an external library is located
This flag allows you to pass the name and location of an external crate that will
be linked into the crate you're buildling.
## `--sysroot`: Override the system root
The "sysroot" is where `rustc` looks for the crates that come with the Rust
distribution; this flag allows that to be overridden.
## `--error-format`: control how errors are produced
This flag lets you control the format of errors.
## `--color`: configure coloring of output
This flag lets you control color settings of the output.

6
src/doc/rustc/src/contributing.md Normal file
View file

@ -0,0 +1,6 @@
# Contributing to rustc
We'd love to have your help improving `rustc`! To that end, we've written [a
whole book](https://rust-lang-nursery.github.io/rustc-guide/) on its
internals, how it works, and how to get started working on it. To learn
more, you'll want to check that out.

29
src/doc/rustc/src/lints/groups.md Normal file
View file

@ -0,0 +1,29 @@
# Lint Groups
`rustc` has the concept of a "lint group", where you can toggle several warnings
through one name.
For example, the `nonstandard-style` lint sets `non-camel-case-types`,
`non-snake-case`, and `non-upper-case-globals` all at once. So these are
equivalent:
```bash
$ rustc -D nonstandard-style
$ rustc -D non-camel-case-types -D non-snake-case -D non-upper-case-globals
```
Here's a list of each lint group, and the lints that they are made up of:
| group | description | lints |
|---------------------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| nonstandard-style | Violation of standard naming conventions | non-camel-case-types, non-snake-case, non-upper-case-globals |
| warnings | all lints that would be issuing warnings | all lints that would be issuing warnings |
| edition-2018 | Lints that will be turned into errors in Rust 2018 | tyvar-behind-raw-pointer |
| rust-2018-idioms | Lints to nudge you toward idiomatic features of Rust 2018 | bare-trait-object, unreachable-pub |
| unused | These lints detect things being declared but not used | unused-imports, unused-variables, unused-assignments, dead-code, unused-mut, unreachable-code, unreachable-patterns, unused-must-use, unused-unsafe, path-statements, unused-attributes, unused-macros, unused-allocation, unused-doc-comment, unused-extern-crates, unused-features, unused-parens |
| future-incompatible | Lints that detect code that has future-compatibility problems | private-in-public, pub-use-of-private-extern-crate, patterns-in-fns-without-body, safe-extern-statics, invalid-type-param-default, legacy-directory-ownership, legacy-imports, legacy-constructor-visibility, missing-fragment-specifier, illegal-floating-point-literal-pattern, anonymous-parameters, parenthesized-params-in-types-and-modules, late-bound-lifetime-arguments, safe-packed-borrows, incoherent-fundamental-impls, tyvar-behind-raw-pointer, unstable-name-collision |
Additionally, there's a `bad-style` lint group that's a deprecated alias for `nonstandard-style`.
Finally, you can also see the table above by invoking `rustc -W help`. This will give you the exact values for the specific
compiler you have installed.

28
src/doc/rustc/src/lints/index.md Normal file
View file

@ -0,0 +1,28 @@
# Lints
In software, a "lint" is a tool used to help improve your source code. The
Rust compiler contains a number of lints, and when it compiles your code, it will
also run the lints. These lints may produce a warning, an error, or nothing at all,
depending on how you've configured things.
Here's a small example:
```bash
$ cat main.rs
fn main() {
let x = 5;
}
> rustc main.rs
warning: unused variable: `x`
--> main.rs:2:9
|
2 | let x = 5;
| ^
|
= note: #[warn(unused_variables)] on by default
= note: to avoid this warning, consider using `_x` instead
```
This is the `unused_variables` lint, and it tells you that you've introduced
a variable that you don't use in your code. That's not *wrong*, so it's not
an error, but it might be a bug, so you get a warning.

252
src/doc/rustc/src/lints/levels.md Normal file
View file

@ -0,0 +1,252 @@
# Lint levels
In `rustc`, lints are divided into four *levels*:
1. allow
2. warn
3. deny
4. forbid
Each lint has a default level (explained in the lint listing later in this
chapter), and the compiler has a default warning level. First, let's explain
what these levels mean, and then we'll talk about configuration.
## allow
These lints exist, but by default, do nothing. For example, consider this
source:
```rust
pub fn foo() {}
```
Compiling this file produces no warnings:
```bash
$ rustc lib.rs --crate-type=lib
$
```
But this code violates the `missing_docs` lint.
These lints exist mostly to be manually turned on via configuration, as we'll
talk about later in this section.
## warn
The 'warn' lint level will produce a warning if you violate the lint. For example,
this code runs afoul of the `unused_variable` lint:
```rust
pub fn foo() {
let x = 5;
}
```
This will produce this warning:
```console
$ rustc lib.rs --crate-type=lib
warning: unused variable: `x`
--> lib.rs:2:9
|
2 | let x = 5;
| ^
|
= note: #[warn(unused_variables)] on by default
= note: to avoid this warning, consider using `_x` instead
```
## deny
A 'deny' lint produces an error if you violate it. For example, this code
runs into the `exceeding_bitshifts` lint.
```rust,ignore
fn main() {
100u8 << 10;
}
```
```bash
> rustc main.rs
error: bitshift exceeds the type's number of bits
--> main.rs:2:13
|
2 | 100u8 << 10;
| ^^^^^^^^^^^
|
= note: #[deny(exceeding_bitshifts)] on by default
```
What's the difference between an error from a lint and a regular old error?
Lints are configurable via levels, so in a similar way to 'allow' lints,
warnings that are 'deny' by default let you allow them. Similarly, you may
wish to set up a lint that is `warn` by default to produce an error instead.
This lint level gives you that.
## forbid
'forbid' is a special lint level that's stronger than 'deny'. It's the same
as 'deny' in that a lint at this level will produce an error, but unlike the
'deny' level, the 'forbid' level can not be overridden to be anything lower
than an error.
## Configuring warning levels
Remember our `missing_docs` example from the 'allow' lint level?
```bash
$ cat lib.rs
pub fn foo() {}
$ rustc lib.rs --crate-type=lib
$
```
We can configure this lint to operate at a higher level, both with
compiler flags, as well as with an attribute in the source code.
You can also "cap" lints so that the compiler can choose to ignore
certain lint levels. We'll talk about that last.
### Via compiler flag
The `-A`, `-W`, `-D`, and `-F` flags let you turn one or more lints
into allowed, warning, deny, or forbid levels, like this:
```bash
$ rustc lib.rs --crate-type=lib -W missing-docs
warning: missing documentation for crate
--> lib.rs:1:1
|
1 | pub fn foo() {}
| ^^^^^^^^^^^^
|
= note: requested on the command line with `-W missing-docs`
warning: missing documentation for a function
--> lib.rs:1:1
|
1 | pub fn foo() {}
| ^^^^^^^^^^^^
> rustc lib.rs --crate-type=lib -D missing-docs
error: missing documentation for crate
--> lib.rs:1:1
|
1 | pub fn foo() {}
| ^^^^^^^^^^^^
|
= note: requested on the command line with `-D missing-docs`
error: missing documentation for a function
--> lib.rs:1:1
|
1 | pub fn foo() {}
| ^^^^^^^^^^^^
error: aborting due to 2 previous errors
```
You can also pass each flag more than once for changing multiple lints:
```bash
rustc lib.rs --crate-type=lib -D missing-docs -D unused-variables
```
And of course, you can mix these four flags together:
```bash
rustc lib.rs --crate-type=lib -D missing-docs -A unused-variables
```
### Via an attribute
You can also modify the lint level with a crate-wide attribute:
```bash
> cat lib.rs
#![warn(missing_docs)]
pub fn foo() {}
$ rustc lib.rs --crate-type=lib
warning: missing documentation for crate
--> lib.rs:1:1
|
1 | / #![warn(missing_docs)]
2 | |
3 | | pub fn foo() {}
| |_______________^
|
note: lint level defined here
--> lib.rs:1:9
|
1 | #![warn(missing_docs)]
| ^^^^^^^^^^^^
warning: missing documentation for a function
--> lib.rs:3:1
|
3 | pub fn foo() {}
| ^^^^^^^^^^^^
```
All four, `warn`, `allow`, `deny`, and `forbid` all work this way.
You can also pass in multiple lints per attribute:
```rust
#![warn(missing_docs, unused_variables)]
pub fn foo() {}
```
And use multiple attributes together:
```rust
#![warn(missing_docs)]
#![deny(unused_variables)]
pub fn foo() {}
```
### Capping lints
`rustc` supports a flag, `--cap-lints LEVEL` that sets the "lint cap level."
This is the maximum level for all lints. So for example, if we take our
code sample from the "deny" lint level above:
```rust,ignore
fn main() {
100u8 << 10;
}
```
And we compile it, capping lints to warn:
```bash
$ rustc lib.rs --cap-lints warn
warning: bitshift exceeds the type's number of bits
--> lib.rs:2:5
|
2 | 100u8 << 10;
| ^^^^^^^^^^^
|
= note: #[warn(exceeding_bitshifts)] on by default
warning: this expression will panic at run-time
--> lib.rs:2:5
|
2 | 100u8 << 10;
| ^^^^^^^^^^^ attempt to shift left with overflow
```
It now only warns, rather than errors. We can go further and allow all lints:
```bash
$ rustc lib.rs --cap-lints allow
$
```
This feature is used heavily by Cargo; it will pass `--cap-lints allow` when
compiling your dependencies, so that if they have any warnings, they do not
pollute the output of your build.

453
src/doc/rustc/src/lints/listing/allowed-by-default.md Normal file
View file

@ -0,0 +1,453 @@
# Allowed-by-default lints
These lints are all set to the 'allow' level by default. As such, they won't show up
unless you set them to a higher lint level with a flag or attribute.
## anonymous-parameters
This lint detects anonymous parameters. Some example code that triggers this lint:
```rust
trait Foo {
fn foo(usize);
}
```
When set to 'deny', this will produce:
```text
error: use of deprecated anonymous parameter
--> src/lib.rs:5:11
|
5 | fn foo(usize);
| ^
|
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #41686 <https://github.com/rust-lang/rust/issues/41686>
```
This syntax is mostly a historical accident, and can be worked around quite
easily:
```rust
trait Foo {
fn foo(_: usize);
}
```
## bare-trait-object
This lint suggests using `dyn Trait` for trait objects. Some example code
that triggers this lint:
```rust
#![feature(dyn_trait)]
trait Trait { }
fn takes_trait_object(_: Box<Trait>) {
}
```
When set to 'deny', this will produce:
```text
error: trait objects without an explicit `dyn` are deprecated
--> src/lib.rs:7:30
|
7 | fn takes_trait_object(_: Box<Trait>) {
| ^^^^^ help: use `dyn`: `dyn Trait`
|
```
To fix it, do as the help message suggests:
```rust
#![feature(dyn_trait)]
#![deny(bare_trait_object)]
trait Trait { }
fn takes_trait_object(_: Box<dyn Trait>) {
}
```
## box-pointers
This lints use of the Box type. Some example code that triggers this lint:
```rust
struct Foo {
x: Box<isize>,
}
```
When set to 'deny', this will produce:
```text
error: type uses owned (Box type) pointers: std::boxed::Box<isize>
--> src/lib.rs:6:5
|
6 | x: Box<isize> //~ ERROR type uses owned
| ^^^^^^^^^^^^^
|
```
This lint is mostly historical, and not particularly useful. `Box<T>` used to
be built into the language, and the only way to do heap allocation. Today's
Rust can call into other allocators, etc.
## elided-lifetime-in-path
This lint detects the use of hidden lifetime parameters. Some example code
that triggers this lint:
```rust
struct Foo<'a> {
x: &'a u32
}
fn foo(x: &Foo) {
}
```
When set to 'deny', this will produce:
```text
error: hidden lifetime parameters are deprecated, try `Foo<'_>`
--> src/lib.rs:5:12
|
5 | fn foo(x: &Foo) {
| ^^^
|
```
Lifetime elision elides this lifetime, but that is being deprecated.
## missing-copy-implementations
This lint detects potentially-forgotten implementations of `Copy`. Some
example code that triggers this lint:
```rust
pub struct Foo {
pub field: i32
}
```
When set to 'deny', this will produce:
```text
error: type could implement `Copy`; consider adding `impl Copy`
--> src/main.rs:3:1
|
3 | / pub struct Foo { //~ ERROR type could implement `Copy`; consider adding `impl Copy`
4 | | pub field: i32
5 | | }
| |_^
|
```
You can fix the lint by deriving `Copy`.
This lint is set to 'allow' because this code isn't bad; it's common to write
newtypes like this specifically so that a `Copy` type is no longer `Copy`.
## missing-debug-implementations
This lint detects missing implementations of `fmt::Debug`. Some example code
that triggers this lint:
```rust
pub struct Foo;
```
When set to 'deny', this will produce:
```text
error: type does not implement `fmt::Debug`; consider adding #[derive(Debug)] or a manual implementation
--> src/main.rs:3:1
|
3 | pub struct Foo;
| ^^^^^^^^^^^^^^^
|
```
You can fix the lint by deriving `Debug`.
## missing-docs
This lint detects missing documentation for public items. Some example code
that triggers this lint:
```rust
pub fn foo() {}
```
When set to 'deny', this will produce:
```text
error: missing documentation for crate
--> src/main.rs:1:1
|
1 | / #![deny(missing_docs)]
2 | |
3 | | pub fn foo() {}
4 | |
5 | | fn main() {}
| |____________^
|
error: missing documentation for a function
--> src/main.rs:3:1
|
3 | pub fn foo() {}
| ^^^^^^^^^^^^
```
To fix the lint, add documentation to all items.
## single-use-lifetime
This lint detects lifetimes that are only used once. Some example code that
triggers this lint:
```rust
struct Foo<'x> {
x: &'x u32
}
```
When set to 'deny', this will produce:
```text
error: lifetime name `'x` only used once
--> src/main.rs:3:12
|
3 | struct Foo<'x> {
| ^^
|
```
## trivial-casts
This lint detects trivial casts which could be removed. Some example code
that triggers this lint:
```rust
let x: &u32 = &42;
let _ = x as *const u32;
```
When set to 'deny', this will produce:
```text
error: trivial cast: `&u32` as `*const u32`. Cast can be replaced by coercion, this might require type ascription or a temporary variable
--> src/main.rs:5:13
|
5 | let _ = x as *const u32;
| ^^^^^^^^^^^^^^^
|
note: lint level defined here
--> src/main.rs:1:9
|
1 | #![deny(trivial_casts)]
| ^^^^^^^^^^^^^
```
## trivial-numeric-casts
This lint detects trivial casts of numeric types which could be removed. Some
example code that triggers this lint:
```rust
let x = 42i32 as i32;
```
When set to 'deny', this will produce:
```text
error: trivial numeric cast: `i32` as `i32`. Cast can be replaced by coercion, this might require type ascription or a temporary variable
--> src/main.rs:4:13
|
4 | let x = 42i32 as i32;
| ^^^^^^^^^^^^
|
```
## unreachable-pub
This lint triggers for `pub` items not reachable from the crate root. Some
example code that triggers this lint:
```rust
mod foo {
pub mod bar {
}
}
```
When set to 'deny', this will produce:
```text
error: unreachable `pub` item
--> src/main.rs:4:5
|
4 | pub mod bar {
| ---^^^^^^^^
| |
| help: consider restricting its visibility: `pub(crate)`
|
```
## unsafe-code
This lint catches usage of `unsafe` code. Some example code that triggers this lint:
```rust
fn main() {
unsafe {
}
}
```
When set to 'deny', this will produce:
```text
error: usage of an `unsafe` block
--> src/main.rs:4:5
|
4 | / unsafe {
5 | |
6 | | }
| |_____^
|
```
## unstable-features
This lint is deprecated and no longer used.
## unused-extern-crates
This lint guards against `extern crate` items that are never used. Some
example code that triggers this lint:
```rust,ignore
extern crate semver;
```
When set to 'deny', this will produce:
```text
error: unused extern crate
--> src/main.rs:3:1
|
3 | extern crate semver;
| ^^^^^^^^^^^^^^^^^^^^
|
```
## unused-import-braces
This lint catches unnecessary braces around an imported item. Some example
code that triggers this lint:
```rust
use test::{A};
pub mod test {
pub struct A;
}
# fn main() {}
```
When set to 'deny', this will produce:
```text
error: braces around A is unnecessary
--> src/main.rs:3:1
|
3 | use test::{A};
| ^^^^^^^^^^^^^^
|
```
To fix it, `use test::A;`
## unused-qualifications
This lint detects unnecessarily qualified names. Some example code that triggers this lint:
```rust
mod foo {
pub fn bar() {}
}
fn main() {
use foo::bar;
foo::bar();
}
```
When set to 'deny', this will produce:
```text
error: unnecessary qualification
--> src/main.rs:9:5
|
9 | foo::bar();
| ^^^^^^^^
|
```
You can call `bar()` directly, without the `foo::`.
## unused-results
This lint checks for the unused result of an expression in a statement. Some
example code that triggers this lint:
```rust,no_run
fn foo<T>() -> T { panic!() }
fn main() {
foo::<usize>();
}
```
When set to 'deny', this will produce:
```text
error: unused result
--> src/main.rs:6:5
|
6 | foo::<usize>();
| ^^^^^^^^^^^^^^^
|
```
## variant-size-differences
This lint detects enums with widely varying variant sizes. Some example code that triggers this lint:
```rust
enum En {
V0(u8),
VBig([u8; 1024]),
}
```
When set to 'deny', this will produce:
```text
error: enum variant is more than three times larger (1024 bytes) than the next largest
--> src/main.rs:5:5
|
5 | VBig([u8; 1024]), //~ ERROR variant is more than three times larger
| ^^^^^^^^^^^^^^^^
|
```

241
src/doc/rustc/src/lints/listing/deny-by-default.md Normal file
View file

@ -0,0 +1,241 @@
# Deny-by-default lints
These lints are all set to the 'deny' level by default.
## exceeding-bitshifts
This lint detects that a shift exceeds the type's number of bits. Some
example code that triggers this lint:
```rust,ignore
1_i32 << 32;
```
This will produce:
```text
error: bitshift exceeds the type's number of bits
--> src/main.rs:2:5
|
2 | 1_i32 << 32;
| ^^^^^^^^^^^
|
```
## invalid-type-param-default
This lint detects type parameter default erroneously allowed in invalid location. Some
example code that triggers this lint:
```rust,ignore
fn foo<T=i32>(t: T) {}
```
This will produce:
```text
error: defaults for type parameters are only allowed in `struct`, `enum`, `type`, or `trait` definitions.
--> src/main.rs:4:8
|
4 | fn foo<T=i32>(t: T) {}
| ^
|
= note: #[deny(invalid_type_param_default)] on by default
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #36887 <https://github.com/rust-lang/rust/issues/36887>
```
## legacy-constructor-visibility
[RFC 1506](https://github.com/rust-lang/rfcs/blob/master/text/1506-adt-kinds.md) modified some
visibility rules, and changed the visibility of struct constructors. Some
example code that triggers this lint:
```rust,ignore
mod m {
pub struct S(u8);
fn f() {
// this is trying to use S from the 'use' line, but becuase the `u8` is
// not pub, it is private
::S;
}
}
use m::S;
```
This will produce:
```text
error: private struct constructors are not usable through re-exports in outer modules
--> src/main.rs:5:9
|
5 | ::S;
| ^^^
|
= note: #[deny(legacy_constructor_visibility)] on by default
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #39207 <https://github.com/rust-lang/rust/issues/39207>
```
## legacy-directory-ownership
The legacy_directory_ownership warning is issued when
* There is a non-inline module with a #[path] attribute (e.g. #[path = "foo.rs"] mod bar;),
* The module's file ("foo.rs" in the above example) is not named "mod.rs", and
* The module's file contains a non-inline child module without a #[path] attribute.
The warning can be fixed by renaming the parent module to "mod.rs" and moving
it into its own directory if appropriate.
## legacy-imports
This lint detects names that resolve to ambiguous glob imports. Some example
code that triggers this lint:
```rust,ignore
pub struct Foo;
mod bar {
struct Foo;
mod baz {
use *;
use bar::*;
fn f(_: Foo) {}
}
}
```
This will produce:
```text
error: `Foo` is ambiguous
--> src/main.rs:9:17
|
7 | use *;
| - `Foo` could refer to the name imported here
8 | use bar::*;
| ------ `Foo` could also refer to the name imported here
9 | fn f(_: Foo) {}
| ^^^
|
= note: #[deny(legacy_imports)] on by default
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #38260 <https://github.com/rust-lang/rust/issues/38260>
```
## missing-fragment-specifier
The missing_fragment_specifier warning is issued when an unused pattern in a
`macro_rules!` macro definition has a meta-variable (e.g. `$e`) that is not
followed by a fragment specifier (e.g. `:expr`).
This warning can always be fixed by removing the unused pattern in the
`macro_rules!` macro definition.
## mutable-transmutes
This lint catches transmuting from `&T` to `&mut T` becuase it is undefined
behavior. Some example code that triggers this lint:
```rust,ignore
unsafe {
let y = std::mem::transmute::<&i32, &mut i32>(&5);
}
```
This will produce:
```text
error: mutating transmuted &mut T from &T may cause undefined behavior, consider instead using an UnsafeCell
--> src/main.rs:3:17
|
3 | let y = std::mem::transmute::<&i32, &mut i32>(&5);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
```
## no-mangle-const-items
This lint detects any `const` items with the `#[no_mangle]` attribute.
Constants do not have their symbols exported, and therefore, this probably
means you meant to use a `static`, not a `const`. Some example code that
triggers this lint:
```rust,ignore
#[no_mangle]
const FOO: i32 = 5;
```
This will produce:
```text
error: const items should never be #[no_mangle]
--> src/main.rs:3:1
|
3 | const FOO: i32 = 5;
| -----^^^^^^^^^^^^^^
| |
| help: try a static value: `pub static`
|
```
## parenthesized-params-in-types-and-modules
This lint detects incorrect parentheses. Some example code that triggers this
lint:
```rust,ignore
let x = 5 as usize();
```
This will produce:
```text
error: parenthesized parameters may only be used with a trait
--> src/main.rs:2:21
|
2 | let x = 5 as usize();
| ^^
|
= note: #[deny(parenthesized_params_in_types_and_modules)] on by default
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #42238 <https://github.com/rust-lang/rust/issues/42238>
```
To fix it, remove the `()`s.
## pub-use-of-private-extern-crate
This lint detects a specific situation of re-exporting a private `extern crate`;
## safe-extern-statics
In older versions of Rust, there was a soundness issue where `extern static`s were allowed
to be accessed in safe code. This lint now catches and denies this kind of code.
## unknown-crate-types
This lint detects an unknown crate type found in a `#[crate_type]` directive. Some
example code that triggers this lint:
```rust,ignore
#![crate_type="lol"]
```
This will produce:
```text
error: invalid `crate_type` value
--> src/lib.rs:1:1
|
1 | #![crate_type="lol"]
| ^^^^^^^^^^^^^^^^^^^^
|
```

5
src/doc/rustc/src/lints/listing/index.md Normal file
View file

@ -0,0 +1,5 @@
# Lint listing
This section lists out all of the lints, grouped by their default lint levels.
You can also see this list by running `rustc -W help`.

1039
src/doc/rustc/src/lints/listing/warn-by-default.md Normal file
View file

File diff suppressed because it is too large Load diff

10
src/doc/rustc/src/targets/built-in.md Normal file
View file

@ -0,0 +1,10 @@
# Built-in Targets
`rustc` ships with the ability to compile to many targets automatically, we
call these "built-in" targets, and they generally correspond to targets that
the team is supporting directly.
To see the list of built-in targets, you can run `rustc --print target-list`,
or look at [the API
docs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_back/target/#modules).
Each module there defines a builder for a particular target.

17
src/doc/rustc/src/targets/custom.md Normal file
View file

@ -0,0 +1,17 @@
# Custom Targets
If you'd like to build for a target that is not yet supported by `rustc`, you can use a
"custom target specification" to define a target. These target specification files
are JSON. To see the JSON for the host target, you can run:
```bash
$ rustc +nightly -Z unstable-options --print target-spec-json
```
To see it for a different target, add the `--target` flag:
```bash
$ rustc +nightly -Z unstable-options --target=wasm32-unknown-unknown --print target-spec-json
```
To use a custom target, see [`xargo`](https://github.com/japaric/xargo).

13
src/doc/rustc/src/targets/index.md Normal file
View file

@ -0,0 +1,13 @@
# Targets
`rustc` is a cross-compiler by default. This means that you can use any compiler to build for any
architecture. The list of *targets* are the possible architectures that you can build for.
To see all the options that you can set with a target, see the docs
[here](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_back/target/struct.Target.html).
To compile to a particular target, use the `--target` flag:
```bash
$ rustc src/main.rs --target=wasm32-unknown-unknown
```

68
src/doc/rustc/src/what-is-rustc.md Normal file
View file

@ -0,0 +1,68 @@
# What is rustc?
Welcome to "The rustc book"! `rustc` is the compiler for the Rust programming
language, provided by the project itself. Compilers take your source code and
produce binary code, either as a library or executable.
Most Rust programmers don't invoke `rustc` directly, but instead do it through
[Cargo](../cargo/index.html). It's all in service of `rustc` though! If you
want to see how Cargo calls `rustc`, you can
```bash
$ cargo build --verbose
```
And it will print out each `rustc` invocation. This book can help you
understand what each of these options does. Additionally, while most
Rustaceans use Cargo, not all do: sometimes they integrate `rustc` into other
build systems. This book should provide a guide to all of the options you'd
need to do so.
## Basic usage
Let's say you've got a little hello world program in a file `hello.rs`:
```rust
fn main() {
println!("Hello, world!");
}
```
To turn this source code into an executable, you can use `rustc`:
```bash
$ rustc hello.rs
$ ./hello # on a *NIX
$ .\hello.exe # on Windows
```
Note that we only ever pass `rustc` the *crate root*, not every file we wish
to compile. For example, if we had a `main.rs` that looked like this:
```rust,ignore
mod foo;
fn main() {
foo::hello();
}
```
And a `foo.rs` that had this:
```rust,ignore
fn hello() {
println!("Hello, world!");
}
```
To compile this, we'd run this command:
```bash
$ rustc main.rs
```
No need to tell `rustc` about `foo.rs`; the `mod` statements give it
everything that it needs. This is different than how you would use a C
compiler, where you invoke the compiler on each file, and then link
everything together. In other words, the *crate* is a translation unit, not a
particular module.