Skip to content

Commit ec38c84

Browse files
borsbors
committed
Auto merge of #9943 - ehuss:stabilize-named-profiles, r=alexcrichton
Stabilize named profiles This stabilizes the named profiles feature. As an overview of what this does, it allows specifying custom named profiles, such as: ```toml [profile.release-lto] inherits = "release" lto = true ``` And enables the use of the `--profile` CLI option to choose a profile by name. Another key change here is that cargo now only uses a single profile per command. Previously, some commands such as `cargo test` would use a mix of profiles based on which package and target were being built. ### Summary of new behavior * Profiles can now have arbitrary names. New profiles require the `inherits` key. * The `--profile` flag is now available on all build commands. * The `CompileMode` is no longer considered for choosing the profile, only one profile will be used. Previously, building a test, benchmark, or doctest would use the test or bench profile, and all dependencies would use the dev/release profiles. This change is done to arguably make it easier to understand, and to possibly give more desired and intuitive behavior. * The `test` profile now inherits settings from the `dev` profile (and `bench` from `release`). ### Deviations from the original RFC and implementation * The original RFC indicated that `--all-targets` without `--profile` would retain the old behavior where it would use different profiles for different targets. However, the implementation uses a single profile, to avoid confusion and to keep things simple. * The `dir-name` key is not exposed to the user. The implementation is retained to handle mapping of built-in profile names (test/dev→debug, bench→release). This can be exposed in the future if necessary. ### Notes about this PR * Fixed an issue where the duplicate package override check would randomly return matches for inherited profiles like `test`. * I left some of the old, vestigial code behind to possibly make it easier to revert this PR if necessary. If this does land, I think it can be eventually removed (code using `Feature::named_profiles` and various things using `named_profiles_enabled`). * Added `target` to reserved list, just because. * Adds a warning if `--release` is combined with `--profile` in `cargo rustc`, `check`, or `fix`. The `--release` flag was being ignored. ### Hazards and concerns * This has had very little real-world testing. * Custom profile directories may conflict with other things in the `target` directory. We have reserved profile names that currently conflict (such as `doc` or `package`). However, they can still collide with target names. This also presents a hazard if Cargo ever wants to add new things to that top directory. We decided to proceed with this because: * We currently have no plans to add new built-in profiles. * We have reserved several profile names (including anything starting with "cargo"), and the profile name syntax is deliberately limited (so cargo is still free to add `.` prefixed hidden directories). * A user creating a profile that collides with a target name resides in the "don't do that" territory. Also, that shouldn't be catastrophic, as the directories are still somewhat organized differently. * Artifacts may no longer be shared in some circumstances. This can lead to substantially increased `target` directory sizes (and build times), particularly if the `test` profile is not the same as the `dev` profile. Previously, dependencies would use the `dev` profile for both. If the user wants to retain the old behavior, they can use an override like `[profile.test.package."*"]` and set the same settings as `dev`. * This may break existing workflows. It is possible, though unlikely, that changes to the profile settings will cause changes to how things build in such a way to break behavior. * Another example is using something like `cargo build` to prime a cache that is used for `cargo test`, and there is a custom `test` profile, the cache will no longer be primed. * The legacy behavior with `cargo rustc`, `cargo check`, and `cargo fix` may be confusing. We may in the future consider something like a `--mode` flag to formalize that behavior. * The `PROFILE` environment variable in build scripts may cause confusion or cause problems since it only sets `release` or `debug`. Some people may be using that to determine if `--release` should be used for a recursive `cargo` invocation. Currently I noted in the documentation that it shouldn't be used. However, I think it could be reasonable to maybe add a separate environment variable (`PROFILE_NAME`?) that exposes the actual profile used. We felt that changing the existing value could cause too much breakage (and the mapping of debug→dev is a little awkward). Closes #6988
2 parents 42035c7 + 595384f commit ec38c84

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+735
-1297
lines changed

‎src/cargo/core/features.rs

