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

   1 # Codegen options
   2
   3 All of these options are passed to `rustc` via the `-C` flag, short for "codegen." You can see
   4 a version of this list for your exact compiler by running `rustc -C help`.
   5
   6 ## ar
   7
   8 This option is deprecated and does nothing.
   9
  10 ## linker
  11
  12 This flag lets you control which linker `rustc` invokes to link your code. It
  13 takes a path to the linker executable. If this flag is not specified, the
  14 linker will be inferred based on the target. See also the
  15 [linker-flavor](#linker-flavor) flag for another way to specify the linker.
  16
  17 ## link-arg
  18
  19 This flag lets you append a single extra argument to the linker invocation.
  20
  21 "Append" is significant; you can pass this flag multiple times to add multiple arguments.
  22
  23 ## link-args
  24
  25 This flag lets you append multiple extra arguments to the linker invocation. The
  26 options should be separated by spaces.
  27
  28 ## linker-flavor
  29
  30 This flag lets you control the linker flavor used by `rustc`. If a linker is given with the
  31 [`-C linker` flag](#linker), then the linker flavor is inferred from the value provided. If no
  32 linker is given then the linker flavor is used to determine the linker to use. Every `rustc` target
  33 defaults to some linker flavor. Valid options are:
  34
  35 * `em`: Uses [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html).
  36 * `gcc`: Uses the `cc` executable, which is typically gcc or clang on many systems.
  37 * `ld`: Uses the `ld` executable.
  38 * `msvc`: Uses the `link.exe` executable from Microsoft Visual Studio MSVC.
  39 * `ptx-linker`: Uses
  40   [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia
  41   NVPTX GPGPU support.
  42 * `wasm-ld`: Uses the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
  43   executable, a port of LLVM `lld` for WebAssembly.
  44 * `ld64.lld`: Uses the LLVM `lld` executable with the [`-flavor darwin`
  45   flag][lld-flavor] for Apple's `ld`.
  46 * `ld.lld`: Uses the LLVM `lld` executable with the [`-flavor gnu`
  47   flag][lld-flavor] for GNU binutils' `ld`.
  48 * `lld-link`: Uses the LLVM `lld` executable with the [`-flavor link`
  49   flag][lld-flavor] for Microsoft's `link.exe`.
  50
  51 [lld-flavor]: https://lld.llvm.org/Driver.html
  52
  53 ## link-dead-code
  54
  55 Normally, the linker will remove dead code. This flag disables this behavior.
  56
  57 An example of when this flag might be useful is when trying to construct code coverage
  58 metrics.
  59
  60 ## lto
  61
  62 This flag instructs LLVM to use [link time
  63 optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce
  64 better optimized code, using whole-program analysis, at the cost of longer
  65 linking time.
  66
  67 This flag may take one of the following values:
  68
  69 * `y`, `yes`, `on`, `fat`, or no value: Performs "fat" LTO which attempts to
  70   perform optimizations across all crates within the dependency graph.
  71 * `n`, `no`, `off`: Disables LTO.
  72 * `thin`: Performs ["thin"
  73   LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html).
  74   This is similar to "fat", but takes substantially less time to run while
  75   still achieving performance gains similar to "fat".
  76
  77 If `-C lto` is not specified, then the compiler will attempt to perform "thin
  78 local LTO" which performs "thin" LTO on the local crate only across its
  79 [codegen units](#codegen-units). When `-C lto` is not specified, LTO is
  80 disabled if codegen units is 1 or optimizations are disabled ([`-C
  81 opt-level=0`](#opt-level)). That is:
  82
  83 * When `-C lto` is not specified:
  84   * `codegen-units=1`: Disables LTO.
  85   * `opt-level=0`: Disables LTO.
  86 * When `-C lto=true`:
  87   * `lto=true`: 16 codegen units, performs fat LTO across crates.
  88   * `codegen-units=1` + `lto=true`: 1 codegen unit, fat LTO across crates.
  89
  90 See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO.
  91
  92 ## linker-plugin-lto
  93
  94 Defers LTO optimizations to the linker. See
  95 [linkger-plugin-LTO](../linker-plugin-lto.md) for more details. Takes one of
  96 the following values:
  97
  98 * `y`, `yes`, `on`, or no value: Enabled.
  99 * `n`, `no`, or `off`: Disabled (default).
 100 * A path to the linker plugin.
 101
 102 ## target-cpu
 103
 104 This instructs `rustc` to generate code specifically for a particular processor.
 105
 106 You can run `rustc --print target-cpus` to see the valid options to pass
 107 here. Additionally, `native` can be passed to use the processor of the host
 108 machine. Each target has a default base CPU.
 109
 110 ## target-feature
 111
 112 Individual targets will support different features; this flag lets you control
 113 enabling or disabling a feature. Each feature should be prefixed with a `+` to
 114 enable it or `-` to disable it. Separate multiple features with commas.
 115
 116 To see the valid options and an example of use, run `rustc --print
 117 target-features`.
 118
 119 Using this flag is unsafe and might result in [undefined runtime
 120 behavior](../targets/known-issues.md).
 121
 122 See also the [`target_feature`
 123 attribute](../../reference/attributes/codegen.md#the-target_feature-attribute)
 124 for controlling features per-function.
 125
 126 This also supports the feature `+crt-static` and `-crt-static` to control
 127 [static C runtime linkage](../../reference/linkage.html#static-and-dynamic-c-runtimes).
 128
 129 Each target and [`target-cpu`](#target-cpu) has a default set of enabled
 130 features.
 131
 132 ## passes
 133
 134 This flag can be used to add extra [LLVM
 135 passes](http://llvm.org/docs/Passes.html) to the compilation.
 136
 137 The list must be separated by spaces.
 138
 139 See also the [`no-prepopulate-passes`](#no-prepopulate-passes) flag.
 140
 141 ## llvm-args
 142
 143 This flag can be used to pass a list of arguments directly to LLVM.
 144
 145 The list must be separated by spaces.
 146
 147 Pass `--help` to see a list of options.
 148
 149 ## save-temps
 150
 151 `rustc` will generate temporary files during compilation; normally it will
 152 delete them after it's done with its work. This option will cause them to be
 153 preserved instead of removed.
 154
 155 ## rpath
 156
 157 This option allows you to enable
 158 [`rpath`](https://en.wikipedia.org/wiki/Rpath).
 159
 160 ## overflow-checks
 161
 162 This flag allows you to control the behavior of [runtime integer
 163 overflow](../../reference/expressions/operator-expr.md#overflow). When
 164 overflow-checks are enabled, a panic will occur on overflow. This flag takes
 165 one of the following values:
 166
 167 * `y`, `yes`, `on`, or no value: Enable overflow checks.
 168 * `n`, `no`, or `off`: Disable overflow checks.
 169
 170 If not specified, overflow checks are enabled if
 171 [debug-assertions](#debug-assertions) are enabled, disabled otherwise.
 172
 173 ## no-prepopulate-passes
 174
 175 The pass manager comes pre-populated with a list of passes; this flag
 176 ensures that list is empty.
 177
 178 ## no-vectorize-loops
 179
 180 By default, `rustc` will attempt to [vectorize
 181 loops](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer). This
 182 flag will turn that behavior off.
 183
 184 ## no-vectorize-slp
 185
 186 By default, `rustc` will attempt to vectorize code using [superword-level
 187 parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer). This
 188 flag will turn that behavior off.
 189
 190 ## soft-float
 191
 192 This option will make `rustc` generate code using "soft floats." By default,
 193 a lot of hardware supports floating point instructions, and so the code generated
 194 will take advantage of this. "soft floats" emulate floating point instructions
 195 in software.
 196
 197 ## prefer-dynamic
 198
 199 By default, `rustc` prefers to statically link dependencies. This option will
 200 indicate that dynamic linking should be used if possible if both a static and
 201 dynamic versions of a library are available. There is an internal algorithm
 202 for determining whether or not it is possible to statically or dynamically
 203 link with a dependency. For example, `cdylib` crate types may only use static
 204 linkage.
 205
 206 ## no-integrated-as
 207
 208 `rustc` normally uses the LLVM internal assembler to create object code. This
 209 flag will disable the internal assembler and emit assembly code to be
 210 translated using an external assembler, currently the linker such as `cc`.
 211
 212 ## no-redzone
 213
 214 This flag allows you to disable [the
 215 red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). This flag can
 216 be passed one of the following options:
 217
 218 * `y`, `yes`, `on`, or no value: Disables the red zone.
 219 * `n`, `no`, or `off`: Enables the red zone.
 220
 221 The default if not specified depends on the target.
 222
 223 ## relocation-model
 224
 225 This option lets you choose which
 226 [relocation](https://en.wikipedia.org/wiki/Relocation_\(computing\)) model to
 227 use.
 228
 229 To find the valid options for this flag, run `rustc --print relocation-models`.
 230
 231 ## code-model
 232
 233 This option lets you choose which code model to use.
 234
 235 To find the valid options for this flag, run `rustc --print code-models`.
 236
 237 ## metadata
 238
 239 This option allows you to control the metadata used for symbol mangling. This
 240 takes a space-separated list of strings. Mangled symbols will incorporate a
 241 hash of the metadata. This may be used, for example, to differentiate symbols
 242 between two different versions of the same crate being linked.
 243
 244 ## extra-filename
 245
 246 This option allows you to put extra data in each output filename. It takes a
 247 string to add as a suffix to the filename. See the [`--emit`
 248 flag][option-emit] for more information.
 249
 250 ## codegen-units
 251
 252 This flag controls how many code generation units the crate is split into. It
 253 takes an integer greater than 0.
 254
 255 When a crate is split into multiple codegen units, LLVM is able to process
 256 them in parallel. Increasing parallelism may speed up compile times, but may
 257 also produce slower code. Setting this to 1 may improve the performance of
 258 generated code, but may be slower to compile.
 259
 260 The default, if not specified, is 16. This flag is ignored if
 261 [incremental](#incremental) is enabled, in which case an internal heuristic is
 262 used to split the crate.
 263
 264 ## remark
 265
 266 This flag lets you print remarks for optimization passes.
 267
 268 The list of passes should be separated by spaces.
 269
 270 `all` will remark on every pass.
 271
 272 ## no-stack-check
 273
 274 This option is deprecated and does nothing.
 275
 276 ## debuginfo
 277
 278 This flag lets you control debug information:
 279
 280 * `0`: no debug info at all (default)
 281 * `1`: line tables only
 282 * `2`: full debug info
 283
 284 Note: The [`-g` flag][option-g-debug] is an alias for `-C debuginfo=2`.
 285
 286 ## opt-level
 287
 288 This flag lets you control the optimization level.
 289
 290 * `0`: no optimizations, also turns on [`cfg(debug_assertions)`](#debug-assertions).
 291 * `1`: basic optimizations
 292 * `2`: some optimizations
 293 * `3`: all optimizations
 294 * `s`: optimize for binary size
 295 * `z`: optimize for binary size, but also turn off loop vectorization.
 296
 297 Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`.
 298
 299 The default is `0`.
 300
 301 ## debug-assertions
 302
 303 This flag lets you turn `cfg(debug_assertions)` [conditional
 304 compilation](../../reference/conditional-compilation.md#debug_assertions) on
 305 or off. It takes one of the following values:
 306
 307 * `y`, `yes`, `on`, or no value: Enable debug-assertions.
 308 * `n`, `no`, or `off`: Disable debug-assertions.
 309
 310 If not specified, debug assertions are automatically enabled only if the
 311 [opt-level](#opt-level) is 0.
 312
 313 ## inline-threshold
 314
 315 This option lets you set the default threshold for inlining a function. It
 316 takes an unsigned integer as a value. Inlining is based on a cost model, where
 317 a higher threshold will allow more inlining.
 318
 319 The default depends on the [opt-level](#opt-level):
 320
 321 | opt-level | Threshold |
 322 |-----------|-----------|
 323 | 0         | N/A, only inlines always-inline functions |
 324 | 1         | N/A, only inlines always-inline functions and LLVM lifetime intrinsics |
 325 | 2         | 225 |
 326 | 3         | 275 |
 327 | s         | 75 |
 328 | z         | 25 |
 329
 330 ## panic
 331
 332 This option lets you control what happens when the code panics.
 333
 334 * `abort`: terminate the process upon panic
 335 * `unwind`: unwind the stack upon panic
 336
 337 If not specified, the default depends on the target.
 338
 339 ## incremental
 340
 341 This flag allows you to enable incremental compilation, which allows `rustc`
 342 to save information after compiling a crate to be reused when recompiling the
 343 crate, improving re-compile times. This takes a path to a directory where
 344 incremental files will be stored.
 345
 346 ## profile-generate
 347
 348 This flag allows for creating instrumented binaries that will collect
 349 profiling data for use with profile-guided optimization (PGO). The flag takes
 350 an optional argument which is the path to a directory into which the
 351 instrumented binary will emit the collected data. See the chapter on
 352 [profile-guided optimization] for more information.
 353
 354 ## profile-use
 355
 356 This flag specifies the profiling data file to be used for profile-guided
 357 optimization (PGO). The flag takes a mandatory argument which is the path
 358 to a valid `.profdata` file. See the chapter on
 359 [profile-guided optimization] for more information.
 360
 361 ## force-frame-pointers
 362
 363 This flag forces the use of frame pointers. It takes one of the following
 364 values:
 365
 366 * `y`, `yes`, `on`, or no value: Frame pointers are forced to be enabled.
 367 * `n`, `no`, or `off`: Frame pointers are not forced to be enabled. This does
 368   not necessarily mean frame pointers will be removed.
 369
 370 The default if not specified depends on the target.
 371
 372 ## default-linker-libraries
 373
 374 This flag controls whether or not the linker includes its default libraries.
 375 It takes one of the following values:
 376
 377 * `y`, `yes`, `on`, or no value: Default libraries are included.
 378 * `n`, `no`, or `off`: Default libraries are **not** included.
 379
 380 For example, for gcc flavor linkers, this issues the `-nodefaultlibs` flag to
 381 the linker.
 382
 383 The default is `yes` if not specified.
 384
 385 [option-emit]: ../command-line-arguments.md#option-emit
 386 [option-o-optimize]: ../command-line-arguments.md#option-o-optimize
 387 [profile-guided optimization]: ../profile-guided-optimization.md
 388 [option-g-debug]: ../command-line-arguments.md#option-g-debug