]>
Commit | Line | Data |
---|---|---|
923072b8 | 1 | # Codegen Options |
83c7162d XL |
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 | ||
9ffffee4 | 52 | * `y`, `yes`, `on`, `true`, `checks`, or no value: enable Control Flow Guard. |
1b1a35ee | 53 | * `nochecks`: emit Control Flow Guard metadata without runtime enforcement checks (this |
3dfed10e | 54 | should only be used for testing purposes as it does not provide security enforcement). |
9ffffee4 | 55 | * `n`, `no`, `off`, `false`: do not enable Control Flow Guard (the default). |
3dfed10e | 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 | ||
9ffffee4 FG |
63 | * `y`, `yes`, `on`, `true`, or no value: enable debug-assertions. |
64 | * `n`, `no`, `off` or `false`: disable debug-assertions. | |
f9f354fc XL |
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 | ||
9ffffee4 FG |
85 | * `y`, `yes`, `on`, `true` or no value: include default libraries (the default). |
86 | * `n`, `no`, `off` or `false`: exclude default libraries. | |
f9f354fc XL |
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 | ||
9ffffee4 FG |
96 | * `y`, `yes`, `on`, `true` or no value: put bitcode in rlibs (the default). |
97 | * `n`, `no`, `off` or `false`: omit bitcode from rlibs. | |
f9f354fc XL |
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 | ||
9ffffee4 FG |
138 | * `y`, `yes`, `on`, `true` or no value: force-enable frame pointers. |
139 | * `n`, `no`, `off` or `false`: do not force-enable frame pointers. This does | |
f9f354fc XL |
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 | ||
9ffffee4 FG |
150 | * `y`, `yes`, `on`, `true` or no value: Unwind tables are forced to be generated. |
151 | * `n`, `no`, `off` or `false`: Unwind tables are not forced to be generated. If unwind | |
17df50a5 | 152 | tables are required by the target an error will be emitted. |
f9f354fc XL |
153 | |
154 | The default if not specified depends on the target. | |
155 | ||
156 | ## incremental | |
157 | ||
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. | |
162 | ||
163 | ## inline-threshold | |
164 | ||
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. | |
168 | ||
169 | The default depends on the [opt-level](#opt-level): | |
170 | ||
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 | | |
175 | | 2 | 225 | | |
176 | | 3 | 275 | | |
177 | | s | 75 | | |
178 | | z | 25 | | |
83c7162d | 179 | |
5099ac24 FG |
180 | ## instrument-coverage |
181 | ||
182 | This option enables instrumentation-based code coverage support. See the | |
183 | chapter on [instrumentation-based code coverage] for more information. | |
184 | ||
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. | |
188 | ||
60c5eb7d | 189 | ## link-arg |
83c7162d XL |
190 | |
191 | This flag lets you append a single extra argument to the linker invocation. | |
192 | ||
193 | "Append" is significant; you can pass this flag multiple times to add multiple arguments. | |
194 | ||
195 | ## link-args | |
196 | ||
197 | This flag lets you append multiple extra arguments to the linker invocation. The | |
198 | options should be separated by spaces. | |
199 | ||
f9f354fc XL |
200 | ## link-dead-code |
201 | ||
202 | This flag controls whether the linker will keep dead code. It takes one of | |
203 | the following values: | |
204 | ||
9ffffee4 FG |
205 | * `y`, `yes`, `on`, `true` or no value: keep dead code. |
206 | * `n`, `no`, `off` or `false`: remove dead code (the default). | |
f9f354fc XL |
207 | |
208 | An example of when this flag might be useful is when trying to construct code coverage | |
209 | metrics. | |
210 | ||
1b1a35ee XL |
211 | ## link-self-contained |
212 | ||
487cf647 FG |
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. | |
1b1a35ee XL |
215 | It takes one of the following values: |
216 | ||
217 | * no value: rustc will use heuristic to disable self-contained mode if system has necessary tools. | |
9ffffee4 FG |
218 | * `y`, `yes`, `on`, `true`: use only libraries/objects shipped with Rust. |
219 | * `n`, `no`, `off` or `false`: rely on the user or the linker to provide non-Rust libraries/objects. | |
1b1a35ee XL |
220 | |
221 | This allows overriding cases when detection fails or user wants to use shipped libraries. | |
222 | ||
f9f354fc XL |
223 | ## linker |
224 | ||
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. | |
229 | ||
0731742a XL |
230 | ## linker-flavor |
231 | ||
ba9703b0 XL |
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: | |
237 | ||
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. | |
242 | * `ptx-linker`: use | |
60c5eb7d XL |
243 | [`rust-ptx-linker`](https://github.com/denzp/rust-ptx-linker) for Nvidia |
244 | NVPTX GPGPU support. | |
17df50a5 XL |
245 | * `bpf-linker`: use |
246 | [`bpf-linker`](https://github.com/alessandrod/bpf-linker) for eBPF support. | |
ba9703b0 | 247 | * `wasm-ld`: use the [`wasm-ld`](https://lld.llvm.org/WebAssembly.html) |
60c5eb7d | 248 | executable, a port of LLVM `lld` for WebAssembly. |
ba9703b0 | 249 | * `ld64.lld`: use the LLVM `lld` executable with the [`-flavor darwin` |
60c5eb7d | 250 | flag][lld-flavor] for Apple's `ld`. |
ba9703b0 | 251 | * `ld.lld`: use the LLVM `lld` executable with the [`-flavor gnu` |
60c5eb7d | 252 | flag][lld-flavor] for GNU binutils' `ld`. |
ba9703b0 | 253 | * `lld-link`: use the LLVM `lld` executable with the [`-flavor link` |
60c5eb7d XL |
254 | flag][lld-flavor] for Microsoft's `link.exe`. |
255 | ||
256 | [lld-flavor]: https://lld.llvm.org/Driver.html | |
0731742a | 257 | |
f9f354fc | 258 | ## linker-plugin-lto |
83c7162d | 259 | |
f9f354fc XL |
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 | |
ba9703b0 XL |
262 | the following values: |
263 | ||
9ffffee4 FG |
264 | * `y`, `yes`, `on`, `true` or no value: enable linker plugin LTO. |
265 | * `n`, `no`, `off` or `false`: disable linker plugin LTO (the default). | |
f9f354fc | 266 | * A path to the linker plugin. |
83c7162d | 267 | |
f9f354fc XL |
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). | |
274 | ||
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. | |
279 | ||
280 | ## llvm-args | |
281 | ||
282 | This flag can be used to pass a list of arguments directly to LLVM. | |
283 | ||
284 | The list must be separated by spaces. | |
285 | ||
286 | Pass `--help` to see a list of options. | |
83c7162d XL |
287 | |
288 | ## lto | |
289 | ||
ba9703b0 | 290 | This flag controls whether LLVM uses [link time |
60c5eb7d XL |
291 | optimizations](https://llvm.org/docs/LinkTimeOptimization.html) to produce |
292 | better optimized code, using whole-program analysis, at the cost of longer | |
ba9703b0 | 293 | linking time. It takes one of the following values: |
83c7162d | 294 | |
9ffffee4 | 295 | * `y`, `yes`, `on`, `true`, `fat`, or no value: perform "fat" LTO which attempts to |
60c5eb7d | 296 | perform optimizations across all crates within the dependency graph. |
9ffffee4 | 297 | * `n`, `no`, `off`, `false`: disables LTO. |
ba9703b0 | 298 | * `thin`: perform ["thin" |
60c5eb7d XL |
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". | |
302 | ||
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: | |
308 | ||
309 | * When `-C lto` is not specified: | |
ba9703b0 XL |
310 | * `codegen-units=1`: disable LTO. |
311 | * `opt-level=0`: disable LTO. | |
6a06907d XL |
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. | |
60c5eb7d XL |
315 | |
316 | See also [linker-plugin-lto](#linker-plugin-lto) for cross-language LTO. | |
317 | ||
f9f354fc | 318 | ## metadata |
83c7162d | 319 | |
f9f354fc XL |
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. | |
60c5eb7d | 324 | |
f9f354fc | 325 | ## no-prepopulate-passes |
60c5eb7d | 326 | |
f9f354fc XL |
327 | This flag tells the pass manager to use an empty list of passes, instead of the |
328 | usual pre-populated list of passes. | |
60c5eb7d | 329 | |
f9f354fc | 330 | ## no-redzone |
e74abb32 | 331 | |
f9f354fc XL |
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: | |
83c7162d | 335 | |
9ffffee4 FG |
336 | * `y`, `yes`, `on`, `true` or no value: disable the red zone. |
337 | * `n`, `no`, `off` or `false`: enable the red zone. | |
83c7162d | 338 | |
f9f354fc | 339 | The default behaviour, if the flag is not specified, depends on the target. |
83c7162d | 340 | |
f9f354fc | 341 | ## no-stack-check |
60c5eb7d | 342 | |
f9f354fc | 343 | This option is deprecated and does nothing. |
83c7162d | 344 | |
f9f354fc | 345 | ## no-vectorize-loops |
83c7162d | 346 | |
f9f354fc XL |
347 | This flag disables [loop |
348 | vectorization](https://llvm.org/docs/Vectorizers.html#the-loop-vectorizer). | |
83c7162d | 349 | |
f9f354fc | 350 | ## no-vectorize-slp |
60c5eb7d | 351 | |
f9f354fc XL |
352 | This flag disables vectorization using |
353 | [superword-level | |
354 | parallelism](https://llvm.org/docs/Vectorizers.html#the-slp-vectorizer). | |
83c7162d | 355 | |
f9f354fc | 356 | ## opt-level |
ba9703b0 | 357 | |
f9f354fc | 358 | This flag controls the optimization level. |
83c7162d | 359 | |
f9f354fc XL |
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. | |
83c7162d | 367 | |
f9f354fc | 368 | Note: The [`-O` flag][option-o-optimize] is an alias for `-C opt-level=2`. |
ba9703b0 | 369 | |
f9f354fc | 370 | The default is `0`. |
83c7162d XL |
371 | |
372 | ## overflow-checks | |
373 | ||
60c5eb7d XL |
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: | |
83c7162d | 378 | |
9ffffee4 FG |
379 | * `y`, `yes`, `on`, `true` or no value: enable overflow checks. |
380 | * `n`, `no`, `off` or `false`: disable overflow checks. | |
60c5eb7d XL |
381 | |
382 | If not specified, overflow checks are enabled if | |
383 | [debug-assertions](#debug-assertions) are enabled, disabled otherwise. | |
83c7162d | 384 | |
f9f354fc | 385 | ## panic |
83c7162d | 386 | |
f9f354fc | 387 | This option lets you control what happens when the code panics. |
83c7162d | 388 | |
f9f354fc XL |
389 | * `abort`: terminate the process upon panic |
390 | * `unwind`: unwind the stack upon panic | |
83c7162d | 391 | |
f9f354fc | 392 | If not specified, the default depends on the target. |
83c7162d | 393 | |
f9f354fc | 394 | ## passes |
83c7162d | 395 | |
f9f354fc XL |
396 | This flag can be used to add extra [LLVM |
397 | passes](http://llvm.org/docs/Passes.html) to the compilation. | |
83c7162d | 398 | |
f9f354fc | 399 | The list must be separated by spaces. |
ba9703b0 | 400 | |
f9f354fc | 401 | See also the [`no-prepopulate-passes`](#no-prepopulate-passes) flag. |
83c7162d XL |
402 | |
403 | ## prefer-dynamic | |
404 | ||
405 | By default, `rustc` prefers to statically link dependencies. This option will | |
60c5eb7d XL |
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 | |
ba9703b0 | 410 | linkage. This flag takes one of the following values: |
83c7162d | 411 | |
9ffffee4 FG |
412 | * `y`, `yes`, `on`, `true` or no value: use dynamic linking. |
413 | * `n`, `no`, `off` or `false`: use static linking (the default). | |
83c7162d | 414 | |
f9f354fc | 415 | ## profile-generate |
83c7162d | 416 | |
f9f354fc XL |
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. | |
60c5eb7d | 422 | |
f9f354fc | 423 | ## profile-use |
83c7162d | 424 | |
f9f354fc XL |
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. | |
83c7162d XL |
429 | |
430 | ## relocation-model | |
431 | ||
f9f354fc XL |
432 | This option controls generation of |
433 | [position-independent code (PIC)](https://en.wikipedia.org/wiki/Position-independent_code). | |
83c7162d | 434 | |
f9f354fc | 435 | Supported values for this option are: |
83c7162d | 436 | |
f9f354fc | 437 | #### Primary relocation models |
83c7162d | 438 | |
f9f354fc | 439 | - `static` - non-relocatable code, machine instructions may use absolute addressing modes. |
83c7162d | 440 | |
f9f354fc XL |
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. | |
83c7162d | 446 | |
c295e0f8 XL |
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). | |
450 | ||
f9f354fc | 451 | #### Special relocation models |
83c7162d | 452 | |
f9f354fc XL |
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. | |
83c7162d | 463 | |
f9f354fc | 464 | Supported values can also be discovered by running `rustc --print relocation-models`. |
83c7162d | 465 | |
f9f354fc | 466 | #### Linking effects |
83c7162d | 467 | |
f9f354fc | 468 | In addition to codegen effects, `relocation-model` has effects during linking. |
83c7162d | 469 | |
f9f354fc XL |
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. | |
83c7162d XL |
476 | |
477 | ## remark | |
478 | ||
60c5eb7d | 479 | This flag lets you print remarks for optimization passes. |
83c7162d XL |
480 | |
481 | The list of passes should be separated by spaces. | |
482 | ||
483 | `all` will remark on every pass. | |
484 | ||
f9f354fc | 485 | ## rpath |
60c5eb7d | 486 | |
f9f354fc XL |
487 | This flag controls whether [`rpath`](https://en.wikipedia.org/wiki/Rpath) is |
488 | enabled. It takes one of the following values: | |
83c7162d | 489 | |
9ffffee4 FG |
490 | * `y`, `yes`, `on`, `true` or no value: enable rpath. |
491 | * `n`, `no`, `off` or `false`: disable rpath (the default). | |
83c7162d | 492 | |
f9f354fc | 493 | ## save-temps |
83c7162d | 494 | |
f9f354fc XL |
495 | This flag controls whether temporary files generated during compilation are |
496 | deleted once compilation finishes. It takes one of the following values: | |
83c7162d | 497 | |
9ffffee4 FG |
498 | * `y`, `yes`, `on`, `true` or no value: save temporary files. |
499 | * `n`, `no`, `off` or `false`: delete temporary files (the default). | |
60c5eb7d | 500 | |
f9f354fc | 501 | ## soft-float |
83c7162d | 502 | |
f9f354fc XL |
503 | This option controls whether `rustc` generates code that emulates floating |
504 | point instructions in software. It takes one of the following values: | |
dc9dc135 | 505 | |
9ffffee4 FG |
506 | * `y`, `yes`, `on`, `true` or no value: use soft floats. |
507 | * `n`, `no`, `off` or `false`: use hardware floats (the default). | |
dc9dc135 | 508 | |
5869c6ff XL |
509 | ## split-debuginfo |
510 | ||
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 | |
cdc7bbd5 | 514 | platforms. Possible values are: |
5869c6ff XL |
515 | |
516 | * `off` - This is the default for platforms with ELF binaries and windows-gnu | |
cdc7bbd5 | 517 | (not Windows MSVC and not macOS). This typically means that DWARF debug |
5869c6ff XL |
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. | |
521 | ||
cdc7bbd5 | 522 | * `packed` - This is the default for Windows MSVC and macOS. The term |
5869c6ff XL |
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` | |
cdc7bbd5 | 526 | file. |
5869c6ff XL |
527 | |
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. | |
533 | ||
487cf647 FG |
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. | |
5869c6ff | 538 | |
3c0e092e XL |
539 | ## strip |
540 | ||
541 | The option `-C strip=val` controls stripping of debuginfo and similar auxiliary | |
542 | data from binaries during linking. | |
543 | ||
544 | Supported values for this option are: | |
545 | ||
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 | |
548 | of MSVC). | |
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 | |
551 | or separate files. | |
552 | - `symbols` - same as `debuginfo`, but the rest of the symbol table section is | |
553 | stripped as well if the linker supports it. | |
554 | ||
04454e1e FG |
555 | ## symbol-mangling-version |
556 | ||
557 | This option controls the [name mangling] format for encoding Rust item names | |
558 | for the purpose of generating object code and linking. | |
559 | ||
560 | Supported values for this option are: | |
561 | ||
562 | * `v0` — The "v0" mangling scheme. The specific format is not specified at | |
563 | this time. | |
564 | ||
9ffffee4 | 565 | The default, if not specified, will use a compiler-chosen default which may |
04454e1e FG |
566 | change in the future. |
567 | ||
568 | [name mangling]: https://en.wikipedia.org/wiki/Name_mangling | |
569 | ||
f9f354fc | 570 | ## target-cpu |
dc9dc135 | 571 | |
f9f354fc | 572 | This instructs `rustc` to generate code specifically for a particular processor. |
dc9dc135 | 573 | |
f9f354fc | 574 | You can run `rustc --print target-cpus` to see the valid options to pass |
29967ef6 XL |
575 | here. Each target has a default base CPU. Special values include: |
576 | ||
5869c6ff | 577 | * `native` can be passed to use the processor of the host machine. |
29967ef6 | 578 | * `generic` refers to an LLVM target with minimal features but modern tuning. |
416331ca | 579 | |
f9f354fc | 580 | ## target-feature |
60c5eb7d | 581 | |
f9f354fc XL |
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. | |
60c5eb7d | 585 | |
f9f354fc XL |
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`. | |
60c5eb7d | 593 | |
f9f354fc XL |
594 | To see the valid options and an example of use, run `rustc --print |
595 | target-features`. | |
60c5eb7d | 596 | |
f9f354fc XL |
597 | Using this flag is unsafe and might result in [undefined runtime |
598 | behavior](../targets/known-issues.md). | |
60c5eb7d | 599 | |
f9f354fc XL |
600 | See also the [`target_feature` |
601 | attribute](../../reference/attributes/codegen.md#the-target_feature-attribute) | |
602 | for controlling features per-function. | |
60c5eb7d | 603 | |
f9f354fc XL |
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). | |
60c5eb7d | 606 | |
f9f354fc XL |
607 | Each target and [`target-cpu`](#target-cpu) has a default set of enabled |
608 | features. | |
60c5eb7d | 609 | |
29967ef6 XL |
610 | ## tune-cpu |
611 | ||
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. | |
615 | ||
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`. | |
618 | ||
619 | This is an unstable option. Use `-Z tune-cpu=machine` to specify a value. | |
620 | ||
621 | Due to limitations in LLVM (12.0.0-git9218f92), this option is currently | |
622 | effective only for x86 targets. | |
623 | ||
60c5eb7d XL |
624 | [option-emit]: ../command-line-arguments.md#option-emit |
625 | [option-o-optimize]: ../command-line-arguments.md#option-o-optimize | |
5099ac24 | 626 | [instrumentation-based code coverage]: ../instrument-coverage.md |
416331ca | 627 | [profile-guided optimization]: ../profile-guided-optimization.md |
60c5eb7d | 628 | [option-g-debug]: ../command-line-arguments.md#option-g-debug |