Document interaction between custom profiles and overrides

[vlovich]

Not sure if I actually captured the behavior correctly.

What does this PR try to resolve?

Do custom profiles keep package overrides requiring the exact same set to be duplicated if a setting needs to be changed, or are the overrides discarded for a custom profile & the overrides need to be repeated if any settings need to be persisted?

How should we test and review this PR?

N/A - just need to document current behavior.

Additional information

N/A

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @epage (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[vlovich]

@rustbot review

[ehuss]

Overrides should be inherited. If you are having problems with the inheritance, I'd recommend opening an issue with a reproduction showing what doesn't seem to be working.

[vlovich]

@ehuss fixed the wording to reflect the correct state.

[weihanglo]

What do you think about adding a sentence at line 250, instead of this?

- setting is not specified.
+ setting is not specified. Note that a custom profile inherits everything from
+ the other profile, including package and build [overrides](#overrides).

[weihanglo]

This doesn't seem to match the current behavior. Check this test as a reference:

cargo/tests/testsuite/profile_custom.rs

Lines 295 to 364 in 61855e7

	fn overrides_with_custom() {
	let p = project()
	.file(
	"Cargo.toml",
	r#"
	[package]
	name = "foo"
	version = "0.0.1"
	edition = "2015"
	authors = []
	[dependencies]
	xxx = {path = "xxx"}
	yyy = {path = "yyy"}
	[profile.dev]
	codegen-units = 7
	[profile.dev.package.xxx]
	codegen-units = 5
	[profile.dev.package.yyy]
	codegen-units = 3
	[profile.other]
	inherits = "dev"
	codegen-units = 2
	[profile.other.package.yyy]
	codegen-units = 6
	"#,
	)
	.file("src/lib.rs", "")
	.file("xxx/Cargo.toml", &basic_lib_manifest("xxx"))
	.file("xxx/src/lib.rs", "")
	.file("yyy/Cargo.toml", &basic_lib_manifest("yyy"))
	.file("yyy/src/lib.rs", "")
	.build();
	// profile overrides are inherited between profiles using inherits and have a
	// higher priority than profile options provided by custom profiles
	p.cargo("build -v")
	.with_stderr_unordered(
	"\
	[LOCKING] 3 packages
	[COMPILING] xxx [..]
	[COMPILING] yyy [..]
	[COMPILING] foo [..]
	[RUNNING] `rustc --crate-name xxx [..] -C codegen-units=5 [..]`
	[RUNNING] `rustc --crate-name yyy [..] -C codegen-units=3 [..]`
	[RUNNING] `rustc --crate-name foo [..] -C codegen-units=7 [..]`
	[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [..]
	",
	)
	.run();
	// This also verifies that the custom profile names appears in the finished line.
	p.cargo("build --profile=other -v")
	.with_stderr_unordered(
	"\
	[COMPILING] xxx [..]
	[COMPILING] yyy [..]
	[COMPILING] foo [..]
	[RUNNING] `rustc --crate-name xxx [..] -C codegen-units=5 [..]`
	[RUNNING] `rustc --crate-name yyy [..] -C codegen-units=6 [..]`
	[RUNNING] `rustc --crate-name foo [..] -C codegen-units=2 [..]`
	[FINISHED] `other` profile [unoptimized + debuginfo] target(s) in [..]
	",
	)
	.run();
	}

[weihanglo]

@rustbot author