Add [hints] table in Cargo.toml, and a hints.mostly-unused hint (#15673)

The `[hints]` table in a `Cargo.toml` manifest provides optional
information that Cargo can use for building the package, and will use
even when using the package as a dependency. All hints can be safely
ignored, and Cargo only warns about unknown hints, but does not error.
This allows packages to use hints without depending on new Cargo.

Add a `mostly-unused` hint, which allows a package to hint that most
users of the package will not use most of its items. This is useful for
improving the build performance of crates with large dependencies.

Crates can override this hint using `hint-mostly-unused = false` in
their profile for a dependency.

---

In the future, this same mechanism could be used for other hints, such
as
`min-opt-level`.

### How to test and review this PR?

This PR is built atop #15643 .
I'd
suggest reviewing that PR separately, then just reviewing the new
commits in
this PR.

The new "hints" testsuite module demonstrates the expected behavior of
hints.

Like #15643 , the nightly-only
tests
will only pass once rust-lang/rust#135656 has
been
merged into Rust.

Author: epage

Cargo.lock

@@ -34,7 +34,7 @@ cargo-platform = { path = "crates/cargo-platform", version = "0.3.0" }
 cargo-test-macro = { version = "0.4.4", path = "crates/cargo-test-macro" }
 cargo-test-support = { version = "0.8.0", path = "crates/cargo-test-support" }
 cargo-util = { version = "0.2.22", path = "crates/cargo-util" }
-cargo-util-schemas = { version = "0.9.0", path = "crates/cargo-util-schemas" }
+cargo-util-schemas = { version = "0.10.0", path = "crates/cargo-util-schemas" }
 cargo_metadata = "0.20.0"
 clap = "4.5.40"
 clap_complete = { version = "4.5.54", features = ["unstable-dynamic"] }

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cargo-util-schemas"
-version = "0.9.1"
+version = "0.10.0"
 rust-version = "1.88"  # MSRV:1
 edition.workspace = true
 license.workspace = true

crates/cargo-util-schemas/Cargo.toml

@@ -167,6 +167,16 @@
         }
       ]
     },
+    "hints": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/Hints"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "workspace": {
       "anyOf": [
         {
@@ -1017,6 +1027,21 @@
         "$ref": "#/$defs/TomlValue"
       }
     },
