Add comment on relationship of RunCustomBuild and UnitFor::host.

diff --git a/src/cargo/core/compiler/unit_dependencies.rs b/src/cargo/core/compiler/unit_dependencies.rs
index 6a0ed3370cb3bb996db87155f0be1e77e7885dda..48841defd6f26e9c26bc0a169563c4c6ed2e5a4e 100644 (file)
--- a/src/cargo/core/compiler/unit_dependencies.rs
+++ b/src/cargo/core/compiler/unit_dependencies.rs
@@ -515,6 +515,31 @@ fn dep_build_script<'a>(
                 .bcx
                 .profiles
                 .get_profile_run_custom_build(&unit.profile);
+            // UnitFor::new_build is used because we want the `host` flag set
+            // for all of our build dependencies (so they all get
+            // build-override profiles), including compiling the build.rs
+            // script itself.
+            //
+            // If `is_for_build_dep` here is `false`, that means we are a
+            // build.rs script for a normal dependency and we want to set the
+            // CARGO_FEATURE_* environment variables to the features as a
+            // normal dep.
+            //
+            // If `is_for_build_dep` here is `true`, that means that this
+            // package is being used as a build dependency, and so we only
+            // want to set CARGO_FEATURE_* variables for the build-dependency
+            // side of the graph.
+            //
+            // Keep in mind that the RunCustomBuild unit and the Compile
+            // build.rs unit use the same features. This is because some
+            // people use `cfg!` and `#[cfg]` expressions to check for enabled
+            // features instead of just checking `CARGO_FEATURE_*` at runtime.
+            // In the case with `-Zfeatures=build_dep`, and a shared
+            // dependency has different features enabled for normal vs. build,
+            // then the build.rs script will get compiled twice. I believe it
+            // is not feasible to only build it once because it would break a
+            // large number of scripts (they would think they have the wrong
+            // set of features enabled).
             let script_unit_for = UnitFor::new_build(unit_for.is_for_build_dep());
             new_unit_dep_with_profile(
                 state,

diff --git a/src/cargo/core/profiles.rs b/src/cargo/core/profiles.rs
index ff3e5283ba697a50b565fbbb97286834d9b93a4d..2f83aba2211aae9884d5c2bf6c2cc5e805cf8b2f 100644 (file)
--- a/src/cargo/core/profiles.rs
+++ b/src/cargo/core/profiles.rs
@@ -768,6 +768,15 @@ pub struct UnitFor {
     /// these targets.
     ///
     /// An invariant is that if `build_dep` is true, `host` must be true.
+    ///
+    /// Note that this is `true` for `RunCustomBuild` units, even though that
+    /// unit should *not* use build-override profiles. This is a bit of a
+    /// special case. When computing the `RunCustomBuild` unit, it manually
+    /// uses the `get_profile_run_custom_build` method to get the correct
+    /// profile information for the unit. `host` needs to be true so that all
+    /// of the dependencies of that `RunCustomBuild` unit have this flag be
+    /// sticky (and forced to `true` for all further dependencies) — which is
+    /// the whole point of `UnitFor`.
     host: bool,
     /// A target for a build dependency (or any of its dependencies). This is
     /// used for computing features of build dependencies independently of