rustc Basics

Purpose

Guide agents through Rust compiler invocation: RUSTFLAGS, Cargo profile configuration, build modes, MIR and assembly inspection, monomorphization, and common compilation error patterns.

Triggers

"How do I configure a release build in Rust for maximum performance?"
"How do I see the assembly output for a Rust function?"
"What is monomorphization and why is it making my compile slow?"
"How do I enable LTO in Rust?"
"My Rust binary is too large — how do I shrink it?"
"How do I read Rust MIR output?"

Workflow

1. Choose a build mode

# Debug (default) — fast compile, no optimization, debug info
cargo build

# Release — optimized, no debug info by default
cargo build --release

# Check only (fastest, no codegen)
cargo check

# Build for specific target
cargo build --release --target aarch64-unknown-linux-gnu

2. Cargo.toml profile configuration

[profile.release]
opt-level = 3          # 0-3, "s" (size), "z" (aggressive size)
debug = false          # true = full, 1 = line tables only, 0 = none
lto = "thin"           # false | "thin" | true (fat LTO)
codegen-units = 1      # 1 = max optimization, higher = faster compile
panic = "abort"        # "unwind" (default) | "abort" (smaller binary)
strip = "symbols"      # "none" | "debuginfo" | "symbols"
overflow-checks = false # default true in debug, false in release

[profile.release-with-debug]
inherits = "release"
debug = true           # release build with debug symbols
strip = "none"

[profile.dev]
opt-level = 1          # Speed up debug builds slightly

Setting	Impact
`lto = true` (fat)	Best optimization, slowest link
`lto = "thin"`	Good optimization, parallel link
`codegen-units = 1`	Best inlining, slower compile
`panic = "abort"`	Removes unwind tables, smaller binary
`opt-level = "z"`	Aggressive size reduction

3. RUSTFLAGS

# Set for a single build
RUSTFLAGS="-C target-cpu=native" cargo build --release

# Enable all target CPU features
RUSTFLAGS="-C target-cpu=native -C target-feature=+avx2,+bmi2" cargo build --release

# Control codegen at invocation level
RUSTFLAGS="-C opt-level=3 -C codegen-units=1 -C lto=on" cargo build --release

Persistent in .cargo/config.toml:

[build]
rustflags = ["-C", "target-cpu=native"]

[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "target-cpu=native", "-C", "link-arg=-fuse-ld=lld"]

4. Inspect assembly output

# Using cargo-show-asm (recommended)
cargo install cargo-show-asm
cargo asm --release 'myapp::module::function_name'

# Using rustc directly
rustc --emit=asm -C opt-level=3 -C target-cpu=native src/lib.rs
cat lib.s

# View MIR (mid-level IR, before codegen)
rustc --emit=mir -C opt-level=3 src/lib.rs
cat lib.mir

# View LLVM IR
rustc --emit=llvm-ir -C opt-level=3 src/lib.rs
cat lib.ll

# Use Compiler Explorer (Godbolt) patterns locally
RUSTFLAGS="--emit=asm" cargo build --release
find target/ -name "*.s"

5. Understand monomorphization

Rust generics are monomorphized — each concrete type instantiation produces separate code. This causes:

Binary size bloat
Longer compile times
Potential i-cache pressure

# Measure monomorphization bloat
cargo install cargo-llvm-lines
cargo llvm-lines --release | head -30

# Shows: lines of LLVM IR per function (monomorphized copies visible)

Mitigation strategies:

// 1. Type erasure with dyn Trait (trades monomorphization for dispatch)
fn process(iter: &mut dyn Iterator<Item = i32>) { ... }

// 2. Non-generic inner function pattern
fn my_generic<T: AsRef<str>>(s: T) {
    fn inner(s: &str) { /* actual work */ }
    inner(s.as_ref())  // monomorphization only in thin wrapper
}

6. Binary size reduction

[profile.release]
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"
strip = "symbols"

# Check binary size breakdown
cargo install cargo-bloat
cargo bloat --release --crates      # per-crate size
cargo bloat --release -n 20         # top 20 largest functions

# Compress executable (at cost of startup time)
upx --best --lzma target/release/myapp

7. Common error triage

Error	Cause	Fix
`cannot find function in this scope`	Missing `use` or wrong module path	Add `use crate::module::fn_name`
`the trait X is not implemented for Y`	Missing impl or wrong generic bound	Implement trait or adjust bounds
`lifetime may not live long enough`	Borrow checker lifetime issue	Add explicit lifetime annotations
`cannot borrow as mutable because also borrowed as immutable`	Aliasing violation	Restructure borrows to not overlap
`use of moved value`	Value used after `move` into closure or function	Use `.clone()` or borrow instead
`mismatched types: expected &str found String`	String vs &str confusion	Use `.as_str()` or `&my_string`

8. Useful rustc flags

# Show all enabled features at a given opt level
rustc -C opt-level=3 --print cfg

# List available targets
rustc --print target-list

# Show target-specific features
rustc --print target-features --target x86_64-unknown-linux-gnu

# Explain an error code
rustc --explain E0382

For RUSTFLAGS reference and Cargo profile patterns, see references/rustflags-profiles.md.

Related skills

Use skills/rust/cargo-workflows for workspace management and Cargo tooling
Use skills/rust/rust-debugging for debugging Rust binaries with GDB/LLDB
Use skills/rust/rust-profiling for profiling and flamegraphs
Use skills/rust/rust-sanitizers-miri for memory safety validation

rustc-basics