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`.
8 This option is deprecated and does nothing.
12 This option lets you choose which code model to use. \
13 Code models put constraints on address ranges that the program and its symbols may use. \
14 With smaller address ranges machine instructions
15 may be able to use more compact addressing modes.
17 The specific ranges depend on target architectures and addressing modes available to them. \
18 For x86 more detailed description of its code models can be found in
19 [System V Application Binary Interface](https://github.com/hjl-tools/x86-psABI/wiki/x86-64-psABI-1.0.pdf)
22 Supported values for this option are:
24 - `tiny` - Tiny code model.
25 - `small` - Small code model. This is the default model for majority of supported targets.
26 - `kernel` - Kernel code model.
27 - `medium` - Medium code model.
28 - `large` - Large code model.
30 Supported values can also be discovered by running `rustc --print code-models`.
34 This flag controls how many code generation units the crate is split into. It
35 takes an integer greater than 0.
37 When a crate is split into multiple codegen units, LLVM is able to process
38 them in parallel. Increasing parallelism may speed up compile times, but may
39 also produce slower code. Setting this to 1 may improve the performance of
40 generated code, but may be slower to compile.
42 The default value, if not specified, is 16 for non-incremental builds. For
43 incremental builds the default is 256 which allows caching to be more granular.
47 This flag controls whether LLVM enables the Windows [Control Flow
48 Guard](https://docs.microsoft.com/en-us/windows/win32/secbp/control-flow-guard)
49 platform security feature. This flag is currently ignored for non-Windows targets.
50 It takes one of the following values:
52 * `y`, `yes`, `on`, `checks`, or no value: enable Control Flow Guard.
53 * `nochecks`: emit Control Flow Guard metadata without runtime enforcement checks (this
54 should only be used for testing purposes as it does not provide security enforcement).
55 * `n`, `no`, `off`: do not enable Control Flow Guard (the default).
59 This flag lets you turn `cfg(debug_assertions)` [conditional
60 compilation](../../reference/conditional-compilation.md#debug_assertions) on
61 or off. It takes one of the following values:
63 * `y`, `yes`, `on`, or no value: enable debug-assertions.
64 * `n`, `no`, or `off`: disable debug-assertions.
66 If not specified, debug assertions are automatically enabled only if the
67 [opt-level](#opt-level) is 0.
71 This flag controls the generation of debug information. It takes one of the
74 * `0`: no debug info at all (the default).
75 * `1`: line tables only.
76 * `2`: full debug info.
78 Note: The [`-g` flag][option-g-debug] is an alias for `-C debuginfo=2`.
80 ## default-linker-libraries
82 This flag controls whether or not the linker includes its default libraries.
83 It takes one of the following values:
85 * `y`, `yes`, `on`, or no value: include default libraries (the default).
86 * `n`, `no`, or `off`: exclude default libraries.
88 For example, for gcc flavor linkers, this issues the `-nodefaultlibs` flag to
93 This flag controls whether or not the compiler embeds LLVM bitcode into object
94 files. It takes one of the following values:
96 * `y`, `yes`, `on`, or no value: put bitcode in rlibs (the default).
97 * `n`, `no`, or `off`: omit bitcode from rlibs.
99 LLVM bitcode is required when rustc is performing link-time optimization (LTO).
100 It is also required on some targets like iOS ones where vendors look for LLVM
101 bitcode. Embedded bitcode will appear in rustc-generated object files inside of
102 a section whose name is defined by the target platform. Most of the time this is
105 The use of `-C embed-bitcode=no` can significantly improve compile times and
106 reduce generated file sizes if your compilation does not actually need bitcode
107 (e.g. if you're not compiling for iOS or you're not performing LTO). For these
108 reasons, Cargo uses `-C embed-bitcode=no` whenever possible. Likewise, if you
109 are building directly with `rustc` we recommend using `-C embed-bitcode=no`
110 whenever you are not using LTO.
112 If combined with `-C lto`, `-C embed-bitcode=no` will cause `rustc` to abort
113 at start-up, because the combination is invalid.
115 > **Note**: if you're building Rust code with LTO then you probably don't even
116 > need the `embed-bitcode` option turned on. You'll likely want to use
117 > `-Clinker-plugin-lto` instead which skips generating object files entirely and
118 > simply replaces object files with LLVM bitcode. The only purpose for
119 > `-Cembed-bitcode` is when you're generating an rlib that is both being used
120 > with and without LTO. For example Rust's standard library ships with embedded
121 > bitcode since users link to it both with and without LTO.
123 > This also may make you wonder why the default is `yes` for this option. The
124 > reason for that is that it's how it was for rustc 1.44 and prior. In 1.45 this
125 > option was added to turn off what had always been the default.
129 This option allows you to put extra data in each output filename. It takes a
130 string to add as a suffix to the filename. See the [`--emit`
131 flag][option-emit] for more information.
133 ## force-frame-pointers
135 This flag forces the use of frame pointers. It takes one of the following
138 * `y`, `yes`, `on`, or no value: force-enable frame pointers.
139 * `n`, `no`, or `off`: do not force-enable frame pointers. This does
140 not necessarily mean frame pointers will be removed.
142 The default behaviour, if frame pointers are not force-enabled, depends on the
145 ## force-unwind-tables
147 This flag forces the generation of unwind tables. It takes one of the following
150 * `y`, `yes`, `on`, or no value: Unwind tables are forced to be generated.
151 * `n`, `no`, or `off`: Unwind tables are not forced to be generated. If unwind
152 tables are required by the target or `-C panic=unwind`, an error will be
155 The default if not specified depends on the target.
159 This flag allows you to enable incremental compilation, which allows `rustc`
160 to save information after compiling a crate to be reused when recompiling the
161 crate, improving re-compile times. This takes a path to a directory where
162 incremental files will be stored.
166 This option lets you set the default threshold for inlining a function. It
167 takes an unsigned integer as a value. Inlining is based on a cost model, where
168 a higher threshold will allow more inlining.
170 The default depends on the [opt-level](#opt-level):
172 | opt-level | Threshold |
173 |-----------|-----------|
174 | 0 | N/A, only inlines always-inline functions |
175 | 1 | N/A, only inlines always-inline functions and LLVM lifetime intrinsics |
183 This flag lets you append a single extra argument to the linker invocation.
185 "Append" is significant; you can pass this flag multiple times to add multiple arguments.
189 This flag lets you append multiple extra arguments to the linker invocation. The
190 options should be separated by spaces.
194 This flag controls whether the linker will keep dead code. It takes one of
195 the following values:
197 * `y`, `yes`, `on`, or no value: keep dead code.
198 * `n`, `no`, or `off`: remove dead code (the default).
200 An example of when this flag might be useful is when trying to construct code coverage
203 ## link-self-contained
205 On targets that support it this flag controls whether the linker will use libraries and objects
206 shipped with Rust instead or those in the system.
207 It takes one of the following values:
209 * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
210 * `y`, `yes`, `on`: use only libraries/objects shipped with Rust.
211 * `n`, `no`, or `off`: rely on the user or the linker to provide non-Rust libraries/objects.
213 This allows overriding cases when detection fails or user wants to use shipped libraries.
217 This flag controls which linker `rustc` invokes to link your code. It takes a
218 path to the linker executable. If this flag is not specified, the linker will
219 be inferred based on the target. See also the [linker-flavor](#linker-flavor)
220 flag for another way to specify the linker.
224 This flag controls the linker flavor used by `rustc`. If a linker is given with
225 the [`-C linker` flag](#linker), then the linker flavor is inferred from the
226 value provided. If no linker is given then the linker flavor is used to
227 determine the linker to use. Every `rustc` target defaults to some linker
228 flavor. Valid options are:
230 * `em`: use [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html).
231 * `gcc`: use the `cc` executable, which is typically gcc or clang on many systems.
232 * `ld`: use the `ld` executable.
233 * `msvc`: use the `link.exe` executable from Microsoft Visual Studio MSVC.
235 [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia
237 * `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
238 executable, a port of LLVM `lld` for WebAssembly.
239 * `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin`
240 flag][lld-flavor] for Apple's `ld`.
241 * `ld.lld`: use the LLVM `lld` executable with the [`-flavor gnu`
242 flag][lld-flavor] for GNU binutils' `ld`.
243 * `lld-link`: use the LLVM `lld` executable with the [`-flavor link`
244 flag][lld-flavor] for Microsoft's `link.exe`.
246 [lld-flavor]: https://lld.llvm.org/Driver.html
250 This flag defers LTO optimizations to the linker. See
251 [linker-plugin-LTO](../linker-plugin-lto.md) for more details. It takes one of
252 the following values:
254 * `y`, `yes`, `on`, or no value: enable linker plugin LTO.
255 * `n`, `no`, or `off`: disable linker plugin LTO (the default).
256 * A path to the linker plugin.
258 More specifically this flag will cause the compiler to replace its typical
259 object file output with LLVM bitcode files. For example an rlib produced with
260 `-Clinker-plugin-lto` will still have `*.o` files in it, but they'll all be LLVM
261 bitcode instead of actual machine code. It is expected that the native platform
262 linker is capable of loading these LLVM bitcode files and generating code at
263 link time (typically after performing optimizations).
265 Note that rustc can also read its own object files produced with
266 `-Clinker-plugin-lto`. If an rlib is only ever going to get used later with a
267 `-Clto` compilation then you can pass `-Clinker-plugin-lto` to speed up
268 compilation and avoid generating object files that aren't used.
272 This flag can be used to pass a list of arguments directly to LLVM.
274 The list must be separated by spaces.
276 Pass `--help` to see a list of options.
280 This flag controls whether LLVM uses [link time
281 optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce
282 better optimized code, using whole-program analysis, at the cost of longer
283 linking time. It takes one of the following values:
285 * `y`, `yes`, `on`, `fat`, or no value: perform "fat" LTO which attempts to
286 perform optimizations across all crates within the dependency graph.
287 * `n`, `no`, `off`: disables LTO.
288 * `thin`: perform ["thin"
289 LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html).
290 This is similar to "fat", but takes substantially less time to run while
291 still achieving performance gains similar to "fat".
293 If `-C lto` is not specified, then the compiler will attempt to perform "thin
294 local LTO" which performs "thin" LTO on the local crate only across its
295 [codegen units](#codegen-units). When `-C lto` is not specified, LTO is
296 disabled if codegen units is 1 or optimizations are disabled ([`-C
297 opt-level=0`](#opt-level)). That is:
299 * When `-C lto` is not specified:
300 * `codegen-units=1`: disable LTO.
301 * `opt-level=0`: disable LTO.
302 * When `-C lto` is specified:
303 * `lto`: 16 codegen units, perform fat LTO across crates.
304 * `codegen-units=1` + `lto`: 1 codegen unit, fat LTO across crates.
306 See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO.
310 This option allows you to control the metadata used for symbol mangling. This
311 takes a space-separated list of strings. Mangled symbols will incorporate a
312 hash of the metadata. This may be used, for example, to differentiate symbols
313 between two different versions of the same crate being linked.
315 ## no-prepopulate-passes
317 This flag tells the pass manager to use an empty list of passes, instead of the
318 usual pre-populated list of passes.
322 This flag allows you to disable [the
323 red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). It takes one
324 of the following values:
326 * `y`, `yes`, `on`, or no value: disable the red zone.
327 * `n`, `no`, or `off`: enable the red zone.
329 The default behaviour, if the flag is not specified, depends on the target.
333 This option is deprecated and does nothing.
335 ## no-vectorize-loops
337 This flag disables [loop
338 vectorization](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer).
342 This flag disables vectorization using
344 parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer).
348 This flag controls the optimization level.
350 * `0`: no optimizations, also turns on
351 [`cfg(debug_assertions)`](#debug-assertions) (the default).
352 * `1`: basic optimizations.
353 * `2`: some optimizations.
354 * `3`: all optimizations.
355 * `s`: optimize for binary size.
356 * `z`: optimize for binary size, but also turn off loop vectorization.
358 Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`.
364 This flag allows you to control the behavior of [runtime integer
365 overflow](../../reference/expressions/operator-expr.md#overflow). When
366 overflow-checks are enabled, a panic will occur on overflow. This flag takes
367 one of the following values:
369 * `y`, `yes`, `on`, or no value: enable overflow checks.
370 * `n`, `no`, or `off`: disable overflow checks.
372 If not specified, overflow checks are enabled if
373 [debug-assertions](#debug-assertions) are enabled, disabled otherwise.
377 This option lets you control what happens when the code panics.
379 * `abort`: terminate the process upon panic
380 * `unwind`: unwind the stack upon panic
382 If not specified, the default depends on the target.
386 This flag can be used to add extra [LLVM
387 passes](http://llvm.org/docs/Passes.html) to the compilation.
389 The list must be separated by spaces.
391 See also the [`no-prepopulate-passes`](#no-prepopulate-passes) flag.
395 By default, `rustc` prefers to statically link dependencies. This option will
396 indicate that dynamic linking should be used if possible if both a static and
397 dynamic versions of a library are available. There is an internal algorithm
398 for determining whether or not it is possible to statically or dynamically
399 link with a dependency. For example, `cdylib` crate types may only use static
400 linkage. This flag takes one of the following values:
402 * `y`, `yes`, `on`, or no value: use dynamic linking.
403 * `n`, `no`, or `off`: use static linking (the default).
407 This flag allows for creating instrumented binaries that will collect
408 profiling data for use with profile-guided optimization (PGO). The flag takes
409 an optional argument which is the path to a directory into which the
410 instrumented binary will emit the collected data. See the chapter on
411 [profile-guided optimization] for more information.
415 This flag specifies the profiling data file to be used for profile-guided
416 optimization (PGO). The flag takes a mandatory argument which is the path
417 to a valid `.profdata` file. See the chapter on
418 [profile-guided optimization] for more information.
422 This option controls generation of
423 [position-independent code (PIC)](https://en.wikipedia.org/wiki/Position-independent_code).
425 Supported values for this option are:
427 #### Primary relocation models
429 - `static` - non-relocatable code, machine instructions may use absolute addressing modes.
431 - `pic` - fully relocatable position independent code,
432 machine instructions need to use relative addressing modes. \
433 Equivalent to the "uppercase" `-fPIC` or `-fPIE` options in other compilers,
434 depending on the produced crate types. \
435 This is the default model for majority of supported targets.
437 #### Special relocation models
439 - `dynamic-no-pic` - relocatable external references, non-relocatable code. \
440 Only makes sense on Darwin and is rarely used. \
441 If StackOverflow tells you to use this as an opt-out of PIC or PIE, don't believe it,
442 use `-C relocation-model=static` instead.
443 - `ropi`, `rwpi` and `ropi-rwpi` - relocatable code and read-only data, relocatable read-write data,
444 and combination of both, respectively. \
445 Only makes sense for certain embedded ARM targets.
446 - `default` - relocation model default to the current target. \
447 Only makes sense as an override for some other explicitly specified relocation model
448 previously set on the command line.
450 Supported values can also be discovered by running `rustc --print relocation-models`.
454 In addition to codegen effects, `relocation-model` has effects during linking.
456 If the relocation model is `pic` and the current target supports position-independent executables
457 (PIE), the linker will be instructed (`-pie`) to produce one. \
458 If the target doesn't support both position-independent and statically linked executables,
459 then `-C target-feature=+crt-static` "wins" over `-C relocation-model=pic`,
460 and the linker is instructed (`-static`) to produce a statically linked
461 but not position-independent executable.
465 This flag lets you print remarks for optimization passes.
467 The list of passes should be separated by spaces.
469 `all` will remark on every pass.
473 This flag controls whether [`rpath`](https://en.wikipedia.org/wiki/Rpath) is
474 enabled. It takes one of the following values:
476 * `y`, `yes`, `on`, or no value: enable rpath.
477 * `n`, `no`, or `off`: disable rpath (the default).
481 This flag controls whether temporary files generated during compilation are
482 deleted once compilation finishes. It takes one of the following values:
484 * `y`, `yes`, `on`, or no value: save temporary files.
485 * `n`, `no`, or `off`: delete temporary files (the default).
489 This option controls whether `rustc` generates code that emulates floating
490 point instructions in software. It takes one of the following values:
492 * `y`, `yes`, `on`, or no value: use soft floats.
493 * `n`, `no`, or `off`: use hardware floats (the default).
497 This option controls the emission of "split debuginfo" for debug information
498 that `rustc` generates. The default behavior of this option is
499 platform-specific, and not all possible values for this option work on all
500 platforms. Possible values are:
502 * `off` - This is the default for platforms with ELF binaries and windows-gnu
503 (not Windows MSVC and not macOS). This typically means that DWARF debug
504 information can be found in the final artifact in sections of the executable.
505 This option is not supported on Windows MSVC. On macOS this options prevents
506 the final execution of `dsymutil` to generate debuginfo.
508 * `packed` - This is the default for Windows MSVC and macOS. The term
509 "packed" here means that all the debug information is packed into a separate
510 file from the main executable. On Windows MSVC this is a `*.pdb` file, on
511 macOS this is a `*.dSYM` folder, and on other platforms this is a `*.dwp`
514 * `unpacked` - This means that debug information will be found in separate
515 files for each compilation unit (object file). This is not supported on
516 Windows MSVC. On macOS this means the original object files will contain
517 debug information. On other Unix platforms this means that `*.dwo` files will
518 contain debug information.
520 Note that `packed` and `unpacked` are gated behind `-Z unstable-options` on
521 non-macOS platforms at this time.
525 This instructs `rustc` to generate code specifically for a particular processor.
527 You can run `rustc --print target-cpus` to see the valid options to pass
528 here. Each target has a default base CPU. Special values include:
530 * `native` can be passed to use the processor of the host machine.
531 * `generic` refers to an LLVM target with minimal features but modern tuning.
535 Individual targets will support different features; this flag lets you control
536 enabling or disabling a feature. Each feature should be prefixed with a `+` to
537 enable it or `-` to disable it.
539 Features from multiple `-C target-feature` options are combined. \
540 Multiple features can be specified in a single option by separating them
541 with commas - `-C target-feature=+x,-y`. \
542 If some feature is specified more than once with both `+` and `-`,
543 then values passed later override values passed earlier. \
544 For example, `-C target-feature=+x,-y,+z -Ctarget-feature=-x,+y`
545 is equivalent to `-C target-feature=-x,+y,+z`.
547 To see the valid options and an example of use, run `rustc --print
550 Using this flag is unsafe and might result in [undefined runtime
551 behavior](../targets/known-issues.md).
553 See also the [`target_feature`
554 attribute](../../reference/attributes/codegen.md#the-target_feature-attribute)
555 for controlling features per-function.
557 This also supports the feature `+crt-static` and `-crt-static` to control
558 [static C runtime linkage](../../reference/linkage.html#static-and-dynamic-c-runtimes).
560 Each target and [`target-cpu`](#target-cpu) has a default set of enabled
565 This instructs `rustc` to schedule code specifically for a particular
566 processor. This does not affect the compatibility (instruction sets or ABI),
567 but should make your code slightly more efficient on the selected CPU.
569 The valid options are the same as those for [`target-cpu`](#target-cpu).
570 The default is `None`, which LLVM translates as the `target-cpu`.
572 This is an unstable option. Use `-Z tune-cpu=machine` to specify a value.
574 Due to limitations in LLVM (12.0.0-git9218f92), this option is currently
575 effective only for x86 targets.
577 [option-emit]: ../command-line-arguments.md#option-emit
578 [option-o-optimize]: ../command-line-arguments.md#option-o-optimize
579 [profile-guided optimization]: ../profile-guided-optimization.md
580 [option-g-debug]: ../command-line-arguments.md#option-g-debug