src/doc/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|mir][=\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 \fBlinker\fR=\fI/path/to/cc\fR
 157 Path to the linker utility to use when linking libraries, executables, and
 158 objects.
 159 .TP
 160 \fBlink\-args\fR='\fI\-flag1 \-flag2\fR'
 161 A space\[hy]separated list of extra arguments to pass to the linker when the linker
 162 is invoked.
 163 .TP
 164 \fBlto\fR
 165 Perform LLVM link\[hy]time optimizations.
 166 .TP
 167 \fBtarget\-cpu\fR=\fIhelp\fR
 168 Selects a target processor.
 169 If the value is 'help', then a list of available CPUs is printed.
 170 .TP
 171 \fBtarget\-feature\fR='\fI+feature1\fR,\fI\-feature2\fR'
 172 A comma\[hy]separated list of features to enable or disable for the target.
 173 A preceding '+' enables a feature while a preceding '\-' disables it.
 174 Available features can be discovered through \fIllc -mcpu=help\fR.
 175 .TP
 176 \fBpasses\fR=\fIval\fR
 177 A space\[hy]separated list of extra LLVM passes to run.
 178 A value of 'list' will cause \fBrustc\fR to print all known passes and
 179 exit.
 180 The passes specified are appended at the end of the normal pass manager.
 181 .TP
 182 \fBllvm\-args\fR='\fI\-arg1\fR \fI\-arg2\fR'
 183 A space\[hy]separated list of arguments to pass through to LLVM.
 184 .TP
 185 \fBsave\-temps\fR
 186 If specified, the compiler will save more files (.bc, .o, .no\-opt.bc) generated
 187 throughout compilation in the output directory.
 188 .TP
 189 \fBrpath\fR
 190 If specified, then the rpath value for dynamic libraries will be set in
 191 either dynamic library or executable outputs.
 192 .TP
 193 \fBno\-prepopulate\-passes\fR
 194 Suppresses pre\[hy]population of the LLVM pass manager that is run over the module.
 195 .TP
 196 \fBno\-vectorize\-loops\fR
 197 Suppresses running the loop vectorization LLVM pass, regardless of optimization
 198 level.
 199 .TP
 200 \fBno\-vectorize\-slp\fR
 201 Suppresses running the LLVM SLP vectorization pass, regardless of optimization
 202 level.
 203 .TP
 204 \fBsoft\-float\fR
 205 Generates software floating point library calls instead of hardware
 206 instructions.
 207 .TP
 208 \fBprefer\-dynamic\fR
 209 Prefers dynamic linking to static linking.
 210 .TP
 211 \fBno\-integrated\-as\fR
 212 Force usage of an external assembler rather than LLVM's integrated one.
 213 .TP
 214 \fBno\-redzone\fR
 215 Disable the use of the redzone.
 216 .TP
 217 \fBrelocation\-model\fR=[pic,static,dynamic\-no\-pic]
 218 The relocation model to use.
 219 (Default: \fIpic\fR)
 220 .TP
 221 \fBcode\-model\fR=[small,kernel,medium,large]
 222 Choose the code model to use.
 223 .TP
 224 \fBmetadata\fR=\fIval\fR
 225 Metadata to mangle symbol names with.
 226 .TP
 227 \fBextra\-filename\fR=\fIval\fR
 228 Extra data to put in each output filename.
 229 .TP
 230 \fBcodegen\-units\fR=\fIn\fR
 231 Divide crate into \fIn\fR units to optimize in parallel.
 232 .TP
 233 \fBremark\fR=\fIval\fR
 234 Print remarks for these optimization passes (space separated, or "all").
 235 .TP
 236 \fBno\-stack\-check\fR
 237 Disable checks for stack exhaustion (a memory\[hy]safety hazard!).
 238 .TP
 239 \fBdebuginfo\fR=\fIval\fR
 240 Debug info emission level:
 241 .RS
 242 .TP
 243 .B 0
 244 no debug info;
 245 .TP
 246 .B 1
 247 line\[hy]tables only (for stacktraces and breakpoints);
 248 .TP
 249 .B 2
 250 full debug info with variable and type information.
 251 .RE
 252 .TP
 253 \fBopt\-level\fR=\fIVAL\fR
 254 Optimize with possible levels 0\[en]3
 255
 256 .SH ENVIRONMENT
 257
 258 Some of these affect the output of the compiler, while others affect programs
 259 which link to the standard library.
 260
 261 .TP
 262 \fBRUST_TEST_THREADS\fR
 263 The test framework Rust provides executes tests in parallel. This variable sets
 264 the maximum number of threads used for this purpose. This setting is overridden
 265 by the --test-threads option.
 266
 267 .TP
 268 \fBRUST_TEST_NOCAPTURE\fR
 269 If set to a value other than "0", a synonym for the --nocapture flag.
 270
 271 .TP
 272 \fBRUST_MIN_STACK\fR
 273 Sets the minimum stack size for new threads.
 274
 275 .TP
 276 \fBRUST_BACKTRACE\fR
 277 If set to a value different than "0", produces a backtrace in the output of a program which panics.
 278
 279 .SH "EXAMPLES"
 280 To build an executable from a source file with a main function:
 281     $ rustc \-o hello hello.rs
 282
 283 To build a library from a source file:
 284     $ rustc \-\-crate\-type=lib hello\-lib.rs
 285
 286 To build either with a crate (.rs) file:
 287     $ rustc hello.rs
 288
 289 To build an executable with debug info:
 290     $ rustc \-g \-o hello hello.rs
 291
 292 .SH "SEE ALSO"
 293
 294 .BR rustdoc (1)
 295
 296 .SH "BUGS"
 297 See https://github.com/rust\-lang/rust/issues for issues.
 298
 299 .SH "AUTHOR"
 300 See https://github.com/rust\-lang/rust/graphs/contributors or use `git log --all --format='%cN <%cE>' | sort -u` in the rust source distribution.
 301
 302 .SH "COPYRIGHT"
 303 This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
 304 See \fICOPYRIGHT\fR file in the rust source distribution.