Command-line arguments

Command-line arguments

Here's a list of command-line arguments to rustc and what they do.

-h/—help: get help

This flag will print out help information for rustc.

—cfg: configure the compilation environment

This flag can turn on or off various #[cfg] settings for conditionalcompilation.

The value can either be a single identifier or two identifiers separated by =.

For examples, —cfg 'verbose' or —cfg 'feature="serde"'. These correspondto #[cfg(verbose)] and #[cfg(feature = "serde")] respectively.

-L: add a directory to the library search path

The -L flag adds a path to search for external crates and libraries.

The kind of search path can optionally be specified with the form -L KIND=PATH where KIND may be one of:

dependency — Only search for transitive dependencies in this directory.
crate — Only search for this crate's direct dependencies in thisdirectory.
native — Only search for native libraries in this directory.
framework — Only search for macOS frameworks in this directory.
all — Search for all library kinds in this directory. This is the defaultif KIND is not specified.

-l: link the generated crate to a native library

This flag allows you to specify linking to a specific native library when buildinga crate.

The kind of library can optionally be specified with the form -l KIND=libwhere KIND may be one of:

dylib — A native dynamic library.
static — A native static library (such as a .a archive).
framework — A macOS framework.

The kind of library can be specified in a #[link]attribute. If the kind is not specified in the linkattribute or on the command-line, it will link a dynamic library if available,otherwise it will use a static library. If the kind is specified on thecommand-line, it will override the kind specified in a link attribute.

The name used in a link attribute may be overridden using the form -l ATTR_NAME:LINK_NAME where ATTR_NAME is the name in the link attribute,and LINK_NAME is the name of the actual library that will be linked.

—crate-type: a list of types of crates for the compiler to emit

This instructs rustc on which crate type to build. This flag accepts acomma-separated list of values, and may be specified multiple times. The validcrate types are:

lib — Generates a library kind preferred by the compiler, currentlydefaults to rlib.
rlib — A Rust static library.
staticlib — A native static library.
dylib — A Rust dynamic library.
cdylib — A native dynamic library.
bin — A runnable executable program.
proc-macro — Generates a format suitable for a procedural macro librarythat may be loaded by the compiler.

The crate type may be specified with the crate_type attribute.The —crate-type command-line value will override the crate_typeattribute.

More details may be found in the linkage chapter of the reference.

—crate-name: specify the name of the crate being built

This informs rustc of the name of your crate.

—edition: specify the edition to use

This flag takes a value of 2015 or 2018. The default is 2015. Moreinformation about editions may be found in the edition guide.

—emit: specifies the types of output files to generate

This flag controls the types of output files generated by the compiler. Itaccepts a comma-separated list of values, and may be specified multiple times.The valid emit kinds are:

asm — Generates a file with the crate's assembly code. The default outputfilename is CRATE_NAME.s.
dep-info — Generates a file with Makefile syntax that indicates all thesource files that were loaded to generate the crate. The default outputfilename is CRATE_NAME.d.
link — Generates the crates specified by —crate-type. The defaultoutput filenames depend on the crate type and platform. This is the defaultif —emit is not specified.
llvm-bc — Generates a binary file containing the LLVM bitcode. Thedefault output filename is CRATE_NAME.bc.
llvm-ir — Generates a file containing LLVM IR. The default outputfilename is CRATE_NAME.ll.
metadata — Generates a file containing metadata about the crate. Thedefault output filename is CRATE_NAME.rmeta.
mir — Generates a file containing rustc's mid-level intermediaterepresentation. The default output filename is CRATE_NAME.mir.
obj — Generates a native object file. The default output filename isCRATE_NAME.o.

The output filename can be set with the -o flag. Asuffix may be added to the filename with the -C extra-filenameflag. The files are written to thecurrent directory unless the —out-dir flag is used. Eachemission type may also specify the output filename with the form KIND=PATH,which takes precedence over the -o flag.

—print: print compiler information

This flag prints out various information about the compiler. This flag may bespecified multiple times, and the information is printed in the order theflags are specified. Specifying a —print flag will usually disable the—emit step and will only print the requested information.The valid types of print values are:

crate-name — The name of the crate.
file-names — The names of the files created by the link emit kind.
sysroot — Path to the sysroot.
cfg — List of cfg values. See conditional compilation for moreinformation about cfg values.
target-list — List of known targets. The target may be selected with the—target flag.
target-cpus — List of available CPU values for the current target. Thetarget CPU may be selected with the -C target-cpu=valflag.
target-features — List of available target features for the currenttarget. Target features may be enabled with the -C target-feature=valflag. This flag is unsafe. Seeknown issues for more details.
relocation-models — List of relocation models. Relocation models may beselected with the -C relocation-model=valflag.
code-models — List of code models. Code models may be selected with the-C code-model=val flag.
tls-models — List of Thread Local Storage models supported. The model maybe selected with the -Z tls-model=val flag.
native-static-libs — This may be used when creating a staticlib cratetype. If this is the only flag, it will perform a full compilation andinclude a diagnostic note that indicates the linker flags to use whenlinking the resulting static library. The note starts with the textnative-static-libs: to make it easier to fetch the output.

