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.
  13
  14 ## link-arg=val
  15
  16 This flag lets you append a single extra argument to the linker invocation.
  17
  18 "Append" is significant; you can pass this flag multiple times to add multiple arguments.
  19
  20 ## link-args
  21
  22 This flag lets you append multiple extra arguments to the linker invocation. The
  23 options should be separated by spaces.
  24
  25 ## linker-flavor
  26
  27 This flag lets you control the linker flavor used by `rustc`. If a linker is given with the
  28 `-C linker` flag described above then the linker flavor is inferred from the value provided. If no
  29 linker is given then the linker flavor is used to determine the linker to use. Every `rustc` target
  30 defaults to some linker flavor.
  31
  32 ## link-dead-code
  33
  34 Normally, the linker will remove dead code. This flag disables this behavior.
  35
  36 An example of when this flag might be useful is when trying to construct code coverage
  37 metrics.
  38
  39 ## lto
  40
  41 This flag instructs LLVM to use [link time
  42 optimizations](https://llvm.org/docs/LinkTimeOptimization.html).
  43
  44 It takes one of two values, `thin` and `fat`. 'thin' LTO [is a new feature of
  45 LLVM](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html),
  46 'fat' referring to the classic version of LTO.
  47
  48 ## target-cpu
  49
  50 This instructs `rustc` to generate code specifically for a particular processor.
  51
  52 You can run `rustc --print target-cpus` to see the valid options to pass
  53 here. Additionally, `native` can be passed to use the processor of the host
  54 machine.
  55
  56 ## target-feature
  57
  58 Individual targets will support different features; this flag lets you control
  59 enabling or disabling a feature.
  60
  61 To see the valid options and an example of use, run `rustc --print
  62 target-features`.
  63
  64 ## passes
  65
  66 This flag can be used to add extra LLVM passes to the compilation.
  67
  68 The list must be separated by spaces.
  69
  70 ## llvm-args
  71
  72 This flag can be used to pass a list of arguments directly to LLVM.
  73
  74 The list must be separated by spaces.
  75
  76 ## save-temps
  77
  78 `rustc` will generate temporary files during compilation; normally it will
  79 delete them after it's done with its work. This option will cause them to be
  80 preserved instead of removed.
  81
  82 ## rpath
  83
  84 This option allows you to set the value of
  85 [`rpath`](https://en.wikipedia.org/wiki/Rpath).
  86
  87 ## overflow-checks
  88
  89 This flag allows you to control the behavior of integer overflow. This flag
  90 can be passed many options:
  91
  92 * To turn overflow checks on: `y`, `yes`, or `on`.
  93 * To turn overflow checks off: `n`, `no`, or `off`.
  94
  95 ## no-prepopulate-passes
  96
  97 The pass manager comes pre-populated with a list of passes; this flag
  98 ensures that list is empty.
  99
 100 ## no-vectorize-loops
 101
 102 By default, `rustc` will attempt to [vectorize
 103 loops](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer). This
 104 flag will turn that behavior off.
 105
 106 ## no-vectorize-slp
 107
 108 By default, `rustc` will attempt to vectorize loops using [superword-level
 109 parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer). This
 110 flag will turn that behavior off.
 111
 112 ## soft-float
 113
 114 This option will make `rustc` generate code using "soft floats." By default,
 115 a lot of hardware supports floating point instructions, and so the code generated
 116 will take advantage of this. "soft floats" emulate floating point instructions
 117 in software.
 118
 119 ## prefer-dynamic
 120
 121 By default, `rustc` prefers to statically link dependencies. This option will
 122 make it use dynamic linking instead.
 123
 124 ## no-integrated-as
 125
 126 LLVM comes with an internal assembler; this option will let you use an
 127 external assembler instead.
 128
 129 ## no-redzone
 130
 131 This flag allows you to disable [the
 132 red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). This flag can
 133 be passed many options:
 134
 135 * To enable the red zone: `y`, `yes`, or `on`.
 136 * To disable it: `n`, `no`, or `off`.
 137
 138 ## relocation-model
 139
 140 This option lets you choose which relocation model to use.
 141
 142 To find the valid options for this flag, run `rustc --print relocation-models`.
 143
 144 ## code-model=val
 145
 146 This option lets you choose which code model to use.
 147
 148 To find the valid options for this flag, run `rustc --print code-models`.
 149
 150 ## metadata
 151
 152 This option allows you to control the metadata used for symbol mangling.
 153
 154 ## extra-filename
 155
 156 This option allows you to put extra data in each output filename.
 157
 158 ## codegen-units
 159
 160 This flag lets you control how many threads are used when doing
 161 code generation.
 162
 163 Increasing parallelism may speed up compile times, but may also
 164 produce slower code.
 165
 166 ## remark
 167
 168 This flag lets you print remarks for these optimization passes.
 169
 170 The list of passes should be separated by spaces.
 171
 172 `all` will remark on every pass.
 173
 174 ## no-stack-check
 175
 176 This option is deprecated and does nothing.
 177
 178 ## debuginfo
 179
 180 This flag lets you control debug information:
 181
 182 * `0`: no debug info at all
 183 * `1`: line tables only
 184 * `2`: full debug info
 185
 186 ## opt-level
 187
 188 This flag lets you control the optimization level.
 189
 190 * `0`: no optimizations, also turn on `cfg(debug_assertions)`.
 191 * `1`: basic optimizations
 192 * `2`: some optimizations
 193 * `3`: all optimizations
 194 * `s`: optimize for binary size
 195 * `z`: optimize for binary size, but also turn off loop vectorization.
 196
 197 ## debug-assertions
 198
 199 This flag lets you turn `cfg(debug_assertions)` on or off.
 200
 201 ## inline-threshold
 202
 203 This option lets you set the threshold for inlining a function.
 204
 205 The default is 225.
 206
 207 ## panic
 208
 209 This option lets you control what happens when the code panics.
 210
 211 * `abort`: terminate the process upon panic
 212 * `unwind`: unwind the stack upon panic
 213
 214 ## incremental
 215
 216 This flag allows you to enable incremental compilation.
 217
 218 ## profile-generate
 219
 220 This flag allows for creating instrumented binaries that will collect
 221 profiling data for use with profile-guided optimization (PGO). The flag takes
 222 an optional argument which is the path to a directory into which the
 223 instrumented binary will emit the collected data. See the chapter on
 224 [profile-guided optimization] for more information.
 225
 226 ## profile-use
 227
 228 This flag specifies the profiling data file to be used for profile-guided
 229 optimization (PGO). The flag takes a mandatory argument which is the path
 230 to a valid `.profdata` file. See the chapter on
 231 [profile-guided optimization] for more information.
 232
 233 [profile-guided optimization]: ../profile-guided-optimization.md