@@ -17,28 +17,147 @@ to `#[cfg(verbose)]` and `#[cfg(feature = "serde")]` respectively.
1717
1818## ` -L ` : add a directory to the library search path
1919
20- When looking for external crates, a directory passed to this flag will be searched.
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.
2133
2234## ` -l ` : link the generated crate to a native library
2335
2436This flag allows you to specify linking to a specific native library when building
2537a crate.
2638
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+
2758## ` --crate-type ` : a list of types of crates for the compiler to emit
2859
29- This instructs ` rustc ` on which crate type to build.
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
3082
3183## ` --crate-name ` : specify the name of the crate being built
3284
3385This informs ` rustc ` of the name of your crate.
3486
35- ## ` --emit ` : emit output other than a crate
36-
37- Instead of producing a crate, this flag can print out things like the assembly or LLVM-IR.
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+
96+ This flag controls the types of output files generated by the compiler. It
97+ accepts a comma-separated list of values, and may be specified multiple times.
98+ The valid emit kinds are:
99+
100+ - ` asm ` — Generates a file with the crate's assembly code. The default output
101+ filename is ` CRATE_NAME.s ` .
102+ - ` dep-info ` — Generates a file with Makefile syntax that indicates all the
103+ source files that were loaded to generate the crate. The default output
104+ filename is ` CRATE_NAME.d ` .
105+ - ` link ` — Generates the crates specified by ` --crate-type ` . The default
106+ output filenames depend on the crate type and platform. This is the default
107+ if ` --emit ` is not specified.
108+ - ` llvm-bc ` — Generates a binary file containing the [ LLVM bitcode] . The
109+ default output filename is ` CRATE_NAME.bc ` .
110+ - ` llvm-ir ` — Generates a file containing [ LLVM IR] . The default output
111+ filename is ` CRATE_NAME.ll ` .
112+ - ` metadata ` — Generates a file containing metadata about the crate. The
113+ default output filename is ` CRATE_NAME.rmeta ` .
114+ - ` mir ` — Generates a file containing rustc's mid-level intermediate
115+ representation. The default output filename is ` CRATE_NAME.mir ` .
116+ - ` obj ` — Generates a native object file. The default output filename is
117+ ` CRATE_NAME.o ` .
118+
119+ The output filename can be set with the ` -o ` flag. A suffix may be added to
120+ the filename with the ` -C extra-filename ` flag. The files are written to the
121+ current directory unless the ` --out-dir ` flag is used. Each emission type may
122+ also specify the output filename with the form ` KIND=PATH ` , which takes
123+ precedence over the ` -o ` flag.
124+
125+ [ LLVM bitcode ] : https://llvm.org/docs/BitCodeFormat.html
126+ [ LLVM IR ] : https://llvm.org/docs/LangRef.html
38127
39128## ` --print ` : print compiler information
40129
41- This flag prints out various information about the compiler.
130+ This flag prints out various information about the compiler. This flag may be
131+ specified multiple times, and the information is printed in the order the
132+ flags are specified. Specifying a ` --print ` flag will usually disable the
133+ ` --emit ` step and will only print the requested information. The valid types
134+ of print values are:
135+
136+ - ` crate-name ` — The name of the crate.
137+ - ` file-names ` — The names of the files created by the ` link ` emit kind.
138+ - ` sysroot ` — Path to the sysroot.
139+ - ` cfg ` — List of cfg values. See [ conditional compilation] for more
140+ information about cfg values.
141+ - ` target-list ` — List of known targets. The target may be selected with the
142+ ` --target ` flag.
143+ - ` target-cpus ` — List of available CPU values for the current target. The
144+ target CPU may be selected with the ` -C target-cpu=val ` flag.
145+ - ` target-features ` — List of available target features for the current
146+ target. Target features may be enabled with the ` -C target-feature=val `
147+ flag.
148+ - ` relocation-models ` — List of relocation models. Relocation models may be
149+ selected with the ` -C relocation-model=val ` flag.
150+ - ` code-models ` — List of code models. Code models may be selected with the
151+ ` -C code-model=val ` flag.
152+ - ` tls-models ` — List of Thread Local Storage models supported. The model may
153+ be selected with the ` -Z tls-model=val ` flag.
154+ - ` native-static-libs ` — This may be used when creating a ` staticlib ` crate
155+ type. If this is the only flag, it will perform a full compilation and
156+ include a diagnostic note that indicates the linker flags to use when
157+ linking the resulting static library. The note starts with the text
158+ ` native-static-libs: ` to make it easier to fetch the output.
159+
160+ [ conditional compilation ] : ../reference/conditional-compilation.html
42161
43162## ` -g ` : include debug information
44163
@@ -54,7 +173,8 @@ This flag controls the output filename.
54173
55174## ` --out-dir ` : directory to write the output in
56175
57- The outputted crate will be written to this directory.
176+ The outputted crate will be written to this directory. This flag is ignored if
177+ the ` -o ` flag is used.
58178
59179## ` --explain ` : provide a detailed explanation of an error message
60180
@@ -111,8 +231,9 @@ This flag, when combined with other flags, makes them produce extra output.
111231
112232## ` --extern ` : specify where an external library is located
113233
114- This flag allows you to pass the name and location of an external crate that will
115- be linked into the crate you're buildling.
234+ This flag allows you to pass the name and location of an external crate that
235+ will be linked into the crate you are building. This flag may be specified
236+ multiple times. The format of the value should be ` CRATENAME=PATH ` .
116237
117238## ` --sysroot ` : Override the system root
118239
@@ -121,8 +242,32 @@ distribution; this flag allows that to be overridden.
121242
122243## ` --error-format ` : control how errors are produced
123244
124- This flag lets you control the format of errors.
245+ This flag lets you control the format of messages. Messages are printed to
246+ stderr. The valid options are:
247+
248+ - ` human ` — Human-readable output. This is the default.
249+ - ` json ` — Structured JSON output.
250+ - ` short ` — Short, one-line messages.
125251
126252## ` --color ` : configure coloring of output
127253
128- This flag lets you control color settings of the output.
254+ This flag lets you control color settings of the output. The valid options
255+ are:
256+
257+ - ` auto ` — Use colors if output goes to a tty. This is the default.
258+ - ` always ` — Always use colors.
259+ - ` never ` — Never colorize output.
260+
261+ ## ` --remap-path-prefix ` : remap source names in output
262+
263+ Remap source path prefixes in all output, including compiler diagnostics,
264+ debug information, macro expansions, etc. It takes a value of the form
265+ ` FROM=TO ` where a path prefix equal to ` FROM ` is rewritten to the value ` TO ` .
266+ The ` FROM ` may itself contain an ` = ` symbol, but the ` TO ` value may not. This
267+ flag may be specified multiple times.
268+
269+ This is useful for normalizing build products, for example by removing the
270+ current directory out of pathnames emitted into the object files. The
271+ replacement is purely textual, with no consideration of the current system's
272+ pathname syntax. For example ` --remap-path-prefix foo=bar ` will match
273+ ` foo/lib.rs ` but not ` ./foo/lib.rs ` .
0 commit comments