From dda81d31776e2eb0f08c21e4c3cf48bbdc407767 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 14 Nov 2019 16:48:41 -0800 Subject: [PATCH] Stabilize profile-overrides. --- src/cargo/core/features.rs | 2 +- src/doc/man/cargo-bench.adoc | 2 +- src/doc/man/generated/cargo-bench.html | 2 +- src/doc/man/generated/cargo-build.html | 2 +- src/doc/man/generated/cargo-check.html | 2 +- src/doc/man/generated/cargo-doc.html | 2 +- src/doc/man/generated/cargo-fix.html | 2 +- src/doc/man/generated/cargo-run.html | 2 +- src/doc/man/generated/cargo-rustc.html | 2 +- src/doc/man/generated/cargo-rustdoc.html | 2 +- src/doc/man/generated/cargo-test.html | 2 +- src/doc/man/section-profiles.adoc | 2 +- src/doc/src/SUMMARY.md | 1 + src/doc/src/faq.md | 4 +- src/doc/src/reference/manifest.md | 80 +---- src/doc/src/reference/profiles.md | 394 +++++++++++++++++++++++ src/doc/src/reference/unstable.md | 36 --- src/etc/man/cargo-bench.1 | 4 +- src/etc/man/cargo-build.1 | 2 +- src/etc/man/cargo-check.1 | 2 +- src/etc/man/cargo-doc.1 | 2 +- src/etc/man/cargo-fix.1 | 2 +- src/etc/man/cargo-run.1 | 2 +- src/etc/man/cargo-rustc.1 | 2 +- src/etc/man/cargo-rustdoc.1 | 2 +- src/etc/man/cargo-test.1 | 2 +- tests/testsuite/profile_config.rs | 59 +--- tests/testsuite/profile_custom.rs | 2 +- tests/testsuite/profile_overrides.rs | 91 +----- 29 files changed, 430 insertions(+), 281 deletions(-) create mode 100644 src/doc/src/reference/profiles.md diff --git a/src/cargo/core/features.rs b/src/cargo/core/features.rs index f7a1cfb60a7..e532cecb527 100644 --- a/src/cargo/core/features.rs +++ b/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, diff --git a/src/doc/man/cargo-bench.adoc b/src/doc/man/cargo-bench.adoc index 879ee2021ce..2dd8f20ee14 100644 --- a/src/doc/man/cargo-bench.adoc +++ b/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 diff --git a/src/doc/man/generated/cargo-bench.html b/src/doc/man/generated/cargo-bench.html index 744fd61e5c4..c6e03d01ca5 100644 --- a/src/doc/man/generated/cargo-bench.html +++ b/src/doc/man/generated/cargo-bench.html @@ -432,7 +432,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-build.html b/src/doc/man/generated/cargo-build.html index ab6f0a752f1..a0d135aa49d 100644 --- a/src/doc/man/generated/cargo-build.html +++ b/src/doc/man/generated/cargo-build.html @@ -372,7 +372,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-check.html b/src/doc/man/generated/cargo-check.html index 32bc64ceb08..4147edbd710 100644 --- a/src/doc/man/generated/cargo-check.html +++ b/src/doc/man/generated/cargo-check.html @@ -363,7 +363,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-doc.html b/src/doc/man/generated/cargo-doc.html index ef3d4eadda3..62d0542bfa3 100644 --- a/src/doc/man/generated/cargo-doc.html +++ b/src/doc/man/generated/cargo-doc.html @@ -333,7 +333,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-fix.html b/src/doc/man/generated/cargo-fix.html index 46ef49e0864..4cd6f46d66e 100644 --- a/src/doc/man/generated/cargo-fix.html +++ b/src/doc/man/generated/cargo-fix.html @@ -434,7 +434,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-run.html b/src/doc/man/generated/cargo-run.html index 2eff28c0aaa..0ee9ab22ed3 100644 --- a/src/doc/man/generated/cargo-run.html +++ b/src/doc/man/generated/cargo-run.html @@ -285,7 +285,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-rustc.html b/src/doc/man/generated/cargo-rustc.html index e46e13e6a2c..ff5b5c0287e 100644 --- a/src/doc/man/generated/cargo-rustc.html +++ b/src/doc/man/generated/cargo-rustc.html @@ -346,7 +346,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-rustdoc.html b/src/doc/man/generated/cargo-rustdoc.html index c4daa0e977b..b8426e51d51 100644 --- a/src/doc/man/generated/cargo-rustdoc.html +++ b/src/doc/man/generated/cargo-rustdoc.html @@ -361,7 +361,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/generated/cargo-test.html b/src/doc/man/generated/cargo-test.html index 8c3ac2fe5d7..4bf31f1dc79 100644 --- a/src/doc/man/generated/cargo-test.html +++ b/src/doc/man/generated/cargo-test.html @@ -462,7 +462,7 @@

