OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Rollup merge of #71897 - alexcrichton:embed-bitcode-docs, r=nnethercote

Browse Source 
Improve docs for embed-bitcode and linker-plugin-lto

Follow-up from #71716 I wasn't able to add in time.
This commit is contained in:
Dylan DPC 2020-05-05 12:55:13 +02:00 committed by GitHub
commit 3efcba693a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
src/doc/rustc/src/codegen-options/index.md
View File

@ -62,24 +62,40 @@ the linker.
## embed-bitcode
This flag controls whether or not the compiler puts LLVM bitcode into generated
rlibs. It takes one of the following values:
This flag controls whether or not the compiler embeds LLVM bitcode into object
files. It takes one of the following values:
* `y`, `yes`, `on`, or no value: put bitcode in rlibs (the default).
* `n`, `no`, or `off`: omit bitcode from rlibs.
LLVM bitcode is only needed when link-time optimization (LTO) is being
performed, but it is enabled by default for backwards compatibility reasons.
LLVM bitcode is required when rustc is performing link-time optimization (LTO).
It is also required on some targets like iOS ones where vendors look for LLVM
bitcode. Embedded bitcode will appear in rustc-generated object files inside of
a section whose name is defined by the target platform. Most of the time this is
`.llvmbc`.
The use of `-C embed-bitcode=no` can significantly improve compile times and
reduce generated file sizes. For these reasons, Cargo uses `-C
embed-bitcode=no` whenever possible. Likewise, if you are building directly
with `rustc` we recommend using `-C embed-bitcode=no` whenever you are not
using LTO.
reduce generated file sizes if your compilation does not actually need bitcode
(e.g. if you're not compiling for iOS or you're not performing LTO). For these
reasons, Cargo uses `-C embed-bitcode=no` whenever possible. Likewise, if you
are building directly with `rustc` we recommend using `-C embed-bitcode=no`
whenever you are not using LTO.
If combined with `-C lto`, `-C embed-bitcode=no` will cause `rustc` to abort
at start-up, because the combination is invalid.
> **Note**: if you're building Rust code with LTO then you probably don't even
> need the `embed-bitcode` option turned on. You'll likely want to use
> `-Clinker-plugin-lto` instead which skips generating object files entirely and
> simply replaces object files with LLVM bitcode. The only purpose for
> `-Cembed-bitcode` is when you're generating an rlib that is both being used
> with and without LTO. For example Rust's standard library ships with embedded
> bitcode since users link to it both with and without LTO.
>
> This also may make you wonder why the default is `yes` for this option. The
> reason for that is that it's how it was for rustc 1.44 and prior. In 1.45 this
> option was added to turn off what had always been the default.
## extra-filename
This option allows you to put extra data in each output filename. It takes a
@ -199,6 +215,18 @@ the following values:
* `n`, `no`, or `off`: disable linker plugin LTO (the default).
* A path to the linker plugin.
More specifically this flag will cause the compiler to replace its typical
object file output with LLVM bitcode files. For example an rlib produced with
`-Clinker-plugin-lto` will still have `*.o` files in it, but they'll all be LLVM
bitcode instead of actual machine code. It is expected that the native platform
linker is capable of loading these LLVM bitcode files and generating code at
link time (typically after performing optimizations).
Note that rustc can also read its own object files produced with
`-Clinker-plugin-lto`. If an rlib is only ever going to get used later with a
`-Clto` compilation then you can pass `-Clinker-plugin-lto` to speed up
compilation and avoid generating object files that aren't used.
## llvm-args
This flag can be used to pass a list of arguments directly to LLVM.