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

joshtriplett · 2025-06-16T21:51:23Z

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.

jeffparsons · 2025-06-17T09:06:06Z

Sorry if this is the wrong place for this, but I'd love to see how this affects a simple binary using the aws-sdk-ec2 crate. I think if it is able to shave much time / memory consumption off those "worst offenders" then that would make a pretty compelling case for its value.

src/cargo/core/profiles.rs

tests/testsuite/hints.rs

src/doc/src/reference/unstable.md

joshtriplett · 2025-06-17T14:33:39Z

Note: should add a test for [hints] parsing to robustly handle a key it knows but syntax it doesn't know (because it might be future syntax).

joshtriplett · 2025-06-17T15:05:32Z

Sorry if this is the wrong place for this, but I'd love to see how this affects a simple binary using the aws-sdk-ec2 crate. I think if it is able to shave much time / memory consumption off those "worst offenders" then that would make a pretty compelling case for its value.

For a crate depending on aws-sdk-ec2, a release build went from 4m07s to 2m04s, and a non-release build went from 2m26s to 1m28s.

src/doc/src/reference/unstable.md

tests/testsuite/hints.rs

src/cargo/core/compiler/mod.rs

epage

Just waiting on #15643

epage · 2025-06-18T19:05:51Z

@rfcbot fcp merge

This insta-stabilizes a new [hints] table to Cargo.toml that affects building this as a dependency. As these are just hints, there are no guarantees about what will actually be done, including us removing the table completely. As such, unstable fields do not error and wrongly-shaped fields do not error.

While this is blocked on rustc, I figured we could run our FCP in parallel.

rfcbot · 2025-06-18T19:05:53Z

Team member @epage has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

src/doc/src/reference/manifest.md

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

epage · 2025-07-12T01:05:49Z

Sorry for the last minute finds

Addressed.

src/doc/src/reference/manifest.md

tests/testsuite/hints.rs

… capped

Update cargo 1 commits in eabb4cd923deb73e714f7ad3f5234d68ca284dbe..6833aa715d724437dc1247d0166afe314ab6854e 2025-07-09 22:07:55 +0000 to 2025-07-13 02:25:52 +0000 - Add `[hints]` table in `Cargo.toml`, and a `hints.mostly-unused` hint (rust-lang/cargo#15673)

rustbot added A-build-execution A-documenting-cargo-itself A-manifest A-profiles A-unstable labels Jun 16, 2025