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 enable branch authentication instructions on AArch64.
13 This option is ignored for non-AArch64 architectures.
14 It takes some combination of the following values, separated by a `+`.
16 - `pac-ret` - Enable pointer authentication for non-leaf functions.
17 - `leaf` - Enable pointer authentication for all functions, including leaf functions.
18 - `b-key` - Sign return addresses with key B, instead of the default key A.
19 - `bti` - Enable branch target identification.
21 `leaf` and `b-key` are only valid if `pac-ret` was previously specified.
22 For example, `-C branch-protection=bti+pac-ret+leaf` is valid, but
23 `-C branch-protection=bti+leaf+pac-ret` is not.
25 Repeated values are ignored.
26 For example, `-C branch-protection=pac-ret+leaf+pac-ret` is equivalent to
27 `-C branch-protection=pac-ret+leaf`.
29 Rust's standard library does not ship with BTI or pointer authentication enabled by default. \
30 In Cargo projects the standard library can be recompiled with pointer authentication using the nightly
31 [build-std](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std) feature.
35 This option lets you choose which code model to use. \
36 Code models put constraints on address ranges that the program and its symbols may use. \
37 With smaller address ranges machine instructions
38 may be able to use more compact addressing modes.
40 The specific ranges depend on target architectures and addressing modes available to them. \
41 For x86 more detailed description of its code models can be found in
42 [System V Application Binary Interface](https://github.com/hjl-tools/x86-psABI/wiki/x86-64-psABI-1.0.pdf)
45 Supported values for this option are:
47 - `tiny` - Tiny code model.
48 - `small` - Small code model. This is the default model for majority of supported targets.
49 - `kernel` - Kernel code model.
50 - `medium` - Medium code model.
51 - `large` - Large code model.
53 Supported values can also be discovered by running `rustc --print code-models`.
57 This flag controls how many code generation units the crate is split into. It
58 takes an integer greater than 0.
60 When a crate is split into multiple codegen units, LLVM is able to process
61 them in parallel. Increasing parallelism may speed up compile times, but may
62 also produce slower code. Setting this to 1 may improve the performance of
63 generated code, but may be slower to compile.
65 The default value, if not specified, is 16 for non-incremental builds. For
66 incremental builds the default is 256 which allows caching to be more granular.
70 This flag controls whether LLVM enables the Windows [Control Flow
71 Guard](https://docs.microsoft.com/en-us/windows/win32/secbp/control-flow-guard)
72 platform security feature. This flag is currently ignored for non-Windows targets.
73 It takes one of the following values:
75 * `y`, `yes`, `on`, `checks`, or no value: enable Control Flow Guard.
76 * `nochecks`: emit Control Flow Guard metadata without runtime enforcement checks (this
77 should only be used for testing purposes as it does not provide security enforcement).
78 * `n`, `no`, `off`: do not enable Control Flow Guard (the default).
82 This flag lets you turn `cfg(debug_assertions)` [conditional
83 compilation](../../reference/conditional-compilation.md#debug_assertions) on
84 or off. It takes one of the following values:
86 * `y`, `yes`, `on`, or no value: enable debug-assertions.
87 * `n`, `no`, or `off`: disable debug-assertions.
89 If not specified, debug assertions are automatically enabled only if the
90 [opt-level](#opt-level) is 0.
94 This flag controls the generation of debug information. It takes one of the
97 * `0`: no debug info at all (the default).
98 * `1`: line tables only.
99 * `2`: full debug info.
101 Note: The [`-g` flag][option-g-debug] is an alias for `-C debuginfo=2`.
103 ## default-linker-libraries
105 This flag controls whether or not the linker includes its default libraries.
106 It takes one of the following values:
108 * `y`, `yes`, `on`, or no value: include default libraries (the default).
109 * `n`, `no`, or `off`: exclude default libraries.
111 For example, for gcc flavor linkers, this issues the `-nodefaultlibs` flag to
116 This flag controls whether or not the compiler embeds LLVM bitcode into object
117 files. It takes one of the following values:
119 * `y`, `yes`, `on`, or no value: put bitcode in rlibs (the default).
120 * `n`, `no`, or `off`: omit bitcode from rlibs.
122 LLVM bitcode is required when rustc is performing link-time optimization (LTO).
123 It is also required on some targets like iOS ones where vendors look for LLVM
124 bitcode. Embedded bitcode will appear in rustc-generated object files inside of
125 a section whose name is defined by the target platform. Most of the time this is
128 The use of `-C embed-bitcode=no` can significantly improve compile times and
129 reduce generated file sizes if your compilation does not actually need bitcode
130 (e.g. if you're not compiling for iOS or you're not performing LTO). For these
131 reasons, Cargo uses `-C embed-bitcode=no` whenever possible. Likewise, if you
132 are building directly with `rustc` we recommend using `-C embed-bitcode=no`
133 whenever you are not using LTO.
135 If combined with `-C lto`, `-C embed-bitcode=no` will cause `rustc` to abort
136 at start-up, because the combination is invalid.
138 > **Note**: if you're building Rust code with LTO then you probably don't even
139 > need the `embed-bitcode` option turned on. You'll likely want to use
140 > `-Clinker-plugin-lto` instead which skips generating object files entirely and
141 > simply replaces object files with LLVM bitcode. The only purpose for
142 > `-Cembed-bitcode` is when you're generating an rlib that is both being used
143 > with and without LTO. For example Rust's standard library ships with embedded
144 > bitcode since users link to it both with and without LTO.
146 > This also may make you wonder why the default is `yes` for this option. The
147 > reason for that is that it's how it was for rustc 1.44 and prior. In 1.45 this
148 > option was added to turn off what had always been the default.
152 This option allows you to put extra data in each output filename. It takes a
153 string to add as a suffix to the filename. See the [`--emit`
154 flag][option-emit] for more information.
156 ## force-frame-pointers
158 This flag forces the use of frame pointers. It takes one of the following
161 * `y`, `yes`, `on`, or no value: force-enable frame pointers.
162 * `n`, `no`, or `off`: do not force-enable frame pointers. This does
163 not necessarily mean frame pointers will be removed.
165 The default behaviour, if frame pointers are not force-enabled, depends on the
168 ## force-unwind-tables
170 This flag forces the generation of unwind tables. It takes one of the following
173 * `y`, `yes`, `on`, or no value: Unwind tables are forced to be generated.
174 * `n`, `no`, or `off`: Unwind tables are not forced to be generated. If unwind
175 tables are required by the target an error will be emitted.
177 The default if not specified depends on the target.
181 This flag allows you to enable incremental compilation, which allows `rustc`
182 to save information after compiling a crate to be reused when recompiling the
183 crate, improving re-compile times. This takes a path to a directory where
184 incremental files will be stored.
188 This option lets you set the default threshold for inlining a function. It
189 takes an unsigned integer as a value. Inlining is based on a cost model, where
190 a higher threshold will allow more inlining.
192 The default depends on the [opt-level](#opt-level):
194 | opt-level | Threshold |
195 |-----------|-----------|
196 | 0 | N/A, only inlines always-inline functions |
197 | 1 | N/A, only inlines always-inline functions and LLVM lifetime intrinsics |
205 This flag lets you append a single extra argument to the linker invocation.
207 "Append" is significant; you can pass this flag multiple times to add multiple arguments.
211 This flag lets you append multiple extra arguments to the linker invocation. The
212 options should be separated by spaces.
216 This flag controls whether the linker will keep dead code. It takes one of
217 the following values:
219 * `y`, `yes`, `on`, or no value: keep dead code.
220 * `n`, `no`, or `off`: remove dead code (the default).
222 An example of when this flag might be useful is when trying to construct code coverage
225 ## link-self-contained
227 On targets that support it this flag controls whether the linker will use libraries and objects
228 shipped with Rust instead or those in the system.
229 It takes one of the following values:
231 * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
232 * `y`, `yes`, `on`: use only libraries/objects shipped with Rust.
233 * `n`, `no`, or `off`: rely on the user or the linker to provide non-Rust libraries/objects.
235 This allows overriding cases when detection fails or user wants to use shipped libraries.
239 This flag controls which linker `rustc` invokes to link your code. It takes a
240 path to the linker executable. If this flag is not specified, the linker will
241 be inferred based on the target. See also the [linker-flavor](#linker-flavor)
242 flag for another way to specify the linker.
246 This flag controls the linker flavor used by `rustc`. If a linker is given with
247 the [`-C linker` flag](#linker), then the linker flavor is inferred from the
248 value provided. If no linker is given then the linker flavor is used to
249 determine the linker to use. Every `rustc` target defaults to some linker
250 flavor. Valid options are:
252 * `em`: use [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html).
253 * `gcc`: use the `cc` executable, which is typically gcc or clang on many systems.
254 * `ld`: use the `ld` executable.
255 * `msvc`: use the `link.exe` executable from Microsoft Visual Studio MSVC.
257 [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia
260 [`bpf-linker`](https://github.com/alessandrod/bpf-linker) for eBPF support.
261 * `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
262 executable, a port of LLVM `lld` for WebAssembly.
263 * `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin`
264 flag][lld-flavor] for Apple's `ld`.
265 * `ld.lld`: use the LLVM `lld` executable with the [`-flavor gnu`
266 flag][lld-flavor] for GNU binutils' `ld`.
267 * `lld-link`: use the LLVM `lld` executable with the [`-flavor link`
268 flag][lld-flavor] for Microsoft's `link.exe`.
270 [lld-flavor]: https://lld.llvm.org/Driver.html
274 This flag defers LTO optimizations to the linker. See
275 [linker-plugin-LTO](../linker-plugin-lto.md) for more details. It takes one of
276 the following values:
278 * `y`, `yes`, `on`, or no value: enable linker plugin LTO.
279 * `n`, `no`, or `off`: disable linker plugin LTO (the default).
280 * A path to the linker plugin.
282 More specifically this flag will cause the compiler to replace its typical
283 object file output with LLVM bitcode files. For example an rlib produced with
284 `-Clinker-plugin-lto` will still have `*.o` files in it, but they'll all be LLVM
285 bitcode instead of actual machine code. It is expected that the native platform
286 linker is capable of loading these LLVM bitcode files and generating code at
287 link time (typically after performing optimizations).
289 Note that rustc can also read its own object files produced with
290 `-Clinker-plugin-lto`. If an rlib is only ever going to get used later with a
291 `-Clto` compilation then you can pass `-Clinker-plugin-lto` to speed up
292 compilation and avoid generating object files that aren't used.
296 This flag can be used to pass a list of arguments directly to LLVM.
298 The list must be separated by spaces.
300 Pass `--help` to see a list of options.
304 This flag controls whether LLVM uses [link time
305 optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce
306 better optimized code, using whole-program analysis, at the cost of longer
307 linking time. It takes one of the following values:
309 * `y`, `yes`, `on`, `fat`, or no value: perform "fat" LTO which attempts to
310 perform optimizations across all crates within the dependency graph.
311 * `n`, `no`, `off`: disables LTO.
312 * `thin`: perform ["thin"
313 LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html).
314 This is similar to "fat", but takes substantially less time to run while
315 still achieving performance gains similar to "fat".
317 If `-C lto` is not specified, then the compiler will attempt to perform "thin
318 local LTO" which performs "thin" LTO on the local crate only across its
319 [codegen units](#codegen-units). When `-C lto` is not specified, LTO is
320 disabled if codegen units is 1 or optimizations are disabled ([`-C
321 opt-level=0`](#opt-level)). That is:
323 * When `-C lto` is not specified:
324 * `codegen-units=1`: disable LTO.
325 * `opt-level=0`: disable LTO.
326 * When `-C lto` is specified:
327 * `lto`: 16 codegen units, perform fat LTO across crates.
328 * `codegen-units=1` + `lto`: 1 codegen unit, fat LTO across crates.
330 See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO.
334 This option allows you to control the metadata used for symbol mangling. This
335 takes a space-separated list of strings. Mangled symbols will incorporate a
336 hash of the metadata. This may be used, for example, to differentiate symbols
337 between two different versions of the same crate being linked.
339 ## no-prepopulate-passes
341 This flag tells the pass manager to use an empty list of passes, instead of the
342 usual pre-populated list of passes.
346 This flag allows you to disable [the
347 red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). It takes one
348 of the following values:
350 * `y`, `yes`, `on`, or no value: disable the red zone.
351 * `n`, `no`, or `off`: enable the red zone.
353 The default behaviour, if the flag is not specified, depends on the target.
357 This option is deprecated and does nothing.
359 ## no-vectorize-loops
361 This flag disables [loop
362 vectorization](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer).
366 This flag disables vectorization using
368 parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer).
372 This flag controls the optimization level.
374 * `0`: no optimizations, also turns on
375 [`cfg(debug_assertions)`](#debug-assertions) (the default).
376 * `1`: basic optimizations.
377 * `2`: some optimizations.
378 * `3`: all optimizations.
379 * `s`: optimize for binary size.
380 * `z`: optimize for binary size, but also turn off loop vectorization.
382 Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`.
388 This flag allows you to control the behavior of [runtime integer
389 overflow](../../reference/expressions/operator-expr.md#overflow). When
390 overflow-checks are enabled, a panic will occur on overflow. This flag takes
391 one of the following values:
393 * `y`, `yes`, `on`, or no value: enable overflow checks.
394 * `n`, `no`, or `off`: disable overflow checks.
396 If not specified, overflow checks are enabled if
397 [debug-assertions](#debug-assertions) are enabled, disabled otherwise.
401 This option lets you control what happens when the code panics.
403 * `abort`: terminate the process upon panic
404 * `unwind`: unwind the stack upon panic
406 If not specified, the default depends on the target.
410 This flag can be used to add extra [LLVM
411 passes](http://llvm.org/docs/Passes.html) to the compilation.
413 The list must be separated by spaces.
415 See also the [`no-prepopulate-passes`](#no-prepopulate-passes) flag.
419 By default, `rustc` prefers to statically link dependencies. This option will
420 indicate that dynamic linking should be used if possible if both a static and
421 dynamic versions of a library are available. There is an internal algorithm
422 for determining whether or not it is possible to statically or dynamically
423 link with a dependency. For example, `cdylib` crate types may only use static
424 linkage. This flag takes one of the following values:
426 * `y`, `yes`, `on`, or no value: use dynamic linking.
427 * `n`, `no`, or `off`: use static linking (the default).
431 This flag allows for creating instrumented binaries that will collect
432 profiling data for use with profile-guided optimization (PGO). The flag takes
433 an optional argument which is the path to a directory into which the
434 instrumented binary will emit the collected data. See the chapter on
435 [profile-guided optimization] for more information.
439 This flag specifies the profiling data file to be used for profile-guided
440 optimization (PGO). The flag takes a mandatory argument which is the path
441 to a valid `.profdata` file. See the chapter on
442 [profile-guided optimization] for more information.
446 This option controls generation of
447 [position-independent code (PIC)](https://en.wikipedia.org/wiki/Position-independent_code).
449 Supported values for this option are:
451 #### Primary relocation models
453 - `static` - non-relocatable code, machine instructions may use absolute addressing modes.
455 - `pic` - fully relocatable position independent code,
456 machine instructions need to use relative addressing modes. \
457 Equivalent to the "uppercase" `-fPIC` or `-fPIE` options in other compilers,
458 depending on the produced crate types. \
459 This is the default model for majority of supported targets.
461 - `pie` - position independent executable, relocatable code but without support for symbol
462 interpositioning (replacing symbols by name using `LD_PRELOAD` and similar). Equivalent to the "uppercase" `-fPIE` option in other compilers. `pie`
463 code cannot be linked into shared libraries (you'll get a linking error on attempt to do this).
465 #### Special relocation models
467 - `dynamic-no-pic` - relocatable external references, non-relocatable code. \
468 Only makes sense on Darwin and is rarely used. \
469 If StackOverflow tells you to use this as an opt-out of PIC or PIE, don't believe it,
470 use `-C relocation-model=static` instead.
471 - `ropi`, `rwpi` and `ropi-rwpi` - relocatable code and read-only data, relocatable read-write data,
472 and combination of both, respectively. \
473 Only makes sense for certain embedded ARM targets.
474 - `default` - relocation model default to the current target. \
475 Only makes sense as an override for some other explicitly specified relocation model
476 previously set on the command line.
478 Supported values can also be discovered by running `rustc --print relocation-models`.
482 In addition to codegen effects, `relocation-model` has effects during linking.
484 If the relocation model is `pic` and the current target supports position-independent executables
485 (PIE), the linker will be instructed (`-pie`) to produce one. \
486 If the target doesn't support both position-independent and statically linked executables,
487 then `-C target-feature=+crt-static` "wins" over `-C relocation-model=pic`,
488 and the linker is instructed (`-static`) to produce a statically linked
489 but not position-independent executable.
493 This flag lets you print remarks for optimization passes.
495 The list of passes should be separated by spaces.
497 `all` will remark on every pass.
501 This flag controls whether [`rpath`](https://en.wikipedia.org/wiki/Rpath) is
502 enabled. It takes one of the following values:
504 * `y`, `yes`, `on`, or no value: enable rpath.
505 * `n`, `no`, or `off`: disable rpath (the default).
509 This flag controls whether temporary files generated during compilation are
510 deleted once compilation finishes. It takes one of the following values:
512 * `y`, `yes`, `on`, or no value: save temporary files.
513 * `n`, `no`, or `off`: delete temporary files (the default).
517 This option controls whether `rustc` generates code that emulates floating
518 point instructions in software. It takes one of the following values:
520 * `y`, `yes`, `on`, or no value: use soft floats.
521 * `n`, `no`, or `off`: use hardware floats (the default).
525 This option controls the emission of "split debuginfo" for debug information
526 that `rustc` generates. The default behavior of this option is
527 platform-specific, and not all possible values for this option work on all
528 platforms. Possible values are:
530 * `off` - This is the default for platforms with ELF binaries and windows-gnu
531 (not Windows MSVC and not macOS). This typically means that DWARF debug
532 information can be found in the final artifact in sections of the executable.
533 This option is not supported on Windows MSVC. On macOS this options prevents
534 the final execution of `dsymutil` to generate debuginfo.
536 * `packed` - This is the default for Windows MSVC and macOS. The term
537 "packed" here means that all the debug information is packed into a separate
538 file from the main executable. On Windows MSVC this is a `*.pdb` file, on
539 macOS this is a `*.dSYM` folder, and on other platforms this is a `*.dwp`
542 * `unpacked` - This means that debug information will be found in separate
543 files for each compilation unit (object file). This is not supported on
544 Windows MSVC. On macOS this means the original object files will contain
545 debug information. On other Unix platforms this means that `*.dwo` files will
546 contain debug information.
548 Note that `packed` and `unpacked` are gated behind `-Z unstable-options` on
549 non-macOS platforms at this time.
553 The option `-C strip=val` controls stripping of debuginfo and similar auxiliary
554 data from binaries during linking.
556 Supported values for this option are:
558 - `none` - debuginfo and symbols (if they exist) are copied to the produced
559 binary or separate files depending on the target (e.g. `.pdb` files in case
561 - `debuginfo` - debuginfo sections and debuginfo symbols from the symbol table
562 section are stripped at link time and are not copied to the produced binary
564 - `symbols` - same as `debuginfo`, but the rest of the symbol table section is
565 stripped as well if the linker supports it.
569 This instructs `rustc` to generate code specifically for a particular processor.
571 You can run `rustc --print target-cpus` to see the valid options to pass
572 here. Each target has a default base CPU. Special values include:
574 * `native` can be passed to use the processor of the host machine.
575 * `generic` refers to an LLVM target with minimal features but modern tuning.
579 Individual targets will support different features; this flag lets you control
580 enabling or disabling a feature. Each feature should be prefixed with a `+` to
581 enable it or `-` to disable it.
583 Features from multiple `-C target-feature` options are combined. \
584 Multiple features can be specified in a single option by separating them
585 with commas - `-C target-feature=+x,-y`. \
586 If some feature is specified more than once with both `+` and `-`,
587 then values passed later override values passed earlier. \
588 For example, `-C target-feature=+x,-y,+z -Ctarget-feature=-x,+y`
589 is equivalent to `-C target-feature=-x,+y,+z`.
591 To see the valid options and an example of use, run `rustc --print
594 Using this flag is unsafe and might result in [undefined runtime
595 behavior](../targets/known-issues.md).
597 See also the [`target_feature`
598 attribute](../../reference/attributes/codegen.md#the-target_feature-attribute)
599 for controlling features per-function.
601 This also supports the feature `+crt-static` and `-crt-static` to control
602 [static C runtime linkage](../../reference/linkage.html#static-and-dynamic-c-runtimes).
604 Each target and [`target-cpu`](#target-cpu) has a default set of enabled
609 This instructs `rustc` to schedule code specifically for a particular
610 processor. This does not affect the compatibility (instruction sets or ABI),
611 but should make your code slightly more efficient on the selected CPU.
613 The valid options are the same as those for [`target-cpu`](#target-cpu).
614 The default is `None`, which LLVM translates as the `target-cpu`.
616 This is an unstable option. Use `-Z tune-cpu=machine` to specify a value.
618 Due to limitations in LLVM (12.0.0-git9218f92), this option is currently
619 effective only for x86 targets.
621 [option-emit]: ../command-line-arguments.md#option-emit
622 [option-o-optimize]: ../command-line-arguments.md#option-o-optimize
623 [profile-guided optimization]: ../profile-guided-optimization.md
624 [option-g-debug]: ../command-line-arguments.md#option-g-debug