Skip to content

Improve documentation for codegen options #141554

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+48 −3
Open

Improve documentation for codegen options #141554

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
51 changes: 48 additions & 3 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 @@ -192,6 +192,8 @@ 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.

Using incremental compilation inhibits certain optimizations (for example by increasing the amount of codegen units) and is therefore not recommend for release builds.

## inline-threshold

This option is deprecated and does nothing.
Expand All @@ -213,6 +215,8 @@ 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.

On Unix-like targets that use `cc` as the linker driver, use `-Clink-arg=-Wl,$ARG` to pass an argument to the actual linker.

## link-args

This flag lets you append multiple extra arguments to the linker invocation. The
Expand Down Expand Up @@ -248,6 +252,10 @@ 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.

Note that on Unix-like targets (for example, `*-unknown-linux-gnu` or `*-unknown-freebsd`)
the C compiler (for example `cc` or `clang`) is used as the "linker" here, serving as a linker driver.
It will invoke the actual linker with all the necessary flags to be able to link against the system libraries like libc.

## linker-flavor

This flag controls the linker flavor used by `rustc`. If a linker is given with
Expand Down Expand Up @@ -301,6 +309,12 @@ The list must be separated by spaces.

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

<div class="warning">

Because this flag directly talks to LLVM, it is not subject to the usual stability guarantees of rustc's CLI interface.

</div>

## lto

This flag controls whether LLVM uses [link time
Expand All @@ -315,6 +329,7 @@ linking time. It takes one of the following values:
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".
For larger projects like the Rust compiler, ThinLTO can even result in better performance than fat LTO.

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
Expand Down Expand Up @@ -343,6 +358,8 @@ between two different versions of the same crate being linked.
This flag tells the pass manager to use an empty list of passes, instead of the
usual pre-populated list of passes.

When combined with `-O --emit llvm-ir`, it can be used to see the optimized LLVM IR emitted by rustc before any optimizations are applied by LLVM.

## no-redzone

This flag allows you to disable [the
Expand Down Expand Up @@ -379,7 +396,7 @@ This flag controls the optimization level.
* `2`: some optimizations.
* `3`: all optimizations.
* `s`: optimize for binary size.
* `z`: optimize for binary size, but also turn off loop vectorization.
* `z`: optimize for binary size, but more aggressively. Often results in larger binaries than `s`
Copy link
Member Author

Choose a reason for hiding this comment

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

I took the description from https://llvm.org/doxygen/classllvm_1_1OptimizationLevel.html#a1e916712888d6a2d3952834c126460e7

The fact that it's often worse is based on experience

Copy link
Member Author

Choose a reason for hiding this comment

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

I'd guess the old information was based on https://stackoverflow.com/questions/15548023/clang-optimization-levels
But that misses all the heuristics that are also affected by this flag, which are much more important (there's no way just not doing vectorization results in significantly bigger binaries)


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

Expand Down Expand Up @@ -407,6 +424,8 @@ This option lets you control what happens when the code panics.

If not specified, the default depends on the target.

If any crate in the crate graph uses `abort`, the final binary (`bin`, `dylib`, `cdylib`, `staticlib`) must also use `abort`.
Copy link
Member

Choose a reason for hiding this comment

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

And if libstd is used as dylib compiled with panic=unwind, the final binary must also use panic=unwind. (In that case libstd.so links against libpanic_unwind.rlib. rustc will emit an error when using panic=abort while linking libpanic_unwind.rlib)


## passes

This flag can be used to add extra [LLVM
Expand All @@ -416,6 +435,12 @@ The list must be separated by spaces.

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

<div class="warning">

Because this flag directly talks to LLVM, it not subject to the usual stability guarantees of rustc's CLI interface.

</div>

## prefer-dynamic

By default, `rustc` prefers to statically link dependencies. This option will
Expand Down Expand Up @@ -523,12 +548,30 @@ The list of passes should be separated by spaces.

## rpath

This flag controls whether [`rpath`](https://en.wikipedia.org/wiki/Rpath) is
enabled. It takes one of the following values:
This flag controls whether rustc sets an [`rpath`](https://en.wikipedia.org/wiki/Rpath) for the binary.
It takes one of the following values:

* `y`, `yes`, `on`, `true` or no value: enable rpath.
* `n`, `no`, `off` or `false`: disable rpath (the default).

This flag only does something on Unix-like platforms (Mach-O and ELF), it is ignored on other platforms.

If enabled, rustc will add output-relative (using `@load_path` on Mach-O and `$ORIGIN` on ELF respectively) rpaths to all `dylib` dependencies.

For example, for the following directory structure, with `libdep.so` being a `dylib` crate compiled with `-Cprefer-dynamic`:

```text
dep
|- libdep.so
a.rs
```

`rustc a.rs --extern dep=dep/libdep.so -Crpath` will, on x86-64 Linux, result in approximately the following `DT_RUNPATH`: `$ORIGIN/dep:$ORIGIN/$RELATIVE_PATH_TO_SYSROOT/lib/rustlib/x86_64-unknown-linux-gnu/lib` (where `RELATIVE_PATH_TO_SYSROOT` depends on the build directory location).

This is primarily useful for local development, to ensure that all the `dylib` dependencies can be found appropriately.

To set the rpath to a different value (which can be useful for distribution), `-Clink-arg` with a platform-specific linker argument can be used to set the rpath directly.

## save-temps

This flag controls whether temporary files generated during compilation are
Expand All @@ -545,6 +588,8 @@ point instructions in software. It takes one of the following values:
* `y`, `yes`, `on`, `true` or no value: use soft floats.
* `n`, `no`, `off` or `false`: use hardware floats (the default).

This flag only works on `*eabihf` targets and **is unsound and deprecated**.

## split-debuginfo

This option controls the emission of "split debuginfo" for debug information
Expand Down
Loading