Auto merge of #7591 - ehuss:stabilize-profile-overrides, r=alexcrichton

Stabilize profile-overrides.

This stabilizes the profile-overrides feature. This was proposed in [RFC 2282](rust-lang/rfcs#2282) and implemented in #5384. Tracking issue is rust-lang/rust#48683.

This is intended to land in 1.41 which will reach the stable channel on Jan 30th.

This includes a new documentation chapter on profiles. See the ["Overrides" section](https://github.com/rust-lang/cargo/blob/9c993a92ce33f219aaaed963bef51fc0f6a7677a/src/doc/src/reference/profiles.md#overrides) in `profiles.md` file for details on what is being stabilized.

Note: The `config-profile` and `named-profiles` features are still unstable.

Closes #6214

**Concerns**
- There is some risk that `build-override` may be confusing with the [proposed future dedicated `build` profile](#6577). There is some more discussion about the differences at rust-lang/rust#48683 (comment). I don't expect it to be a significant drawback. If we proceed later with a dedicated `build` profile, I think we can handle explaining the differences in the documentation. (The linked PR is designed to work with profile-overrides.)
- I don't anticipate any unexpected interactions with `config-profiles` or `named-profiles`.
- Some of the syntax like `"*"` or `build-override` may not be immediately obvious what it means without reading the documentation. Nobody suggested any alternatives, though.
- Configuring overrides for multiple packages is currently a pain, as you have to repeat the settings separately for each package. I propose that we can extend the syntax in the future to allow a comma-separated list of package names to alleviate this concern if it is deemed worthwhile.
- The user may not know which packages to override, particularly for some dependencies that are split across multiple crates. I think, since this is an advanced feature, the user will likely be comfortable with using things like `cargo tree` to understand what needs to be overridden. There is [some discussion](rust-lang/rust#48683 (comment)) in the tracking issue about automatically including a package's dependencies, but this is somewhat complex.
- There is some possibly confusing interaction with the test/bench profile. Because dependencies are always built with the dev/release profiles, overridding test/bench usually does not have an effect (unless specifying a workspace member that is being tested/benched). Overriding test/bench was previously prohibited, but was relaxed when named profiles were added.
- We may want to allow overriding the `panic`, `lto`, and `rpath` settings in the future. I can imagine a case where someone has a large workspace, and wants to override those settings for just one package in the workspace. They are currently not allowed because it doesn't make sense to change those settings for rlibs, and `panic` usually needs to be in sync for the whole profile.
- There are some strange interactions with `dylib` crates detailed in rust-lang/rust#64319. A fix was attempted, but later reverted. Since `dylib` crates are rare (this mostly applied to `libstd`), and a workaround was implemented for `build-std` (it no longer builds a dylib), I'm not too worried about this.
- The interaction with `share-generics` can be quite confusing (see rust-lang/rust#63484). I added a section in the docs that tries to address this concern. It's also possible future versions of `rustc` may handle this better.
- The new documentation duplicates some of the information in the rustc book.  I think it's fine, as there are subtle differences, and it avoids needing to flip back and forth between the two books to learn what the settings do.

src/cargo/core/features.rs

@@ -190,7 +190,7 @@ features! {
         [unstable] publish_lockfile: bool,
 
         // Overriding profiles for dependencies.
-        [unstable] profile_overrides: bool,
+        [stable] profile_overrides: bool,
 
         // Separating the namespaces for features and dependencies
         [unstable] namespaced_features: bool,

src/doc/man/cargo-bench.adoc

@@ -111,7 +111,7 @@ include::options-jobs.adoc[]
 
 Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-linkcargo:reference/manifest.html#the-profile-sections[the reference]
+linkcargo:reference/profiles.html[the reference]
 for more details.
 
 Benchmarks are always built with the `bench` profile. Binary and lib targets

src/doc/man/generated/cargo-bench.html

@@ -432,7 +432,7 @@ <h2 id="cargo_bench_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-build.html

@@ -372,7 +372,7 @@ <h2 id="cargo_build_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-check.html

@@ -363,7 +363,7 @@ <h2 id="cargo_check_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-doc.html

@@ -333,7 +333,7 @@ <h2 id="cargo_doc_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-fix.html

@@ -434,7 +434,7 @@ <h2 id="cargo_fix_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-run.html

@@ -285,7 +285,7 @@ <h2 id="cargo_run_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-rustc.html

@@ -346,7 +346,7 @@ <h2 id="cargo_rustc_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-rustdoc.html

@@ -361,7 +361,7 @@ <h2 id="cargo_rustdoc_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/generated/cargo-test.html

@@ -462,7 +462,7 @@ <h2 id="cargo_test_profiles">PROFILES</h2>
 <div class="paragraph">
 <p>Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-<a href="../reference/manifest.html#the-profile-sections">the reference</a>
+<a href="../reference/profiles.html">the reference</a>
 for more details.</p>
 </div>
 <div class="paragraph">

src/doc/man/section-profiles.adoc

@@ -2,7 +2,7 @@
 
 Profiles may be used to configure compiler options such as optimization levels
 and debug settings. See
-linkcargo:reference/manifest.html#the-profile-sections[the reference]
+linkcargo:reference/profiles.html[the reference]
 for more details.
 
 Profile selection depends on the target and crate being built. By default the

src/doc/src/SUMMARY.md

@@ -21,6 +21,7 @@
 * [Cargo Reference](reference/index.md)
     * [Specifying Dependencies](reference/specifying-dependencies.md)
     * [The Manifest Format](reference/manifest.md)
+    * [Profiles](reference/profiles.md)
     * [Configuration](reference/config.md)
     * [Environment Variables](reference/environment-variables.md)
     * [Build Scripts](reference/build-scripts.md)

src/doc/src/faq.md

@@ -81,9 +81,9 @@ packages using Cargo.
 
 ### Does Cargo support environments, like `production` or `test`?
 
-We support environments through the use of [profiles][profile] to support:
+We support environments through the use of [profiles] to support:
 
-[profile]: reference/manifest.md#the-profile-sections
+[profiles]: reference/profiles.md
 
 * environment-specific flags (like `-g --opt-level=0` for development
   and `--opt-level=3` for production).

src/doc/src/reference/manifest.md

@@ -391,83 +391,9 @@ information on the `[dependencies]`, `[dev-dependencies]`,
 
 ### The `[profile.*]` sections
 
-Cargo supports custom configuration of how rustc is invoked through profiles at
-the top level. Any manifest may declare a profile, but only the top level
-package’s profiles are actually read. All dependencies’ profiles will be
-overridden. This is done so the top-level package has control over how its
-dependencies are compiled.
-
-There are four currently supported profile names, all of which have the same
-configuration available to them. Listed below is the configuration available,
-along with the defaults for each profile.
-
-```toml
-# The development profile, used for `cargo build`.
-[profile.dev]
-opt-level = 0      # controls the `--opt-level` the compiler builds with.
-                   # 0-1 is good for debugging. 2 is well-optimized. Max is 3.
-                   # 's' attempts to reduce size, 'z' reduces size even more.
-debug = true       # (u32 or bool) Include debug information (debug symbols).
-                   # Equivalent to `-C debuginfo=2` compiler flag.
-rpath = false      # controls whether compiler should set loader paths.
-                   # If true, passes `-C rpath` flag to the compiler.
-lto = false        # Link Time Optimization usually reduces size of binaries
-                   # and static libraries. Increases compilation time.
-                   # If true, passes `-C lto` flag to the compiler, and if a
-                   # string is specified like 'thin' then `-C lto=thin` will
-                   # be passed.
-debug-assertions = true # controls whether debug assertions are enabled
-                   # (e.g., debug_assert!() and arithmetic overflow checks)
-codegen-units = 16 # if > 1 enables parallel code generation which improves
-                   # compile times, but prevents some optimizations.
-                   # Passes `-C codegen-units`.
-panic = 'unwind'   # panic strategy (`-C panic=...`), can also be 'abort'
-incremental = true # whether or not incremental compilation is enabled
-                   # This can be overridden globally with the CARGO_INCREMENTAL
-                   # environment variable or `build.incremental` config
-                   # variable. Incremental is only used for path sources.
-overflow-checks = true # use overflow checks for integer arithmetic.
-                   # Passes the `-C overflow-checks=...` flag to the compiler.
-
-# The release profile, used for `cargo build --release` (and the dependencies
-# for `cargo test --release`, including the local library or binary).
-[profile.release]
-opt-level = 3
-debug = false
-rpath = false
-lto = false
-debug-assertions = false
-codegen-units = 16
-panic = 'unwind'
-incremental = false
-overflow-checks = false
-
-# The testing profile, used for `cargo test` (for `cargo test --release` see
-# the `release` and `bench` profiles).
-[profile.test]
-opt-level = 0
-debug = 2
-rpath = false
-lto = false
-debug-assertions = true
-codegen-units = 16
-panic = 'unwind'
-incremental = true
-overflow-checks = true
-
-# The benchmarking profile, used for `cargo bench` (and the test targets and
-# unit tests for `cargo test --release`).
-[profile.bench]
-opt-level = 3
-debug = false
-rpath = false
-lto = false
-debug-assertions = false
-codegen-units = 16
-panic = 'unwind'
-incremental = false
-overflow-checks = false
-```
+The `[profile]` tables provide a way to customize compiler settings such as
+optimizations and debug settings. See [the Profiles chapter](profiles.md) for
+more detail.
 
 ### The `[features]` section