src/doc/man/rustc.1

   1 .TH RUSTC "1" "April 2019" "rustc <INSERT VERSION HERE>" "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|proc\-macro]
  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|metadata|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|\:target\-libdir|\:cfg|\:target\-list|\:target\-cpus|\:target\-features|\:relocation\-models|\:code\-models|\:tls\-models|\:target\-spec\-json|\:native\-static\-libs|\:stack\-protector\-strategies|\:link\-args]
  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\-\-remap\-path\-prefix\fR \fIfrom\fR=\fIto\fR
 129 Remap source path prefixes in all output, including compiler diagnostics, debug information,
 130 macro expansions, etc. The \fIfrom\fR=\fIto\fR parameter is scanned from right to left, so \fIfrom\fR
 131 may contain '=', but \fIto\fR may not.
 132
 133 This is useful for normalizing build products, for example by removing the current directory out of
 134 pathnames emitted into the object files. The replacement is purely textual, with no consideration of
 135 the current system's pathname syntax. For example \fI\-\-remap\-path\-prefix foo=bar\fR will
 136 match \fBfoo/lib.rs\fR but not \fB./foo/lib.rs\fR.
 137 .TP
 138 \fB\-\-extern\fR \fINAME\fR=\fIPATH\fR
 139 Specify where an external rust library is located. These should match
 140 \fIextern\fR declarations in the crate's source code.
 141 .TP
 142 \fB\-\-sysroot\fR \fIPATH\fR
 143 Override the system root.
 144 .TP
 145 \fB\-Z\fR \fIFLAG\fR
 146 Set unstable / perma-unstable options.
 147 Use \fI\-Z help\fR to print available options.
 148 .TP
 149 \fB\-\-color\fR auto|always|never
 150 Configure coloring of output:
 151 .RS
 152 .TP
 153 .B auto
 154 colorize, if output goes to a tty (default);
 155 .TP
 156 .B always
 157 always colorize output;
 158 .TP
 159 .B never
 160 never colorize output.
 161 .RE
 162
 163 .SH CODEGEN OPTIONS
 164
 165 .TP
 166 \fBlinker\fR=\fI/path/to/cc\fR
 167 Path to the linker utility to use when linking libraries, executables, and
 168 objects.
 169 .TP
 170 \fBlink\-args\fR='\fI\-flag1 \-flag2\fR'
 171 A space\[hy]separated list of extra arguments to pass to the linker when the linker
 172 is invoked.
 173 .TP
 174 \fBlto\fR
 175 Perform LLVM link\[hy]time optimizations.
 176 .TP
 177 \fBtarget\-cpu\fR=\fIhelp\fR
 178 Selects a target processor.
 179 If the value is 'help', then a list of available CPUs is printed.
 180 .TP
 181 \fBtarget\-feature\fR='\fI+feature1\fR,\fI\-feature2\fR'
 182 A comma\[hy]separated list of features to enable or disable for the target.
 183 A preceding '+' enables a feature while a preceding '\-' disables it.
 184 Available features can be discovered through \fIllc -mcpu=help\fR.
 185 .TP
 186 \fBpasses\fR=\fIval\fR
 187 A space\[hy]separated list of extra LLVM passes to run.
 188 A value of 'list' will cause \fBrustc\fR to print all known passes and
 189 exit.
 190 The passes specified are appended at the end of the normal pass manager.
 191 .TP
 192 \fBllvm\-args\fR='\fI\-arg1\fR \fI\-arg2\fR'
 193 A space\[hy]separated list of arguments to pass through to LLVM.
 194 .TP
 195 \fBsave\-temps\fR
 196 If specified, the compiler will save more files (.bc, .o, .no\-opt.bc) generated
 197 throughout compilation in the output directory.
 198 .TP
 199 \fBrpath\fR
 200 If specified, then the rpath value for dynamic libraries will be set in
 201 either dynamic library or executable outputs.
 202 .TP
 203 \fBno\-prepopulate\-passes\fR
 204 Suppresses pre\[hy]population of the LLVM pass manager that is run over the module.
 205 .TP
 206 \fBno\-vectorize\-loops\fR
 207 Suppresses running the loop vectorization LLVM pass, regardless of optimization
 208 level.
 209 .TP
 210 \fBno\-vectorize\-slp\fR
 211 Suppresses running the LLVM SLP vectorization pass, regardless of optimization
 212 level.
 213 .TP
 214 \fBsoft\-float\fR
 215 Generates software floating point library calls instead of hardware
 216 instructions.
 217 .TP
 218 \fBprefer\-dynamic\fR
 219 Prefers dynamic linking to static linking.
 220 .TP
 221 \fBno\-integrated\-as\fR
 222 Force usage of an external assembler rather than LLVM's integrated one.
 223 .TP
 224 \fBno\-redzone\fR
 225 Disable the use of the redzone.
 226 .TP
 227 \fBrelocation\-model\fR=[pic,static,dynamic\-no\-pic]
 228 The relocation model to use.
 229 (Default: \fIpic\fR)
 230 .TP
 231 \fBcode\-model\fR=[small,kernel,medium,large]
 232 Choose the code model to use.
 233 .TP
 234 \fBmetadata\fR=\fIval\fR
 235 Metadata to mangle symbol names with.
 236 .TP
 237 \fBextra\-filename\fR=\fIval\fR
 238 Extra data to put in each output filename.
 239 .TP
 240 \fBcodegen\-units\fR=\fIn\fR
 241 Divide crate into \fIn\fR units to optimize in parallel.
 242 .TP
 243 \fBremark\fR=\fIval\fR
 244 Print remarks for these optimization passes (space separated, or "all").
 245 .TP
 246 \fBno\-stack\-check\fR
 247 Disable checks for stack exhaustion (a memory\[hy]safety hazard!).
 248 .TP
 249 \fBdebuginfo\fR=\fIval\fR
 250 Debug info emission level:
 251 .RS
 252 .TP
 253 .B 0
 254 no debug info;
 255 .TP
 256 .B 1
 257 line\[hy]tables only (for stacktraces and breakpoints);
 258 .TP
 259 .B 2
 260 full debug info with variable and type information.
 261 .RE
 262 .TP
 263 \fBopt\-level\fR=\fIVAL\fR
 264 Optimize with possible levels 0\[en]3, s (optimize for size), or z (for minimal size)
 265
 266 .SH ENVIRONMENT
 267
 268 Some of these affect only test harness programs (generated via rustc --test);
 269 others affect all programs which link to the Rust standard library.
 270
 271 .TP
 272 \fBRUST_TEST_THREADS\fR
 273 The test framework Rust provides executes tests in parallel. This variable sets
 274 the maximum number of threads used for this purpose. This setting is overridden
 275 by the --test-threads option.
 276
 277 .TP
 278 \fBRUST_TEST_NOCAPTURE\fR
 279 If set to a value other than "0", a synonym for the --nocapture flag.
 280
 281 .TP
 282 \fBRUST_MIN_STACK\fR
 283 Sets the minimum stack size for new threads.
 284
 285 .TP
 286 \fBRUST_BACKTRACE\fR
 287 If set to a value different than "0", produces a backtrace in the output of a program which panics.
 288
 289 .SH "EXAMPLES"
 290 To build an executable from a source file with a main function:
 291     $ rustc \-o hello hello.rs
 292
 293 To build a library from a source file:
 294     $ rustc \-\-crate\-type=lib hello\-lib.rs
 295
 296 To build either with a crate (.rs) file:
 297     $ rustc hello.rs
 298
 299 To build an executable with debug info:
 300     $ rustc \-g \-o hello hello.rs
 301
 302 .SH "SEE ALSO"
 303
 304 .BR rustdoc (1)
 305
 306 .SH "BUGS"
 307 See https://github.com/rust\-lang/rust/issues for issues.
 308
 309 .SH "AUTHOR"
 310 See https://github.com/rust\-lang/rust/graphs/contributors or use `git log --all --format='%cN <%cE>' | sort -u` in the rust source distribution.
 311
 312 .SH "COPYRIGHT"
 313 This work is dual\[hy]licensed under Apache\ 2.0 and MIT terms.
 314 See \fICOPYRIGHT\fR file in the rust source distribution.