RUSTC(1)

📦 version 1.97.1, in ubuntu stonking

✨ RUSTC(1) ✨

okay bestie, sit down, hydrate, because we're about to talk about rustc, which is the Rust compiler, and also lowkey the moment your .rs file stops being vibes and starts being a binary. this is the rustc(1) manual, User Commands edition, and yes i'm gonna walk you through every single flag like it's a group chat recap. no skips. no "we'll get to that later." we're doing all of it. 💅

🌸 NAME 🌸

rustc — The Rust compiler. that's it. that's the name. iconic, honestly. 👑

🦋 SYNOPSIS 🦋

rustc [OPTIONS] INPUT

like… that's the whole thing. options, then the input file, go. slay.

💜 DESCRIPTION 💜

okay so this program is a compiler for the Rust language, and if you wanna find the language itself it lives at https://www.rust-lang.org. that's the whole description. short. mysterious. main character energy. 🫶

🎀 OPTIONS 🎀

here's where it gets juicy. every flag, right here, no crumbs left behind.

  • -h, --help — shows you the help message. when in doubt, bestie, ask for help. 🙈
  • --cfg SPEC — configure the compilation environment. you're setting the vibe of the build.
  • -L [KIND=]PATH — adds a directory to the library search path. the KIND part is optional, and when you use it, it can be exactly one of these:
    • dependency — only lookup transitive dependencies here
    • crate — only lookup local extern crate directives here
    • native — only lookup native libraries here
    • framework — only look for OSX frameworks here
    • all — look for anything here (this one's the default 💖)
  • -l [KIND=]NAME — links the generated crate(s) to the library called NAME. KIND is optional and can be static, dylib, or framework. if you skip it entirely, dylib is assumed. not me reminding you about defaults 😭
  • --crate-type [bin|lib|rlib|dylib|cdylib|staticlib|proc-macro] — a comma separated list of the types of crates the compiler should emit. pick your fighter(s).
  • --crate-name NAME — tells the compiler what the crate being built is called. name it like you mean it.
  • --emit [asm|llvm-bc|llvm-ir|obj|metadata|link|dep-info|mir][=PATH] — configures the output rustc will produce. each emission can also have its own optional explicit output PATH for that particular emission kind. heads up: that path takes precedence over the -o option. periodt. 🔥
  • --print [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] — a comma separated list of compiler info to print on stdout. it's giving "tell me everything about yourself" and honestly? respect. ⭐
  • -g — equivalent to -C debuginfo=2.
  • -O — equivalent to -C opt-level=2.
  • -o FILENAME — writes output to FILENAME. it gets ignored if multiple --emit outputs are specified which don't have an explicit path otherwise. read that twice, bestie, it matters. 👀
  • --out-dir DIR — writes output to a compiler-chosen filename inside DIR. ignored if -o is specified. defaults to the current directory.
  • --explain OPT — gives you a detailed explanation of an error message. like a translator for when the compiler yells at you 🥺
  • --test — builds a test harness.
  • --target TARGET — the target tuple for which the code is compiled. this option defaults to the host's target tuple. the target tuple has the general format <arch><sub>-<vendor>-<sys>-<abi>, where:
    • <arch> — x86, arm, thumb, mips, etc.
    • <sub> — for example on ARM: v5, v6m, v7a, v7m, etc.
    • <vendor> — pc, apple, nvidia, ibm, etc.
    • <sys> — none, linux, win32, darwin, cuda, etc.
    • <abi> — eabi, gnu, android, macho, elf, etc.
  • -W help — prints 'lint' options and their default settings. a little lint menu. bon appétit 🍓
  • -W OPT, --warn OPT — sets lint warnings.
  • -A OPT, --allow OPT — sets lint allowed.
  • -D OPT, --deny OPT — sets lint denied.
  • -F OPT, --forbid OPT — sets lint forbidden. the final boss of lint levels 💀
  • -C FLAG[=VAL], --codegen FLAG[=VAL] — sets a codegen-related flag to the value you specified. use -C help to print the available flags. and like… see CODEGEN OPTIONS below, because we're going there. (spoiler: it's a whole section) 🌈
  • -V, --version — prints version info and exits. the "who even am i" flag.
  • -v, --verbose — use verbose output. more words. more info. more everything. 📢
  • --remap-path-prefix from=to — remaps source path prefixes in all output, including compiler diagnostics, debug information, macro expansions, etc. the from=to parameter is scanned from right to left, so from may contain '=', but to may not.

this is useful for normalizing build products — for example, by removing the current directory out of pathnames emitted into the object files. the replacement is purely textual, with no consideration of the current system's pathname syntax. for example, --remap-path-prefix foo=bar will match foo/lib.rs but not ./foo/lib.rs. that last bit is a jump scare, bestie, write it down. 😭

  • --extern NAME=PATH — specifies where an external rust library is located. these should match extern declarations in the crate's source code.
  • --sysroot PATH — overrides the system root.
  • -Z FLAG — sets unstable / perma-unstable options. use -Z help to print the available options. (iykyk 🧚)
  • --color auto|always|never — configures coloring of the output:
    • auto — colorize, if output goes to a tty (this is the default);
    • always — always colorize output;
    • never — never colorize output.

