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 This flag allows you to specify linking to a specific native library when building
43 The kind of library can optionally be specified with the form `-l KIND=lib`
44 where `KIND` may be one of:
46 - `dylib` — A native dynamic library.
47 - `static` — A native static library (such as a `.a` archive).
48 - `framework` — A macOS framework.
50 The kind of library can be specified in a [`#[link]`
51 attribute][link-attribute]. If the kind is not specified in the `link`
52 attribute or on the command-line, it will link a dynamic library if available,
53 otherwise it will use a static library. If the kind is specified on the
54 command-line, it will override the kind specified in a `link` attribute.
56 The name used in a `link` attribute may be overridden using the form `-l
57 ATTR_NAME:LINK_NAME` where `ATTR_NAME` is the name in the `link` attribute,
58 and `LINK_NAME` is the name of the actual library that will be linked.
60 [link-attribute]: ../reference/items/external-blocks.html#the-link-attribute
62 <a id="option-crate-type"></a>
63 ## `--crate-type`: a list of types of crates for the compiler to emit
65 This instructs `rustc` on which crate type to build. This flag accepts a
66 comma-separated list of values, and may be specified multiple times. The valid
69 - `lib` — Generates a library kind preferred by the compiler, currently
71 - `rlib` — A Rust static library.
72 - `staticlib` — A native static library.
73 - `dylib` — A Rust dynamic library.
74 - `cdylib` — A native dynamic library.
75 - `bin` — A runnable executable program.
76 - `proc-macro` — Generates a format suitable for a procedural macro library
77 that may be loaded by the compiler.
79 The crate type may be specified with the [`crate_type` attribute][crate_type].
80 The `--crate-type` command-line value will override the `crate_type`
83 More details may be found in the [linkage chapter] of the reference.
85 [linkage chapter]: ../reference/linkage.html
86 [crate_type]: ../reference/linkage.html
88 <a id="option-crate-name"></a>
89 ## `--crate-name`: specify the name of the crate being built
91 This informs `rustc` of the name of your crate.
93 <a id="option-edition"></a>
94 ## `--edition`: specify the edition to use
96 This flag takes a value of `2015` or `2018`. The default is `2015`. More
97 information about editions may be found in the [edition guide].
99 [edition guide]: ../edition-guide/introduction.html
101 <a id="option-emit"></a>
102 ## `--emit`: specifies the types of output files to generate
104 This flag controls the types of output files generated by the compiler. It
105 accepts a comma-separated list of values, and may be specified multiple times.
106 The valid emit kinds are:
108 - `asm` — Generates a file with the crate's assembly code. The default output
109 filename is `CRATE_NAME.s`.
110 - `dep-info` — Generates a file with Makefile syntax that indicates all the
111 source files that were loaded to generate the crate. The default output
112 filename is `CRATE_NAME.d`.
113 - `link` — Generates the crates specified by `--crate-type`. The default
114 output filenames depend on the crate type and platform. This is the default
115 if `--emit` is not specified.
116 - `llvm-bc` — Generates a binary file containing the [LLVM bitcode]. The
117 default output filename is `CRATE_NAME.bc`.
118 - `llvm-ir` — Generates a file containing [LLVM IR]. The default output
119 filename is `CRATE_NAME.ll`.
120 - `metadata` — Generates a file containing metadata about the crate. The
121 default output filename is `CRATE_NAME.rmeta`.
122 - `mir` — Generates a file containing rustc's mid-level intermediate
123 representation. The default output filename is `CRATE_NAME.mir`.
124 - `obj` — Generates a native object file. The default output filename is
127 The output filename can be set with the [`-o` flag](#option-o-output). A
128 suffix may be added to the filename with the [`-C extra-filename`
129 flag](codegen-options/index.md#extra-filename). The files are written to the
130 current directory unless the [`--out-dir` flag](#option-out-dir) is used. Each
131 emission type may also specify the output filename with the form `KIND=PATH`,
132 which takes precedence over the `-o` flag.
134 [LLVM bitcode]: https://llvm.org/docs/BitCodeFormat.html
135 [LLVM IR]: https://llvm.org/docs/LangRef.html
137 <a id="option-print"></a>
138 ## `--print`: print compiler information
140 This flag prints out various information about the compiler. This flag may be
141 specified multiple times, and the information is printed in the order the
142 flags are specified. Specifying a `--print` flag will usually disable the
143 [`--emit`](#option-emit) step and will only print the requested information.
144 The valid types of print values are:
146 - `crate-name` — The name of the crate.
147 - `file-names` — The names of the files created by the `link` emit kind.
148 - `sysroot` — Path to the sysroot.
149 - `target-libdir` - Path to the target libdir.
150 - `cfg` — List of cfg values. See [conditional compilation] for more
151 information about cfg values.
152 - `target-list` — List of known targets. The target may be selected with the
154 - `target-cpus` — List of available CPU values for the current target. The
155 target CPU may be selected with the [`-C target-cpu=val`
156 flag](codegen-options/index.md#target-cpu).
157 - `target-features` — List of available target features for the current
158 target. Target features may be enabled with the [`-C target-feature=val`
159 flag](codegen-options/index.md#target-feature). This flag is unsafe. See
160 [known issues](targets/known-issues.md) for more details.
161 - `relocation-models` — List of relocation models. Relocation models may be
162 selected with the [`-C relocation-model=val`
163 flag](codegen-options/index.md#relocation-model).
164 - `code-models` — List of code models. Code models may be selected with the
165 [`-C code-model=val` flag](codegen-options/index.md#code-model).
166 - `tls-models` — List of Thread Local Storage models supported. The model may
167 be selected with the `-Z tls-model=val` flag.
168 - `native-static-libs` — This may be used when creating a `staticlib` crate
169 type. If this is the only flag, it will perform a full compilation and
170 include a diagnostic note that indicates the linker flags to use when
171 linking the resulting static library. The note starts with the text
172 `native-static-libs:` to make it easier to fetch the output.
174 [conditional compilation]: ../reference/conditional-compilation.html
176 <a id="option-g-debug"></a>
177 ## `-g`: include debug information
179 A synonym for [`-C debuginfo=2`](codegen-options/index.md#debuginfo).
181 <a id="option-o-optimize"></a>
182 ## `-O`: optimize your code
184 A synonym for [`-C opt-level=2`](codegen-options/index.md#opt-level).
186 <a id="option-o-output"></a>
187 ## `-o`: filename of the output
189 This flag controls the output filename.
191 <a id="option-out-dir"></a>
192 ## `--out-dir`: directory to write the output in
194 The outputted crate will be written to this directory. This flag is ignored if
195 the [`-o` flag](#option-o-output) is used.
197 <a id="option-explain"></a>
198 ## `--explain`: provide a detailed explanation of an error message
200 Each error of `rustc`'s comes with an error code; this will print
201 out a longer explanation of a given error.
203 <a id="option-test"></a>
204 ## `--test`: build a test harness
206 When compiling this crate, `rustc` will ignore your `main` function
207 and instead produce a test harness.
209 <a id="option-target"></a>
210 ## `--target`: select a target triple to build
212 This controls which [target](targets/index.md) to produce.
214 <a id="option-w-warn"></a>
215 ## `-W`: set lint warnings
217 This flag will set which lints should be set to the [warn level](lints/levels.md#warn).
219 _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.
221 <a id="option-a-allow"></a>
222 ## `-A`: set lint allowed
224 This flag will set which lints should be set to the [allow level](lints/levels.md#allow).
226 _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.
228 <a id="option-d-deny"></a>
229 ## `-D`: set lint denied
231 This flag will set which lints should be set to the [deny level](lints/levels.md#deny).
233 _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.
235 <a id="option-f-forbid"></a>
236 ## `-F`: set lint forbidden
238 This flag will set which lints should be set to the [forbid level](lints/levels.md#forbid).
240 _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.
242 <a id="option-z-unstable"></a>
243 ## `-Z`: set unstable options
245 This flag will allow you to set unstable options of rustc. In order to set multiple options,
246 the -Z flag can be used multiple times. For example: `rustc -Z verbose -Z time`.
247 Specifying options with -Z is only available on nightly. To view all available options
248 run: `rustc -Z help`.
250 <a id="option-cap-lints"></a>
251 ## `--cap-lints`: set the most restrictive lint level
253 This flag lets you 'cap' lints, for more, [see here](lints/levels.md#capping-lints).
255 <a id="option-codegen"></a>
256 ## `-C`/`--codegen`: code generation options
258 This flag will allow you to set [codegen options](codegen-options/index.md).
260 <a id="option-version"></a>
261 ## `-V`/`--version`: print a version
263 This flag will print out `rustc`'s version.
265 <a id="option-verbose"></a>
266 ## `-v`/`--verbose`: use verbose output
268 This flag, when combined with other flags, makes them produce extra output.
270 <a id="option-extern"></a>
271 ## `--extern`: specify where an external library is located
273 This flag allows you to pass the name and location for an external crate of a
274 direct dependency. Indirect dependencies (dependencies of dependencies) are
275 located using the [`-L` flag](#option-l-search-path). The given crate name is
276 added to the [extern prelude], which is the same as specifying `extern crate`
277 within the root module. The given crate name does not need to match the name
278 the library was built with.
280 This flag may be specified multiple times. This flag takes an argument with
281 either of the following formats:
283 * `CRATENAME=PATH` — Indicates the given crate is found at the given path.
284 * `CRATENAME` — Indicates the given crate may be found in the search path,
285 such as within the sysroot or via the `-L` flag.
287 The same crate name may be specified multiple times for different crate types.
288 If both an `rlib` and `dylib` are found, an internal algorithm is used to
289 decide which to use for linking. The [`-C prefer-dynamic`
290 flag][prefer-dynamic] may be used to influence which is used.
292 If the same crate name is specified with and without a path, the one with the
293 path is used and the pathless flag has no effect.
295 [extern prelude]: ../reference/items/extern-crates.html#extern-prelude
296 [prefer-dynamic]: codegen-options/index.md#prefer-dynamic
298 <a id="option-sysroot"></a>
299 ## `--sysroot`: Override the system root
301 The "sysroot" is where `rustc` looks for the crates that come with the Rust
302 distribution; this flag allows that to be overridden.
304 <a id="option-error-format"></a>
305 ## `--error-format`: control how errors are produced
307 This flag lets you control the format of messages. Messages are printed to
308 stderr. The valid options are:
310 - `human` — Human-readable output. This is the default.
311 - `json` — Structured JSON output. See [the JSON chapter] for more detail.
312 - `short` — Short, one-line messages.
314 <a id="option-color"></a>
315 ## `--color`: configure coloring of output
317 This flag lets you control color settings of the output. The valid options
320 - `auto` — Use colors if output goes to a tty. This is the default.
321 - `always` — Always use colors.
322 - `never` — Never colorize output.
324 <a id="option-remap-path-prefix"></a>
325 ## `--remap-path-prefix`: remap source names in output
327 Remap source path prefixes in all output, including compiler diagnostics,
328 debug information, macro expansions, etc. It takes a value of the form
329 `FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`.
330 The `FROM` may itself contain an `=` symbol, but the `TO` value may not. This
331 flag may be specified multiple times.
333 This is useful for normalizing build products, for example by removing the
334 current directory out of pathnames emitted into the object files. The
335 replacement is purely textual, with no consideration of the current system's
336 pathname syntax. For example `--remap-path-prefix foo=bar` will match
337 `foo/lib.rs` but not `./foo/lib.rs`.
339 <a id="option-json"></a>
340 ## `--json`: configure json messages printed by the compiler
342 When the [`--error-format=json` option](#option-error-format) is passed to
343 rustc then all of the compiler's diagnostic output will be emitted in the form
344 of JSON blobs. The `--json` argument can be used in conjunction with
345 `--error-format=json` to configure what the JSON blobs contain as well as
346 which ones are emitted.
348 With `--error-format=json` the compiler will always emit any compiler errors as
349 a JSON blob, but the following options are also available to the `--json` flag
350 to customize the output:
352 - `diagnostic-short` - json blobs for diagnostic messages should use the "short"
353 rendering instead of the normal "human" default. This means that the output of
354 `--error-format=short` will be embedded into the JSON diagnostics instead of
355 the default `--error-format=human`.
357 - `diagnostic-rendered-ansi` - by default JSON blobs in their `rendered` field
358 will contain a plain text rendering of the diagnostic. This option instead
359 indicates that the diagnostic should have embedded ANSI color codes intended
360 to be used to colorize the message in the manner rustc typically already does
361 for terminal outputs. Note that this is usefully combined with crates like
362 [`fwdansi`](https://crates.io/crates/fwdansi) to translate these ANSI codes
363 on Windows to console commands or
364 [`strip-ansi-escapes`](https://crates.io/crates/strip-ansi-escapes) if you'd
365 like to optionally remove the ansi colors afterwards.
367 - `artifacts` - this instructs rustc to emit a JSON blob for each artifact that
368 is emitted. An artifact corresponds to a request from the [`--emit` CLI
369 argument](#option-emit), and as soon as the artifact is available on the
370 filesystem a notification will be emitted.
372 Note that it is invalid to combine the `--json` argument with the
373 [`--color`](#option-color) argument, and it is required to combine `--json`
374 with `--error-format=json`.
376 See [the JSON chapter] for more detail.
379 ## `@path`: load command-line flags from a path
381 If you specify `@path` on the command-line, then it will open `path` and read
382 command line options from it. These options are one per line; a blank line indicates
383 an empty option. The file can use Unix or Windows style line endings, and must be
386 [the JSON chapter]: json.md