A Rust command-line tool's release binary is 2.5 MB; which Cargo profile settings make it smaller, and what does each one cost?
answer
- measure one key at a time
- size levels are not guaranteed smaller
- whole-program optimisation at link time
- unwinding tables and the symbol table
basics
~20 sIn the release profile: lto = true, codegen-units = 1, panic = "abort", strip = true and opt-level "s" or "z", each measured alone. They cost build time, backtraces or panic recovery; since Cargo 1.77 debuginfo is already stripped by default.
solid answer
~50 sI would add settings to `[profile.release]` (or a custom profile that inherits it) and measure each one. `lto = true` (fat LTO) optimises across all crates and drops unused code, at the cost of a much slower link. `codegen-units = 1` gives LLVM the whole crate at once, which shrinks and speeds the code but compiles less in parallel. `panic = "abort"` removes unwinding machinery, but a panic then ends the process at once. `strip = true` means `"symbols"`: it removes the symbol table as well as debuginfo, so backtraces lose function names. `opt-level = "s"` or `"z"` optimise for size, but the Cargo book warns they are not necessarily smaller. Since Cargo 1.77, a profile with debug info off already strips debuginfo outside Windows MSVC, so `strip = "debuginfo"` adds nothing to a default release build.
code
toml · 7 lines[profile.min-size]
inherits = "release"
opt-level = "z"
lto = true
codegen-units = 1
panic = "abort"
strip = truego deeper
Recall the five keys that shrink a release build, lto, codegen-units, panic, strip and opt-level "s" or "z", and that they go under a profile table in Cargo.toml.
Explain what each key does and costs, that strip = true means "symbols", and that debuginfo is already stripped by default since Cargo 1.77 outside Windows MSVC.
Insist on measuring one change at a time with -v to confirm the flags, and call out the behaviour changes, abort on panic and lost backtrace names, before accepting the size win.
Weigh size against build minutes and diagnosability, and decide whether size tuning lives in the release profile or in a separate profile used only for shipped artifacts.
## Start from what the release profile already does A **profile** is the bundle of compiler settings Cargo applies to a build; `cargo build --release` uses the `release` profile. Its defaults are tuned for runtime speed, not size: `opt-level = 3`, `debug = false`, `lto = false`, `codegen-units = 16`, `panic = "unwind"`, `strip = "none"`. One detail is easy to miss. **Since Cargo 1.77, turning debug info off implies `strip = "debuginfo"`** when `strip` is not set, so Cargo strips the pre-built debuginfo that the standard library carries. Running `cargo build --release -v` shows `-C strip=debuginfo` on the `rustc` line even though `strip` defaults to `"none"`. Cargo 1.78 stopped doing this on Windows MSVC targets because it broke backtraces there. Writing `strip = "debuginfo"` into a default release profile therefore changes nothing on macOS or Linux. ## The keys that change size | key | what it does | what it costs | |---|---|---| | `lto = true` / `"fat"` | link-time optimisation across every crate in the graph | much longer link; more memory while linking | | `lto = "thin"` | cheaper cross-crate LTO, aimed at speed | may barely change size | | `codegen-units = 1` | the crate is optimised as one unit | slower, less parallel compile | | `panic = "abort"` | no unwinding tables or landing pads | a panic kills the process; no recovery | | `strip = true` (= `"symbols"`) | removes the symbol table and debuginfo | backtraces and profilers lose names | | `opt-level = "s"` / `"z"` | optimise for size; `"z"` also turns off loop vectorisation | can be slower; not always smaller | ## What one measurement showed A small tool built from `clap` and `regex` with Cargo 1.99.1 on aarch64 macOS, each custom profile inheriting `release` and changing one key: - default release: 2,577,104 bytes; - `opt-level = "z"` alone: 2,860,704 bytes — **larger**, exactly the surprise the Cargo book warns about; - `strip = true`: 2,010,096; `lto = true`: 2,025,936; `codegen-units = 1`: 2,035,552; `panic = "abort"`: 2,242,448; - all five together: 1,166,432 bytes, under half the default. The lesson is procedural. Settings interact: `opt-level = "z"` made things worse alone, yet the smallest build combined it with fat LTO and one codegen unit, where LLVM can see enough code to make size choices pay. **Measure each change** on your own binary and target rather than copying a table. ## What each cost means in practice 1. **Build time.** Fat LTO plus `codegen-units = 1` can turn a release build that took seconds into one that takes minutes on a large dependency graph. That is why many teams keep these in a separate custom profile used only for shipped artifacts. 2. **Panic behaviour.** With `panic = "abort"` the process terminates on the first panic: destructors do not run on the way out and nothing can catch the panic. What catching a panic means in code is the language's topic; for the build, the point is that this is a behaviour change, not a free size win. Tests, benchmarks, build scripts and proc macros ignore the `panic` setting. 3. **Diagnostics.** On the same macOS build, `RUST_BACKTRACE=1` on a default release binary listed function names, while the `strip = true` binary listed no frames at all. The panic message, with its file and line, still printed, because that text is compiled into the program. `rustc`'s own documentation advises programs that want crash reporting to avoid `-C strip=symbols`. 4. **Runtime speed.** `"s"` and `"z"` trade speed for size; LTO and one codegen unit usually help both. ## Levers outside the profile Two big ones are not profile keys. Trimming dependency features (turning off a crate's default features) is the job of the feature flags; linker choices belong to Cargo's config file. Both can matter as much as anything above, but they live in other parts of the build. ## Why the combination beat the parts - **Fat LTO** lets the optimiser see across crate boundaries, so code from dependencies that the tool never calls can be dropped. - **One codegen unit** removes the duplication and missed inlining that come from splitting a crate into 16 pieces. - With the whole program visible, **`opt-level = "z"`** has room to choose smaller code paths, a likely reason it helped in combination and hurt alone. ## A sensible order - Confirm you are measuring a `--release` build, not `target/debug`. - Add `lto = true` and `codegen-units = 1`; measure. - Decide deliberately about `panic = "abort"` and `strip = true`, because both change behaviour, not just size. - Try `opt-level = "s"` and `"z"` last, and keep whichever your measurements prefer.
- What do you give up with `strip = true` compared with the default release build?`strip = true` equals `strip = "symbols"`: the symbol table goes as well as debuginfo. On macOS, `RUST_BACKTRACE=1` on such a binary printed no frames, where the default release binary still listed function names. The panic message with file and line survives. `rustc` advises crash-reporting programs to avoid `-C strip=symbols`.
- How do you check which flags a profile actually passes to `rustc`?Run the build with `-v`, for example `cargo build --release -v`. Each `Running` line shows the full `rustc` command, so you can see `-C opt-level=3`, `-C lto`, `-C codegen-units=1` or the implied `-C strip=debuginfo` and confirm the profile you edited is the one in effect.
- Does `lto = false` mean no link-time optimisation at all?No. `lto = false` is the default and means "thin local LTO": thin LTO within the current crate across its codegen units, skipped when `codegen-units` is 1 or `opt-level` is 0. `lto = "off"` disables LTO entirely, and Cargo then passes `-C lto=off`.
- opt-level = "z" on its own always gives the smallest binary.
- Adding strip = "debuginfo" shrinks a default release build on Linux or macOS.
- panic = "abort" only changes the panic message, not the program.
- lto = false means the compiler does no link-time optimisation at all.
- codegen-units = 1 makes release builds compile faster.
- strip = true removes the file and line from panic messages.
Assumes Cargo 1.99; since Cargo 1.77 a profile with debug info off strips debuginfo by default (no longer on Windows MSVC since 1.78).