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

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.

Author: joshtriplett

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

@@ -167,6 +167,16 @@
         }
       ]
     },
+    "hints": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/Hints"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "workspace": {
       "anyOf": [
         {
@@ -1017,6 +1027,17 @@
         "$ref": "#/$defs/TomlValue"
       }
     },
+    "Hints": {
+      "type": "object",
+      "properties": {
+        "mostly-unused": {
+          "type": [
+            "boolean",
+            "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,13 @@ 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 {
+    pub mostly_unused: Option<bool>,
+}
+
 #[derive(Copy, Clone, Debug)]
 pub struct InvalidCargoFeatures {}
 

src/cargo/core/compiler/mod.rs

@@ -1138,6 +1138,7 @@ fn build_base_args(
         hint_mostly_unused,
         ..
     } = unit.profile.clone();
+    let hints = unit.pkg.hints().cloned().unwrap_or_default();
     let test = unit.mode.is_any_test();
 
     cmd.arg("--crate-name").arg(&unit.target.crate_name());
@@ -1326,13 +1327,19 @@ fn build_base_args(
         opt(cmd, "-C", "incremental=", Some(dir));
     }
 
-    if hint_mostly_unused {
+    if hint_mostly_unused.or(hints.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 hint_mostly_unused.is_some() {
+                bcx.gctx
+                    .shell()
+                    .warn("ignoring 'hint-mostly-unused' profile option, pass `-Zprofile-hint-mostly-unused` to enable it")?;
+            } else if hints.mostly_unused.is_some() {
+                bcx.gctx
+                    .shell()
+                    .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/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,

tests/testsuite/hints.rs

@@ -5,7 +5,7 @@ use cargo_test_support::registry::Package;
 use cargo_test_support::{project, str};
 
 #[cargo_test]
-fn empty_hints_warn() {
+fn empty_hints_no_warn() {
     let p = project()
         .file(
             "Cargo.toml",
@@ -22,7 +22,6 @@ fn empty_hints_warn() {
         .build();
     p.cargo("check -v")
         .with_stderr_data(str![[r#"
-[WARNING] unused manifest key: hints
 [CHECKING] foo v0.0.1 ([ROOT]/foo)
 [RUNNING] `rustc --crate-name foo [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
@@ -50,7 +49,7 @@ fn unknown_hints_warn() {
         .build();
     p.cargo("check -v")
         .with_stderr_data(str![[r#"
-[WARNING] unused manifest key: hints
+[WARNING] unused manifest key: hints.this-is-an-unknown-hint
 [CHECKING] foo v0.0.1 ([ROOT]/foo)
 [RUNNING] `rustc --crate-name foo [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
@@ -92,16 +91,19 @@ fn hint_unknown_type_warn() {
         .file("src/main.rs", "fn main() {}")
         .build();
     p.cargo("check -v")
+        .with_status(101)
         .with_stderr_data(str![[r#"
 [UPDATING] `dummy-registry` index
 [LOCKING] 1 package to latest compatible version
 [DOWNLOADING] crates ...
 [DOWNLOADED] bar v1.0.0 (registry `dummy-registry`)
-[CHECKING] bar v1.0.0
-[RUNNING] `rustc --crate-name bar [..]`
-[CHECKING] foo v0.0.1 ([ROOT]/foo)
-[RUNNING] `rustc --crate-name foo [..]`
-[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
+[ERROR] invalid type: integer `1`, expected a boolean
+ --> ../home/.cargo/registry/src/-[HASH]/bar-1.0.0/Cargo.toml:8:29
+  |
+8 |             mostly-unused = 1
+  |                             ^
+  |
+[ERROR] failed to download replaced source registry `crates-io`
 
 "#]])
         .with_stderr_does_not_contain("-Zhint-mostly-unused")
@@ -146,6 +148,7 @@ fn hints_mostly_unused_warn_without_gate() {
 [LOCKING] 1 package to latest compatible version
 [DOWNLOADING] crates ...
 [DOWNLOADED] bar v1.0.0 (registry `dummy-registry`)
+[WARNING] ignoring 'hints.mostly-unused', pass `-Zprofile-hint-mostly-unused` to enable it
 [CHECKING] bar v1.0.0
 [RUNNING] `rustc --crate-name bar [..]`
 [CHECKING] foo v0.0.1 ([ROOT]/foo)
@@ -197,7 +200,7 @@ fn hints_mostly_unused_nightly() {
 [DOWNLOADING] crates ...
 [DOWNLOADED] bar v1.0.0 (registry `dummy-registry`)
 [CHECKING] bar v1.0.0
-[RUNNING] `rustc --crate-name bar [..]`
+[RUNNING] `rustc --crate-name bar [..] -Zhint-mostly-unused [..]`
 [CHECKING] foo v0.0.1 ([ROOT]/foo)
 [RUNNING] `rustc --crate-name foo [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
@@ -284,7 +287,6 @@ fn mostly_unused_profile_overrides_hints_on_self_nightly() {
         .build();
     p.cargo("check -v")
         .with_stderr_data(str![[r#"
-[WARNING] unused manifest key: hints
 [CHECKING] foo v0.0.1 ([ROOT]/foo)
 [RUNNING] `rustc --crate-name foo [..]`
 [FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s