Matthew Maurer | bd39854 | 2019-09-05 16:25:08 -0700 | [diff] [blame] | 1 | .TH RUSTC "1" "September 2019" "rustc 1.36.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|\:cfg|\:target\-list|\:target\-cpus|\:target\-features|\:relocation\-models|\:code\-models|\:tls\-models|\:target\-spec\-json|\:native\-static\-libs] |
| 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 internal debugging 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. |