From 98e9f986eea2c7291e10b64d48aa91b460079e3d Mon Sep 17 00:00:00 2001 From: Dan Aloni Date: Thu, 4 Apr 2019 10:31:44 +0300 Subject: [PATCH 01/20] RFC: Named custom cargo profiles --- text/0000-named-custom-cargo-profiles.md | 275 +++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 text/0000-named-custom-cargo-profiles.md diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md new file mode 100644 index 00000000000..c189c7c2e73 --- /dev/null +++ b/text/0000-named-custom-cargo-profiles.md @@ -0,0 +1,275 @@ +- Feature Name: `custom_named_cargo_profiles` +- Start Date: 2019-04-04 +- RFC PR: (leave this empty) +- Rust Issue: N/A + +# Summary +[summary]: #summary + +The proposed change to Cargo is to add the ability to specify user-defined +profiles in addition to the five predefined profiles, `dev`, `release`, `test`, +`bench`, and the less talked-about `doc`. It is also desired in this scope to +reduce confusion regarding where final outputs reside, and increase the +flexbility to specify the user-defined profile attributes. + +# Motivation +[motivation]: #motivation + +Past proposal to increase flexibility of Cargo’s build flags for crates within +a single cargo build invocation, has resulted in [RFC 2282](https://github.com/rust-lang/rfcs/blob/master/text/2282-profile-dependencies.md), +which adds the flexibility of changing attributes of specific crates under one +of the default profiles. However, it does not allow for a full custom profile +name definition that can have its own additional final outputs. + +The motivation is illustrated by a prominant example — the ability to easily +throw everything under a custom compilation mode in addition to the existing +compilation modes. + +For example, suppose we are frequently comparing between both a release build +and a super-optimized release+LTO build, we would like Cargo to having two +separate `target/` directories, e.g. `target/release`, and +`target/release-lto`, for which the binaries and incremental compilation is +managed separately. This is so that we can easily switch between the two modes +without penalty. + +Here's an example for a real-world user: [tikv/issue/4189](https://github.com/tikv/tikv/issues/4189) + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +With this proposal implemented, a user can define custom profiles under new +names, provided that an `inherited` key is used in order to receive attributes +from other profiles. + +For example: + + [profile.release-lto] + inherits = "release" + lto = true + +Passing `--profile` with the profile's name to various Cargo commands will +resolve to the custom profile. Overrides specified in the profiles from which +the custom profile inherits will be inherited too, and all final outputs may +go to a different directory by default: + + $ cargo build + $ cargo build --release + $ cargo build --profile release-lto + $ ls -l target + debug release release-lto + +Cargo will emit errors in case `inherits` loops are detected. When considering +inheritence hierarchy, all profiles directly or indirectly inherit from +either from `release` or from `dev`. + +This also affects other Cargo commands: + +* `cargo test` also receives `--profile`, but unless it is specified, uses + the predefined `test` profile which is described below. +* `cargo bench` also receives `--profile`, but unless it is specified, uses + the predefined `bench` profile which is described below. +* `cargo doc` also receives `--profile`, but unless it is specified, uses + the predefined `doc` profile which is described below. + + +## New `dir-name` attribute + +Some of the paths generated under `target/` have resulted in a de-facto "build +protocol", where `cargo` is invoked as a part of a larger project build. So, to +preserve the existing behavior, there is also a new attribute `dir-name`, which +when left unspecified, defaults to the name of the profile. For example: + + [profile.release-lto] + inherits = "release" + dir-name = "lto" # Emits to target/lto instead of target/release-lto + lto = true + +* The `dir-name` attribute is used mainly to direct the outputs of `bench` and + `test` to their respective directories: `target/release` and `target/debug`. + This preserves existing behavior. +* The `dir-name` attribute is the only attribute not passed by inheritance. +* Path seperators are not allowed in `dir-name`. + + +## Treatment to the pre-defined profiles + +* The `release` profile remains as it is, with settings overridable as + before. +* The `dev` profile receives the `dir-name = "debug"` attribute, so that its + final outputs are emitted to `target/debug`, as existing Rust developers will + expect this behavior. This should be added in the official + documentation for the Cargo manifest, to make this fact clearer for users. +* A `debug` profile name is not allowed, with a warning saying to use the + already established `dev` name. +* The `bench` profile defaults to the following definition, to preserve current + behavior: + +``` +[bench] +inherits = "release" +dir-name = "release" +``` + +* The `test` profile defaults to the following definition, to preserve current behavior: +``` +[test] +inherits = "dev" +dir-name = "debug" +``` + +* The `doc` profile defaults to the following definition, to preserve current + behavior: +``` +[doc] +inherits = "dev" +dir-name = "debug" +``` + + +* The (upcoming) `build` profile defaults to the following definition: +``` +[build] +inherits = "dev" +dir-name = "debug" +debug = false +``` + + +## Treatment to Cargo's 'Finished' print + +For `cargo build`, the profile's name is emitted in the "Finished" line: + + Finished release-lto [optimized + lto] target(s) in 3.83s + +* As before, optimization mode is always printed, with `optimized` if + `opt-level > 0` and `unoptimized` othersize. +* As before, information regarding debuginfo is printed, with `debuginfo` if + `debug != false`, and nothing if `debug == false` (or `debug == 0`). +* Other differences from the inherited root profile pre-defined defaults are + printed in a concise manner. + + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +The 'final outputs' phrasing was used in this RFC, knowing that there are +intermediate outputs that live under `target/` that are usually not a concern +for most Cargo users. The paths that constitue the final build outputs however, +constitute as sort of a protocol for invokers of Cargo. This RFC extends on +that protocol, allowing for outputs in more directories. + +## Cargo code changes + +In implementation details, there are various hand-coded references to pre-defined +profiles, that we would like to remove. + +The `BuildConfig` structure currently has a `release` boolean. The +implementation will replace it with a value of type `enum Profile {Dev, +Release, Custom(String))`. + +* The `Profiles` struct in `cargo/core/profiles.rs` currently has hardcoded + `dev`, `release`, `test`, `bench`, and `doc` fields. This should be changed + into a `BTreeMap` based on profile names. The pre-defined profiles can be + loaded into it, before `TomlProfile` overrides are applied to them. +* Similarly, `TomlProfiles` will be changed to hold profiles in a `BTreeMap`. +* We would need to compute the actual `build_override` for a profile based on + resolution through the `inherited` key. +* Custom build scripts: For compatibility, the `PROFILE` environment currently + being passed to the `build.rs` script is going to bear the name of the output + directory and not the name of the profile. + +## Collision under the target directory + +To guard against the unlikely case that a target name is identical to a profile +name, we should compare the lists for overlap. + +# Drawbacks +[drawbacks]: #drawbacks + +The main drawback is that future ideas regarding Cargo workflows, if +implemented, may supersede the benefits gained from implementing this RFC, +making the added complexity unjustified in retrospect. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +Considering the example provided above, there could be other ways to accomplish +the same result. + +## Direct `cargo build` flags alternative + +If comparing between final build outputs is the main concern to address, there +could be an alternative, in the form of providing those overrides from the +command line. For example, a `--enable-lto` flag to `cargo build`. Used +together with `CARGO_TARGET_DIR` we would be able to do the following: + + + $ cargo build --release + $ CARGO_TARGET_DIR=target/lto cargo build --release --enable-lto + + $ ls -1 target/release/exe target/lto/release/exe + target/release/exe target/lto/release/exe + +The main drawback for this alternative is invocation complexity, and not being able +to utilize a future implementation of a binary cache under the target directory +(see 'future possibilties'). + + +## Workspace `Cargo.toml` auto-generation + +By generating the workspace's `Cargo.toml` from a script, per build, we can +control the parameters of the `release` profile without editing +source-controlled files. Beside build-time complexity, this has another +drawback, for example — it would trip the timestamp comparision with +`Cargo.lock` and cause unnecessary updates to it. + +## Cargo workflows + +It is unclear when the ideas concerning [Cargo +workflows](http://aturon.github.io/2018/04/05/workflows/) will manifest in +changes that would allow similar functionality. + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +* Bikeshedding the `inherits` keyword name. +* Should we keep user profiles under a Toml namespace of their own? + +For example: + + [profile.custom.release-lto] + inherits = "release" + lto = true + +* If so, should the `inherits` keyword be able to refer to custom and + pre-defined profiles differently? +* Profile names would collide with rustc target names under `target/`. Should + the output directory be also under a different namespace, e.g. + `target/custom/release-lto`? +* Do we really need pre-defined profiles for `test`, `bench` and/or `doc`, or + can we make them obsolete? +* Is it worthwhile keeping `test` and `bench` outputs in `target/debug` and + `target/release`? Doing so would save compilation time and space. +* If so, is the `dir-name` keyword necessary? Alternatively, we can hand-code + the output directory of `bench` and `test` to be `release` and `debug` to + keep the current behavior. This may be sufficient until a "global binary cache" + feature is implemented, or a per-workspace `target/.cache` + ([related discussion](https://github.com/rust-lang/cargo/pull/6577#issuecomment-459415283)). + +## Existing `--profile` parameters in Cargo + +The `check`, `fix` and `rustc` commands receive a profile name via `--profile`. +However these only control how `rustc` is invoked and is not related directly +to the actual Cargo profile whether pre-defined or custom. For example, `cargo rustc` +can receive `--profile bench` and `--release` together or separately, with +rather confusing results. If we move forward with this change, it's maybe +worthwhile to remove this parameter to avoid further confusion, and provide a +similar functionality in a different way. + + +# Future possibilities +[future-possibilities]: #future-possibilities + +This RFC mentioned a global binary cache. A global binary cache can reside +under `target/.cache` or in the user home directory under `.cargo`, to be +shared by multiple workspaces. From 778346da4b8e685c156f36311d0f30855aaca9b7 Mon Sep 17 00:00:00 2001 From: kennytm Date: Thu, 4 Apr 2019 22:34:23 +0300 Subject: [PATCH 02/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index c189c7c2e73..3fd2250c0d7 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -112,7 +112,7 @@ dir-name = "release" * The `test` profile defaults to the following definition, to preserve current behavior: ``` -[test] +[profile.test] inherits = "dev" dir-name = "debug" ``` From 2f7c3ea8e0845dc7927d163fea9f61e5c4d86070 Mon Sep 17 00:00:00 2001 From: kennytm Date: Thu, 4 Apr 2019 22:34:35 +0300 Subject: [PATCH 03/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 3fd2250c0d7..aa78ad82aee 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -120,7 +120,7 @@ dir-name = "debug" * The `doc` profile defaults to the following definition, to preserve current behavior: ``` -[doc] +[profile.doc] inherits = "dev" dir-name = "debug" ``` From 6670e28a9c70e6d5aae7ecc6db1c7dd441aa1a9f Mon Sep 17 00:00:00 2001 From: kennytm Date: Thu, 4 Apr 2019 22:34:40 +0300 Subject: [PATCH 04/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index aa78ad82aee..e2ec2f60c21 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -128,7 +128,7 @@ dir-name = "debug" * The (upcoming) `build` profile defaults to the following definition: ``` -[build] +[profile.build] inherits = "dev" dir-name = "debug" debug = false From 01e36bacb017e9e2c7e7259c87f7e49e1d0f3fd7 Mon Sep 17 00:00:00 2001 From: kennytm Date: Thu, 4 Apr 2019 22:34:49 +0300 Subject: [PATCH 05/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index e2ec2f60c21..63e88143dbd 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -105,7 +105,7 @@ when left unspecified, defaults to the name of the profile. For example: behavior: ``` -[bench] +[profile.bench] inherits = "release" dir-name = "release" ``` From 38ae96b6e812909fc6ed0add3c439ade16db55a4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:21:25 +0300 Subject: [PATCH 06/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 63e88143dbd..00275010fc5 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -130,7 +130,7 @@ dir-name = "debug" ``` [profile.build] inherits = "dev" -dir-name = "debug" +dir-name = "build" debug = false ``` From 4c8698aecda87077e3a6edd3e16c9cb7c570cc1f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:21:38 +0300 Subject: [PATCH 07/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 00275010fc5..047e31977f1 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -88,7 +88,7 @@ when left unspecified, defaults to the name of the profile. For example: `test` to their respective directories: `target/release` and `target/debug`. This preserves existing behavior. * The `dir-name` attribute is the only attribute not passed by inheritance. -* Path seperators are not allowed in `dir-name`. +* Path separators are not allowed in `dir-name`. ## Treatment to the pre-defined profiles From a34dd1a9a49c83e6eb8ecf642893978a8ab9b7f2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:21:50 +0300 Subject: [PATCH 08/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 047e31977f1..a069c1fcc4b 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -59,7 +59,7 @@ go to a different directory by default: debug release release-lto Cargo will emit errors in case `inherits` loops are detected. When considering -inheritence hierarchy, all profiles directly or indirectly inherit from +inheritance hierarchy, all profiles directly or indirectly inherit from either from `release` or from `dev`. This also affects other Cargo commands: From f36f01cd85e3dff6812065168be40cfa02d259da Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:21:57 +0300 Subject: [PATCH 09/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index a069c1fcc4b..993ca2776c9 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -21,7 +21,7 @@ which adds the flexibility of changing attributes of specific crates under one of the default profiles. However, it does not allow for a full custom profile name definition that can have its own additional final outputs. -The motivation is illustrated by a prominant example — the ability to easily +The motivation is illustrated by a prominent example — the ability to easily throw everything under a custom compilation mode in addition to the existing compilation modes. From f13f58fbe6f1becaf961665cd0059461c845362b Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:22:10 +0300 Subject: [PATCH 10/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 993ca2776c9..fbbd02ecdc3 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -10,7 +10,7 @@ The proposed change to Cargo is to add the ability to specify user-defined profiles in addition to the five predefined profiles, `dev`, `release`, `test`, `bench`, and the less talked-about `doc`. It is also desired in this scope to reduce confusion regarding where final outputs reside, and increase the -flexbility to specify the user-defined profile attributes. +flexibility to specify the user-defined profile attributes. # Motivation [motivation]: #motivation From d843482bc941c3e11fae89241d48297454c4f726 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:22:17 +0300 Subject: [PATCH 11/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index fbbd02ecdc3..b153deb41c9 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -38,7 +38,7 @@ Here's an example for a real-world user: [tikv/issue/4189](https://github.com/ti [guide-level-explanation]: #guide-level-explanation With this proposal implemented, a user can define custom profiles under new -names, provided that an `inherited` key is used in order to receive attributes +names, provided that an `inherits` key is used in order to receive attributes from other profiles. For example: From 6de67fa575a25f2f0a6c989cc5a94c92f2b0d27f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:36:42 +0300 Subject: [PATCH 12/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index b153deb41c9..1f7877ab836 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -142,7 +142,7 @@ For `cargo build`, the profile's name is emitted in the "Finished" line: Finished release-lto [optimized + lto] target(s) in 3.83s * As before, optimization mode is always printed, with `optimized` if - `opt-level > 0` and `unoptimized` othersize. + `opt-level > 0` and `unoptimized` otherwise. * As before, information regarding debuginfo is printed, with `debuginfo` if `debug != false`, and nothing if `debug == false` (or `debug == 0`). * Other differences from the inherited root profile pre-defined defaults are From d703399a8553339848c4807ba72deb431141fa9d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:37:08 +0300 Subject: [PATCH 13/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 1f7877ab836..9a26800ba4f 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -154,7 +154,7 @@ For `cargo build`, the profile's name is emitted in the "Finished" line: The 'final outputs' phrasing was used in this RFC, knowing that there are intermediate outputs that live under `target/` that are usually not a concern -for most Cargo users. The paths that constitue the final build outputs however, +for most Cargo users. The paths that constitute the final build outputs however, constitute as sort of a protocol for invokers of Cargo. This RFC extends on that protocol, allowing for outputs in more directories. From e3b94619342fb987600b84e2e571e2d42ebc7179 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:37:18 +0300 Subject: [PATCH 14/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 9a26800ba4f..30fd939a430 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -212,7 +212,7 @@ together with `CARGO_TARGET_DIR` we would be able to do the following: The main drawback for this alternative is invocation complexity, and not being able to utilize a future implementation of a binary cache under the target directory -(see 'future possibilties'). +(see 'future possibilities'). ## Workspace `Cargo.toml` auto-generation From 2fe85b9c5f0f1d2557ca0e6bc8c0c43093a14acb Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:37:30 +0300 Subject: [PATCH 15/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 30fd939a430..68dda4d258c 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -220,7 +220,7 @@ to utilize a future implementation of a binary cache under the target directory By generating the workspace's `Cargo.toml` from a script, per build, we can control the parameters of the `release` profile without editing source-controlled files. Beside build-time complexity, this has another -drawback, for example — it would trip the timestamp comparision with +drawback, for example — it would trip the timestamp comparison with `Cargo.lock` and cause unnecessary updates to it. ## Cargo workflows From 868d024c874f3e51afc8dc34531bf0c31640259d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 14 Apr 2019 11:37:39 +0300 Subject: [PATCH 16/20] Update text/0000-named-custom-cargo-profiles.md Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 68dda4d258c..c2e3ec31dc8 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -173,7 +173,7 @@ Release, Custom(String))`. loaded into it, before `TomlProfile` overrides are applied to them. * Similarly, `TomlProfiles` will be changed to hold profiles in a `BTreeMap`. * We would need to compute the actual `build_override` for a profile based on - resolution through the `inherited` key. + resolution through the `inherits` key. * Custom build scripts: For compatibility, the `PROFILE` environment currently being passed to the `build.rs` script is going to bear the name of the output directory and not the name of the profile. From 864951e43016d40d9a4801588ea96be8f00aaf92 Mon Sep 17 00:00:00 2001 From: Dan Aloni Date: Sun, 14 Apr 2019 20:32:05 +0300 Subject: [PATCH 17/20] Fixes following @ehuss's review --- text/0000-named-custom-cargo-profiles.md | 78 ++++++++++++++++-------- 1 file changed, 51 insertions(+), 27 deletions(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index c2e3ec31dc8..9c6779b76f2 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -8,9 +8,9 @@ The proposed change to Cargo is to add the ability to specify user-defined profiles in addition to the five predefined profiles, `dev`, `release`, `test`, -`bench`, and the less talked-about `doc`. It is also desired in this scope to -reduce confusion regarding where final outputs reside, and increase the -flexibility to specify the user-defined profile attributes. +`bench`. It is also desired in this scope to reduce confusion regarding where +final outputs reside, and increase the flexibility to specify the user-defined +profile attributes. # Motivation [motivation]: #motivation @@ -47,6 +47,9 @@ For example: inherits = "release" lto = true +Valid profile names are: must not be empty, use only alphanumeric characters or +`-` or `_`. + Passing `--profile` with the profile's name to various Cargo commands will resolve to the custom profile. Overrides specified in the profiles from which the custom profile inherits will be inherited too, and all final outputs may @@ -71,6 +74,18 @@ This also affects other Cargo commands: * `cargo doc` also receives `--profile`, but unless it is specified, uses the predefined `doc` profile which is described below. +## Effect over the use of profile in commands + +The mixtures of profiles used for `--all-targets` is still in effect, as +long as `--profile` is not specified. + +## Combined specification with `--release` + +For now, `--release` is supported for backward-compatibility. + +Using `--profile` and `--release` together in the same invocation emits an +error unless `--profile=release`. Using `--release` on its own is equivalent +to specifying `--profile=release` ## New `dir-name` attribute @@ -88,8 +103,13 @@ when left unspecified, defaults to the name of the profile. For example: `test` to their respective directories: `target/release` and `target/debug`. This preserves existing behavior. * The `dir-name` attribute is the only attribute not passed by inheritance. -* Path separators are not allowed in `dir-name`. +* Valid directory names are: must not be empty, use only alphanumeric + characters or `-` or `_`. +## Cross compilation + +Under cross compilation with a profile, paths corresponding to +`target//` will be created. ## Treatment to the pre-defined profiles @@ -125,8 +145,8 @@ inherits = "dev" dir-name = "debug" ``` - * The (upcoming) `build` profile defaults to the following definition: + ``` [profile.build] inherits = "dev" @@ -134,20 +154,7 @@ dir-name = "build" debug = false ``` - -## Treatment to Cargo's 'Finished' print - -For `cargo build`, the profile's name is emitted in the "Finished" line: - - Finished release-lto [optimized + lto] target(s) in 3.83s - -* As before, optimization mode is always printed, with `optimized` if - `opt-level > 0` and `unoptimized` otherwise. -* As before, information regarding debuginfo is printed, with `debuginfo` if - `debug != false`, and nothing if `debug == false` (or `debug == 0`). -* Other differences from the inherited root profile pre-defined defaults are - printed in a concise manner. - +(NOTE: the `build` profile is experimental and may be removed later) # Reference-level explanation [reference-level-explanation]: #reference-level-explanation @@ -175,13 +182,15 @@ Release, Custom(String))`. * We would need to compute the actual `build_override` for a profile based on resolution through the `inherits` key. * Custom build scripts: For compatibility, the `PROFILE` environment currently - being passed to the `build.rs` script is going to bear the name of the output - directory and not the name of the profile. + being passed to the `build.rs` script is set to either `release` or `debug`, + based on `inherits` relationship of the specified profile, in case it is not + `release` or `dev` directly. -## Collision under the target directory +## Profile name and directory name exclusion -To guard against the unlikely case that a target name is identical to a profile -name, we should compare the lists for overlap. +To prevent collisions under the target directory, predefined set of string +excludes both the custom profile names and the dir-name. For example, +`package`, `build`, `debug`, `doc`, and strings that start with `.`. # Drawbacks [drawbacks]: #drawbacks @@ -270,6 +279,21 @@ similar functionality in a different way. # Future possibilities [future-possibilities]: #future-possibilities -This RFC mentioned a global binary cache. A global binary cache can reside -under `target/.cache` or in the user home directory under `.cargo`, to be -shared by multiple workspaces. +This RFC mentions a global binary cache. A global binary cache can reside under +`target/.cache` or in the user home directory under `.cargo`, to be shared by +multiple workspaces. This may further assist in reducing compilation times when +switching between compilation flags. + +## Treatment to Cargo's 'Finished' print + +Currently, the `Finished` line being emitted when Cargo is done building, is +confusing, and sometimes does not bear a relation to the specified profile. We +may take this opportunity to revise the output of this line to include the name +of the profile. + +Some targets use more than one profile in their compilation process, so we may +want to pick a different scheme than simply printing out the name of the main +profile being used. One option is to print a line for each one of the built +targets with concise description of profiles that used to build it, but there +may be better options worth considering following the implementation of this +RFC. From 67ff2e4b8dc33d79b081930ba095ee1ef26c3082 Mon Sep 17 00:00:00 2001 From: Dan Aloni Date: Thu, 2 May 2019 15:45:58 +0300 Subject: [PATCH 18/20] Further cleanups regarding the unused doc profile --- text/0000-named-custom-cargo-profiles.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 9c6779b76f2..61a3090b6fd 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -1,3 +1,4 @@ +B - Feature Name: `custom_named_cargo_profiles` - Start Date: 2019-04-04 - RFC PR: (leave this empty) @@ -71,8 +72,6 @@ This also affects other Cargo commands: the predefined `test` profile which is described below. * `cargo bench` also receives `--profile`, but unless it is specified, uses the predefined `bench` profile which is described below. -* `cargo doc` also receives `--profile`, but unless it is specified, uses - the predefined `doc` profile which is described below. ## Effect over the use of profile in commands @@ -137,14 +136,6 @@ inherits = "dev" dir-name = "debug" ``` -* The `doc` profile defaults to the following definition, to preserve current - behavior: -``` -[profile.doc] -inherits = "dev" -dir-name = "debug" -``` - * The (upcoming) `build` profile defaults to the following definition: ``` @@ -175,9 +166,9 @@ implementation will replace it with a value of type `enum Profile {Dev, Release, Custom(String))`. * The `Profiles` struct in `cargo/core/profiles.rs` currently has hardcoded - `dev`, `release`, `test`, `bench`, and `doc` fields. This should be changed - into a `BTreeMap` based on profile names. The pre-defined profiles can be - loaded into it, before `TomlProfile` overrides are applied to them. + `dev`, `release`, `test`, `bench`. This should be changed into a `BTreeMap` + based on profile names. The pre-defined profiles can be loaded into it, + before `TomlProfile` overrides are applied to them. * Similarly, `TomlProfiles` will be changed to hold profiles in a `BTreeMap`. * We would need to compute the actual `build_override` for a profile based on resolution through the `inherits` key. @@ -255,7 +246,7 @@ For example: * Profile names would collide with rustc target names under `target/`. Should the output directory be also under a different namespace, e.g. `target/custom/release-lto`? -* Do we really need pre-defined profiles for `test`, `bench` and/or `doc`, or +* Do we really need pre-defined profiles for `test`, `bench`, or can we make them obsolete? * Is it worthwhile keeping `test` and `bench` outputs in `target/debug` and `target/release`? Doing so would save compilation time and space. From b384bd233dea333dd6144075be37aefa2e4cf7c1 Mon Sep 17 00:00:00 2001 From: Joe ST Date: Fri, 3 May 2019 11:38:57 +0300 Subject: [PATCH 19/20] Update text/0000-named-custom-cargo-profiles.md Spurious b indeed. Thanks. Co-Authored-By: da-x --- text/0000-named-custom-cargo-profiles.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/0000-named-custom-cargo-profiles.md index 61a3090b6fd..39a89748695 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/0000-named-custom-cargo-profiles.md @@ -1,4 +1,3 @@ -B - Feature Name: `custom_named_cargo_profiles` - Start Date: 2019-04-04 - RFC PR: (leave this empty) From f8d8376b977b1f8389d36ebd5200270e475716ed Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Sat, 1 Jun 2019 10:13:37 +0200 Subject: [PATCH 20/20] RFC 2678 --- ...-cargo-profiles.md => 2678-named-custom-cargo-profiles.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename text/{0000-named-custom-cargo-profiles.md => 2678-named-custom-cargo-profiles.md} (98%) diff --git a/text/0000-named-custom-cargo-profiles.md b/text/2678-named-custom-cargo-profiles.md similarity index 98% rename from text/0000-named-custom-cargo-profiles.md rename to text/2678-named-custom-cargo-profiles.md index 39a89748695..2a1f2c874ab 100644 --- a/text/0000-named-custom-cargo-profiles.md +++ b/text/2678-named-custom-cargo-profiles.md @@ -1,7 +1,7 @@ - Feature Name: `custom_named_cargo_profiles` - Start Date: 2019-04-04 -- RFC PR: (leave this empty) -- Rust Issue: N/A +- RFC PR: [rust-lang/rfcs#2678](https://github.com/rust-lang/rfcs/pull/2678) +- Cargo Issue: [rust-lang/cargo#6988](https://github.com/rust-lang/cargo/issues/6988) # Summary [summary]: #summary