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