1 # Command-line Arguments
3 Here's a list of command-line arguments to `rustc` and what they do.
5 <a id="option-help"></a>
6 ## `-h`/`--help`: get help
8 This flag will print out help information for `rustc`.
10 <a id="option-cfg"></a>
11 ## `--cfg`: configure the compilation environment
13 This flag can turn on or off various `#[cfg]` settings for [conditional
14 compilation](../reference/conditional-compilation.md).
16 The value can either be a single identifier or two identifiers separated by `=`.
18 For examples, `--cfg 'verbose'` or `--cfg 'feature="serde"'`. These correspond
19 to `#[cfg(verbose)]` and `#[cfg(feature = "serde")]` respectively.
21 <a id="option-l-search-path"></a>
22 ## `-L`: add a directory to the library search path
24 The `-L` flag adds a path to search for external crates and libraries.
26 The kind of search path can optionally be specified with the form `-L
27 KIND=PATH` where `KIND` may be one of:
29 - `dependency` — Only search for transitive dependencies in this directory.
30 - `crate` — Only search for this crate's direct dependencies in this
32 - `native` — Only search for native libraries in this directory.
33 - `framework` — Only search for macOS frameworks in this directory.
34 - `all` — Search for all library kinds in this directory. This is the default
35 if `KIND` is not specified.
37 <a id="option-l-link-lib"></a>
38 ## `-l`: link the generated crate to a native library
40 Syntax: `-l [KIND[:MODIFIERS]=]NAME[:RENAME]`.
42 This flag allows you to specify linking to a specific native library when building
45 The kind of library can optionally be specified with the form `-l KIND=lib`
46 where `KIND` may be one of:
48 - `dylib` — A native dynamic library.
49 - `static` — A native static library (such as a `.a` archive).
50 - `framework` — A macOS framework.
52 If the kind is specified, then linking modifiers can be attached to it.
53 Modifiers are specified as a comma-delimited string with each modifier prefixed with
54 either a `+` or `-` to indicate that the modifier is enabled or disabled, respectively.
55 Specifying multiple `modifiers` arguments in a single `link` attribute,
56 or multiple identical modifiers in the same `modifiers` argument is not currently supported. \
57 Example: `-l static:+whole-archive=mylib`.
59 The kind of library and the modifiers can also be specified in a [`#[link]`
60 attribute][link-attribute]. If the kind is not specified in the `link`
61 attribute or on the command-line, it will link a dynamic library if available,
62 otherwise it will use a static library. If the kind is specified on the
63 command-line, it will override the kind specified in a `link` attribute.
65 The name used in a `link` attribute may be overridden using the form `-l
66 ATTR_NAME:LINK_NAME` where `ATTR_NAME` is the name in the `link` attribute,
67 and `LINK_NAME` is the name of the actual library that will be linked.
69 [link-attribute]: ../reference/items/external-blocks.html#the-link-attribute
71 ### Linking modifiers: `whole-archive`
73 This modifier is only compatible with the `static` linking kind.
74 Using any other kind will result in a compiler error.
76 `+whole-archive` means that the static library is linked as a whole archive
77 without throwing any object files away.
79 This modifier translates to `--whole-archive` for `ld`-like linkers,
80 to `/WHOLEARCHIVE` for `link.exe`, and to `-force_load` for `ld64`.
81 The modifier does nothing for linkers that don't support it.
83 The default for this modifier is `-whole-archive`. \
84 NOTE: The default may currently be different in some cases for backward compatibility,
85 but it is not guaranteed. If you need whole archive semantics use `+whole-archive` explicitly.
87 ### Linking modifiers: `bundle`
89 This modifier is only compatible with the `static` linking kind.
90 Using any other kind will result in a compiler error.
92 When building a rlib or staticlib `+bundle` means that the native static library
93 will be packed into the rlib or staticlib archive, and then retrieved from there
94 during linking of the final binary.
96 When building a rlib `-bundle` means that the native static library is registered as a dependency
97 of that rlib "by name", and object files from it are included only during linking of the final
98 binary, the file search by that name is also performed during final linking. \
99 When building a staticlib `-bundle` means that the native static library is simply not included
100 into the archive and some higher level build system will need to add it later during linking of
103 This modifier has no effect when building other targets like executables or dynamic libraries.
105 The default for this modifier is `+bundle`.
107 <a id="option-crate-type"></a>
108 ## `--crate-type`: a list of types of crates for the compiler to emit
110 This instructs `rustc` on which crate type to build. This flag accepts a
111 comma-separated list of values, and may be specified multiple times. The valid
114 - `lib` — Generates a library kind preferred by the compiler, currently
116 - `rlib` — A Rust static library.
117 - `staticlib` — A native static library.
118 - `dylib` — A Rust dynamic library.
119 - `cdylib` — A native dynamic library.
120 - `bin` — A runnable executable program.
121 - `proc-macro` — Generates a format suitable for a procedural macro library
122 that may be loaded by the compiler.
124 The crate type may be specified with the [`crate_type` attribute][crate_type].
125 The `--crate-type` command-line value will override the `crate_type`
128 More details may be found in the [linkage chapter] of the reference.
130 [linkage chapter]: ../reference/linkage.html
131 [crate_type]: ../reference/linkage.html
133 <a id="option-crate-name"></a>
134 ## `--crate-name`: specify the name of the crate being built
136 This informs `rustc` of the name of your crate.
138 <a id="option-edition"></a>
139 ## `--edition`: specify the edition to use
141 This flag takes a value of `2015`, `2018` or `2021`. The default is `2015`. More
142 information about editions may be found in the [edition guide].
144 [edition guide]: ../edition-guide/introduction.html
146 <a id="option-emit"></a>
147 ## `--emit`: specifies the types of output files to generate
149 This flag controls the types of output files generated by the compiler. It
150 accepts a comma-separated list of values, and may be specified multiple times.
151 The valid emit kinds are:
153 - `asm` — Generates a file with the crate's assembly code. The default output
154 filename is `CRATE_NAME.s`.
155 - `dep-info` — Generates a file with Makefile syntax that indicates all the
156 source files that were loaded to generate the crate. The default output
157 filename is `CRATE_NAME.d`.
158 - `link` — Generates the crates specified by `--crate-type`. The default
159 output filenames depend on the crate type and platform. This is the default
160 if `--emit` is not specified.
161 - `llvm-bc` — Generates a binary file containing the [LLVM bitcode]. The
162 default output filename is `CRATE_NAME.bc`.
163 - `llvm-ir` — Generates a file containing [LLVM IR]. The default output
164 filename is `CRATE_NAME.ll`.
165 - `metadata` — Generates a file containing metadata about the crate. The
166 default output filename is `libCRATE_NAME.rmeta`.
167 - `mir` — Generates a file containing rustc's mid-level intermediate
168 representation. The default output filename is `CRATE_NAME.mir`.
169 - `obj` — Generates a native object file. The default output filename is
172 The output filename can be set with the [`-o` flag](#option-o-output). A
173 suffix may be added to the filename with the [`-C extra-filename`
174 flag](codegen-options/index.md#extra-filename). The files are written to the
175 current directory unless the [`--out-dir` flag](#option-out-dir) is used. Each
176 emission type may also specify the output filename with the form `KIND=PATH`,
177 which takes precedence over the `-o` flag.
179 [LLVM bitcode]: https://llvm.org/docs/BitCodeFormat.html
180 [LLVM IR]: https://llvm.org/docs/LangRef.html
182 <a id="option-print"></a>
183 ## `--print`: print compiler information
185 This flag prints out various information about the compiler. This flag may be
186 specified multiple times, and the information is printed in the order the
187 flags are specified. Specifying a `--print` flag will usually disable the
188 [`--emit`](#option-emit) step and will only print the requested information.
189 The valid types of print values are:
191 - `crate-name` — The name of the crate.
192 - `file-names` — The names of the files created by the `link` emit kind.
193 - `sysroot` — Path to the sysroot.
194 - `target-libdir` - Path to the target libdir.
195 - `cfg` — List of cfg values. See [conditional compilation] for more
196 information about cfg values.
197 - `target-list` — List of known targets. The target may be selected with the
199 - `target-cpus` — List of available CPU values for the current target. The
200 target CPU may be selected with the [`-C target-cpu=val`
201 flag](codegen-options/index.md#target-cpu).
202 - `target-features` — List of available target features for the current
203 target. Target features may be enabled with the [`-C target-feature=val`
204 flag](codegen-options/index.md#target-feature). This flag is unsafe. See
205 [known issues](targets/known-issues.md) for more details.
206 - `relocation-models` — List of relocation models. Relocation models may be
207 selected with the [`-C relocation-model=val`
208 flag](codegen-options/index.md#relocation-model).
209 - `code-models` — List of code models. Code models may be selected with the
210 [`-C code-model=val` flag](codegen-options/index.md#code-model).
211 - `tls-models` — List of Thread Local Storage models supported. The model may
212 be selected with the `-Z tls-model=val` flag.
213 - `native-static-libs` — This may be used when creating a `staticlib` crate
214 type. If this is the only flag, it will perform a full compilation and
215 include a diagnostic note that indicates the linker flags to use when
216 linking the resulting static library. The note starts with the text
217 `native-static-libs:` to make it easier to fetch the output.
218 - `link-args` — This flag does not disable the `--emit` step. When linking,
219 this flag causes `rustc` to print the full linker invocation in a
220 human-readable form. This can be useful when debugging linker options. The
221 exact format of this debugging output is not a stable guarantee, other than
222 that it will include the linker executable and the text of each command-line
223 argument passed to the linker.
225 [conditional compilation]: ../reference/conditional-compilation.html
227 <a id="option-g-debug"></a>
228 ## `-g`: include debug information
230 A synonym for [`-C debuginfo=2`](codegen-options/index.md#debuginfo).
232 <a id="option-o-optimize"></a>
233 ## `-O`: optimize your code
235 A synonym for [`-C opt-level=2`](codegen-options/index.md#opt-level).
237 <a id="option-o-output"></a>
238 ## `-o`: filename of the output
240 This flag controls the output filename.
242 <a id="option-out-dir"></a>
243 ## `--out-dir`: directory to write the output in
245 The outputted crate will be written to this directory. This flag is ignored if
246 the [`-o` flag](#option-o-output) is used.
248 <a id="option-explain"></a>
249 ## `--explain`: provide a detailed explanation of an error message
251 Each error of `rustc`'s comes with an error code; this will print
252 out a longer explanation of a given error.
254 <a id="option-test"></a>
255 ## `--test`: build a test harness
257 When compiling this crate, `rustc` will ignore your `main` function
258 and instead produce a test harness. See the [Tests chapter](tests/index.md)
259 for more information about tests.
261 <a id="option-target"></a>
262 ## `--target`: select a target triple to build
264 This controls which [target](targets/index.md) to produce.
266 <a id="option-w-warn"></a>
267 ## `-W`: set lint warnings
269 This flag will set which lints should be set to the [warn level](lints/levels.md#warn).
271 _Note:_ The order of these lint level arguments is taken into account, see [lint level via compiler flag](lints/levels.md#via-compiler-flag) for more information.
273 <a id="option-force-warn"></a>
274 ## `--force-warn`: force a lint to warn
276 This flag sets the given lint to the [forced warn level](lints/levels.md#force-warn) and the level cannot be overridden, even ignoring the [lint caps](lints/levels.md#capping-lints).
278 <a id="option-a-allow"></a>
279 ## `-A`: set lint allowed
281 This flag will set which lints should be set to the [allow level](lints/levels.md#allow).
283 _Note:_ The order of these lint level arguments is taken into account, see [lint level via compiler flag](lints/levels.md#via-compiler-flag) for more information.
285 <a id="option-d-deny"></a>
286 ## `-D`: set lint denied
288 This flag will set which lints should be set to the [deny level](lints/levels.md#deny).
290 _Note:_ The order of these lint level arguments is taken into account, see [lint level via compiler flag](lints/levels.md#via-compiler-flag) for more information.
292 <a id="option-f-forbid"></a>
293 ## `-F`: set lint forbidden
295 This flag will set which lints should be set to the [forbid level](lints/levels.md#forbid).
297 _Note:_ The order of these lint level arguments is taken into account, see [lint level via compiler flag](lints/levels.md#via-compiler-flag) for more information.
299 <a id="option-z-unstable"></a>
300 ## `-Z`: set unstable options
302 This flag will allow you to set unstable options of rustc. In order to set multiple options,
303 the -Z flag can be used multiple times. For example: `rustc -Z verbose -Z time-passes`.
304 Specifying options with -Z is only available on nightly. To view all available options
305 run: `rustc -Z help`, or see [The Unstable Book](../unstable-book/index.html).
307 <a id="option-cap-lints"></a>
308 ## `--cap-lints`: set the most restrictive lint level
310 This flag lets you 'cap' lints, for more, [see here](lints/levels.md#capping-lints).
312 <a id="option-codegen"></a>
313 ## `-C`/`--codegen`: code generation options
315 This flag will allow you to set [codegen options](codegen-options/index.md).
317 <a id="option-version"></a>
318 ## `-V`/`--version`: print a version
320 This flag will print out `rustc`'s version.
322 <a id="option-verbose"></a>
323 ## `-v`/`--verbose`: use verbose output
325 This flag, when combined with other flags, makes them produce extra output.
327 <a id="option-extern"></a>
328 ## `--extern`: specify where an external library is located
330 This flag allows you to pass the name and location for an external crate of a
331 direct dependency. Indirect dependencies (dependencies of dependencies) are
332 located using the [`-L` flag](#option-l-search-path). The given crate name is
333 added to the [extern prelude], similar to specifying `extern crate` within the
334 root module. The given crate name does not need to match the name
335 the library was built with.
337 Specifying `--extern` has one behavior difference from `extern crate`:
338 `--extern` merely makes the crate a _candidate_ for being linked; it does not
339 actually link it unless it's actively used. In rare occasions you may wish
340 to ensure a crate is linked even if you don't actively use it from your
341 code: for example, if it changes the global allocator or if it contains
342 `#[no_mangle]` symbols for use by other programming languages. In such
343 cases you'll need to use `extern crate`.
345 This flag may be specified multiple times. This flag takes an argument with
346 either of the following formats:
348 * `CRATENAME=PATH` — Indicates the given crate is found at the given path.
349 * `CRATENAME` — Indicates the given crate may be found in the search path,
350 such as within the sysroot or via the `-L` flag.
352 The same crate name may be specified multiple times for different crate types.
353 If both an `rlib` and `dylib` are found, an internal algorithm is used to
354 decide which to use for linking. The [`-C prefer-dynamic`
355 flag][prefer-dynamic] may be used to influence which is used.
357 If the same crate name is specified with and without a path, the one with the
358 path is used and the pathless flag has no effect.
360 [extern prelude]: ../reference/names/preludes.html#extern-prelude
361 [prefer-dynamic]: codegen-options/index.md#prefer-dynamic
363 <a id="option-sysroot"></a>
364 ## `--sysroot`: Override the system root
366 The "sysroot" is where `rustc` looks for the crates that come with the Rust
367 distribution; this flag allows that to be overridden.
369 <a id="option-error-format"></a>
370 ## `--error-format`: control how errors are produced
372 This flag lets you control the format of messages. Messages are printed to
373 stderr. The valid options are:
375 - `human` — Human-readable output. This is the default.
376 - `json` — Structured JSON output. See [the JSON chapter] for more detail.
377 - `short` — Short, one-line messages.
379 <a id="option-color"></a>
380 ## `--color`: configure coloring of output
382 This flag lets you control color settings of the output. The valid options
385 - `auto` — Use colors if output goes to a tty. This is the default.
386 - `always` — Always use colors.
387 - `never` — Never colorize output.
389 <a id="option-diagnostic-width"></a>
390 ## `--diagnostic-width`: specify the terminal width for diagnostics
392 This flag takes a number that specifies the width of the terminal in characters.
393 Formatting of diagnostics will take the width into consideration to make them better fit on the screen.
395 <a id="option-remap-path-prefix"></a>
396 ## `--remap-path-prefix`: remap source names in output
398 Remap source path prefixes in all output, including compiler diagnostics,
399 debug information, macro expansions, etc. It takes a value of the form
400 `FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`.
401 The `FROM` may itself contain an `=` symbol, but the `TO` value may not. This
402 flag may be specified multiple times.
404 This is useful for normalizing build products, for example by removing the
405 current directory out of pathnames emitted into the object files. The
406 replacement is purely textual, with no consideration of the current system's
407 pathname syntax. For example `--remap-path-prefix foo=bar` will match
408 `foo/lib.rs` but not `./foo/lib.rs`.
410 <a id="option-json"></a>
411 ## `--json`: configure json messages printed by the compiler
413 When the [`--error-format=json` option](#option-error-format) is passed to
414 rustc then all of the compiler's diagnostic output will be emitted in the form
415 of JSON blobs. The `--json` argument can be used in conjunction with
416 `--error-format=json` to configure what the JSON blobs contain as well as
417 which ones are emitted.
419 With `--error-format=json` the compiler will always emit any compiler errors as
420 a JSON blob, but the following options are also available to the `--json` flag
421 to customize the output:
423 - `diagnostic-short` - json blobs for diagnostic messages should use the "short"
424 rendering instead of the normal "human" default. This means that the output of
425 `--error-format=short` will be embedded into the JSON diagnostics instead of
426 the default `--error-format=human`.
428 - `diagnostic-rendered-ansi` - by default JSON blobs in their `rendered` field
429 will contain a plain text rendering of the diagnostic. This option instead
430 indicates that the diagnostic should have embedded ANSI color codes intended
431 to be used to colorize the message in the manner rustc typically already does
432 for terminal outputs. Note that this is usefully combined with crates like
433 [`fwdansi`](https://crates.io/crates/fwdansi) to translate these ANSI codes
434 on Windows to console commands or
435 [`strip-ansi-escapes`](https://crates.io/crates/strip-ansi-escapes) if you'd
436 like to optionally remove the ansi colors afterwards.
438 - `artifacts` - this instructs rustc to emit a JSON blob for each artifact that
439 is emitted. An artifact corresponds to a request from the [`--emit` CLI
440 argument](#option-emit), and as soon as the artifact is available on the
441 filesystem a notification will be emitted.
443 - `future-incompat` - includes a JSON message that contains a report if the
444 crate contains any code that may fail to compile in the future.
446 Note that it is invalid to combine the `--json` argument with the
447 [`--color`](#option-color) argument, and it is required to combine `--json`
448 with `--error-format=json`.
450 See [the JSON chapter] for more detail.
453 ## `@path`: load command-line flags from a path
455 If you specify `@path` on the command-line, then it will open `path` and read
456 command line options from it. These options are one per line; a blank line indicates
457 an empty option. The file can use Unix or Windows style line endings, and must be
460 [the JSON chapter]: json.md