Skip to content

Commit b35bb1b

Browse files
borsbors
committed
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.
2 parents 86d057c + dda81d3 commit b35bb1b

29 files changed

+430
-281
lines changed

‎src/cargo/core/features.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ features! {
190190
[unstable] publish_lockfile: bool,
191191

192192
// Overriding profiles for dependencies.
193-
[unstable] profile_overrides: bool,
193+
[stable] profile_overrides: bool,
194194

195195
// Separating the namespaces for features and dependencies
196196
[unstable] namespaced_features: bool,

‎src/doc/man/cargo-bench.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ include::options-jobs.adoc[]
111111

112112
Profiles may be used to configure compiler options such as optimization levels
113113
and debug settings. See
114-
linkcargo:reference/manifest.html#the-profile-sections[the reference]
114+
linkcargo:reference/profiles.html[the reference]
115115
for more details.
116116

117117
Benchmarks are always built with the `bench` profile. Binary and lib targets

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -432,7 +432,7 @@ <h2 id="cargo_bench_profiles">PROFILES</h2>
432432
<div class="paragraph">
433433
<p>Profiles may be used to configure compiler options such as optimization levels
434434
and debug settings. See
435-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
435+
<a href="../reference/profiles.html">the reference</a>
436436
for more details.</p>
437437
</div>
438438
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -372,7 +372,7 @@ <h2 id="cargo_build_profiles">PROFILES</h2>
372372
<div class="paragraph">
373373
<p>Profiles may be used to configure compiler options such as optimization levels
374374
and debug settings. See
375-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
375+
<a href="../reference/profiles.html">the reference</a>
376376
for more details.</p>
377377
</div>
378378
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -363,7 +363,7 @@ <h2 id="cargo_check_profiles">PROFILES</h2>
363363
<div class="paragraph">
364364
<p>Profiles may be used to configure compiler options such as optimization levels
365365
and debug settings. See
366-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
366+
<a href="../reference/profiles.html">the reference</a>
367367
for more details.</p>
368368
</div>
369369
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -333,7 +333,7 @@ <h2 id="cargo_doc_profiles">PROFILES</h2>
333333
<div class="paragraph">
334334
<p>Profiles may be used to configure compiler options such as optimization levels
335335
and debug settings. See
336-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
336+
<a href="../reference/profiles.html">the reference</a>
337337
for more details.</p>
338338
</div>
339339
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -434,7 +434,7 @@ <h2 id="cargo_fix_profiles">PROFILES</h2>
434434
<div class="paragraph">
435435
<p>Profiles may be used to configure compiler options such as optimization levels
436436
and debug settings. See
437-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
437+
<a href="../reference/profiles.html">the reference</a>
438438
for more details.</p>
439439
</div>
440440
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -285,7 +285,7 @@ <h2 id="cargo_run_profiles">PROFILES</h2>
285285
<div class="paragraph">
286286
<p>Profiles may be used to configure compiler options such as optimization levels
287287
and debug settings. See
288-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
288+
<a href="../reference/profiles.html">the reference</a>
289289
for more details.</p>
290290
</div>
291291
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -346,7 +346,7 @@ <h2 id="cargo_rustc_profiles">PROFILES</h2>
346346
<div class="paragraph">
347347
<p>Profiles may be used to configure compiler options such as optimization levels
348348
and debug settings. See
349-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
349+
<a href="../reference/profiles.html">the reference</a>
350350
for more details.</p>
351351
</div>
352352
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ <h2 id="cargo_rustdoc_profiles">PROFILES</h2>
361361
<div class="paragraph">
362362
<p>Profiles may be used to configure compiler options such as optimization levels
363363
and debug settings. See
364-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
364+
<a href="../reference/profiles.html">the reference</a>
365365
for more details.</p>
366366
</div>
367367
<div class="paragraph">

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -462,7 +462,7 @@ <h2 id="cargo_test_profiles">PROFILES</h2>
462462
<div class="paragraph">
463463
<p>Profiles may be used to configure compiler options such as optimization levels
464464
and debug settings. See
465-
<a href="../reference/manifest.html#the-profile-sections">the reference</a>
465+
<a href="../reference/profiles.html">the reference</a>
466466
for more details.</p>
467467
</div>
468468
<div class="paragraph">

‎src/doc/man/section-profiles.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Profiles may be used to configure compiler options such as optimization levels
44
and debug settings. See
5-
linkcargo:reference/manifest.html#the-profile-sections[the reference]
5+
linkcargo:reference/profiles.html[the reference]
66
for more details.
77

88
Profile selection depends on the target and crate being built. By default the

‎src/doc/src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
* [Cargo Reference](reference/index.md)
2222
* [Specifying Dependencies](reference/specifying-dependencies.md)
2323
* [The Manifest Format](reference/manifest.md)
24+
* [Profiles](reference/profiles.md)
2425
* [Configuration](reference/config.md)
2526
* [Environment Variables](reference/environment-variables.md)
2627
* [Build Scripts](reference/build-scripts.md)

‎src/doc/src/faq.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -81,9 +81,9 @@ packages using Cargo.
8181

8282
### Does Cargo support environments, like `production` or `test`?
8383

84-
We support environments through the use of [profiles][profile] to support:
84+
We support environments through the use of [profiles] to support:
8585

86-
[profile]: reference/manifest.md#the-profile-sections
86+
[profiles]: reference/profiles.md
8787

8888
* environment-specific flags (like `-g --opt-level=0` for development
8989
and `--opt-level=3` for production).

‎src/doc/src/reference/manifest.md

+3-77
Original file line numberDiff line numberDiff line change
@@ -391,83 +391,9 @@ information on the `[dependencies]`, `[dev-dependencies]`,
391391

392392
### The `[profile.*]` sections
393393

394-
Cargo supports custom configuration of how rustc is invoked through profiles at
395-
the top level. Any manifest may declare a profile, but only the top level
396-
package’s profiles are actually read. All dependencies’ profiles will be
397-
overridden. This is done so the top-level package has control over how its
398-
dependencies are compiled.
399-
400-
There are four currently supported profile names, all of which have the same
401-
configuration available to them. Listed below is the configuration available,
402-
along with the defaults for each profile.
403-
404-
```toml
405-
# The development profile, used for `cargo build`.
406-
[profile.dev]
407-
opt-level = 0 # controls the `--opt-level` the compiler builds with.
408-
# 0-1 is good for debugging. 2 is well-optimized. Max is 3.
409-
# 's' attempts to reduce size, 'z' reduces size even more.
410-
debug = true # (u32 or bool) Include debug information (debug symbols).
411-
# Equivalent to `-C debuginfo=2` compiler flag.
412-
rpath = false # controls whether compiler should set loader paths.
413-
# If true, passes `-C rpath` flag to the compiler.
414-
lto = false # Link Time Optimization usually reduces size of binaries
415-
# and static libraries. Increases compilation time.
416-
# If true, passes `-C lto` flag to the compiler, and if a
417-
# string is specified like 'thin' then `-C lto=thin` will
418-
# be passed.
419-
debug-assertions = true # controls whether debug assertions are enabled
420-
# (e.g., debug_assert!() and arithmetic overflow checks)
421-
codegen-units = 16 # if > 1 enables parallel code generation which improves
422-
# compile times, but prevents some optimizations.
423-
# Passes `-C codegen-units`.
424-
panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort'
425-
incremental = true # whether or not incremental compilation is enabled
426-
# This can be overridden globally with the CARGO_INCREMENTAL
427-
# environment variable or `build.incremental` config
428-
# variable. Incremental is only used for path sources.
429-
overflow-checks = true # use overflow checks for integer arithmetic.
430-
# Passes the `-C overflow-checks=...` flag to the compiler.
431-
432-
# The release profile, used for `cargo build --release` (and the dependencies
433-
# for `cargo test --release`, including the local library or binary).
434-
[profile.release]
435-
opt-level = 3
436-
debug = false
437-
rpath = false
438-
lto = false
439-
debug-assertions = false
440-
codegen-units = 16
441-
panic = 'unwind'
442-
incremental = false
443-
overflow-checks = false
444-
445-
# The testing profile, used for `cargo test` (for `cargo test --release` see
446-
# the `release` and `bench` profiles).
447-
[profile.test]
448-
opt-level = 0
449-
debug = 2
450-
rpath = false
451-
lto = false
452-
debug-assertions = true
453-
codegen-units = 16
454-
panic = 'unwind'
455-
incremental = true
456-
overflow-checks = true
457-
458-
# The benchmarking profile, used for `cargo bench` (and the test targets and
459-
# unit tests for `cargo test --release`).
460-
[profile.bench]
461-
opt-level = 3
462-
debug = false
463-
rpath = false
464-
lto = false
465-
debug-assertions = false
466-
codegen-units = 16
467-
panic = 'unwind'
468-
incremental = false
469-
overflow-checks = false
470-
```
394+
The `[profile]` tables provide a way to customize compiler settings such as
395+
optimizations and debug settings. See [the Profiles chapter](profiles.md) for
396+
more detail.
471397

472398
### The `[features]` section
473399

0 commit comments

Comments
 (0)