man/rustc.1

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