+6-3
Original file line numberDiff line numberDiff line change
@@ -387,7 +387,7 @@ features! {
387387
(unstable, public_dependency, "", "reference/unstable.html#public-dependency"),
388388

389389
// Allow to specify profiles other than 'dev', 'release', 'test', etc.
390-
(unstable, named_profiles, "", "reference/unstable.html#custom-named-profiles"),
390+
(stable, named_profiles, "1.57", "reference/profiles.html#custom-profiles"),
391391

392392
// Opt-in new-resolver behavior.
393393
(stable, resolver, "1.51", "reference/resolver.html#resolver-versions"),
@@ -643,7 +643,6 @@ unstable_cli_options!(
643643
minimal_versions: bool = ("Resolve minimal dependency versions instead of maximum"),
644644
mtime_on_use: bool = ("Configure Cargo to update the mtime of used files"),
645645
multitarget: bool = ("Allow passing multiple `--target` flags to the cargo subcommand selected"),
646-
named_profiles: bool = ("Allow defining custom profiles"),
647646
namespaced_features: bool = ("Allow features with `dep:` prefix"),
648647
no_index_update: bool = ("Do not update the registry index even if the cache is outdated"),
649648
panic_abort_tests: bool = ("Enable support to run tests with -Cpanic=abort"),
@@ -699,6 +698,10 @@ const STABILIZED_CONFIGURABLE_ENV: &str = "The [env] section is now always enabl
699698

700699
const STABILIZED_PATCH_IN_CONFIG: &str = "The patch-in-config feature is now always enabled.";
701700

701+
const STABILIZED_NAMED_PROFILES: &str = "The named-profiles feature is now always enabled.\n\
702+
See https://doc.rust-lang.org/nightly/cargo/reference/profiles.html#custom-profiles \
703+
for more information";
704+
702705
fn deserialize_build_std<'de, D>(deserializer: D) -> Result<Option<Vec<String>>, D::Error>
703706
where
704707
D: serde::Deserializer<'de>,
@@ -830,7 +833,7 @@ impl CliUnstable {
830833
"dual-proc-macros" => self.dual_proc_macros = parse_empty(k, v)?,
831834
// can also be set in .cargo/config or with and ENV
832835
"mtime-on-use" => self.mtime_on_use = parse_empty(k, v)?,
833-
"named-profiles" => self.named_profiles = parse_empty(k, v)?,
836+
"named-profiles" => stabilized_warn(k, "1.57", STABILIZED_NAMED_PROFILES),
834837
"binary-dep-depinfo" => self.binary_dep_depinfo = parse_empty(k, v)?,
835838
"build-std" => {
836839
self.build_std = Some(crate::core::compiler::standard_lib::parse_unstable_flag(v))

‎src/cargo/core/profiles.rs

+24
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,11 @@ pub struct Profiles {
2020
dir_names: HashMap<InternedString, InternedString>,
2121
/// The profile makers. Key is the profile name.
2222
by_name: HashMap<InternedString, ProfileMaker>,
23+
/// The original profiles written by the user in the manifest and config.
24+
///
25+
/// This is here to assist with error reporting, as the `ProfileMaker`
26+
/// values have the inherits chains all merged together.
27+
original_profiles: BTreeMap<InternedString, TomlProfile>,
2328
/// Whether or not unstable "named" profiles are enabled.
2429
named_profiles_enabled: bool,
2530
/// The profile the user requested to use.
@@ -44,6 +49,7 @@ impl Profiles {
4449
named_profiles_enabled: false,
4550
dir_names: Self::predefined_dir_names(),
4651
by_name: HashMap::new(),
52+
original_profiles: profiles.clone(),
4753
requested_profile,
4854
rustc_host,
4955
};
@@ -97,6 +103,7 @@ impl Profiles {
97103
named_profiles_enabled: true,
98104
dir_names: Self::predefined_dir_names(),
99105
by_name: HashMap::new(),
106+
original_profiles: profiles.clone(),
100107
requested_profile,
101108
rustc_host,
102109
};
@@ -420,6 +427,19 @@ impl Profiles {
420427
resolve: &Resolve,
421428
) -> CargoResult<()> {
422429
for (name, profile) in &self.by_name {
430+
// If the user did not specify an override, skip this. This is here
431+
// to avoid generating errors for inherited profiles which don't
432+
// specify package overrides. The `by_name` profile has had the inherits
433+
// chain merged, so we need to look at the original source to check
434+
// if an override was specified.
435+
if self
436+
.original_profiles
437+
.get(name)
438+
.and_then(|orig| orig.package.as_ref())
439+
.is_none()
440+
{
441+
continue;
442+
}
423443
let found = validate_packages_unique(resolve, name, &profile.toml)?;
424444
// We intentionally do not validate unmatched packages for config
425445
// profiles, in case they are defined in a central location. This
@@ -456,6 +476,10 @@ struct ProfileMaker {
456476
/// The starting, hard-coded defaults for the profile.
457477
default: Profile,
458478
/// The TOML profile defined in `Cargo.toml` or config.
479+
///
480+
/// This is None if the user did not specify one, in which case the
481+
/// `default` is used. Note that the built-in defaults for test/bench/doc
482+
/// always set this since they need to declare the `inherits` value.
459483
toml: Option<TomlProfile>,
460484
}
461485

‎src/cargo/util/command_prelude.rs

+12-6
Original file line numberDiff line numberDiff line change
@@ -363,16 +363,22 @@ pub trait ArgMatchesExt {
363363
// This is an early exit, since it allows combination with `--release`.
364364
match (specified_profile, profile_checking) {
365365
// `cargo rustc` has legacy handling of these names
366-
(Some(name @ ("dev" | "test" | "bench" | "check")), ProfileChecking::LegacyRustc) |
366+
(Some(name @ ("dev" | "test" | "bench" | "check")), ProfileChecking::LegacyRustc)
367367
// `cargo fix` and `cargo check` has legacy handling of this profile name
368-
(Some(name @ "test"), ProfileChecking::LegacyTestOnly) => return Ok(InternedString::new(name)),
368+
| (Some(name @ "test"), ProfileChecking::LegacyTestOnly) => {
369+
if self._is_present("release") {
370+
config.shell().warn(
371+
"the `--release` flag should not be specified with the `--profile` flag\n\
372+
The `--release` flag will be ignored.\n\
373+
This was historically accepted, but will become an error \
374+
in a future release."
375+
)?;
376+
}
377+
return Ok(InternedString::new(name));
378+
}
369379
_ => {}
370380
}
371381

372-
if specified_profile.is_some() && !config.cli_unstable().unstable_options {
373-
bail!("usage of `--profile` requires `-Z unstable-options`");
374-
}
375-
376382
let conflict = |flag: &str, equiv: &str, specified: &str| -> anyhow::Error {
377383
anyhow::format_err!(
378384
"conflicting usage of --profile={} and --{flag}\n\

‎src/cargo/util/toml/mod.rs

+1
Original file line numberDiff line numberDiff line change
@@ -602,6 +602,7 @@ impl TomlProfile {
602602
| "rust"
603603
| "rustc"
604604
| "rustdoc"
605+
| "target"
605606
| "tmp"
606607
| "uninstall"
607608
) || lower_name.starts_with("cargo")

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

+10-17
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,14 @@ function to handle running benchmarks.
4646
> running benchmarks on the stable channel, such as
4747
> [Criterion](https://crates.io/crates/criterion).
4848
49+
By default, `cargo bench` uses the [`bench` profile], which enables
50+
optimizations and disables debugging information. If you need to debug a
51+
benchmark, you can use the `--profile=dev` command-line option to switch to
52+
the dev profile. You can then run the debug-enabled benchmark within a
53+
debugger.
54+
55+
[`bench` profile]: ../reference/profiles.html#bench
56+
4957
## OPTIONS
5058

5159
### Benchmark Options
@@ -83,6 +91,8 @@ target.
8391

8492
{{> options-target-triple }}
8593

94+
{{> options-profile }}
95+
8696
{{> options-ignore-rust-version }}
8797

8898
{{/options}}
@@ -129,23 +139,6 @@ Rust test harness runs benchmarks serially in a single thread.
129139
{{> options-jobs }}
130140
{{/options}}
131141

132-
## PROFILES
133-
134-
Profiles may be used to configure compiler options such as optimization levels
135-
and debug settings. See
136-
[the reference](../reference/profiles.html)
137-
for more details.
138-
139-
Benchmarks are always built with the `bench` profile. Binary and lib targets
140-
are built separately as benchmarks with the `bench` profile. Library targets
141-
are built with the `release` profiles when linked to binaries and benchmarks.
142-
Dependencies use the `release` profile.
143-
144-
If you need a debug build of a benchmark, try building it with
145-
{{man "cargo-build" 1}} which will use the `test` profile which is by default
146-
unoptimized and includes debug information. You can then run the debug-enabled
147-
benchmark manually.
148-
149142
{{> section-environment }}
150143

151144
{{> section-exit-status }}

‎src/doc/man/cargo-build.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ they have `required-features` that are missing.
3535

3636
{{> options-release }}
3737

38+
{{> options-profile }}
39+
3840
{{> options-ignore-rust-version }}
3941

4042
{{/options}}
@@ -89,8 +91,6 @@ See <https://github.com/rust-lang/cargo/issues/5579> for more information.
8991
{{> options-jobs }}
9092
{{/options}}
9193

92-
{{> section-profiles }}
93-
9494
{{> section-environment }}
9595

9696
{{> section-exit-status }}

‎src/doc/man/cargo-check.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ they have `required-features` that are missing.
4040

4141
{{> options-release }}
4242

43-
{{> options-profile }}
43+
{{> options-profile-legacy-check }}
4444

4545
{{> options-ignore-rust-version }}
4646

@@ -76,8 +76,6 @@ they have `required-features` that are missing.
7676
{{> options-jobs }}
7777
{{/options}}
7878

79-
{{> section-profiles }}
80-
8179
{{> section-environment }}
8280

8381
{{> section-exit-status }}

‎src/doc/man/cargo-clean.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,11 @@ the target directory.
4040
{{/option}}
4141

4242
{{#option "`--release`" }}
43-
Clean all artifacts that were built with the `release` or `bench` profiles.
43+
Remove all artifacts in the `release` directory.
44+
{{/option}}
45+
46+
{{#option "`--profile` _name_" }}
47+
Remove all artifacts in the directory with the given profile name.
4448
{{/option}}
4549

4650
{{> options-target-dir }}

‎src/doc/man/cargo-doc.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ and supports common Unix glob patterns.
7474

7575
{{> options-release }}
7676

77+
{{> options-profile }}
78+
7779
{{> options-ignore-rust-version }}
7880

7981
{{/options}}
@@ -108,8 +110,6 @@ and supports common Unix glob patterns.
108110
{{> options-jobs }}
109111
{{/options}}
110112

111-
{{> section-profiles }}
112-
113113
{{> section-environment }}
114114

115115
{{> section-exit-status }}

‎src/doc/man/cargo-fix.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ When no target selection options are given, `cargo fix` will fix all targets
120120

121121
{{> options-release }}
122122

123-
{{> options-profile }}
123+
{{> options-profile-legacy-check }}
124124

125125
{{> options-ignore-rust-version }}
126126

@@ -156,8 +156,6 @@ When no target selection options are given, `cargo fix` will fix all targets
156156
{{> options-jobs }}
157157
{{/options}}
158158

159-
{{> section-profiles }}
160-
161159
{{> section-environment }}
162160

163161
{{> section-exit-status }}

‎src/doc/man/cargo-install.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ change, then Cargo will reinstall the package:
4242
- The package version and source.
4343
- The set of binary names installed.
4444
- The chosen features.
45-
- The release mode (`--debug`).
45+
- The profile (`--profile`).
4646
- The target (`--target`).
4747

4848
Installing with `--path` will always build and install, unless there are
@@ -162,8 +162,11 @@ Directory to install packages into.
162162

163163
{{#option "`--debug`" }}
164164
Build with the `dev` profile instead the `release` profile.
165+
See also the `--profile` option for choosing a specific profile by name.
165166
{{/option}}
166167

168+
{{> options-profile }}
169+
167170
{{/options}}
168171

169172
### Manifest Options

‎src/doc/man/cargo-run.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,8 @@ Run the specified example.
5050

5151
{{> options-release }}
5252

53+
{{> options-profile }}
54+
5355
{{> options-ignore-rust-version }}
5456

5557
{{/options}}
@@ -88,8 +90,6 @@ Run the specified example.
8890
{{> options-jobs }}
8991
{{/options}}
9092

91-
{{> section-profiles }}
92-
9393
{{> section-environment }}
9494

9595
{{> section-exit-status }}

‎src/doc/man/cargo-rustc.md

+17-2
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,23 @@ binary and library targets of the selected package.
4747

4848
{{> options-release }}
4949

50+
{{#option "`--profile` _name_" }}
51+
Build with the given profile.
52+
53+
The `rustc` subcommand will treat the following named profiles with special behaviors:
54+
55+
* `check` — Builds in the same way as the {{man "cargo-check" 1}} command with
56+
the `dev` profile.
57+
* `test` — Builds in the same way as the {{man "cargo-test" 1}} command,
58+
enabling building in test mode which will enable tests and enable the `test`
59+
cfg option. See [rustc
60+
tests](https://doc.rust-lang.org/rustc/tests/index.html) for more detail.
61+
* `bench` — Builds in the same was as the {{man "cargo-bench" 1}} command,
62+
similar to the `test` profile.
63+
64+
See the [the reference](../reference/profiles.html) for more details on profiles.
65+
{{/option}}
66+
5067
{{> options-ignore-rust-version }}
5168

5269
{{/options}}
@@ -85,8 +102,6 @@ binary and library targets of the selected package.
85102
{{> options-jobs }}
86103
{{/options}}
87104

88-
{{> section-profiles }}
89-
90105
{{> section-environment }}
91106

92107
{{> section-exit-status }}

‎src/doc/man/cargo-rustdoc.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ if its name is the same as the lib target. Binaries are skipped if they have
6262

6363
{{> options-release }}
6464

65+
{{> options-profile }}
66+
6567
{{> options-ignore-rust-version }}
6668

6769
{{/options}}
@@ -96,8 +98,6 @@ if its name is the same as the lib target. Binaries are skipped if they have
9698
{{> options-jobs }}
9799
{{/options}}
98100

99-
{{> section-profiles }}
100-
101101
{{> section-environment }}
102102

103103
{{> section-exit-status }}

‎src/doc/man/cargo-test.md

+2-10
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,8 @@ target options.
102102

103103
{{> options-release }}
104104

105+
{{> options-profile }}
106+
105107
{{> options-ignore-rust-version }}
106108

107109
{{/options}}
@@ -154,16 +156,6 @@ includes an option to control the number of threads used:
154156

155157
{{/options}}
156158

157-
{{> section-profiles }}
158-
159-
Unit tests are separate executable artifacts which use the `test`/`bench`
160-
profiles. Example targets are built the same as with `cargo build` (using the
161-
`dev`/`release` profiles) unless you are building them with the test harness
162-
(by setting `test = true` in the manifest or using the `--example` flag) in
163-
which case they use the `test`/`bench` profiles. Library targets are built
164-
with the `dev`/`release` profiles when linked to an integration test, binary,
165-
or doctest.
166-
167159
{{> section-environment }}
168160

169161
{{> section-exit-status }}

0 commit comments

Comments
 (0)