mohitmishra786/rustc-basics

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