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 an error will be emitted.
154 The default if not specified depends on the target.
158 This flag allows you to enable incremental compilation, which allows `rustc`
159 to save information after compiling a crate to be reused when recompiling the
160 crate, improving re-compile times. This takes a path to a directory where
161 incremental files will be stored.
165 This option lets you set the default threshold for inlining a function. It
166 takes an unsigned integer as a value. Inlining is based on a cost model, where
167 a higher threshold will allow more inlining.
169 The default depends on the [opt-level](#opt-level):
171 | opt-level | Threshold |
172 |-----------|-----------|
173 | 0 | N/A, only inlines always-inline functions |
174 | 1 | N/A, only inlines always-inline functions and LLVM lifetime intrinsics |
180 ## instrument-coverage
182 This option enables instrumentation-based code coverage support. See the
183 chapter on [instrumentation-based code coverage] for more information.
185 Note that while the `-C instrument-coverage` option is stable, the profile data
186 format produced by the resulting instrumentation may change, and may not work
187 with coverage tools other than those built and shipped with the compiler.
191 This flag lets you append a single extra argument to the linker invocation.
193 "Append" is significant; you can pass this flag multiple times to add multiple arguments.
197 This flag lets you append multiple extra arguments to the linker invocation. The
198 options should be separated by spaces.
202 This flag controls whether the linker will keep dead code. It takes one of
203 the following values:
205 * `y`, `yes`, `on`, or no value: keep dead code.
206 * `n`, `no`, or `off`: remove dead code (the default).
208 An example of when this flag might be useful is when trying to construct code coverage
211 ## link-self-contained
213 On `windows-gnu`, `linux-musl`, and `wasi` targets, this flag controls whether the
214 linker will use libraries and objects shipped with Rust instead or those in the system.
215 It takes one of the following values:
217 * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools.
218 * `y`, `yes`, `on`: use only libraries/objects shipped with Rust.
219 * `n`, `no`, or `off`: rely on the user or the linker to provide non-Rust libraries/objects.
221 This allows overriding cases when detection fails or user wants to use shipped libraries.
225 This flag controls which linker `rustc` invokes to link your code. It takes a
226 path to the linker executable. If this flag is not specified, the linker will
227 be inferred based on the target. See also the [linker-flavor](#linker-flavor)
228 flag for another way to specify the linker.
232 This flag controls the linker flavor used by `rustc`. If a linker is given with
233 the [`-C linker` flag](#linker), then the linker flavor is inferred from the
234 value provided. If no linker is given then the linker flavor is used to
235 determine the linker to use. Every `rustc` target defaults to some linker
236 flavor. Valid options are:
238 * `em`: use [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html).
239 * `gcc`: use the `cc` executable, which is typically gcc or clang on many systems.
240 * `ld`: use the `ld` executable.
241 * `msvc`: use the `link.exe` executable from Microsoft Visual Studio MSVC.
243 [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia
246 [`bpf-linker`](https://github.com/alessandrod/bpf-linker) for eBPF support.
247 * `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html)
248 executable, a port of LLVM `lld` for WebAssembly.
249 * `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin`
250 flag][lld-flavor] for Apple's `ld`.
251 * `ld.lld`: use the LLVM `lld` executable with the [`-flavor gnu`
252 flag][lld-flavor] for GNU binutils' `ld`.
253 * `lld-link`: use the LLVM `lld` executable with the [`-flavor link`
254 flag][lld-flavor] for Microsoft's `link.exe`.
256 [lld-flavor]: https://lld.llvm.org/Driver.html
260 This flag defers LTO optimizations to the linker. See
261 [linker-plugin-LTO](../linker-plugin-lto.md) for more details. It takes one of
262 the following values:
264 * `y`, `yes`, `on`, or no value: enable linker plugin LTO.
265 * `n`, `no`, or `off`: disable linker plugin LTO (the default).
266 * A path to the linker plugin.
268 More specifically this flag will cause the compiler to replace its typical
269 object file output with LLVM bitcode files. For example an rlib produced with
270 `-Clinker-plugin-lto` will still have `*.o` files in it, but they'll all be LLVM
271 bitcode instead of actual machine code. It is expected that the native platform
272 linker is capable of loading these LLVM bitcode files and generating code at
273 link time (typically after performing optimizations).
275 Note that rustc can also read its own object files produced with
276 `-Clinker-plugin-lto`. If an rlib is only ever going to get used later with a
277 `-Clto` compilation then you can pass `-Clinker-plugin-lto` to speed up
278 compilation and avoid generating object files that aren't used.
282 This flag can be used to pass a list of arguments directly to LLVM.
284 The list must be separated by spaces.
286 Pass `--help` to see a list of options.
290 This flag controls whether LLVM uses [link time
291 optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce
292 better optimized code, using whole-program analysis, at the cost of longer
293 linking time. It takes one of the following values:
295 * `y`, `yes`, `on`, `fat`, or no value: perform "fat" LTO which attempts to
296 perform optimizations across all crates within the dependency graph.
297 * `n`, `no`, `off`: disables LTO.
298 * `thin`: perform ["thin"
299 LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html).
300 This is similar to "fat", but takes substantially less time to run while
301 still achieving performance gains similar to "fat".
303 If `-C lto` is not specified, then the compiler will attempt to perform "thin
304 local LTO" which performs "thin" LTO on the local crate only across its
305 [codegen units](#codegen-units). When `-C lto` is not specified, LTO is
306 disabled if codegen units is 1 or optimizations are disabled ([`-C
307 opt-level=0`](#opt-level)). That is:
309 * When `-C lto` is not specified:
310 * `codegen-units=1`: disable LTO.
311 * `opt-level=0`: disable LTO.
312 * When `-C lto` is specified:
313 * `lto`: 16 codegen units, perform fat LTO across crates.
314 * `codegen-units=1` + `lto`: 1 codegen unit, fat LTO across crates.
316 See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO.
320 This option allows you to control the metadata used for symbol mangling. This
321 takes a space-separated list of strings. Mangled symbols will incorporate a
322 hash of the metadata. This may be used, for example, to differentiate symbols
323 between two different versions of the same crate being linked.
325 ## no-prepopulate-passes
327 This flag tells the pass manager to use an empty list of passes, instead of the
328 usual pre-populated list of passes.
332 This flag allows you to disable [the
333 red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). It takes one
334 of the following values:
336 * `y`, `yes`, `on`, or no value: disable the red zone.
337 * `n`, `no`, or `off`: enable the red zone.
339 The default behaviour, if the flag is not specified, depends on the target.
343 This option is deprecated and does nothing.
345 ## no-vectorize-loops
347 This flag disables [loop
348 vectorization](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer).
352 This flag disables vectorization using
354 parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer).
358 This flag controls the optimization level.
360 * `0`: no optimizations, also turns on
361 [`cfg(debug_assertions)`](#debug-assertions) (the default).
362 * `1`: basic optimizations.
363 * `2`: some optimizations.
364 * `3`: all optimizations.
365 * `s`: optimize for binary size.
366 * `z`: optimize for binary size, but also turn off loop vectorization.
368 Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`.
374 This flag allows you to control the behavior of [runtime integer
375 overflow](../../reference/expressions/operator-expr.md#overflow). When
376 overflow-checks are enabled, a panic will occur on overflow. This flag takes
377 one of the following values:
379 * `y`, `yes`, `on`, or no value: enable overflow checks.
380 * `n`, `no`, or `off`: disable overflow checks.
382 If not specified, overflow checks are enabled if
383 [debug-assertions](#debug-assertions) are enabled, disabled otherwise.
387 This option lets you control what happens when the code panics.
389 * `abort`: terminate the process upon panic
390 * `unwind`: unwind the stack upon panic
392 If not specified, the default depends on the target.
396 This flag can be used to add extra [LLVM
397 passes](http://llvm.org/docs/Passes.html) to the compilation.
399 The list must be separated by spaces.
401 See also the [`no-prepopulate-passes`](#no-prepopulate-passes) flag.
405 By default, `rustc` prefers to statically link dependencies. This option will
406 indicate that dynamic linking should be used if possible if both a static and
407 dynamic versions of a library are available. There is an internal algorithm
408 for determining whether or not it is possible to statically or dynamically
409 link with a dependency. For example, `cdylib` crate types may only use static
410 linkage. This flag takes one of the following values:
412 * `y`, `yes`, `on`, or no value: use dynamic linking.
413 * `n`, `no`, or `off`: use static linking (the default).
417 This flag allows for creating instrumented binaries that will collect
418 profiling data for use with profile-guided optimization (PGO). The flag takes
419 an optional argument which is the path to a directory into which the
420 instrumented binary will emit the collected data. See the chapter on
421 [profile-guided optimization] for more information.
425 This flag specifies the profiling data file to be used for profile-guided
426 optimization (PGO). The flag takes a mandatory argument which is the path
427 to a valid `.profdata` file. See the chapter on
428 [profile-guided optimization] for more information.
432 This option controls generation of
433 [position-independent code (PIC)](https://en.wikipedia.org/wiki/Position-independent_code).
435 Supported values for this option are:
437 #### Primary relocation models
439 - `static` - non-relocatable code, machine instructions may use absolute addressing modes.
441 - `pic` - fully relocatable position independent code,
442 machine instructions need to use relative addressing modes. \
443 Equivalent to the "uppercase" `-fPIC` or `-fPIE` options in other compilers,
444 depending on the produced crate types. \
445 This is the default model for majority of supported targets.
447 - `pie` - position independent executable, relocatable code but without support for symbol
448 interpositioning (replacing symbols by name using `LD_PRELOAD` and similar). Equivalent to the "uppercase" `-fPIE` option in other compilers. `pie`
449 code cannot be linked into shared libraries (you'll get a linking error on attempt to do this).
451 #### Special relocation models
453 - `dynamic-no-pic` - relocatable external references, non-relocatable code. \
454 Only makes sense on Darwin and is rarely used. \
455 If StackOverflow tells you to use this as an opt-out of PIC or PIE, don't believe it,
456 use `-C relocation-model=static` instead.
457 - `ropi`, `rwpi` and `ropi-rwpi` - relocatable code and read-only data, relocatable read-write data,
458 and combination of both, respectively. \
459 Only makes sense for certain embedded ARM targets.
460 - `default` - relocation model default to the current target. \
461 Only makes sense as an override for some other explicitly specified relocation model
462 previously set on the command line.
464 Supported values can also be discovered by running `rustc --print relocation-models`.
468 In addition to codegen effects, `relocation-model` has effects during linking.
470 If the relocation model is `pic` and the current target supports position-independent executables
471 (PIE), the linker will be instructed (`-pie`) to produce one. \
472 If the target doesn't support both position-independent and statically linked executables,
473 then `-C target-feature=+crt-static` "wins" over `-C relocation-model=pic`,
474 and the linker is instructed (`-static`) to produce a statically linked
475 but not position-independent executable.
479 This flag lets you print remarks for optimization passes.
481 The list of passes should be separated by spaces.
483 `all` will remark on every pass.
487 This flag controls whether [`rpath`](https://en.wikipedia.org/wiki/Rpath) is
488 enabled. It takes one of the following values:
490 * `y`, `yes`, `on`, or no value: enable rpath.
491 * `n`, `no`, or `off`: disable rpath (the default).
495 This flag controls whether temporary files generated during compilation are
496 deleted once compilation finishes. It takes one of the following values:
498 * `y`, `yes`, `on`, or no value: save temporary files.
499 * `n`, `no`, or `off`: delete temporary files (the default).
503 This option controls whether `rustc` generates code that emulates floating
504 point instructions in software. It takes one of the following values:
506 * `y`, `yes`, `on`, or no value: use soft floats.
507 * `n`, `no`, or `off`: use hardware floats (the default).
511 This option controls the emission of "split debuginfo" for debug information
512 that `rustc` generates. The default behavior of this option is
513 platform-specific, and not all possible values for this option work on all
514 platforms. Possible values are:
516 * `off` - This is the default for platforms with ELF binaries and windows-gnu
517 (not Windows MSVC and not macOS). This typically means that DWARF debug
518 information can be found in the final artifact in sections of the executable.
519 This option is not supported on Windows MSVC. On macOS this options prevents
520 the final execution of `dsymutil` to generate debuginfo.
522 * `packed` - This is the default for Windows MSVC and macOS. The term
523 "packed" here means that all the debug information is packed into a separate
524 file from the main executable. On Windows MSVC this is a `*.pdb` file, on
525 macOS this is a `*.dSYM` folder, and on other platforms this is a `*.dwp`
528 * `unpacked` - This means that debug information will be found in separate
529 files for each compilation unit (object file). This is not supported on
530 Windows MSVC. On macOS this means the original object files will contain
531 debug information. On other Unix platforms this means that `*.dwo` files will
532 contain debug information.
534 Note that all three options are supported on Linux and Apple platforms,
535 `packed` is supported on Windows-MSVC, and all other platforms support `off`.
536 Attempting to use an unsupported option requires using the nightly channel
537 with the `-Z unstable-options` flag.
541 The option `-C strip=val` controls stripping of debuginfo and similar auxiliary
542 data from binaries during linking.
544 Supported values for this option are:
546 - `none` - debuginfo and symbols (if they exist) are copied to the produced
547 binary or separate files depending on the target (e.g. `.pdb` files in case
549 - `debuginfo` - debuginfo sections and debuginfo symbols from the symbol table
550 section are stripped at link time and are not copied to the produced binary
552 - `symbols` - same as `debuginfo`, but the rest of the symbol table section is
553 stripped as well if the linker supports it.
555 ## symbol-mangling-version
557 This option controls the [name mangling] format for encoding Rust item names
558 for the purpose of generating object code and linking.
560 Supported values for this option are:
562 * `v0` — The "v0" mangling scheme. The specific format is not specified at
565 The default, if not specified, will use a compiler-chosen default which may
566 change in the future.
568 [name mangling]: https://en.wikipedia.org/wiki/Name_mangling
572 This instructs `rustc` to generate code specifically for a particular processor.
574 You can run `rustc --print target-cpus` to see the valid options to pass
575 here. Each target has a default base CPU. Special values include:
577 * `native` can be passed to use the processor of the host machine.
578 * `generic` refers to an LLVM target with minimal features but modern tuning.
582 Individual targets will support different features; this flag lets you control
583 enabling or disabling a feature. Each feature should be prefixed with a `+` to
584 enable it or `-` to disable it.
586 Features from multiple `-C target-feature` options are combined. \
587 Multiple features can be specified in a single option by separating them
588 with commas - `-C target-feature=+x,-y`. \
589 If some feature is specified more than once with both `+` and `-`,
590 then values passed later override values passed earlier. \
591 For example, `-C target-feature=+x,-y,+z -Ctarget-feature=-x,+y`
592 is equivalent to `-C target-feature=-x,+y,+z`.
594 To see the valid options and an example of use, run `rustc --print
597 Using this flag is unsafe and might result in [undefined runtime
598 behavior](../targets/known-issues.md).
600 See also the [`target_feature`
601 attribute](../../reference/attributes/codegen.md#the-target_feature-attribute)
602 for controlling features per-function.
604 This also supports the feature `+crt-static` and `-crt-static` to control
605 [static C runtime linkage](../../reference/linkage.html#static-and-dynamic-c-runtimes).
607 Each target and [`target-cpu`](#target-cpu) has a default set of enabled
612 This instructs `rustc` to schedule code specifically for a particular
613 processor. This does not affect the compatibility (instruction sets or ABI),
614 but should make your code slightly more efficient on the selected CPU.
616 The valid options are the same as those for [`target-cpu`](#target-cpu).
617 The default is `None`, which LLVM translates as the `target-cpu`.
619 This is an unstable option. Use `-Z tune-cpu=machine` to specify a value.
621 Due to limitations in LLVM (12.0.0-git9218f92), this option is currently
622 effective only for x86 targets.
624 [option-emit]: ../command-line-arguments.md#option-emit
625 [option-o-optimize]: ../command-line-arguments.md#option-o-optimize
626 [instrumentation-based code coverage]: ../instrument-coverage.md
627 [profile-guided optimization]: ../profile-guided-optimization.md
628 [option-g-debug]: ../command-line-arguments.md#option-g-debug