src/doc/rustc/src/command-line-arguments.md

   1 # Command-line arguments
   2
   3 Here's a list of command-line arguments to `rustc` and what they do.
   4
   5 ## `-h`/`--help`: get help
   6
   7 This flag will print out help information for `rustc`.
   8
   9 ## `--cfg`: configure the compilation environment
  10
  11 This flag can turn on or off various `#[cfg]` settings.
  12
  13 The value can either be a single identifier or two identifiers separated by `=`.
  14
  15 For examples, `--cfg 'verbose'` or `--cfg 'feature="serde"'`. These correspond
  16 to `#[cfg(verbose)]` and `#[cfg(feature = "serde")]` respectively.
  17
  18 ## `-L`: add a directory to the library search path
  19
  20 When looking for external crates or libraries, a directory passed to this flag
  21 will be searched.
  22
  23 The kind of search path can optionally be specified with the form `-L
  24 KIND=PATH` where `KIND` may be one of:
  25
  26 - `dependency` — Only search for transitive dependencies in this directory.
  27 - `crate` — Only search for this crate's direct dependencies in this
  28   directory.
  29 - `native` — Only search for native libraries in this directory.
  30 - `framework` — Only search for macOS frameworks in this directory.
  31 - `all` — Search for all library kinds in this directory. This is the default
  32   if `KIND` is not specified.
  33
  34 ## `-l`: link the generated crate to a native library
  35
  36 This flag allows you to specify linking to a specific native library when building
  37 a crate.
  38
  39 The kind of library can optionally be specified with the form `-l KIND=lib`
  40 where `KIND` may be one of:
  41
  42 - `dylib` — A native dynamic library.
  43 - `static` — A native static library (such as a `.a` archive).
  44 - `framework` — A macOS framework.
  45
  46 The kind of library can be specified in a [`#[link]`
  47 attribute][link-attribute]. If the kind is not specified in the `link`
  48 attribute or on the command-line, it will link a dynamic library if available,
  49 otherwise it will use a static library. If the kind is specified on the
  50 command-line, it will override the kind specified in a `link` attribute.
  51
  52 The name used in a `link` attribute may be overridden using the form `-l
  53 ATTR_NAME:LINK_NAME` where `ATTR_NAME` is the name in the `link` attribute,
  54 and `LINK_NAME` is the name of the actual library that will be linked.
  55
  56 [link-attribute]: ../reference/items/external-blocks.html#the-link-attribute
  57
  58 ## `--crate-type`: a list of types of crates for the compiler to emit
  59
  60 This instructs `rustc` on which crate type to build. This flag accepts a
  61 comma-separated list of values, and may be specified multiple times. The valid
  62 crate types are:
  63
  64 - `lib` — Generates a library kind preferred by the compiler, currently
  65   defaults to `rlib`.
  66 - `rlib` — A Rust static library.
  67 - `staticlib` — A native static library.
  68 - `dylib` — A Rust dynamic library.
  69 - `cdylib` — A native dynamic library.
  70 - `bin` — A runnable executable program.
  71 - `proc-macro` — Generates a format suitable for a procedural macro library
  72   that may be loaded by the compiler.
  73
  74 The crate type may be specified with the [`crate_type` attribute][crate_type].
  75 The `--crate-type` command-line value will override the `crate_type`
  76 attribute.
  77
  78 More details may be found in the [linkage chapter] of the reference.
  79
  80 [linkage chapter]: ../reference/linkage.html
  81 [crate_type]: ../reference/linkage.html
  82
  83 ## `--crate-name`: specify the name of the crate being built
  84
  85 This informs `rustc` of the name of your crate.
  86
  87 ## `--edition`: specify the edition to use
  88
  89 This flag takes a value of `2015` or `2018`. The default is `2015`. More
  90 information about editions may be found in the [edition guide].
  91
  92 [edition guide]: ../edition-guide/introduction.html
  93
  94 ## `--emit`: specifies the types of output files to generate
  95  <a id="option-emit"></a>
  96
  97 This flag controls the types of output files generated by the compiler. It
  98 accepts a comma-separated list of values, and may be specified multiple times.
  99 The valid emit kinds are:
 100
 101 - `asm` — Generates a file with the crate's assembly code. The default output
 102   filename is `CRATE_NAME.s`.
 103 - `dep-info` — Generates a file with Makefile syntax that indicates all the
 104   source files that were loaded to generate the crate. The default output
 105   filename is `CRATE_NAME.d`.
 106 - `link` — Generates the crates specified by `--crate-type`. The default
 107   output filenames depend on the crate type and platform. This is the default
 108   if `--emit` is not specified.
 109 - `llvm-bc` — Generates a binary file containing the [LLVM bitcode]. The
 110   default output filename is `CRATE_NAME.bc`.
 111 - `llvm-ir` — Generates a file containing [LLVM IR]. The default output
 112   filename is `CRATE_NAME.ll`.
 113 - `metadata` — Generates a file containing metadata about the crate. The
 114   default output filename is `CRATE_NAME.rmeta`.
 115 - `mir` — Generates a file containing rustc's mid-level intermediate
 116   representation. The default output filename is `CRATE_NAME.mir`.
 117 - `obj` — Generates a native object file. The default output filename is
 118   `CRATE_NAME.o`.
 119
 120 The output filename can be set with the `-o` flag. A suffix may be added to
 121 the filename with the `-C extra-filename` flag. The files are written to the
 122 current directory unless the `--out-dir` flag is used. Each emission type may
 123 also specify the output filename with the form `KIND=PATH`, which takes
 124 precedence over the `-o` flag.
 125
 126 [LLVM bitcode]: https://llvm.org/docs/BitCodeFormat.html
 127 [LLVM IR]: https://llvm.org/docs/LangRef.html
 128
 129 ## `--print`: print compiler information
 130
 131 This flag prints out various information about the compiler. This flag may be
 132 specified multiple times, and the information is printed in the order the
 133 flags are specified. Specifying a `--print` flag will usually disable the
 134 `--emit` step and will only print the requested information. The valid types
 135 of print values are:
 136
 137 - `crate-name` — The name of the crate.
 138 - `file-names` — The names of the files created by the `link` emit kind.
 139 - `sysroot` — Path to the sysroot.
 140 - `cfg` — List of cfg values. See [conditional compilation] for more
 141   information about cfg values.
 142 - `target-list` — List of known targets. The target may be selected with the
 143   `--target` flag.
 144 - `target-cpus` — List of available CPU values for the current target. The
 145   target CPU may be selected with the `-C target-cpu=val` flag.
 146 - `target-features` — List of available target features for the current
 147   target. Target features may be enabled with the `-C target-feature=val`
 148   flag. This flag is unsafe. See [known issues](targets/known-issues.md) for more details.
 149 - `relocation-models` — List of relocation models. Relocation models may be
 150   selected with the `-C relocation-model=val` flag.
 151 - `code-models` — List of code models. Code models may be selected with the
 152   `-C code-model=val` flag.
 153 - `tls-models` — List of Thread Local Storage models supported. The model may
 154   be selected with the `-Z tls-model=val` flag.
 155 - `native-static-libs` — This may be used when creating a `staticlib` crate
 156   type. If this is the only flag, it will perform a full compilation and
 157   include a diagnostic note that indicates the linker flags to use when
 158   linking the resulting static library. The note starts with the text
 159   `native-static-libs:` to make it easier to fetch the output.
 160
 161 [conditional compilation]: ../reference/conditional-compilation.html
 162
 163 ## `-g`: include debug information
 164
 165 A synonym for `-C debuginfo=2`, for more see [here](codegen-options/index.md#debuginfo).
 166
 167 ## `-O`: optimize your code
 168
 169 A synonym for `-C opt-level=2`, for more see [here](codegen-options/index.md#opt-level).
 170
 171 ## `-o`: filename of the output
 172
 173 This flag controls the output filename.
 174
 175 ## `--out-dir`: directory to write the output in
 176
 177 The outputted crate will be written to this directory. This flag is ignored if
 178 the `-o` flag is used.
 179
 180 ## `--explain`: provide a detailed explanation of an error message
 181
 182 Each error of `rustc`'s comes with an error code; this will print
 183 out a longer explanation of a given error.
 184
 185 ## `--test`: build a test harness
 186
 187 When compiling this crate, `rustc` will ignore your `main` function
 188 and instead produce a test harness.
 189
 190 ## `--target`: select a target triple to build
 191
 192 This controls which [target](targets/index.md) to produce.
 193
 194 ## `-W`: set lint warnings
 195
 196 This flag will set which lints should be set to the [warn level](lints/levels.md#warn).
 197
 198 ## `-A`: set lint allowed
 199
 200 This flag will set which lints should be set to the [allow level](lints/levels.md#allow).
 201
 202 ## `-D`: set lint denied
 203
 204 This flag will set which lints should be set to the [deny level](lints/levels.md#deny).
 205
 206 ## `-F`: set lint forbidden
 207
 208 This flag will set which lints should be set to the [forbid level](lints/levels.md#forbid).
 209
 210 ## `-Z`: set unstable options
 211
 212 This flag will allow you to set unstable options of rustc. In order to set multiple options,
 213 the -Z flag can be used multiple times. For example: `rustc -Z verbose -Z time`.
 214 Specifying options with -Z is only available on nightly. To view all available options
 215 run: `rustc -Z help`.
 216
 217 ## `--cap-lints`: set the most restrictive lint level
 218
 219 This flag lets you 'cap' lints, for more, [see here](lints/levels.md#capping-lints).
 220
 221 ## `-C`/`--codegen`: code generation options
 222
 223 This flag will allow you to set [codegen options](codegen-options/index.md).
 224
 225 ## `-V`/`--version`: print a version
 226
 227 This flag will print out `rustc`'s version.
 228
 229 ## `-v`/`--verbose`: use verbose output
 230
 231 This flag, when combined with other flags, makes them produce extra output.
 232
 233 ## `--extern`: specify where an external library is located
 234
 235 This flag allows you to pass the name and location of an external crate that
 236 will be linked into the crate you are building. This flag may be specified
 237 multiple times. The format of the value should be `CRATENAME=PATH`.
 238
 239 ## `--sysroot`: Override the system root
 240
 241 The "sysroot" is where `rustc` looks for the crates that come with the Rust
 242 distribution; this flag allows that to be overridden.
 243
 244 ## `--error-format`: control how errors are produced
 245  <a id="option-error-format"></a>
 246
 247 This flag lets you control the format of messages. Messages are printed to
 248 stderr. The valid options are:
 249
 250 - `human` — Human-readable output. This is the default.
 251 - `json` — Structured JSON output. See [the JSON chapter] for more detail.
 252 - `short` — Short, one-line messages.
 253
 254 ## `--color`: configure coloring of output
 255
 256 This flag lets you control color settings of the output. The valid options
 257 are:
 258
 259 - `auto` — Use colors if output goes to a tty. This is the default.
 260 - `always` — Always use colors.
 261 - `never` — Never colorize output.
 262
 263 ## `--remap-path-prefix`: remap source names in output
 264
 265 Remap source path prefixes in all output, including compiler diagnostics,
 266 debug information, macro expansions, etc. It takes a value of the form
 267 `FROM=TO` where a path prefix equal to `FROM` is rewritten to the value `TO`.
 268 The `FROM` may itself contain an `=` symbol, but the `TO` value may not. This
 269 flag may be specified multiple times.
 270
 271 This is useful for normalizing build products, for example by removing the
 272 current directory out of pathnames emitted into the object files. The
 273 replacement is purely textual, with no consideration of the current system's
 274 pathname syntax. For example `--remap-path-prefix foo=bar` will match
 275 `foo/lib.rs` but not `./foo/lib.rs`.
 276
 277 ## `--json`: configure json messages printed by the compiler
 278  <a id="option-json"></a>
 279
 280 When the `--error-format=json` option is passed to rustc then all of the
 281 compiler's diagnostic output will be emitted in the form of JSON blobs. The
 282 `--json` argument can be used in conjunction with `--error-format=json` to
 283 configure what the JSON blobs contain as well as which ones are emitted.
 284
 285 With `--error-format=json` the compiler will always emit any compiler errors as
 286 a JSON blob, but the following options are also available to the `--json` flag
 287 to customize the output:
 288
 289 - `diagnostic-short` - json blobs for diagnostic messages should use the "short"
 290   rendering instead of the normal "human" default. This means that the output of
 291   `--error-format=short` will be embedded into the JSON diagnostics instead of
 292   the default `--error-format=human`.
 293
 294 - `diagnostic-rendered-ansi` - by default JSON blobs in their `rendered` field
 295   will contain a plain text rendering of the diagnostic. This option instead
 296   indicates that the diagnostic should have embedded ANSI color codes intended
 297   to be used to colorize the message in the manner rustc typically already does
 298   for terminal outputs. Note that this is usefully combined with crates like
 299   `fwdansi` to translate these ANSI codes on Windows to console commands or
 300   `strip-ansi-escapes` if you'd like to optionally remove the ansi colors
 301   afterwards.
 302
 303 - `artifacts` - this instructs rustc to emit a JSON blob for each artifact that
 304   is emitted. An artifact corresponds to a request from the `--emit` CLI
 305   argument, and as soon as the artifact is available on the filesystem a
 306   notification will be emitted.
 307
 308 Note that it is invalid to combine the `--json` argument with the `--color`
 309 argument, and it is required to combine `--json` with `--error-format=json`.
 310
 311 See [the JSON chapter] for more detail.
 312
 313 ## `@path`: load command-line flags from a path
 314
 315 If you specify `@path` on the command-line, then it will open `path` and read
 316 command line options from it. These options are one per line; a blank line indicates
 317 an empty option. The file can use Unix or Windows style line endings, and must be
 318 encoded as UTF-8.
 319
 320 [the JSON chapter]: json.md