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

Cargo.toml

@@ -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"] }

crates/cargo-util-schemas/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/manifest.schema.json

@@ -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/src/manifest/mod.rs

@@ -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 {}
 

src/cargo/core/compiler/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/manifest.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/package.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/profiles.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/sources/registry/index/cache.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);

src/cargo/util/toml/mod.rs

@@ -327,6 +327,7 @@ fn normalize_toml(
         build_dependencies2: None,
         target: None,
         lints: None,
+        hints: None,
         workspace: original_toml.workspace.clone().or_else(|| {
             // Prevent looking for a workspace by `read_manifest_from_str`
             is_embedded.then(manifest::TomlWorkspace::default)
@@ -571,6 +572,8 @@ fn normalize_toml(
             lints,
         });
 
+        normalized_toml.hints = original_toml.hints.clone();
+
         normalized_toml.badges = original_toml.badges.clone();
     } else {
         if let Some(field) = original_toml.requires_package().next() {
@@ -1628,6 +1631,8 @@ pub fn to_real_manifest(
             .unwrap_or(&default),
     )?;
 
+    let hints = normalized_toml.hints.clone();
+
     let metadata = ManifestMetadata {
         description: normalized_package
             .normalized_description()
@@ -1819,6 +1824,7 @@ pub fn to_real_manifest(
         metabuild,
         resolve_behavior,
         rustflags,
+        hints,
         is_embedded,
     );
     if manifest
@@ -3080,6 +3086,7 @@ fn prepare_toml_for_publish(
             None => None,
         },
         lints: me.lints.clone(),
+        hints: me.hints.clone(),
         workspace: None,
         profile: me.profile.clone(),
         patch: None,

src/doc/src/reference/manifest.md

@@ -50,6 +50,7 @@ Every manifest file consists of the following sections:
 * [`[badges]`](#the-badges-section) --- Badges to display on a registry.
 * [`[features]`](features.md) --- Conditional compilation features.
 * [`[lints]`](#the-lints-section) --- Configure linters for this package.
+* [`[hints]`](#the-hints-section) --- Provide hints for compiling this package.
 * [`[patch]`](overriding-dependencies.md#the-patch-section) --- Override dependencies.
 * [`[replace]`](overriding-dependencies.md#the-replace-section) --- Override dependencies (deprecated).
 * [`[profile]`](profiles.md) --- Compiler settings and optimizations.
@@ -565,6 +566,26 @@ As for dependents, Cargo suppresses lints from non-path dependencies with featur
 
 > **MSRV:** Respected as of 1.74
 
+## The `[hints]` section
+
+The `[hints]` section allows specifying hints for compiling this package. Cargo
+will respect these hints by default when compiling this package, though the
+top-level package being built can override these values through the `[profile]`
+mechanism. Hints are, by design, always safe for Cargo to ignore; if Cargo
+encounters a hint it doesn't understand, or a hint it understands but with a
+value it doesn't understand, it will warn, but not error. As a result,
+specifying hints in a crate does not impact the MSRV of the crate.
+
+Individual hints may have an associated unstable feature gate that you need to
+pass in order to apply the configuration they specify, but if you don't specify
+that unstable feature gate, you will again get only a warning, not an error.
+
+There are no stable hints at this time. See the [hint-mostly-unused
+documentation](unstable.md#profile-hint-mostly-unused-option) for information
+on an unstable hint.
+
+> **MSRV:** Respected as of 1.90.
+
 ## The `[badges]` section
 
 The `[badges]` section is for specifying status badges that can be displayed