-
Notifications
You must be signed in to change notification settings - Fork 12.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add "the Rustc book" #49707
Merged
Merged
Add "the Rustc book" #49707
Changes from 16 commits
Commits
Show all changes
18 commits
Select commit
Hold shift + click to select a range
0dd0a5b
initialize the rustc book
steveklabnik b99418d
Add rustc book to the build system
steveklabnik 7de5b60
update doc index to link to the rustc book
steveklabnik c942bf4
Add a TOC
steveklabnik 4f6ed51
fix authorship in book.toml
steveklabnik 5424dc4
write headings for command line arguments
steveklabnik cd55364
write 'what is rustc'
steveklabnik 78b076d
add targets to TOC
steveklabnik 50b3a3d
add a lot of text about lints
steveklabnik df81ca3
document deny by default lints
steveklabnik 758a77d
more lints
steveklabnik 142c52f
fix tests
steveklabnik cb6a199
add codegen options section
steveklabnik cd3f6cf
fill out command line arguments
steveklabnik b204968
fill out contributing
steveklabnik 00c860e
write docs for targets
steveklabnik ac79c41
review nits
steveklabnik 36475d9
more nits
steveklabnik File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
book |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
[book] | ||
authors = ["The Rust Project Developers"] | ||
multilingual = false | ||
src = "src" | ||
title = "The rustc book" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
parallism](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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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`/`--verision`: print a version | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
|
||
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`: configur coloring of output | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
|
||
This flag lets you control color settings of the output. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
parallelism