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