-g: include debug information

A synonym for -C debuginfo=2.

-O: optimize your code

A synonym for -C opt-level=2.

-o: filename of the output

This flag controls the output filename.

—out-dir: directory to write the output in

The outputted crate will be written to this directory. This flag is ignored ifthe -o flag is used.

—explain: provide a detailed explanation of an error message

Each error of rustc's comes with an error code; this will printout a longer explanation of a given error.

—test: build a test harness

When compiling this crate, rustc will ignore your main functionand instead produce a test harness.

—target: select a target triple to build

This controls which target to produce.

-W: set lint warnings

This flag will set which lints should be set to the warn level.

-A: set lint allowed

This flag will set which lints should be set to the allow level.

-D: set lint denied

This flag will set which lints should be set to the deny level.

-F: set lint forbidden

This flag will set which lints should be set to the forbid level.

-Z: set unstable options

This flag will allow you to set unstable options of rustc. In order to set multiple options,the -Z flag can be used multiple times. For example: rustc -Z verbose -Z time.Specifying options with -Z is only available on nightly. To view all available optionsrun: rustc -Z help.

—cap-lints: set the most restrictive lint level

This flag lets you 'cap' lints, for more, see here.

-C/—codegen: code generation options

This flag will allow you to set codegen options.

-V/—version: print a version

This flag will print out rustc's version.

-v/—verbose: use verbose output

This flag, when combined with other flags, makes them produce extra output.

—extern: specify where an external library is located

This flag allows you to pass the name and location for an external crate of adirect dependency. Indirect dependencies (dependencies of dependencies) arelocated using the -L flag. The given crate name isadded to the extern prelude, which is the same as specifying extern cratewithin the root module. The given crate name does not need to match the namethe library was built with.

This flag may be specified multiple times. This flag takes an argument witheither of the following formats:

CRATENAME=PATH — Indicates the given crate is found at the given path.
CRATENAME — Indicates the given crate may be found in the search path,such as within the sysroot or via the -L flag.

The same crate name may be specified multiple times for different crate types.If both an rlib and dylib are found, an internal algorithm is used todecide which to use for linking. The -C prefer-dynamicflag may be used to influence which is used.

If the same crate name is specified with and without a path, the one with thepath is used and the pathless flag has no effect.

—sysroot: Override the system root

The "sysroot" is where rustc looks for the crates that come with the Rustdistribution; this flag allows that to be overridden.

—error-format: control how errors are produced

This flag lets you control the format of messages. Messages are printed tostderr. The valid options are:

human — Human-readable output. This is the default.
json — Structured JSON output. See the JSON chapter for more detail.
short — Short, one-line messages.

—color: configure coloring of output

This flag lets you control color settings of the output. The valid optionsare:

auto — Use colors if output goes to a tty. This is the default.
always — Always use colors.
never — Never colorize output.

—remap-path-prefix: remap source names in output

Remap source path prefixes in all output, including compiler diagnostics,debug information, macro expansions, etc. It takes a value of the formFROM=TO where a path prefix equal to FROM is rewritten to the value TO.The FROM may itself contain an = symbol, but the TO value may not. Thisflag may be specified multiple times.

This is useful for normalizing build products, for example by removing thecurrent directory out of pathnames emitted into the object files. Thereplacement is purely textual, with no consideration of the current system'spathname syntax. For example —remap-path-prefix foo=bar will matchfoo/lib.rs but not ./foo/lib.rs.

—json: configure json messages printed by the compiler

When the —error-format=json option is passed torustc then all of the compiler's diagnostic output will be emitted in the formof JSON blobs. The —json argument can be used in conjunction with—error-format=json to configure what the JSON blobs contain as well aswhich ones are emitted.

With —error-format=json the compiler will always emit any compiler errors asa JSON blob, but the following options are also available to the —json flagto customize the output:

diagnostic-short - json blobs for diagnostic messages should use the "short"rendering instead of the normal "human" default. This means that the output of—error-format=short will be embedded into the JSON diagnostics instead ofthe default —error-format=human.
diagnostic-rendered-ansi - by default JSON blobs in their rendered fieldwill contain a plain text rendering of the diagnostic. This option insteadindicates that the diagnostic should have embedded ANSI color codes intendedto be used to colorize the message in the manner rustc typically already doesfor terminal outputs. Note that this is usefully combined with crates likefwdansi to translate these ANSI codeson Windows to console commands orstrip-ansi-escapes if you'dlike to optionally remove the ansi colors afterwards.
artifacts - this instructs rustc to emit a JSON blob for each artifact thatis emitted. An artifact corresponds to a request from the —emit CLIargument, and as soon as the artifact is available on thefilesystem a notification will be emitted.

Note that it is invalid to combine the —json argument with the—color argument, and it is required to combine —jsonwith —error-format=json.

See the JSON chapter for more detail.

@path: load command-line flags from a path

If you specify @path on the command-line, then it will open path and readcommand line options from it. These options are one per line; a blank line indicatesan empty option. The file can use Unix or Windows style line endings, and must beencoded as UTF-8.

2. Command-line arguments