Update codegen option documentation.

Author: ehuss

src/doc/rustc/src/codegen-options/index.md

@@ -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.
 
@@ -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`
+  flag][lld-flavor] for Microsoft's `link.exe`.
+
+[lld-flavor]: https://lld.llvm.org/Driver.html
 
 ## link-dead-code
 
@@ -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 it 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)).
+
+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
@@ -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
 
@@ -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.
 
@@ -181,30 +262,47 @@ 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 turn 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 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 threshold for inlining a function. It takes a
+positive 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). Current values are between
+25 to 275.
 
 ## panic
 
@@ -213,9 +311,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
 
@@ -232,4 +335,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