Skip to content

Commit

Permalink
Rollup merge of #71897 - alexcrichton:embed-bitcode-docs, r=nnethercote
Browse files Browse the repository at this point in the history
Improve docs for embed-bitcode and linker-plugin-lto

Follow-up from #71716 I wasn't able to add in time.
  • Loading branch information
Dylan-DPC authored May 5, 2020
2 parents 67a7b7a + 0b35692 commit 3efcba6
Showing 1 changed file with 36 additions and 8 deletions.
44 changes: 36 additions & 8 deletions src/doc/rustc/src/codegen-options/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit 3efcba6

Please sign in to comment.