]>
Commit | Line | Data |
---|---|---|
83c7162d XL |
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 | ||
f9f354fc | 10 | ## code-model |
83c7162d | 11 | |
f9f354fc XL |
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 | |
3dfed10e | 15 | may be able to use more compact addressing modes. |
f9f354fc XL |
16 | |
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) | |
20 | specification. | |
21 | ||
22 | Supported values for this option are: | |
23 | ||
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. | |
29 | ||
30 | Supported values can also be discovered by running `rustc --print code-models`. | |
31 | ||
32 | ## codegen-units | |
33 | ||
34 | This flag controls how many code generation units the crate is split into. It | |
35 | takes an integer greater than 0. | |
36 | ||
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. | |
41 | ||
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. | |
44 | ||
3dfed10e XL |
45 | ## control-flow-guard |
46 | ||
1b1a35ee XL |
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. | |
3dfed10e XL |
50 | It takes one of the following values: |
51 | ||
52 | * `y`, `yes`, `on`, `checks`, or no value: enable Control Flow Guard. | |
1b1a35ee | 53 | * `nochecks`: emit Control Flow Guard metadata without runtime enforcement checks (this |
3dfed10e XL |
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). | |
56 | ||
f9f354fc XL |
57 | ## debug-assertions |
58 | ||
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: | |
62 | ||
63 | * `y`, `yes`, `on`, or no value: enable debug-assertions. | |
64 | * `n`, `no`, or `off`: disable debug-assertions. | |
65 | ||
66 | If not specified, debug assertions are automatically enabled only if the | |
67 | [opt-level](#opt-level) is 0. | |
68 | ||
69 | ## debuginfo | |
70 | ||
71 | This flag controls the generation of debug information. It takes one of the | |
72 | following values: | |
73 | ||
74 | * `0`: no debug info at all (the default). | |
75 | * `1`: line tables only. | |
76 | * `2`: full debug info. | |
77 | ||
78 | Note: The [`-g` flag][option-g-debug] is an alias for `-C debuginfo=2`. | |
79 | ||
80 | ## default-linker-libraries | |
81 | ||
82 | This flag controls whether or not the linker includes its default libraries. | |
83 | It takes one of the following values: | |
84 | ||
85 | * `y`, `yes`, `on`, or no value: include default libraries (the default). | |
86 | * `n`, `no`, or `off`: exclude default libraries. | |
87 | ||
88 | For example, for gcc flavor linkers, this issues the `-nodefaultlibs` flag to | |
89 | the linker. | |
90 | ||
91 | ## embed-bitcode | |
92 | ||
93 | This flag controls whether or not the compiler embeds LLVM bitcode into object | |
94 | files. It takes one of the following values: | |
95 | ||
96 | * `y`, `yes`, `on`, or no value: put bitcode in rlibs (the default). | |
97 | * `n`, `no`, or `off`: omit bitcode from rlibs. | |
98 | ||
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 | |
103 | `.llvmbc`. | |
104 | ||
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. | |
111 | ||
112 | If combined with `-C lto`, `-C embed-bitcode=no` will cause `rustc` to abort | |
113 | at start-up, because the combination is invalid. | |
114 | ||
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. | |
122 | > | |
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. | |
126 | ||
127 | ## extra-filename | |
128 | ||
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. | |
132 | ||
133 | ## force-frame-pointers | |
134 | ||
135 | This flag forces the use of frame pointers. It takes one of the following | |
136 | values: | |
137 | ||
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. | |
141 | ||
142 | The default behaviour, if frame pointers are not force-enabled, depends on the | |
143 | target. | |
144 | ||
145 | ## force-unwind-tables | |
146 | ||
147 | This flag forces the generation of unwind tables. It takes one of the following | |
148 | values: | |
149 | ||
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 | |
153 | emitted. | |
154 | ||
155 | The default if not specified depends on the target. | |
156 | ||
157 | ## incremental | |
158 | ||
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. | |
163 | ||
f20569fa XL |
164 | Note that this option currently does not take effect unless |
165 | `RUSTC_FORCE_INCREMENTAL=1` in the environment. | |
166 | ||
f9f354fc XL |
167 | ## inline-threshold |
168 | ||
169 | This option lets you set the default threshold for inlining a function. It | |
170 | takes an unsigned integer as a value. Inlining is based on a cost model, where | |
171 | a higher threshold will allow more inlining. | |
172 | ||
173 | The default depends on the [opt-level](#opt-level): | |
174 | ||
175 | | opt-level | Threshold | | |
176 | |-----------|-----------| | |
177 | | 0 | N/A, only inlines always-inline functions | | |
178 | | 1 | N/A, only inlines always-inline functions and LLVM lifetime intrinsics | | |
179 | | 2 | 225 | | |
180 | | 3 | 275 | | |
181 | | s | 75 | | |
182 | | z | 25 | | |
83c7162d | 183 | |
60c5eb7d | 184 | ## link-arg |
83c7162d XL |
185 | |
186 | This flag lets you append a single extra argument to the linker invocation. | |
187 | ||
188 | "Append" is significant; you can pass this flag multiple times to add multiple arguments. | |
189 | ||
190 | ## link-args | |
191 | ||
192 | This flag lets you append multiple extra arguments to the linker invocation. The | |
193 | options should be separated by spaces. | |
194 | ||
f9f354fc XL |
195 | ## link-dead-code |
196 | ||
197 | This flag controls whether the linker will keep dead code. It takes one of | |
198 | the following values: | |
199 | ||
200 | * `y`, `yes`, `on`, or no value: keep dead code. | |
201 | * `n`, `no`, or `off`: remove dead code (the default). | |
202 | ||
203 | An example of when this flag might be useful is when trying to construct code coverage | |
204 | metrics. | |
205 | ||
1b1a35ee XL |
206 | ## link-self-contained |
207 | ||
208 | On targets that support it this flag controls whether the linker will use libraries and objects | |
209 | shipped with Rust instead or those in the system. | |
210 | It takes one of the following values: | |
211 | ||
212 | * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools. | |
213 | * `y`, `yes`, `on`: use only libraries/objects shipped with Rust. | |
214 | * `n`, `no`, or `off`: rely on the user or the linker to provide non-Rust libraries/objects. | |
215 | ||
216 | This allows overriding cases when detection fails or user wants to use shipped libraries. | |
217 | ||
f9f354fc XL |
218 | ## linker |
219 | ||
220 | This flag controls which linker `rustc` invokes to link your code. It takes a | |
221 | path to the linker executable. If this flag is not specified, the linker will | |
222 | be inferred based on the target. See also the [linker-flavor](#linker-flavor) | |
223 | flag for another way to specify the linker. | |
224 | ||
0731742a XL |
225 | ## linker-flavor |
226 | ||
ba9703b0 XL |
227 | This flag controls the linker flavor used by `rustc`. If a linker is given with |
228 | the [`-C linker` flag](#linker), then the linker flavor is inferred from the | |
229 | value provided. If no linker is given then the linker flavor is used to | |
230 | determine the linker to use. Every `rustc` target defaults to some linker | |
231 | flavor. Valid options are: | |
232 | ||
233 | * `em`: use [Emscripten `emcc`](https://emscripten.org/docs/tools_reference/emcc.html). | |
234 | * `gcc`: use the `cc` executable, which is typically gcc or clang on many systems. | |
235 | * `ld`: use the `ld` executable. | |
236 | * `msvc`: use the `link.exe` executable from Microsoft Visual Studio MSVC. | |
237 | * `ptx-linker`: use | |
60c5eb7d XL |
238 | [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia |
239 | NVPTX GPGPU support. | |
ba9703b0 | 240 | * `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html) |
60c5eb7d | 241 | executable, a port of LLVM `lld` for WebAssembly. |
ba9703b0 | 242 | * `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin` |
60c5eb7d | 243 | flag][lld-flavor] for Apple's `ld`. |
ba9703b0 | 244 | * `ld.lld`: use the LLVM `lld` executable with the [`-flavor gnu` |
60c5eb7d | 245 | flag][lld-flavor] for GNU binutils' `ld`. |
ba9703b0 | 246 | * `lld-link`: use the LLVM `lld` executable with the [`-flavor link` |
60c5eb7d XL |
247 | flag][lld-flavor] for Microsoft's `link.exe`. |
248 | ||
249 | [lld-flavor]: https://lld.llvm.org/Driver.html | |
0731742a | 250 | |
f9f354fc | 251 | ## linker-plugin-lto |
83c7162d | 252 | |
f9f354fc XL |
253 | This flag defers LTO optimizations to the linker. See |
254 | [linker-plugin-LTO](../linker-plugin-lto.md) for more details. It takes one of | |
ba9703b0 XL |
255 | the following values: |
256 | ||
f9f354fc XL |
257 | * `y`, `yes`, `on`, or no value: enable linker plugin LTO. |
258 | * `n`, `no`, or `off`: disable linker plugin LTO (the default). | |
259 | * A path to the linker plugin. | |
83c7162d | 260 | |
f9f354fc XL |
261 | More specifically this flag will cause the compiler to replace its typical |
262 | object file output with LLVM bitcode files. For example an rlib produced with | |
263 | `-Clinker-plugin-lto` will still have `*.o` files in it, but they'll all be LLVM | |
264 | bitcode instead of actual machine code. It is expected that the native platform | |
265 | linker is capable of loading these LLVM bitcode files and generating code at | |
266 | link time (typically after performing optimizations). | |
267 | ||
268 | Note that rustc can also read its own object files produced with | |
269 | `-Clinker-plugin-lto`. If an rlib is only ever going to get used later with a | |
270 | `-Clto` compilation then you can pass `-Clinker-plugin-lto` to speed up | |
271 | compilation and avoid generating object files that aren't used. | |
272 | ||
273 | ## llvm-args | |
274 | ||
275 | This flag can be used to pass a list of arguments directly to LLVM. | |
276 | ||
277 | The list must be separated by spaces. | |
278 | ||
279 | Pass `--help` to see a list of options. | |
83c7162d XL |
280 | |
281 | ## lto | |
282 | ||
ba9703b0 | 283 | This flag controls whether LLVM uses [link time |
60c5eb7d XL |
284 | optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce |
285 | better optimized code, using whole-program analysis, at the cost of longer | |
ba9703b0 | 286 | linking time. It takes one of the following values: |
83c7162d | 287 | |
ba9703b0 | 288 | * `y`, `yes`, `on`, `fat`, or no value: perform "fat" LTO which attempts to |
60c5eb7d | 289 | perform optimizations across all crates within the dependency graph. |
ba9703b0 XL |
290 | * `n`, `no`, `off`: disables LTO. |
291 | * `thin`: perform ["thin" | |
60c5eb7d XL |
292 | LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html). |
293 | This is similar to "fat", but takes substantially less time to run while | |
294 | still achieving performance gains similar to "fat". | |
295 | ||
296 | If `-C lto` is not specified, then the compiler will attempt to perform "thin | |
297 | local LTO" which performs "thin" LTO on the local crate only across its | |
298 | [codegen units](#codegen-units). When `-C lto` is not specified, LTO is | |
299 | disabled if codegen units is 1 or optimizations are disabled ([`-C | |
300 | opt-level=0`](#opt-level)). That is: | |
301 | ||
302 | * When `-C lto` is not specified: | |
ba9703b0 XL |
303 | * `codegen-units=1`: disable LTO. |
304 | * `opt-level=0`: disable LTO. | |
6a06907d XL |
305 | * When `-C lto` is specified: |
306 | * `lto`: 16 codegen units, perform fat LTO across crates. | |
307 | * `codegen-units=1` + `lto`: 1 codegen unit, fat LTO across crates. | |
60c5eb7d XL |
308 | |
309 | See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO. | |
310 | ||
f9f354fc | 311 | ## metadata |
83c7162d | 312 | |
f9f354fc XL |
313 | This option allows you to control the metadata used for symbol mangling. This |
314 | takes a space-separated list of strings. Mangled symbols will incorporate a | |
315 | hash of the metadata. This may be used, for example, to differentiate symbols | |
316 | between two different versions of the same crate being linked. | |
60c5eb7d | 317 | |
f9f354fc | 318 | ## no-prepopulate-passes |
60c5eb7d | 319 | |
f9f354fc XL |
320 | This flag tells the pass manager to use an empty list of passes, instead of the |
321 | usual pre-populated list of passes. | |
60c5eb7d | 322 | |
f9f354fc | 323 | ## no-redzone |
e74abb32 | 324 | |
f9f354fc XL |
325 | This flag allows you to disable [the |
326 | red zone](https://en.wikipedia.org/wiki/Red_zone_\(computing\)). It takes one | |
327 | of the following values: | |
83c7162d | 328 | |
f9f354fc XL |
329 | * `y`, `yes`, `on`, or no value: disable the red zone. |
330 | * `n`, `no`, or `off`: enable the red zone. | |
83c7162d | 331 | |
f9f354fc | 332 | The default behaviour, if the flag is not specified, depends on the target. |
83c7162d | 333 | |
f9f354fc | 334 | ## no-stack-check |
60c5eb7d | 335 | |
f9f354fc | 336 | This option is deprecated and does nothing. |
83c7162d | 337 | |
f9f354fc | 338 | ## no-vectorize-loops |
83c7162d | 339 | |
f9f354fc XL |
340 | This flag disables [loop |
341 | vectorization](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer). | |
83c7162d | 342 | |
f9f354fc | 343 | ## no-vectorize-slp |
60c5eb7d | 344 | |
f9f354fc XL |
345 | This flag disables vectorization using |
346 | [superword-level | |
347 | parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer). | |
83c7162d | 348 | |
f9f354fc | 349 | ## opt-level |
ba9703b0 | 350 | |
f9f354fc | 351 | This flag controls the optimization level. |
83c7162d | 352 | |
f9f354fc XL |
353 | * `0`: no optimizations, also turns on |
354 | [`cfg(debug_assertions)`](#debug-assertions) (the default). | |
355 | * `1`: basic optimizations. | |
356 | * `2`: some optimizations. | |
357 | * `3`: all optimizations. | |
358 | * `s`: optimize for binary size. | |
359 | * `z`: optimize for binary size, but also turn off loop vectorization. | |
83c7162d | 360 | |
f9f354fc | 361 | Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`. |
ba9703b0 | 362 | |
f9f354fc | 363 | The default is `0`. |
83c7162d XL |
364 | |
365 | ## overflow-checks | |
366 | ||
60c5eb7d XL |
367 | This flag allows you to control the behavior of [runtime integer |
368 | overflow](../../reference/expressions/operator-expr.md#overflow). When | |
369 | overflow-checks are enabled, a panic will occur on overflow. This flag takes | |
370 | one of the following values: | |
83c7162d | 371 | |
ba9703b0 XL |
372 | * `y`, `yes`, `on`, or no value: enable overflow checks. |
373 | * `n`, `no`, or `off`: disable overflow checks. | |
60c5eb7d XL |
374 | |
375 | If not specified, overflow checks are enabled if | |
376 | [debug-assertions](#debug-assertions) are enabled, disabled otherwise. | |
83c7162d | 377 | |
f9f354fc | 378 | ## panic |
83c7162d | 379 | |
f9f354fc | 380 | This option lets you control what happens when the code panics. |
83c7162d | 381 | |
f9f354fc XL |
382 | * `abort`: terminate the process upon panic |
383 | * `unwind`: unwind the stack upon panic | |
83c7162d | 384 | |
f9f354fc | 385 | If not specified, the default depends on the target. |
83c7162d | 386 | |
f9f354fc | 387 | ## passes |
83c7162d | 388 | |
f9f354fc XL |
389 | This flag can be used to add extra [LLVM |
390 | passes](http://llvm.org/docs/Passes.html) to the compilation. | |
83c7162d | 391 | |
f9f354fc | 392 | The list must be separated by spaces. |
ba9703b0 | 393 | |
f9f354fc | 394 | See also the [`no-prepopulate-passes`](#no-prepopulate-passes) flag. |
83c7162d XL |
395 | |
396 | ## prefer-dynamic | |
397 | ||
398 | By default, `rustc` prefers to statically link dependencies. This option will | |
60c5eb7d XL |
399 | indicate that dynamic linking should be used if possible if both a static and |
400 | dynamic versions of a library are available. There is an internal algorithm | |
401 | for determining whether or not it is possible to statically or dynamically | |
402 | link with a dependency. For example, `cdylib` crate types may only use static | |
ba9703b0 | 403 | linkage. This flag takes one of the following values: |
83c7162d | 404 | |
ba9703b0 XL |
405 | * `y`, `yes`, `on`, or no value: use dynamic linking. |
406 | * `n`, `no`, or `off`: use static linking (the default). | |
83c7162d | 407 | |
f9f354fc | 408 | ## profile-generate |
83c7162d | 409 | |
f9f354fc XL |
410 | This flag allows for creating instrumented binaries that will collect |
411 | profiling data for use with profile-guided optimization (PGO). The flag takes | |
412 | an optional argument which is the path to a directory into which the | |
413 | instrumented binary will emit the collected data. See the chapter on | |
414 | [profile-guided optimization] for more information. | |
60c5eb7d | 415 | |
f9f354fc | 416 | ## profile-use |
83c7162d | 417 | |
f9f354fc XL |
418 | This flag specifies the profiling data file to be used for profile-guided |
419 | optimization (PGO). The flag takes a mandatory argument which is the path | |
420 | to a valid `.profdata` file. See the chapter on | |
421 | [profile-guided optimization] for more information. | |
83c7162d XL |
422 | |
423 | ## relocation-model | |
424 | ||
f9f354fc XL |
425 | This option controls generation of |
426 | [position-independent code (PIC)](https://en.wikipedia.org/wiki/Position-independent_code). | |
83c7162d | 427 | |
f9f354fc | 428 | Supported values for this option are: |
83c7162d | 429 | |
f9f354fc | 430 | #### Primary relocation models |
83c7162d | 431 | |
f9f354fc | 432 | - `static` - non-relocatable code, machine instructions may use absolute addressing modes. |
83c7162d | 433 | |
f9f354fc XL |
434 | - `pic` - fully relocatable position independent code, |
435 | machine instructions need to use relative addressing modes. \ | |
436 | Equivalent to the "uppercase" `-fPIC` or `-fPIE` options in other compilers, | |
437 | depending on the produced crate types. \ | |
438 | This is the default model for majority of supported targets. | |
83c7162d | 439 | |
f9f354fc | 440 | #### Special relocation models |
83c7162d | 441 | |
f9f354fc XL |
442 | - `dynamic-no-pic` - relocatable external references, non-relocatable code. \ |
443 | Only makes sense on Darwin and is rarely used. \ | |
444 | If StackOverflow tells you to use this as an opt-out of PIC or PIE, don't believe it, | |
445 | use `-C relocation-model=static` instead. | |
446 | - `ropi`, `rwpi` and `ropi-rwpi` - relocatable code and read-only data, relocatable read-write data, | |
447 | and combination of both, respectively. \ | |
448 | Only makes sense for certain embedded ARM targets. | |
449 | - `default` - relocation model default to the current target. \ | |
450 | Only makes sense as an override for some other explicitly specified relocation model | |
451 | previously set on the command line. | |
83c7162d | 452 | |
f9f354fc | 453 | Supported values can also be discovered by running `rustc --print relocation-models`. |
83c7162d | 454 | |
f9f354fc | 455 | #### Linking effects |
83c7162d | 456 | |
f9f354fc | 457 | In addition to codegen effects, `relocation-model` has effects during linking. |
83c7162d | 458 | |
f9f354fc XL |
459 | If the relocation model is `pic` and the current target supports position-independent executables |
460 | (PIE), the linker will be instructed (`-pie`) to produce one. \ | |
461 | If the target doesn't support both position-independent and statically linked executables, | |
462 | then `-C target-feature=+crt-static` "wins" over `-C relocation-model=pic`, | |
463 | and the linker is instructed (`-static`) to produce a statically linked | |
464 | but not position-independent executable. | |
83c7162d XL |
465 | |
466 | ## remark | |
467 | ||
60c5eb7d | 468 | This flag lets you print remarks for optimization passes. |
83c7162d XL |
469 | |
470 | The list of passes should be separated by spaces. | |
471 | ||
472 | `all` will remark on every pass. | |
473 | ||
f9f354fc | 474 | ## rpath |
60c5eb7d | 475 | |
f9f354fc XL |
476 | This flag controls whether [`rpath`](https://en.wikipedia.org/wiki/Rpath) is |
477 | enabled. It takes one of the following values: | |
83c7162d | 478 | |
f9f354fc XL |
479 | * `y`, `yes`, `on`, or no value: enable rpath. |
480 | * `n`, `no`, or `off`: disable rpath (the default). | |
83c7162d | 481 | |
f9f354fc | 482 | ## save-temps |
83c7162d | 483 | |
f9f354fc XL |
484 | This flag controls whether temporary files generated during compilation are |
485 | deleted once compilation finishes. It takes one of the following values: | |
83c7162d | 486 | |
f9f354fc XL |
487 | * `y`, `yes`, `on`, or no value: save temporary files. |
488 | * `n`, `no`, or `off`: delete temporary files (the default). | |
60c5eb7d | 489 | |
f9f354fc | 490 | ## soft-float |
83c7162d | 491 | |
f9f354fc XL |
492 | This option controls whether `rustc` generates code that emulates floating |
493 | point instructions in software. It takes one of the following values: | |
dc9dc135 | 494 | |
f9f354fc XL |
495 | * `y`, `yes`, `on`, or no value: use soft floats. |
496 | * `n`, `no`, or `off`: use hardware floats (the default). | |
dc9dc135 | 497 | |
5869c6ff XL |
498 | ## split-debuginfo |
499 | ||
500 | This option controls the emission of "split debuginfo" for debug information | |
501 | that `rustc` generates. The default behavior of this option is | |
502 | platform-specific, and not all possible values for this option work on all | |
503 | platform. Possible values are: | |
504 | ||
505 | * `off` - This is the default for platforms with ELF binaries and windows-gnu | |
506 | (not Windows MSVC and not macOS). This typically means that dwarf debug | |
507 | information can be found in the final artifact in sections of the executable. | |
508 | This option is not supported on Windows MSVC. On macOS this options prevents | |
509 | the final execution of `dsymutil` to generate debuginfo. | |
510 | ||
511 | * `packed` - This is the default for Windows MSVC and macOS platforms. The term | |
512 | "packed" here means that all the debug information is packed into a separate | |
513 | file from the main executable. On Windows MSVC this is a `*.pdb` file, on | |
514 | macOS this is a `*.dSYM` folder, and on other platforms this is a `*.dwp` | |
515 | files. | |
516 | ||
517 | * `unpacked` - This means that debug information will be found in separate | |
518 | files for each compilation unit (object file). This is not supported on | |
519 | Windows MSVC. On macOS this means the original object files will contain | |
520 | debug information. On other Unix platforms this means that `*.dwo` files will | |
521 | contain debug information. | |
522 | ||
523 | Note that `packed` and `unpacked` gated behind `-Zunstable-options` on | |
524 | non-macOS platforms at this time. | |
525 | ||
f9f354fc | 526 | ## target-cpu |
dc9dc135 | 527 | |
f9f354fc | 528 | This instructs `rustc` to generate code specifically for a particular processor. |
dc9dc135 | 529 | |
f9f354fc | 530 | You can run `rustc --print target-cpus` to see the valid options to pass |
29967ef6 XL |
531 | here. Each target has a default base CPU. Special values include: |
532 | ||
5869c6ff | 533 | * `native` can be passed to use the processor of the host machine. |
29967ef6 | 534 | * `generic` refers to an LLVM target with minimal features but modern tuning. |
416331ca | 535 | |
f9f354fc | 536 | ## target-feature |
60c5eb7d | 537 | |
f9f354fc XL |
538 | Individual targets will support different features; this flag lets you control |
539 | enabling or disabling a feature. Each feature should be prefixed with a `+` to | |
540 | enable it or `-` to disable it. | |
60c5eb7d | 541 | |
f9f354fc XL |
542 | Features from multiple `-C target-feature` options are combined. \ |
543 | Multiple features can be specified in a single option by separating them | |
544 | with commas - `-C target-feature=+x,-y`. \ | |
545 | If some feature is specified more than once with both `+` and `-`, | |
546 | then values passed later override values passed earlier. \ | |
547 | For example, `-C target-feature=+x,-y,+z -Ctarget-feature=-x,+y` | |
548 | is equivalent to `-C target-feature=-x,+y,+z`. | |
60c5eb7d | 549 | |
f9f354fc XL |
550 | To see the valid options and an example of use, run `rustc --print |
551 | target-features`. | |
60c5eb7d | 552 | |
f9f354fc XL |
553 | Using this flag is unsafe and might result in [undefined runtime |
554 | behavior](../targets/known-issues.md). | |
60c5eb7d | 555 | |
f9f354fc XL |
556 | See also the [`target_feature` |
557 | attribute](../../reference/attributes/codegen.md#the-target_feature-attribute) | |
558 | for controlling features per-function. | |
60c5eb7d | 559 | |
f9f354fc XL |
560 | This also supports the feature `+crt-static` and `-crt-static` to control |
561 | [static C runtime linkage](../../reference/linkage.html#static-and-dynamic-c-runtimes). | |
60c5eb7d | 562 | |
f9f354fc XL |
563 | Each target and [`target-cpu`](#target-cpu) has a default set of enabled |
564 | features. | |
60c5eb7d | 565 | |
29967ef6 XL |
566 | ## tune-cpu |
567 | ||
568 | This instructs `rustc` to schedule code specifically for a particular | |
569 | processor. This does not affect the compatibility (instruction sets or ABI), | |
570 | but should make your code slightly more efficient on the selected CPU. | |
571 | ||
572 | The valid options are the same as those for [`target-cpu`](#target-cpu). | |
573 | The default is `None`, which LLVM translates as the `target-cpu`. | |
574 | ||
575 | This is an unstable option. Use `-Z tune-cpu=machine` to specify a value. | |
576 | ||
577 | Due to limitations in LLVM (12.0.0-git9218f92), this option is currently | |
578 | effective only for x86 targets. | |
579 | ||
60c5eb7d XL |
580 | [option-emit]: ../command-line-arguments.md#option-emit |
581 | [option-o-optimize]: ../command-line-arguments.md#option-o-optimize | |
416331ca | 582 | [profile-guided optimization]: ../profile-guided-optimization.md |
60c5eb7d | 583 | [option-g-debug]: ../command-line-arguments.md#option-g-debug |