PROFILES

Profiles may be used to configure compiler options such as optimization levels and debug settings. See -the reference +the reference for more details.

diff --git a/src/doc/man/section-profiles.adoc b/src/doc/man/section-profiles.adoc index 02cf4acaa0b..85f208997f9 100644 --- a/src/doc/man/section-profiles.adoc +++ b/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 diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index 369fa9627b3..c07392647c3 100644 --- a/src/doc/src/SUMMARY.md +++ b/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) diff --git a/src/doc/src/faq.md b/src/doc/src/faq.md index 0aa179454e1..ee006621856 100644 --- a/src/doc/src/faq.md +++ b/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). diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 230aa4f7922..4608ff219c9 100644 --- a/src/doc/src/reference/manifest.md +++ b/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 diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md new file mode 100644 index 00000000000..795edebe7ef --- /dev/null +++ b/src/doc/src/reference/profiles.md @@ -0,0 +1,394 @@ +## Profiles + +Profiles provide a way to alter the compiler settings, influencing things like +optimizations and debugging symbols. + +Cargo has 4 built-in profiles: `dev`, `release`, `test`, and `bench`. It +automatically chooses the profile based on which command is being run, the +package and target that is being built, and command-line flags like +`--release`. The selection process is [described below](#profile-selection). + +Profile settings can be changed in [`Cargo.toml`](manifest.md) with the +`[profile]` table. Within each named profile, individual settings can be changed +with key/value pairs like this: + +```toml +[profile.dev] +opt-level = 1 # Use slightly better optimizations. +overflow-checks = false # Disable integer overflow checks. +``` + +Cargo only looks at the profile settings in the `Cargo.toml` manifest at the +root of the workspace. Profile settings defined in dependencies will be +ignored. + +### Profile settings + +The following is a list of settings that can be controlled in a profile. + +#### opt-level + +The `opt-level` setting controls the [`-C opt-level` flag] which controls the level +of optimization. Higher optimization levels may produce faster runtime code at +the expense of longer compiler times. Higher levels may also change and +rearrange the compiled code which may make it harder to use with a debugger. + +The valid options are: + +* `0`: no optimizations, also turns on [`cfg(debug_assertions)`](#debug-assertions). +* `1`: basic optimizations +* `2`: some optimizations +* `3`: all optimizations +* `"s"`: optimize for binary size +* `"z"`: optimize for binary size, but also turn off loop vectorization. + +It is recommended to experiment with different levels to find the right +balance for your project. There may be surprising results, such as level `3` +being slower than `2`, or the `"s"` and `"z"` levels not being necessarily +smaller. You may also want to reevaluate your settings over time as newer +versions of `rustc` changes optimization behavior. + +See also [Profile Guided Optimization] for more advanced optimization +techniques. + +[`-C opt-level` flag]: ../../rustc/codegen-options/index.html#opt-level +[Profile Guided Optimization]: ../../rustc/profile-guided-optimization.html + +#### debug + +The `debug` setting controls the [`-C debuginfo` flag] which controls the +amount of debug information included in the compiled binary. + +The valid options are: + +* `0` or `false`: no debug info at all +* `1`: line tables only +* `2` or `true`: full debug info + +[`-C debuginfo` flag]: ../../rustc/codegen-options/index.html#debuginfo + +#### debug-assertions + +The `debug-assertions` setting controls the [`-C debug-assertions` flag] which +turns `cfg(debug_assertions)` [conditional compilation] on or off. Debug +assertions are intended to include runtime validation which is only available +in debug/development builds. These may be things that are too expensive or +otherwise undesirable in a release build. Debug assertions enables the +[`debug_assert!` macro] in the standard library. + +The valid options are: + +* `true`: enabled +* `false`: disabled + +[`-C debug-assertions` flag]: ../../rustc/codegen-options/index.html#debug-assertions +[conditional compilation]: ../../reference/conditional-compilation.md#debug_assertions +[`debug_assert!` macro]: ../../std/macro.debug_assert.html + +#### overflow-checks + +The `overflow-checks` setting controls the [`-C overflow-checks` flag] which +controls the behavior of [runtime integer overflow]. When overflow-checks are +enabled, a panic will occur on overflow. + +The valid options are: + +* `true`: enabled +* `false`: disabled + +[`-C overflow-checks` flag]: ../../rustc/codegen-options/index.html#overflow-checks +[runtime integer overflow]: ../../reference/expressions/operator-expr.md#overflow + +#### lto + +The `lto` setting controls the [`-C lto` flag] which controls LLVM's [link +time optimizations]. LTO can produce better optimized code, using +whole-program analysis, at the cost of longer linking time. + +The valid options are: + +* `false`: Performs "thin local LTO" which performs "thin" LTO on the local + crate only across its [codegen units](#codegen-units). No LTO is performed + if codegen units is 1 or [opt-level](#opt-level) is 0. +* `true` or `"fat"`: Performs "fat" LTO which attempts to perform + optimizations across all crates within the dependency graph. +* `"thin"`: Performs ["thin" LTO]. This is similar to "fat", but takes + substantially less time to run while still achieving performance gains + similar to "fat". +* `"off"`: Disables LTO. + +See also the [`-C linker-plugin-lto`] `rustc` flag for cross-language LTO. + +[`-C lto` flag]: ../../rustc/codegen-options/index.html#lto +[link time optimizations]: https://llvm.org/docs/LinkTimeOptimization.html +[`-C linker-plugin-lto`]: ../../rustc/codegen-options/index.html#linker-plugin-lto +["thin" LTO]: http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html + +#### panic + +The `panic` setting controls the [`-C panic` flag] which controls which panic +strategy to use. + +The valid options are: + +* `"unwind"`: Unwind the stack upon panic. +* `"abort"`: Terminate the process upon panic. + +When set to `"unwind"`, the actual value depends on the default of the target +platform. For example, the NVPTX platform does not support unwinding, so it +always uses `"abort"`. + +Tests, benchmarks, build scripts, and proc macros ignore the `panic` setting. +The `rustc` test harness currently requires `unwind` behavior. See the +[`panic-abort-tests`] unstable flag which enables `abort` behavior. + +Additionally, when using the `abort` strategy and building a test, all of the +dependencies will also be forced to built with the `unwind` strategy. + +[`-C panic` flag]: ../../rustc/codegen-options/index.html#panic +[`panic-abort-tests`]: unstable.md#panic-abort-tests + +#### incremental + +The `incremental` setting controls the [`-C incremental` flag] which controls +whether or not incremental compilation is enabled. Incremental compilation +causes `rustc` to to save additional information to disk which will be reused +when recompiling the crate, improving re-compile times. The additional +information is stored in the `target` directory. + +The valid options are: + +* `true`: enabled +* `false`: disabled + +Incremental compilation is only used for workspace members and "path" +dependencies. + +The incremental value can be overridden globally with the `CARGO_INCREMENTAL` +[environment variable] or the `build.incremental` [config variable]. + +[`-C incremental` flag]: ../../rustc/codegen-options/index.html#incremental +[environment variable]: environment-variables.md +[config variable]: config.md + +#### codegen-units + +The `codegen-units` setting controls the [`-C codegen-units` flag] which +controls how many "code generation units" a crate will be split into. More +code generation units allows more of a crate to be processed in parallel +possibly reducing compile time, but may produce slower code. + +This option takes an integer greater than 0. + +This option is ignored if [incremental](#incremental) is enabled, in which +case `rustc` uses an internal heuristic to split the crate. + +[`-C codegen-units` flag]: ../../rustc/codegen-options/index.html#codegen-units + +#### rpath + +The `rpath` setting controlls the [`-C rpath` flag] which controls +whether or not [`rpath`] is enabled. + +[`-C rpath` flag]: ../../rustc/codegen-options/index.html#rpath +[`rpath`]: https://en.wikipedia.org/wiki/Rpath + +### Default profiles + +#### dev + +The `dev` profile is used for normal development and debugging. It is the +default for build commands like [`cargo build`]. + +The default settings for the `dev` profile are: + +```toml +[profile.dev] +opt-level = 0 +debug = true +debug-assertions = true +overflow-checks = true +lto = false +panic = 'unwind' +incremental = true +codegen-units = 16 # Note: ignored because `incremental` is enabled. +rpath = false +``` + +#### release + +The `release` profile is intended for optimized artifacts used for releases +and in production. This profile is used when the `--release` flag is used, and +is the default for [`cargo install`]. + +The default settings for the `release` profile are: + +```toml +[profile.release] +opt-level = 3 +debug = false +debug-assertions = false +overflow-checks = false +lto = false +panic = 'unwind' +incremental = false +codegen-units = 16 +rpath = false +``` + +#### test + +The `test` profile is used for building tests, or when benchmarks are built in +debug mode with `cargo build`. + +The default settings for the `test` profile are: + +```toml +[profile.test] +opt-level = 0 +debug = 2 +debug-assertions = true +overflow-checks = true +lto = false +panic = 'unwind' # This setting is always ignored. +incremental = true +codegen-units = 16 # Note: ignored because `incremental` is enabled. +rpath = false +``` + +#### bench + +The `bench` profile is used for building benchmarks, or when tests are built +with the `--release` flag. + +The default settings for the `bench` profile are: + +```toml +[profile.bench] +opt-level = 3 +debug = false +debug-assertions = false +overflow-checks = false +lto = false +panic = 'unwind' # This setting is always ignored. +incremental = false +codegen-units = 16 +rpath = false +``` + + +### Profile selection + +The profile used depends on the command, the package, the Cargo target, and +command-line flags like `--release`. + +Build commands like [`cargo build`], [`cargo rustc`], [`cargo check`], and +[`cargo run`] default to using the `dev` profile. The `--release` flag may be +used to switch to the `release` profile. + +The [`cargo install`] command defaults to the `release` profile, and may use +the `--debug` flag to switch to the `dev` profile. + +Test targets are built with the `test` profile by default. The `--release` +flag switches tests to the `bench` profile. + +Bench targets are built with the `bench` profile by default. The [`cargo +build`] command can be used to build a bench target with the `test` profile to +enable debugging. + +Note that when using the [`cargo test`] and [`cargo bench`] commands, the +`test`/`bench` profiles only apply to the final test executable. Dependencies +will continue to use the `dev`/`release` profiles. Also note that when a +library is built for unit tests, then the library is built with the `test` +profile. However, when building an integration test target, the library target +is built with the `dev` profile and linked into the integration test +executable. + +[`cargo bench`]: ../commands/cargo-bench.md +[`cargo build`]: ../commands/cargo-build.md +[`cargo check`]: ../commands/cargo-check.md +[`cargo install`]: ../commands/cargo-install.md +[`cargo run`]: ../commands/cargo-run.md +[`cargo rustc`]: ../commands/cargo-rustc.md +[`cargo test`]: ../commands/cargo-test.md + +### Overrides + +Profile settings can be overridden for specific packages and build-time +crates. To override the settings for a specific package, use the `package` +table to change the settings for the named package: + +```toml +# The `foo` package will use the -Copt-level=3 flag. +[profile.dev.package.foo] +opt-level = 3 +``` + +The package name is actually a [Package ID Spec](pkgid-spec.md), so you can +target individual versions of a package with syntax such as +`[profile.dev.package."foo:2.1.0"]`. + +To override the settings for all dependencies (but not any workspace member), +use the `"*"` package name: + +```toml +# Set the default for dependencies. +[profile.dev.package."*"] +opt-level = 2 +``` + +To override the settings for build scripts, proc macros, and their +dependencies, use the `build-override` table: + +```toml +# Set the settings for build scripts and proc-macros. +[profile.dev.build-override] +opt-level = 3 +``` + +> Note: When a dependency is both a normal dependency and a build dependency, +> Cargo will try to only build it once when `--target` is not specified. When +> using `build-override`, the dependency may need to be built twice, once as a +> normal dependency and once with the overridden build settings. This may +> increase initial build times. + +The precedence for which value is used is done in the following order (first +match wins): + +1. `[profile.dev.package.name]` — A named package. +2. `[profile.dev.package."*"]` — For any non-workspace member. +3. `[profile.dev.build-override]` — Only for build scripts, proc macros, and + their dependencies. +4. `[profile.dev]` — Settings in `Cargo.toml`. +5. Default values built-in to Cargo. + +Overrides cannot specify the `panic`, `lto`, or `rpath` settings. + +#### Overrides and generics + +The location where generic code is instantiated will influence the +optimization settings used for that generic code. This can cause subtle +interactions when using profile overrides to change the optimization level of +a specific crate. If you attempt to raise the optimization level of a +dependency which defines generic functions, those generic functions may not be +optimized when used in your local crate. This is because the code may be +generated in the crate where it is instantiated, and thus may use the +optimization settings of that crate. + +For example, [nalgebra] is a library which defines vectors and matrices making +heavy use of generic parameters. If your local code defines concrete nalgebra +types like `Vector4` and uses their methods, the corresponding nalgebra +code will be instantiated and built within your crate. Thus, if you attempt to +increase the optimization level of `nalgebra` using a profile override, it may +not result in faster performance. + +Further complicating the issue, `rustc` has some optimizations where it will +attempt to share monomorphized generics between crates. If the opt-level is 2 +or 3, then a crate will not use monomorphized generics from other crates, nor +will it export locally defined monomorphized items to be shared with other +crates. When experimenting with optimizing dependencies for development, +consider trying opt-level 1, which will apply some optimizations while still +allowing monomorphized items to be shared. + + +[nalgebra]: https://crates.io/crates/nalgebra diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 861a6885e5f..71c1fd24549 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -92,42 +92,6 @@ information from `.cargo/config`. See the rustc issue for more information. cargo test --target foo -Zdoctest-xcompile ``` -### Profile Overrides -* Tracking Issue: [rust-lang/rust#48683](https://github.com/rust-lang/rust/issues/48683) -* RFC: [#2282](https://github.com/rust-lang/rfcs/blob/master/text/2282-profile-dependencies.md) - -Profiles can be overridden for specific packages and custom build scripts. -The general format looks like this: - -```toml -cargo-features = ["profile-overrides"] - -[package] -... - -[profile.dev] -opt-level = 0 -debug = true - -# the `image` crate will be compiled with -Copt-level=3 -[profile.dev.package.image] -opt-level = 3 - -# All dependencies (but not this crate itself or any workspace member) -# will be compiled with -Copt-level=2 . This includes build dependencies. -[profile.dev.package."*"] -opt-level = 2 - -# Build scripts or proc-macros and their dependencies will be compiled with -# `-Copt-level=3`. By default, they use the same rules as the rest of the -# profile. -[profile.dev.build-override] -opt-level = 3 -``` - -Overrides can be specified for any profile, including custom named profiles. - - ### Custom named profiles * Tracking Issue: [rust-lang/cargo#6988](https://github.com/rust-lang/cargo/issues/6988) diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 33eca8c000d..626facce232 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -501,7 +501,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Benchmarks are always built with the \fBbench\fP profile. Binary and lib targets @@ -567,4 +567,4 @@ cargo bench \-\-bench bench_name \-\- modname::some_benchmark .RE .SH "SEE ALSO" .sp -\fBcargo\fP(1), \fBcargo\-test\fP(1) \ No newline at end of file +\fBcargo\fP(1), \fBcargo\-test\fP(1) diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index d078ceaf7cf..5a8565b8b3e 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -420,7 +420,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index 20f9b0b0b65..93c4efef929 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -406,7 +406,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 39b9f077ab3..726db633ca2 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -365,7 +365,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index c1f290042bc..3a493f9265c 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -476,7 +476,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index eb3a5376030..410f3a9521a 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -317,7 +317,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index e179c2d117a..17b7722c86c 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -386,7 +386,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 98f31b656f2..668b083e9f0 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -396,7 +396,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index bade8a1c982..476ea5f254f 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -549,7 +549,7 @@ the number of CPUs. Profiles may be used to configure compiler options such as optimization levels and debug settings. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" for more details. .sp Profile selection depends on the target and crate being built. By default the diff --git a/tests/testsuite/profile_config.rs b/tests/testsuite/profile_config.rs index f48c46ff99c..f1b6299449c 100644 --- a/tests/testsuite/profile_config.rs +++ b/tests/testsuite/profile_config.rs @@ -27,16 +27,7 @@ fn profile_config_gated() { #[cargo_test] fn profile_config_validate_warnings() { let p = project() - .file( - "Cargo.toml", - r#" - cargo-features = ["profile-overrides"] - - [package] - name = "foo" - version = "0.0.1" - "#, - ) + .file("Cargo.toml", &basic_lib_manifest("foo")) .file("src/lib.rs", "") .file( ".cargo/config", @@ -113,16 +104,7 @@ Caused by: #[cargo_test] fn profile_config_validate_errors() { let p = project() - .file( - "Cargo.toml", - r#" - cargo-features = ["profile-overrides"] - - [package] - name = "foo" - version = "0.0.1" - "#, - ) + .file("Cargo.toml", &basic_lib_manifest("foo")) .file("src/lib.rs", "") .file( ".cargo/config", @@ -181,8 +163,6 @@ fn profile_config_override_spec_multiple() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] - [package] name = "foo" version = "0.0.1" @@ -202,16 +182,7 @@ fn profile_config_override_spec_multiple() { "#, ) .file("src/lib.rs", "") - .file( - "bar/Cargo.toml", - r#" - cargo-features = ["profile-overrides"] - - [package] - name = "bar" - version = "0.5.0" - "#, - ) + .file("bar/Cargo.toml", &basic_lib_manifest("bar")) .file("bar/src/lib.rs", "") .build(); @@ -279,8 +250,6 @@ fn profile_config_override_precedence() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] - [package] name = "foo" version = "0.0.1" @@ -296,16 +265,7 @@ fn profile_config_override_precedence() { "#, ) .file("src/lib.rs", "") - .file( - "bar/Cargo.toml", - r#" - cargo-features = ["profile-overrides"] - - [package] - name = "bar" - version = "0.0.1" - "#, - ) + .file("bar/Cargo.toml", &basic_lib_manifest("bar")) .file("bar/src/lib.rs", "") .file( ".cargo/config", @@ -332,16 +292,7 @@ fn profile_config_override_precedence() { #[cargo_test] fn profile_config_no_warn_unknown_override() { let p = project() - .file( - "Cargo.toml", - r#" - cargo-features = ["profile-overrides"] - - [package] - name = "foo" - version = "0.0.1" - "#, - ) + .file("Cargo.toml", &basic_lib_manifest("foo")) .file("src/lib.rs", "") .file( ".cargo/config", diff --git a/tests/testsuite/profile_custom.rs b/tests/testsuite/profile_custom.rs index 1b95a80aff3..cf40072ab20 100644 --- a/tests/testsuite/profile_custom.rs +++ b/tests/testsuite/profile_custom.rs @@ -282,7 +282,7 @@ fn overrides_with_custom() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides", "named-profiles"] + cargo-features = ["named-profiles"] [package] name = "foo" diff --git a/tests/testsuite/profile_overrides.rs b/tests/testsuite/profile_overrides.rs index da197fcd419..56f2b84340d 100644 --- a/tests/testsuite/profile_overrides.rs +++ b/tests/testsuite/profile_overrides.rs @@ -1,79 +1,12 @@ use cargo_test_support::registry::Package; use cargo_test_support::{basic_lib_manifest, basic_manifest, project}; -#[cargo_test] -fn profile_override_gated() { - let p = project() - .file( - "Cargo.toml", - r#" - [package] - name = "foo" - version = "0.0.1" - authors = [] - - [profile.dev.build-override] - opt-level = 3 - "#, - ) - .file("src/lib.rs", "") - .build(); - - p.cargo("build") - .masquerade_as_nightly_cargo() - .with_status(101) - .with_stderr( - "\ -error: failed to parse manifest at `[..]` - -Caused by: - feature `profile-overrides` is required - -consider adding `cargo-features = [\"profile-overrides\"]` to the manifest -", - ) - .run(); - - let p = project() - .file( - "Cargo.toml", - r#" - [package] - name = "foo" - version = "0.0.1" - authors = [] - - [profile.dev.package."*"] - opt-level = 3 - "#, - ) - .file("src/lib.rs", "") - .build(); - - p.cargo("build") - .masquerade_as_nightly_cargo() - .with_status(101) - .with_stderr( - "\ -error: failed to parse manifest at `[..]` - -Caused by: - feature `profile-overrides` is required - -consider adding `cargo-features = [\"profile-overrides\"]` to the manifest -", - ) - .run(); -} - #[cargo_test] fn profile_override_basic() { let p = project() .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] - [package] name = "foo" version = "0.0.1" @@ -95,7 +28,6 @@ fn profile_override_basic() { .build(); p.cargo("build -v") - .masquerade_as_nightly_cargo() .with_stderr( "[COMPILING] bar [..] [RUNNING] `rustc --crate-name bar [..] -C opt-level=3 [..]` @@ -112,8 +44,6 @@ fn profile_override_warnings() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] - [package] name = "foo" version = "0.0.1" @@ -136,7 +66,7 @@ fn profile_override_warnings() { .file("bar/src/lib.rs", "") .build(); - p.cargo("build").masquerade_as_nightly_cargo().with_stderr_contains( + p.cargo("build").with_stderr_contains( "\ [WARNING] version or URL in package profile spec `bar:1.2.3` does not match any of the packages: bar v0.5.0 ([..]) [WARNING] package profile spec `bart` did not match any packages @@ -175,8 +105,6 @@ fn profile_override_bad_settings() { "Cargo.toml", &format!( r#" - cargo-features = ["profile-overrides"] - [package] name = "foo" version = "0.0.1" @@ -196,7 +124,6 @@ fn profile_override_bad_settings() { .build(); p.cargo("build") - .masquerade_as_nightly_cargo() .with_status(101) .with_stderr_contains(format!("Caused by:\n {}", expected)) .run(); @@ -210,8 +137,6 @@ fn profile_override_hierarchy() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] - [workspace] members = ["m1", "m2", "m3"] @@ -285,7 +210,7 @@ fn profile_override_hierarchy() { // m2: 2 (as [profile.dev.package.m2]) // m1: 1 (as [profile.dev]) - p.cargo("build -v").masquerade_as_nightly_cargo().with_stderr_unordered("\ + p.cargo("build -v").with_stderr_unordered("\ [COMPILING] m3 [..] [COMPILING] dep [..] [RUNNING] `rustc --crate-name m3 m3/src/lib.rs [..] --crate-type lib --emit=[..]link -C codegen-units=4 [..] @@ -311,8 +236,6 @@ fn profile_override_spec_multiple() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] - [package] name = "foo" version = "0.0.1" @@ -333,7 +256,6 @@ fn profile_override_spec_multiple() { .build(); p.cargo("build -v") - .masquerade_as_nightly_cargo() .with_status(101) .with_stderr_contains( "\ @@ -349,8 +271,6 @@ fn profile_override_spec() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] - [workspace] members = ["m1", "m2"] @@ -402,7 +322,6 @@ fn profile_override_spec() { .build(); p.cargo("build -v") - .masquerade_as_nightly_cargo() .with_stderr_contains("[RUNNING] `rustc [..]dep1/src/lib.rs [..] -C codegen-units=1 [..]") .with_stderr_contains("[RUNNING] `rustc [..]dep2/src/lib.rs [..] -C codegen-units=2 [..]") .run(); @@ -415,7 +334,6 @@ fn override_proc_macro() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] [package] name = "foo" version = "0.1.0" @@ -459,7 +377,6 @@ fn override_proc_macro() { .build(); p.cargo("build -v") - .masquerade_as_nightly_cargo() // Shared built for the proc-macro. .with_stderr_contains("[RUNNING] `rustc [..]--crate-name shared [..]-C codegen-units=4[..]") // Shared built for the library. @@ -482,7 +399,6 @@ fn override_package_rename() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] [package] name = "foo" version = "0.1.0" @@ -503,7 +419,6 @@ fn override_package_rename() { .build(); p.cargo("check") - .masquerade_as_nightly_cargo() .with_stderr("\ [WARNING] profile key `overrides` has been renamed to `package`, please update the manifest to the new key name [CHECKING] bar [..] @@ -520,7 +435,6 @@ fn no_warning_ws() { .file( "Cargo.toml", r#" - cargo-features = ["profile-overrides"] [workspace] members = ["a", "b"] @@ -535,7 +449,6 @@ fn no_warning_ws() { .build(); p.cargo("build -p b") - .masquerade_as_nightly_cargo() .with_stderr( "\ [COMPILING] b [..]