Rust for C-Programmers

23.6 Build Profiles

Build profiles allow you to configure compiler settings for different scenarios when building your package’s crates. Cargo defines four profiles by default: dev, release, test, and bench. The dev and release profiles are the most commonly used.

• dev: The default profile used by cargo build and cargo run. Optimized for fast compilation times.
  • opt-level = 0 (no optimization)
  • debug = true (include debug info)
  • incremental = true (use incremental compilation)
• release: Used when the --release flag is passed. Optimized for runtime performance.
  • opt-level = 3 (maximum optimization)
  • debug = false (omit debug info by default)
  • incremental = false (do not use incremental compilation by default)

You can customize these profiles in Cargo.toml under [profile.*] sections:

[profile.dev]
opt-level = 1    # Enable basic optimizations even in debug builds
# debug = 2      # Use '2' for full debug info, '1' for line tables only, '0' for none
# incremental = true # Default for dev

[profile.release]
lto = "fat"      # Enable "fat" LTO for potentially better performance/size
codegen-units = 1 # Reduce parallelism, potentially better optimization (slower build)
panic = 'abort'   # Abort on panic instead of unwinding (can reduce binary size)
# strip = true    # Strip symbols from the binary (requires Rust 1.59+)
# incremental = false # Default for release

Key profile settings include:

• opt-level: Controls the level of optimization (0, 1, 2, 3, s for size, z for more size).
• debug: Controls the amount of debug information included (true/2, false/0, 1).
• lto: Enables Link-Time Optimization (false, true/“thin”, "fat", "off"). Can improve performance but increases link times.
• codegen-units: Number of parallel code generation units for compiling the package’s crates. More units mean faster compilation but potentially less optimal code. 1 can yield the best optimizations.
• panic: Strategy for handling panics ('unwind' or 'abort') in the compiled code.
• incremental: Explicitly enable or disable incremental compilation (true or false).

Profile settings in a dependency package’s Cargo.toml are ignored; only the settings in the top-level package’s Cargo.toml (the one being built directly) are used.