Improve documentation for codegen options
This adds more information to many different codegen options. It should not add any new guarantees, just document existing behavior.
This commit is contained in:
Noratrieb
parent
a88fc0eaae
commit
198e89b533
1 changed files with 49 additions and 3 deletions
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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`
|
||||
|
||||
Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=3`.
|
||||
|
||||
|
|
@ -407,6 +424,9 @@ 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`.
|
||||
If `std` is used as a `dylib` with `unwind`, the final binary must also use `unwind`.
|
||||
|
||||
## passes
|
||||
|
||||
This flag can be used to add extra [LLVM
|
||||
|
|
@ -416,6 +436,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
|
||||
|
|
@ -523,12 +549,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
|
||||
|
|
@ -545,6 +589,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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue