Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Update codegen option documentation. #65136

Merged
merged 4 commits into from
Nov 5, 2019
Merged

Update codegen option documentation. #65136

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f3e8c2e
Update codegen option documentation.
ehuss Oct 5, 2019
bd70c03
Apply suggestions from kinnison
ehuss Oct 26, 2019
c6bfe28
Be more specific with -C inline-threshold.
ehuss Oct 26, 2019
9b9d651
Attempt to clarify LTO and codegen-units.
ehuss Nov 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 175 additions & 37 deletions src/doc/rustc/src/codegen-options/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,12 @@ This option is deprecated and does nothing.

## linker

This flag lets you control which linker `rustc` invokes to link your code.
This flag lets you control which linker `rustc` invokes to link your code. It
takes a path to the linker executable. If this flag is not specified, the
linker will be inferred based on the target. See also the
[linker-flavor](#linker-flavor) flag for another way to specify the linker.

## link-arg=val
## link-arg

This flag lets you append a single extra argument to the linker invocation.

Expand All @@ -25,9 +28,27 @@ options should be separated by spaces.
## linker-flavor

This flag lets you control the linker flavor used by `rustc`. If a linker is given with the
`-C linker` flag described above then the linker flavor is inferred from the value provided. If no
[`-C linker` flag](#linker), then the linker flavor is inferred from the value provided. If no
linker is given then the linker flavor is used to determine the linker to use. Every `rustc` target
defaults to some linker flavor.
defaults to some linker flavor. Valid options are:

* `em`: Uses [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html).
* `gcc`: Uses the `cc` executable, which is typically gcc or clang on many systems.
* `ld`: Uses the `ld` executable.
* `msvc`: Uses the `link.exe` executable from Microsoft Visual Studio MSVC.
* `ptx-linker`: Uses
[`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia
NVPTX GPGPU support.
* `wasm-ld`: Uses the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
executable, a port of LLVM `lld` for WebAssembly.
* `ld64.lld`: Uses the LLVM `lld` executable with the [`-flavor darwin`
flag][lld-flavor] for Apple's `ld`.
* `ld.lld`: Uses the LLVM `lld` executable with the [`-flavor gnu`
flag][lld-flavor] for GNU binutils' `ld`.
* `lld-link`: Uses the LLVM `lld` executable with the [`-flavor link`
Dylan-DPC-zz marked this conversation as resolved.
Show resolved Hide resolved
flag][lld-flavor] for Microsoft's `link.exe`.

[lld-flavor]: https://lld.llvm.org/Driver.html

## link-dead-code

Expand All @@ -39,42 +60,84 @@ metrics.
## lto

This flag instructs LLVM to use [link time
optimizations](https://llvm.org/docs/LinkTimeOptimization.html).
optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce
better optimized code, using whole-program analysis, at the cost of longer
linking time.

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.
This flag may take one of the following values:

* `y`, `yes`, `on`, `fat`, or no value: Performs "fat" LTO which attempts to
perform optimizations across all crates within the dependency graph.
* `n`, `no`, `off`: Disables LTO.
* `thin`: Performs ["thin"
LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html).
This is similar to "fat", but takes substantially less time to run while
still achieving performance gains similar to "fat".

If `-C lto` is not specified, then the compiler will attempt to perform "thin local LTO"
which performs "thin" LTO on the local crate only across its [codegen
units](#codegen-units). In this case, LTO is disabled if codegen units is 1 or
optimizations are disabled ([`-C opt-level=0`](#opt-level)).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this true?
I tried to set exclusive lto and codegen-units option and the binary size is
increased than when I set both lto=true and codegen-units=1.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By "exclusive LTO", do you mean not including the flag? Can you clarify which commands you ran?

I would expect it to be larger, since lto=true is "fat", and without the flag it is only "thin local", which does less optimization.

Here is the logic this is referring to.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By "exclusive" I mean I either set lto or codegen-units.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I set these options in Cargo.toml, not via rustc arguments

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still not sure I understand the confusion here. lto=true + codegen-units=1 should be the smallest. It does fat LTO, and with 1 CGU per crate, so it has more optimization potential (but is very slow to compile). That is:

  • codegen-units=1: Disables LTO, so won't have cross-crate optimizations.
  • lto=true: 16 cgus, performs fat LTO across crates.
  • codegen-units=1 + lto=true: 1 cgu, fat LTO across crates.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO adding that to the documentation seems really helpful.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I'll try to make it a little clearer.


See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO.

## linker-plugin-lto

Defers LTO optimizations to the linker. See
[linkger-plugin-LTO](../linker-plugin-lto.md) for more details. Takes one of
the following values:

* `y`, `yes`, `on`, or no value: Enabled.
* `n`, `no`, or `off`: Disabled (default).
* A path to the linker plugin.

## 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.
machine. Each target has a default base CPU.

## target-feature

Individual targets will support different features; this flag lets you control
enabling or disabling a feature.
enabling or disabling a feature. Each feature should be prefixed with a `+` to
enable it or `-` to disable it. Separate multiple features with commas.

To see the valid options and an example of use, run `rustc --print
target-features`.

Using this flag is unsafe and might result in [undefined runtime behavior](../targets/known-issues.md).
Using this flag is unsafe and might result in [undefined runtime
behavior](../targets/known-issues.md).

See also the [`target_feature`
attribute](../../reference/attributes/codegen.md#the-target_feature-attribute)
for controlling features per-function.

This also supports the feature `+crt-static` and `-crt-static` to control
[static C runtime linkage](../../reference/linkage.html#static-and-dynamic-c-runtimes).

Each target and [`target-cpu`](#target-cpu) has a default set of enabled
features.

## passes

This flag can be used to add extra LLVM passes to the compilation.
This flag can be used to add extra [LLVM
passes](http://llvm.org/docs/Passes.html) to the compilation.

The list must be separated by spaces.

See also the [`no-prepopulate-passes`](#no-prepopulate-passes) flag.

## llvm-args

This flag can be used to pass a list of arguments directly to LLVM.

The list must be separated by spaces.

Pass `--help` to see a list of options.

## save-temps

`rustc` will generate temporary files during compilation; normally it will
Expand All @@ -83,16 +146,21 @@ preserved instead of removed.

## rpath

This option allows you to set the value of
This option allows you to enable
[`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:
This flag allows you to control the behavior of [runtime integer
overflow](../../reference/expressions/operator-expr.md#overflow). When
overflow-checks are enabled, a panic will occur on overflow. This flag takes
one of the following values:

* `y`, `yes`, `on`, or no value: Enable overflow checks.
* `n`, `no`, or `off`: Disable overflow checks.

* To turn overflow checks on: `y`, `yes`, or `on`.
* To turn overflow checks off: `n`, `no`, or `off`.
If not specified, overflow checks are enabled if
[debug-assertions](#debug-assertions) are enabled, disabled otherwise.

## no-prepopulate-passes

Expand Down Expand Up @@ -125,49 +193,62 @@ 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.
`rustc` normally uses the LLVM internal assembler to create object code. This
flag will disable the internal assembler and emit assembly code to be
translated using an external assembler, currently the linker such as `cc`.

## 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:
be passed one of the following options:

* To enable the red zone: `y`, `yes`, or `on`.
* To disable it: `n`, `no`, or `off`.
* `y`, `yes`, `on`, or no value: Disables the red zone.
* `n`, `no`, or `off`: Enables the red zone.

The default if not specified depends on the target.

## relocation-model

This option lets you choose which relocation model to use.
This option lets you choose which
[relocation](https://en.wikipedia.org/wiki/Relocation_\(computing\)) model to
use.

To find the valid options for this flag, run `rustc --print relocation-models`.

## code-model=val
## code-model

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.
This option allows you to control the metadata used for symbol mangling. This
takes a space-separated list of strings. Mangled symbols will incorporate a
hash of the metadata. This may be used, for example, to differentiate symbols
between two different versions of the same crate being linked.

## extra-filename

This option allows you to put extra data in each output filename.
This option allows you to put extra data in each output filename. It takes a
string to add as a suffix to the filename. See the [`--emit`
flag][option-emit] for more information.

## codegen-units

This flag lets you control how many threads are used when doing
code generation.
This flag lets you control how many threads are used when doing code
generation. It takes an integer greater than 0.

Increasing parallelism may speed up compile times, but may also produce slower
code. Setting this to 1 may improve the performance of generated code, but may
be slower to compile.

Increasing parallelism may speed up compile times, but may also
produce slower code.
The default, if not specified, is 16.

## remark

This flag lets you print remarks for these optimization passes.
This flag lets you print remarks for optimization passes.

The list of passes should be separated by spaces.

Expand All @@ -181,30 +262,55 @@ This option is deprecated and does nothing.

This flag lets you control debug information:

* `0`: no debug info at all
* `0`: no debug info at all (default)
* `1`: line tables only
* `2`: full debug info

Note: The [`-g` flag][option-g-debug] is an alias for `-C debuginfo=2`.

## opt-level

This flag lets you control the optimization level.

* `0`: no optimizations, also turn on `cfg(debug_assertions)`.
* `0`: no optimizations, also turns on [`cfg(debug_assertions)`](#debug-assertions).
* `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.

Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`.

The default is `0`.

## debug-assertions

This flag lets you turn `cfg(debug_assertions)` on or off.
This flag lets you turn `cfg(debug_assertions)` [conditional
compilation](../../reference/conditional-compilation.md#debug_assertions) on
or off. It takes one of the following values:

* `y`, `yes`, `on`, or no value: Enable debug-assertions.
* `n`, `no`, or `off`: Disable debug-assertions.

If not specified, debug assertions are automatically enabled only if the
[opt-level](#opt-level) is 0.

## inline-threshold

This option lets you set the threshold for inlining a function.
This option lets you set the default threshold for inlining a function. It
takes an unsigned integer as a value. Inlining is based on a cost model, where
a higher threshold will allow more inlining.

The default is 225.
The default depends on the [opt-level](#opt-level):

| opt-level | Threshold |
|-----------|-----------|
| 0 | N/A, only inlines always-inline functions |
| 1 | N/A, only inlines always-inline functions and LLVM lifetime intrinsics |
| 2 | 225 |
| 3 | 275 |
| s | 75 |
| z | 25 |

## panic

Expand All @@ -213,9 +319,14 @@ This option lets you control what happens when the code panics.
* `abort`: terminate the process upon panic
* `unwind`: unwind the stack upon panic

If not specified, the default depends on the target.

## incremental

This flag allows you to enable incremental compilation.
This flag allows you to enable incremental compilation, which allows `rustc`
to save information after compiling a crate to be reused when recompiling the
crate, improving re-compile times. This takes a path to a directory where
incremental files will be stored.

## profile-generate

Expand All @@ -232,4 +343,31 @@ optimization (PGO). The flag takes a mandatory argument which is the path
to a valid `.profdata` file. See the chapter on
[profile-guided optimization] for more information.

## force-frame-pointers

This flag forces the use of frame pointers. It takes one of the following
values:

* `y`, `yes`, `on`, or no value: Frame pointers are forced to be enabled.
* `n`, `no`, or `off`: Frame pointers are not forced to be enabled. This does
not necessarily mean frame pointers will be removed.

The default if not specified depends on the target.

## default-linker-libraries

This flag controls whether or not the linker includes its default libraries.
It takes one of the following values:

* `y`, `yes`, `on`, or no value: Default libraries are included.
* `n`, `no`, or `off`: Default libraries are **not** included.

For example, for gcc flavor linkers, this issues the `-nodefaultlibs` flag to
the linker.

The default is `yes` if not specified.

[option-emit]: ../command-line-arguments.md#option-emit
[option-o-optimize]: ../command-line-arguments.md#option-o-optimize
[profile-guided optimization]: ../profile-guided-optimization.md
[option-g-debug]: ../command-line-arguments.md#option-g-debug
Loading