man/rustc.1

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