In Cargo, what changes when you run `cargo build --release` instead of `cargo build`, and which profile settings cause it?
answer
- two built-in profiles
- optimisation level zero versus three
- debug info and runtime checks
- target/debug versus target/release
basics
~20 sPlain cargo build uses the dev profile: opt-level 0, full debug info, debug assertions and overflow checks on, incremental. The --release flag selects the release profile: opt-level 3, no debug info, both checks off, so builds are slower and binaries faster.
solid answer
~40 sCargo compiles every build under a **profile**. `cargo build`, `run` and `check` use `dev`: `opt-level = 0`, `debug = true` (full debug info), `debug-assertions = true`, `overflow-checks = true`, `incremental = true`, `codegen-units = 256`. `--release` is the same as `--profile release`: `opt-level = 3`, `debug = false`, both checks off, `incremental = false`, `codegen-units = 16`. The result is a slower compile and a much faster binary in which `debug_assert!` is compiled out and integer overflow wraps instead of panicking. Output lands in `target/debug` or `target/release`. `cargo test` uses the `test` profile, which inherits `dev`; `cargo bench` uses `bench`, which inherits `release`; `cargo install` builds with `release` unless told otherwise.
code
rust · 9 linesuse std::hint::black_box;
fn main() {
let hp: u8 = black_box(250);
let heal: u8 = black_box(10);
debug_assert!(heal <= 5, "heal {heal} exceeds the cap");
let total = hp + heal;
println!("total = {total}");
}go deeper
Recall the two profiles, that --release means --profile release, and the headline defaults: opt-level 0 vs 3, debug info on vs off, and the target/debug and target/release folders.
Explain every changed default, including debug-assertions, overflow-checks, incremental and codegen-units, and which profile cargo test, cargo bench and cargo install pick by default.
Show you know which default bites in production: overflow wrapping silently and debug_assert! vanishing, and when to switch overflow-checks back on in the release profile.
Treat the defaults as a starting point the team owns: which ones you would change in the root manifest, and how you would keep local builds fast while shipping tuned artifacts.
## What a profile is A **profile** is a named bundle of compiler settings that Cargo turns into `rustc` flags. You never pass `-C opt-level=3` by hand: Cargo picks a profile for the command you ran, reads its settings, and passes the matching flags to every crate it compiles. Cargo has four built-in profiles — `dev`, `release`, `test` and `bench` — and you can change any of them with a `[profile.<name>]` table in the workspace's root `Cargo.toml`. The two you meet first are `dev` (what `cargo build` and `cargo run` use) and `release` (what `--release` selects). The `--release` flag is exactly `--profile release`, and Cargo rejects a command that passes both. ## The two defaults side by side These are the defaults the Cargo book lists for both profiles: | setting | `dev` | `release` | what it controls | |---|---|---|---| | `opt-level` | `0` | `3` | how hard LLVM optimises | | `debug` | `true` (full) | `false` (none) | debug information in the binary | | `debug-assertions` | `true` | `false` | `cfg(debug_assertions)` and `debug_assert!` | | `overflow-checks` | `true` | `false` | panic on integer overflow | | `incremental` | `true` | `false` | reuse of previous compilation work | | `codegen-units` | `256` | `16` | how many pieces a crate is split into | | `lto` | `false` | `false` | link-time optimisation (none across crates) | | `panic` | `"unwind"` | `"unwind"` | the panic strategy | So `--release` does not just "add optimisation". It switches off two families of runtime checks and stops writing debug info as well. ## What you notice when you switch - **Speed of the program.** `opt-level = 3` lets LLVM inline, vectorise and remove dead code; tight loops often run many times faster than at `opt-level = 0`. - **Speed of the build.** Optimisation passes cost time, incremental compilation is off and fewer codegen units means less parallelism, so a release build is slower to produce. - **Assertions.** `debug_assert!` is compiled out because `debug-assertions` is `false`; plain `assert!` still runs in every profile. - **Overflow.** With `overflow-checks = false`, `250u8 + 10` wraps to `4` instead of panicking with `attempt to add with overflow`. What overflow *means* in code is the language's business; Cargo only decides whether the check is compiled in. - **Debugging.** `dev` carries full debug info for a debugger; `release` carries none. - **Where the binary goes.** Each profile writes to a directory under `target/`: `target/debug` for `dev`, `target/release` for `release`, `target/<name>` for a custom profile. The `Finished` line names the profile: ``Finished `dev` profile [unoptimized + debuginfo]`` versus ``Finished `release` profile [optimized]``. ## Which command picks which profile 1. `cargo build`, `cargo run`, `cargo check` and `cargo rustc` default to `dev`. 2. `cargo test` defaults to `test`, which has `inherits = "dev"`. 3. `cargo bench` defaults to `bench`, which has `inherits = "release"`. 4. `cargo install` defaults to `release`; `cargo install --debug` uses the `debug` profile, which inherits `dev`. 5. `--release` or `--profile NAME` overrides the default, and the chosen profile applies to every Cargo target in the build — library, binaries, examples, tests and benchmarks. That `debug` profile can also be selected with `--profile debug`; it writes to `target/debug` like `dev`. ## Changing one setting Any key can be overridden in the root manifest, and the rest keep their defaults: ```toml [profile.release] overflow-checks = true ``` With that table, a release build of the same `250u8 + 10` panics with `attempt to add with overflow`, while `debug_assert!` stays compiled out — the two settings are independent keys even though both default to `true` in `dev` and `false` in `release`. ## Why the defaults look like this The two profiles serve two different moments in a developer's day: - **`dev` optimises for the edit-compile-run loop.** No optimisation, many codegen units and incremental compilation mean a small change rebuilds in seconds, and full debug info plus the runtime checks catch mistakes close to where they happen. - **`release` optimises for the person running the program.** Optimisation is on, the checks that cost time on every arithmetic operation or assertion are off, and nothing is spent on debug info nobody ships. - **`test` and `bench` follow the same split.** Tests inherit `dev` so they build fast and keep their checks; benchmarks inherit `release` so the numbers describe optimised code. ## Common confusions - `--release` is not a strip step: the code is compiled differently, not just shrunk. - `cargo test` does not run in release mode unless you pass `--release`. - `debug` (debug info) and `debug-assertions` (the `cfg` and `debug_assert!`) are different keys.
- Why does a release build take longer to compile than a dev build?`opt-level = 3` runs LLVM's optimisation passes, `incremental` is off so nothing is reused from the previous build, and `codegen-units = 16` instead of `256` gives the compiler fewer pieces to process in parallel. The time is spent once so the program runs faster afterwards.
- Can a release build still panic on integer overflow?Yes. Set `overflow-checks = true` under `[profile.release]` in the root manifest. Every checked arithmetic operation then panics on overflow, at a small runtime cost. `debug-assertions` stays `false`, so `debug_assert!` remains compiled out; the two keys are independent.
- Which profile does `cargo check` use, and why does that matter?`cargo check` defaults to `dev`, like `build` and `run`, and accepts `--release` or `--profile`. Profile settings that affect `cfg`, such as `debug-assertions` turning on `cfg(debug_assertions)`, can change which code gets checked, so `cargo check --release` can report errors that plain `cargo check` does not.
The dev profile is a draft kept with margin notes and spell-check on, quick to revise; the release profile is the typeset print run: slower to produce, faster to read, with the notes and checks left out.
- --release only strips symbols; the code is compiled the same way.
- Integer overflow panics in release builds exactly as in dev builds.
- cargo test builds with the release profile by default.
- debug_assert! still runs in release builds, just more quietly.
- Release builds compile faster because they skip debug info.
- The debug key and debug-assertions are the same setting.