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

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

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

RUSTFLAGS and Cargo Profiles Reference

RUSTFLAGS Complete Reference

Codegen flags (-C)

Emit flags (--emit)

# Multiple outputs
rustc --emit=asm,llvm-ir,mir src/lib.rs

# In cargo:
RUSTFLAGS="--emit=asm" cargo build --release

Cargo Profile Options (Complete)

[profile.release]
# Optimization
opt-level = 3                    # 0|1|2|3|"s"|"z"
lto = "thin"                     # false|"thin"|true
codegen-units = 1                # integer

# Debug information
debug = 0                        # false|0|"line-directives-only"|"line-tables-only"|1|true|2|"full"
debug-assertions = false         # bool
split-debuginfo = "off"          # "off"|"packed"|"unpacked"

# Runtime behavior
panic = "abort"                  # "unwind"|"abort"
overflow-checks = false          # bool
rpath = false                    # bool

# Output
strip = "none"                   # "none"|"debuginfo"|"symbols"
incremental = false              # bool

# Build performance
build-override = {}              # Override for build scripts

Profile Inheritance

# Custom profiles must inherit from dev or release
[profile.production]
inherits = "release"
lto = true
codegen-units = 1
panic = "abort"
strip = "symbols"

[profile.staging]
inherits = "release"
debug = 1
strip = "none"

Per-Package Profile Overrides

# Override profile for specific dependencies
[profile.release.package.serde]
opt-level = 3

[profile.dev.package."*"]
opt-level = 1    # Optimize all deps even in dev mode

Common Configurations

Maximum performance

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

# .cargo/config.toml
[build]
rustflags = ["-C", "target-cpu=native"]

Minimum binary size

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

Fast CI builds

[profile.dev]
opt-level = 0
incremental = true

[profile.dev.package."*"]
opt-level = 1    # Compiled deps faster than test code

Linker Configuration

# .cargo/config.toml

# Use mold (fastest linker)
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

# Use lld
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

# macOS with lld
[target.x86_64-apple-darwin]
rustflags = ["-C", "link-arg=-fuse-ld=/usr/local/bin/lld"]

x86-64 Microarchitecture Levels

# Broadwell and newer (most cloud VMs)
RUSTFLAGS="-C target-cpu=x86-64-v3" cargo build --release

# Cascade Lake and newer (AVX-512)
RUSTFLAGS="-C target-cpu=x86-64-v4" cargo build --release

# Specific CPUs
RUSTFLAGS="-C target-cpu=skylake" cargo build --release
RUSTFLAGS="-C target-cpu=znver3" cargo build --release  # AMD Zen3