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.

rustbot · 2025-06-20T05:33:29Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

These tests show what prior versions of Cargo will do with hints. The subsequent addition of support for hints will modify these tests to reflect the corresponding changes to Cargo.

…vior) These tests demonstrate the behavior of current Cargo, and will be changed when adding `hints.mostly-unused` to reflect the new behavior.

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.

Make it only a warning, not an error, to have a hint value of the wrong type.

src/cargo/core/compiler/mod.rs

src/doc/src/reference/manifest.md

joshtriplett · 2025-06-22T01:15:55Z

Another fun benchmark number for this, using --timings:

I built a crate that depended on the windows crate, with all of its "Graphics*" and "UI*" features enabled.

Without hint-mostly-unused, windows took 15.1s, of which 49% was codegen.

With hint-mostly-unused, windows took 7.5s, of which 1% was codegen.

rustbot added A-build-execution Area: anything dealing with executing the compiler A-documenting-cargo-itself Area: Cargo's documentation A-manifest Area: Cargo.toml issues A-profiles Area: profiles A-unstable Area: nightly unstable support labels Jun 16, 2025