+    "Hints": {
+      "type": "object",
+      "properties": {
+        "mostly-unused": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/TomlValue"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
     "TomlWorkspace": {
       "type": "object",
       "properties": {

crates/cargo-util-schemas/manifest.schema.json

@@ -56,6 +56,7 @@ pub struct TomlManifest {
     pub build_dependencies2: Option<BTreeMap<PackageName, InheritableDependency>>,
     pub target: Option<BTreeMap<String, TomlPlatform>>,
     pub lints: Option<InheritableLints>,
+    pub hints: Option<Hints>,
 
     pub workspace: Option<TomlWorkspace>,
     pub profile: Option<TomlProfiles>,
@@ -85,6 +86,7 @@ impl TomlManifest {
                 .map(|_| "build-dependencies"),
             self.target.as_ref().map(|_| "target"),
             self.lints.as_ref().map(|_| "lints"),
+            self.hints.as_ref().map(|_| "hints"),
         ]
         .into_iter()
         .flatten()
@@ -1644,6 +1646,17 @@ pub enum TomlLintLevel {
     Allow,
 }
 
+#[derive(Serialize, Deserialize, Debug, Default, Clone)]
+#[serde(rename_all = "kebab-case")]
+#[cfg_attr(feature = "unstable-schema", derive(schemars::JsonSchema))]
+pub struct Hints {
+    #[cfg_attr(
+        feature = "unstable-schema",
+        schemars(with = "Option<TomlValueWrapper>")
+    )]
+    pub mostly_unused: Option<toml::Value>,
+}
+
 #[derive(Copy, Clone, Debug)]
 pub struct InvalidCargoFeatures {}
 

crates/cargo-util-schemas/src/manifest/mod.rs

@@ -1135,11 +1135,27 @@ fn build_base_args(
         strip,
         rustflags: profile_rustflags,
         trim_paths,
-        hint_mostly_unused,
+        hint_mostly_unused: profile_hint_mostly_unused,
         ..
     } = unit.profile.clone();
+    let hints = unit.pkg.hints().cloned().unwrap_or_default();
     let test = unit.mode.is_any_test();
 
+    let warn = |msg: &str| {
+        bcx.gctx.shell().warn(format!(
+            "{}@{}: {msg}",
+            unit.pkg.package_id().name(),
+            unit.pkg.package_id().version()
+        ))
+    };
+    let unit_capped_warn = |msg: &str| {
+        if unit.show_warnings(bcx.gctx) {
+            warn(msg)
+        } else {
+            Ok(())
+        }
+    };
+
     cmd.arg("--crate-name").arg(&unit.target.crate_name());
 
     let edition = unit.target.edition();
@@ -1326,13 +1342,34 @@ fn build_base_args(
         opt(cmd, "-C", "incremental=", Some(dir));
     }
 
-    if hint_mostly_unused {
+    let pkg_hint_mostly_unused = match hints.mostly_unused {
+        None => None,
+        Some(toml::Value::Boolean(b)) => Some(b),
+        Some(v) => {
+            unit_capped_warn(&format!(
+                "ignoring unsupported value type ({}) for 'hints.mostly-unused', which expects a boolean",
+                v.type_str()
+            ))?;
+            None
+        }
+    };
+    if profile_hint_mostly_unused
+        .or(pkg_hint_mostly_unused)
+        .unwrap_or(false)
+    {
         if bcx.gctx.cli_unstable().profile_hint_mostly_unused {
             cmd.arg("-Zhint-mostly-unused");
         } else {
-            bcx.gctx
-                .shell()
-                .warn("ignoring 'hint-mostly-unused' profile option, pass `-Zprofile-hint-mostly-unused` to enable it")?;
+            if profile_hint_mostly_unused.is_some() {
+                // Profiles come from the top-level unit, so we don't use `unit_capped_warn` here.
+                warn(
+                    "ignoring 'hint-mostly-unused' profile option, pass `-Zprofile-hint-mostly-unused` to enable it",
+                )?;
+            } else if pkg_hint_mostly_unused.is_some() {
+                unit_capped_warn(
+                    "ignoring 'hints.mostly-unused', pass `-Zprofile-hint-mostly-unused` to enable it",
+                )?;
+            }
         }
     }
 

src/cargo/core/compiler/mod.rs

@@ -8,7 +8,7 @@ use std::sync::Arc;
 
 use anyhow::Context as _;
 use cargo_util_schemas::manifest::RustVersion;
-use cargo_util_schemas::manifest::{TomlManifest, TomlProfiles};
+use cargo_util_schemas::manifest::{Hints, TomlManifest, TomlProfiles};
 use semver::Version;
 use serde::Serialize;
 use serde::ser;
@@ -90,6 +90,7 @@ pub struct Manifest {
     metabuild: Option<Vec<String>>,
     resolve_behavior: Option<ResolveBehavior>,
     lint_rustflags: Vec<String>,
+    hints: Option<Hints>,
     embedded: bool,
 }
 
@@ -521,6 +522,7 @@ impl Manifest {
         metabuild: Option<Vec<String>>,
         resolve_behavior: Option<ResolveBehavior>,
         lint_rustflags: Vec<String>,
+        hints: Option<Hints>,
         embedded: bool,
     ) -> Manifest {
         Manifest {
@@ -551,6 +553,7 @@ impl Manifest {
             metabuild,
             resolve_behavior,
             lint_rustflags,
+            hints,
             embedded,
         }
     }
@@ -668,6 +671,10 @@ impl Manifest {
         self.lint_rustflags.as_slice()
     }
 
+    pub fn hints(&self) -> Option<&Hints> {
+        self.hints.as_ref()
+    }
+
     pub fn map_source(self, to_replace: SourceId, replace_with: SourceId) -> Manifest {
         Manifest {
             summary: self.summary.map_source(to_replace, replace_with),

src/cargo/core/manifest.rs

@@ -9,7 +9,7 @@ use std::rc::Rc;
 use std::time::{Duration, Instant};
 
 use anyhow::Context as _;
-use cargo_util_schemas::manifest::RustVersion;
+use cargo_util_schemas::manifest::{Hints, RustVersion};
 use curl::easy::Easy;
 use curl::multi::{EasyHandle, Multi};
 use lazycell::LazyCell;
@@ -95,6 +95,8 @@ pub struct SerializedPackage {
     metabuild: Option<Vec<String>>,
     default_run: Option<String>,
     rust_version: Option<RustVersion>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    hints: Option<Hints>,
 }
 
 impl Package {
@@ -172,6 +174,11 @@ impl Package {
         self.manifest().rust_version()
     }
 
+    /// Gets the package's hints.
+    pub fn hints(&self) -> Option<&Hints> {
+        self.manifest().hints()
+    }
+
     /// Returns `true` if the package uses a custom build script for any target.
     pub fn has_custom_build(&self) -> bool {
         self.targets().iter().any(|t| t.is_custom_build())
@@ -241,6 +248,7 @@ impl Package {
             publish: self.publish().as_ref().cloned(),
             default_run: self.manifest().default_run().map(|s| s.to_owned()),
             rust_version: self.rust_version().cloned(),
+            hints: self.hints().cloned(),
         }
     }
 }

src/cargo/core/package.rs

@@ -578,7 +578,7 @@ fn merge_profile(profile: &mut Profile, toml: &TomlProfile) {
         profile.trim_paths = Some(trim_paths.clone());
     }
     if let Some(hint_mostly_unused) = toml.hint_mostly_unused {
-        profile.hint_mostly_unused = hint_mostly_unused;
+        profile.hint_mostly_unused = Some(hint_mostly_unused);
     }
     profile.strip = match toml.strip {
         Some(StringOrBool::Bool(true)) => Strip::Resolved(StripInner::Named("symbols".into())),
@@ -629,8 +629,8 @@ pub struct Profile {
     // remove when `-Ztrim-paths` is stablized
     #[serde(skip_serializing_if = "Option::is_none")]
     pub trim_paths: Option<TomlTrimPaths>,
-    #[serde(skip_serializing_if = "std::ops::Not::not")]
-    pub hint_mostly_unused: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hint_mostly_unused: Option<bool>,
 }
 
 impl Default for Profile {
@@ -652,7 +652,7 @@ impl Default for Profile {
             strip: Strip::Deferred(StripInner::None),
             rustflags: vec![],
             trim_paths: None,
-            hint_mostly_unused: false,
+            hint_mostly_unused: None,
         }
     }
 }

src/cargo/core/profiles.rs

@@ -204,7 +204,7 @@ impl<'a> SummariesCache<'a> {
         let size = self
             .versions
             .iter()
-            .map(|(_version, data)| (10 + data.len()))
+            .map(|(_version, data)| 10 + data.len())
             .sum();
         let mut contents = Vec::with_capacity(size);
         contents.push(CURRENT_CACHE_VERSION);