🔥 CODEGEN OPTIONS 🔥

bestie these are the -C / --codegen flags and there are. so. many. every single one below, no cap.

  • linker=/path/to/cc — path to the linker utility to use when linking libraries, executables, and objects.
  • link-args='-flag1 -flag2' — a space-separated list of extra arguments to pass to the linker when the linker is invoked.
  • lto — performs LLVM link-time optimizations.
  • target-cpu=help — selects a target processor. if the value is 'help', then a list of available CPUs is printed.
  • target-feature='+feature1,-feature2' — a comma-separated list of features to enable or disable for the target. a preceding '+' enables a feature while a preceding '-' disables it. available features can be discovered through llc -mcpu=help.
  • passes=val — a space-separated list of extra LLVM passes to run. a value of 'list' will cause rustc to print all known passes and exit. the passes specified are appended at the end of the normal pass manager.
  • llvm-args='-arg1 -arg2' — a space-separated list of arguments to pass through to LLVM.
  • save-temps — if specified, the compiler will save more files (.bc, .o, .no-opt.bc) generated throughout compilation in the output directory. hoarder behavior, but make it compiling 🎀
  • rpath — if specified, then the rpath value for dynamic libraries will be set in either dynamic library or executable outputs.
  • no-prepopulate-passes — suppresses pre-population of the LLVM pass manager that is run over the module.
  • no-vectorize-loops — suppresses running the loop vectorization LLVM pass, regardless of optimization level.
  • no-vectorize-slp — suppresses running the LLVM SLP vectorization pass, regardless of optimization level.
  • soft-float — generates software floating point library calls instead of hardware instructions.
  • prefer-dynamic — prefers dynamic linking to static linking.
  • no-integrated-as — force usage of an external assembler rather than LLVM's integrated one. it's giving "i don't trust the built-in one" 💅
  • no-redzone — disables the use of the redzone.
  • relocation-model=[pic,static,dynamic-no-pic] — the relocation model to use. (Default: pic)
  • code-model=[small,kernel,medium,large] — choose the code model to use.
  • metadata=val — metadata to mangle symbol names with.
  • extra-filename=val — extra data to put in each output filename.
  • codegen-units=n — divides the crate into n units to optimize in parallel. multitasking icon 💖
  • remark=val — print remarks for these optimization passes (space separated, or "all").
  • no-stack-check — disables checks for stack exhaustion. this one is a memory-safety hazard! a real one! not a cute one! be careful bestie 😭
  • debuginfo=val — the debug info emission level:
    • 0 — no debug info;
    • 1 — line-tables only (for stacktraces and breakpoints);
    • 2 — full debug info with variable and type information.
  • opt-level=VAL — optimizes with possible levels 0–3, s (optimize for size), or z (for minimal size).

🌈 ENVIRONMENT 🌈

some of these affect only test harness programs (the ones generated via rustc --test); others affect all programs which link to the Rust standard library. read carefully, they're not all the same kind of thing.

  • RUST_TEST_THREADS — the test framework Rust provides executes tests in parallel. this variable sets the maximum number of threads used for that purpose. this setting is overridden by the --test-threads option.
  • RUST_TEST_NOCAPTURE — if set to a value other than "0", it's a synonym for the --nocapture flag.
  • RUST_MIN_STACK — sets the minimum stack size for new threads.
  • RUST_BACKTRACE — if set to a value different than "0", produces a backtrace in the output of a program which panics. your little "what even happened here" receipt 🫶

⭐ EXAMPLES ⭐

okay bestie here's what it actually looks like in the wild.

to build an executable from a source file with a main function:

$ rustc -o hello hello.rs

to build a library from a source file:

$ rustc --crate-type=lib hello-lib.rs

to build either with a crate (.rs) file:

$ rustc hello.rs

to build an executable with debug info:

$ rustc -g -o hello hello.rs

ate. every time. 🔥

💅 SEE ALSO 💅

👑 BUGS 👑

see https://github.com/rust-lang/rust/issues for issues. (if you found one… first of all sorry, second of all, tell them, they're lovely about it)

🧚 AUTHOR 🧚

see https://github.com/rust-lang/rust/graphs/contributors — or, if you're feeling fancy and you have the rust source distribution lying around, run this:

git log --all --format='%cN <%cE>' | sort -u

this work is dual-licensed under Apache 2.0 and MIT terms. see the COPYRIGHT file in the rust source distribution for the full details.

okay that's the whole page, bestie, you made it to the end and i'm so proud of you 🫶 one last thing for the sign-off — this was rustc 1.97.1 (8bab26f4f 2026-07...), dated April 2019, and it lives in section RUSTC(1) of the manual. go compile something cute. mwah. 💖✨

📦 where this page comes from