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.

Author: bors

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">