]> git.proxmox.com Git - rustc.git/blame - man/rustc.1
Imported Upstream version 1.9.0+dfsg1
[rustc.git] / man / rustc.1
CommitLineData
62682a34 1.TH RUSTC "1" "August 2015" "rustc 1.2.0" "User Commands"
223e47cc 2.SH NAME
1a4d82fc 3rustc \- The Rust compiler
223e47cc
LB
4.SH SYNOPSIS
5.B rustc
6[\fIOPTIONS\fR] \fIINPUT\fR
7
8.SH DESCRIPTION
7453a54e 9This program is a compiler for the Rust language, available at https://www.rust\-lang.org.
223e47cc
LB
10
11.SH OPTIONS
12
13.TP
1a4d82fc 14\fB\-h\fR, \fB\-\-help\fR
c34b1796 15Display the help message.
223e47cc 16.TP
c34b1796
AL
17\fB\-\-cfg\fR \fISPEC\fR
18Configure the compilation environment.
223e47cc 19.TP
c34b1796
AL
20\fB\-L\fR [\fIKIND\fR=]\fIPATH\fR
21Add a directory to the library search path.
22The optional \fIKIND\fR can be one of:
23.RS
85aaf69f 24.TP
c34b1796
AL
25\fBdependency\fR
26only lookup transitive dependencies here
1a4d82fc 27.TP
c34b1796
AL
28.B crate
29only lookup local `extern crate` directives here
223e47cc 30.TP
c34b1796
AL
31.B native
32only lookup native libraries here
970d7e83 33.TP
c34b1796
AL
34.B framework
35only look for OSX frameworks here
970d7e83 36.TP
c34b1796
AL
37.B all
38look for anything here (the default)
39.RE
40.TP
41\fB\-l\fR [\fIKIND\fR=]\fINAME\fR
e9174d1e 42Link the generated crate(s) to the specified library \fINAME\fR.
c34b1796
AL
43The optional \fIKIND\fR can be one of \fIstatic\fR, \fIdylib\fR, or
44\fIframework\fR.
45If omitted, \fIdylib\fR is assumed.
46.TP
47\fB\-\-crate\-type\fR [bin|lib|rlib|dylib|staticlib]
48Comma separated list of types of crates for the compiler to emit.
49.TP
50\fB\-\-crate\-name\fR \fINAME\fR
51Specify the name of the crate being built.
52.TP
92a42be0 53\fB\-\-emit\fR [asm|llvm\-bc|llvm\-ir|obj|link|dep\-info][=\fIPATH\fR]
7453a54e
SL
54Configure the output that \fBrustc\fR will produce. Each emission may also have
55an optional explicit output \fIPATH\fR specified for that particular emission
56kind. This path takes precedence over the \fB-o\fR option.
c34b1796
AL
57.TP
58\fB\-\-print\fR [crate\-name|file\-names|sysroot]
59Comma separated list of compiler information to print on stdout.
223e47cc 60.TP
1a4d82fc 61\fB\-g\fR
c34b1796 62Equivalent to \fI\-C\ debuginfo=2\fR.
223e47cc
LB
63.TP
64\fB\-O\fR
c34b1796 65Equivalent to \fI\-C\ opt\-level=2\fR.
223e47cc 66.TP
c34b1796 67\fB\-o\fR \fIFILENAME\fR
7453a54e
SL
68Write output to \fIFILENAME\fR. Ignored if multiple \fI\-\-emit\fR outputs are specified which
69don't have an explicit path otherwise.
970d7e83 70.TP
c34b1796 71\fB\-\-out\-dir\fR \fIDIR\fR
7453a54e 72Write output to compiler\[hy]chosen filename in \fIDIR\fR. Ignored if \fI\-o\fR is specified.
c34b1796 73Defaults to the current directory.
223e47cc 74.TP
c34b1796
AL
75\fB\-\-explain\fR \fIOPT\fR
76Provide a detailed explanation of an error message.
223e47cc
LB
77.TP
78\fB\-\-test\fR
c34b1796 79Build a test harness.
223e47cc 80.TP
7453a54e
SL
81\fB\-\-target\fR \fITARGET\fR
82Target triple for which the code is compiled. This option defaults to the host’s target
83triple. The target triple has the general format <arch><sub>\-<vendor>\-<sys>\-<abi>, where:
84.RS
85.TP
86.B <arch>
87x86, arm, thumb, mips, etc.
88.TP
89.B <sub>
90for example on ARM: v5, v6m, v7a, v7m, etc.
91.TP
92.B <vendor>
93pc, apple, nvidia, ibm, etc.
94.TP
95.B <sys>
96none, linux, win32, darwin, cuda, etc.
97.TP
98.B <abi>
99eabi, gnu, android, macho, elf, etc.
100.RE
970d7e83 101.TP
c34b1796
AL
102\fB\-W help\fR
103Print 'lint' options and default settings.
223e47cc 104.TP
c34b1796
AL
105\fB\-W\fR \fIOPT\fR, \fB\-\-warn\fR \fIOPT\fR
106Set lint warnings.
223e47cc 107.TP
c34b1796
AL
108\fB\-A\fR \fIOPT\fR, \fB\-\-allow\fR \fIOPT\fR
109Set lint allowed.
223e47cc 110.TP
c34b1796
AL
111\fB\-D\fR \fIOPT\fR, \fB\-\-deny\fR \fIOPT\fR
112Set lint denied.
223e47cc 113.TP
c34b1796
AL
114\fB\-F\fR \fIOPT\fR, \fB\-\-forbid\fR \fIOPT\fR
115Set lint forbidden.
223e47cc 116.TP
c34b1796
AL
117\fB\-C\fR \fIFLAG\fR[=\fIVAL\fR], \fB\-\-codegen\fR \fIFLAG\fR[=\fIVAL\fR]
118Set a codegen\[hy]related flag to the value specified.
119Use \fI\-C help\fR to print available flags.
120See CODEGEN OPTIONS below.
1a4d82fc
JJ
121.TP
122\fB\-V\fR, \fB\-\-version\fR
c34b1796 123Print version info and exit.
1a4d82fc
JJ
124.TP
125\fB\-v\fR, \fB\-\-verbose\fR
c34b1796 126Use verbose output.
1a4d82fc 127.TP
c34b1796 128\fB\-\-extern\fR \fINAME\fR=\fIPATH\fR
e9174d1e
SL
129Specify where an external rust library is located. These should match
130\fIextern\fR declarations in the crate's source code.
1a4d82fc 131.TP
c34b1796
AL
132\fB\-\-sysroot\fR \fIPATH\fR
133Override the system root.
1a4d82fc 134.TP
c34b1796
AL
135\fB\-Z\fR \fIFLAG\fR
136Set internal debugging options.
137Use \fI\-Z help\fR to print available options.
223e47cc 138.TP
1a4d82fc
JJ
139\fB\-\-color\fR auto|always|never
140Configure coloring of output:
c34b1796
AL
141.RS
142.TP
143.B auto
144colorize, if output goes to a tty (default);
145.TP
146.B always
147always colorize output;
148.TP
149.B never
150never colorize output.
151.RE
1a4d82fc
JJ
152
153.SH CODEGEN OPTIONS
154
155.TP
c34b1796 156\fBar\fR=\fI/path/to/ar\fR
1a4d82fc
JJ
157Path to the archive utility to use when assembling archives.
158.TP
c34b1796 159\fBlinker\fR=\fI/path/to/cc\fR
1a4d82fc
JJ
160Path to the linker utility to use when linking libraries, executables, and
161objects.
162.TP
c34b1796
AL
163\fBlink\-args\fR='\fI\-flag1 \-flag2\fR'
164A space\[hy]separated list of extra arguments to pass to the linker when the linker
1a4d82fc
JJ
165is invoked.
166.TP
167\fBlto\fR
c34b1796 168Perform LLVM link\[hy]time optimizations.
1a4d82fc 169.TP
c34b1796
AL
170\fBtarget\-cpu\fR=\fIhelp\fR
171Selects a target processor.
172If the value is 'help', then a list of available CPUs is printed.
1a4d82fc 173.TP
c34b1796
AL
174\fBtarget\-feature\fR='\fI+feature1\fR,\fI\-feature2\fR'
175A comma\[hy]separated list of features to enable or disable for the target.
176A preceding '+' enables a feature while a preceding '\-' disables it.
d9579d0f 177Available features can be discovered through \fIllc -mcpu=help\fR.
1a4d82fc 178.TP
c34b1796
AL
179\fBpasses\fR=\fIval\fR
180A space\[hy]separated list of extra LLVM passes to run.
181A value of 'list' will cause \fBrustc\fR to print all known passes and
182exit.
183The passes specified are appended at the end of the normal pass manager.
1a4d82fc 184.TP
c34b1796
AL
185\fBllvm\-args\fR='\fI\-arg1\fR \fI\-arg2\fR'
186A space\[hy]separated list of arguments to pass through to LLVM.
1a4d82fc 187.TP
c34b1796
AL
188\fBsave\-temps\fR
189If specified, the compiler will save more files (.bc, .o, .no\-opt.bc) generated
1a4d82fc
JJ
190throughout compilation in the output directory.
191.TP
192\fBrpath\fR
193If specified, then the rpath value for dynamic libraries will be set in
194either dynamic library or executable outputs.
195.TP
c34b1796
AL
196\fBno\-prepopulate\-passes\fR
197Suppresses pre\[hy]population of the LLVM pass manager that is run over the module.
1a4d82fc 198.TP
c34b1796 199\fBno\-vectorize\-loops\fR
1a4d82fc
JJ
200Suppresses running the loop vectorization LLVM pass, regardless of optimization
201level.
202.TP
c34b1796 203\fBno\-vectorize\-slp\fR
1a4d82fc
JJ
204Suppresses running the LLVM SLP vectorization pass, regardless of optimization
205level.
206.TP
c34b1796 207\fBsoft\-float\fR
1a4d82fc
JJ
208Generates software floating point library calls instead of hardware
209instructions.
210.TP
c34b1796 211\fBprefer\-dynamic\fR
1a4d82fc
JJ
212Prefers dynamic linking to static linking.
213.TP
c34b1796 214\fBno\-integrated\-as\fR
1a4d82fc
JJ
215Force usage of an external assembler rather than LLVM's integrated one.
216.TP
c34b1796 217\fBno\-redzone\fR
1a4d82fc
JJ
218Disable the use of the redzone.
219.TP
c34b1796
AL
220\fBrelocation\-model\fR=[pic,static,dynamic\-no\-pic]
221The relocation model to use.
222(Default: \fIpic\fR)
1a4d82fc 223.TP
c34b1796 224\fBcode\-model\fR=[small,kernel,medium,large]
1a4d82fc
JJ
225Choose the code model to use.
226.TP
c34b1796 227\fBmetadata\fR=\fIval\fR
1a4d82fc
JJ
228Metadata to mangle symbol names with.
229.TP
c34b1796 230\fBextra\-filename\fR=\fIval\fR
1a4d82fc
JJ
231Extra data to put in each output filename.
232.TP
c34b1796
AL
233\fBcodegen\-units\fR=\fIn\fR
234Divide crate into \fIn\fR units to optimize in parallel.
1a4d82fc 235.TP
c34b1796 236\fBremark\fR=\fIval\fR
1a4d82fc
JJ
237Print remarks for these optimization passes (space separated, or "all").
238.TP
c34b1796
AL
239\fBno\-stack\-check\fR
240Disable checks for stack exhaustion (a memory\[hy]safety hazard!).
1a4d82fc 241.TP
c34b1796 242\fBdebuginfo\fR=\fIval\fR
1a4d82fc 243Debug info emission level:
c34b1796
AL
244.RS
245.TP
246.B 0
247no debug info;
248.TP
249.B 1
250line\[hy]tables only (for stacktraces and breakpoints);
251.TP
252.B 2
253full debug info with variable and type information.
254.RE
255.TP
256\fBopt\-level\fR=\fIVAL\fR
257Optimize with possible levels 0\[en]3
258
259.SH ENVIRONMENT
260
261Some of these affect the output of the compiler, while others affect programs
262which link to the standard library.
263
264.TP
265\fBRUST_TEST_THREADS\fR
266The test framework Rust provides executes tests in parallel. This variable sets
267the maximum number of threads used for this purpose.
268
269.TP
270\fBRUST_TEST_NOCAPTURE\fR
54a0048b 271If set to a value other than "0", a synonym for the --nocapture flag.
c34b1796
AL
272
273.TP
274\fBRUST_MIN_STACK\fR
275Sets the minimum stack size for new threads.
276
1a4d82fc 277.TP
c34b1796 278\fBRUST_BACKTRACE\fR
54a0048b 279If set to a value different than "0", produces a backtrace in the output of a program which panics.
223e47cc
LB
280
281.SH "EXAMPLES"
282To build an executable from a source file with a main function:
c34b1796 283 $ rustc \-o hello hello.rs
223e47cc
LB
284
285To build a library from a source file:
c34b1796 286 $ rustc \-\-crate\-type=lib hello\-lib.rs
1a4d82fc
JJ
287
288To build either with a crate (.rs) file:
289 $ rustc hello.rs
223e47cc 290
1a4d82fc 291To build an executable with debug info:
c34b1796 292 $ rustc \-g \-o hello hello.rs
223e47cc 293
1a4d82fc 294.SH "SEE ALSO"
223e47cc 295
c34b1796 296.BR rustdoc (1)
223e47cc
LB
297
298.SH "BUGS"
7453a54e 299See https://github.com/rust\-lang/rust/issues for issues.
223e47cc
LB
300
301.SH "AUTHOR"
c34b1796 302See \fIAUTHORS.txt\fR in the Rust source distribution.
223e47cc
LB
303
304.SH "COPYRIGHT"
c34b1796
AL
305This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
306See \fICOPYRIGHT\fR file in the rust source distribution.