cargo new: add a [profile.release] section with commented out suggestions

[nnethercote]

Problem

There are various options you can use to optimize a release build's runtime speed or binary size. I recently rewrote the section in The Rust Performance Book that discusses them. But lots of people don't know about them. We could make them more discoverable.

Proposed Solution

The Cargo.toml produced by cargo new could include a [profile.release] section with some of these options present but commented out, with a brief explanation. This idea was inspired by the config.example.toml file in rustc, which does something similar and which I find extremely useful.

Here is some possible text:

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

# The default settings for release builds are reasonable, but if you want higher performance there
# are several options worth considering. Uncomment the relevant lines to try them.
[profile.release]

# This enables some extra optimization during code generation. It can increase runtime speed and
# reduce binary size at the cost of slower compile times.
#codegen-units = 1

# This enables link-time optimization. It can increase runtime speed and reduce binary size at the
# cost of slower compile times. "thin" is a basic version. "fat" is a more aggressive version that
# may have larger effects.
#lto = "thin"
#lto = "fat"

# This optimizes for code size. It can reduce binary size at the cost of worse runtime speed.
#opt-level = "z"

# This causes your program to immediately abort on panic, which is suitable if you do not need to
# catch or unwind panics. It can reduce binary size and improve runtime speed.
#panic = "abort"

# This causes the compiler to strip some information from the compiled program. This may reduce
# binary size at the cost of making the program more difficult to debug and profile. For example,
# backtraces on panic may be less informative. "debuginfo" strips just debug info. "symbols" strips
# both debug info and symbols.
#strip = "debuginfo"
#strip = "symbols"

Notes

No response

[epage]

In my experience, one of the biggest annoyances of package scaffolding is boilerplate that I have to remove. For example, I'm for removing the existing comment we have in #12210.

If we were to do something like this, we'd need to keep in mind that profile is only relevant for the root manifest, whether its a package without a workspace or a package in a workspace. Currently, we don't support creating workspace packages (see #8365). We do detect if a package would be in a workspace and behave differently (e.g. inherit workspace.package fields)

[rben01]

I think rather than add this boilerplate to every Cargo.toml, I think it'd be better to have a cargo manifest subcommand with the following behavior:

1. cargo manifest print a description of the options (in man page format, or similar; something like ordinary English with full-ish sentences)
2. cargo manifest SECTION filters the above to SECTION (profile.release, package, dependencies…)
3. cargo manifest --toml SECTION prints the default values for SECTION in TOML so you can easily copy paste or do cargo manifest --toml profile.release >> Cargo.toml

Various other options would be possible, such as --include field1,field2 to limit the keys to just those fields, --exclude (self-explanatory), --explained to add a comment above each line explaining what it does and what the permitted values are, --commented to comment out every line so that appending the result to Cargo.toml would have no practical effect, etc.

Anyway regardless of the precise naming and semantics, I think the place to put this functionality is in Cargo itself, not in Cargo.toml when you first set up a project.

[ehuss]

I'm going to move to close this, and defer to #5151. In #6881 the team explicitly decided not to add more boilerplate or content to the default manifest beyond the link to the documentation. I realize discovery and education is difficult, but I think on balance adding a large section that everyone will need to delete has its own downsides. I'm not sure if configurable templates would be the solution, but I think it would be a pre-requisite if we were to decide to make this default to offer a simple way to turn it off.

[weihanglo]

@rben01, thanks for the suggestion. Just FYI, there are some discussion out there in #12114 (comment), which is essentially cargo help <topic> for reading guidance via the help command.

[weihanglo]

Make sense. Thank you people for thinking over this issue. Going to close this in favor of #5151. See #12769 (comment).