Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused #135656

joshtriplett · 2025-01-17T21:29:50Z

This hint allows the compiler to optimize its operation based on this assumption, in order to compile faster. This is a hint, and does not guarantee any particular behavior.

This option can substantially speed up compilation if applied to a large dependency where the majority of the dependency does not get used. This flag may slow down compilation in other cases.

Currently, this option makes the compiler defer as much code generation as possible from functions in the crate, until later crates invoke those functions. Functions that never get invoked will never have code generated for them. For instance, if a crate provides thousands of functions, but only a few of them will get called, this flag will result in the compiler only doing code generation for the called functions. (This uses the same mechanisms as cross-crate inlining of functions.) This does not affect extern functions, or functions marked as #[inline(never)].

This option has already existed in nightly as -Zcross-crate-inline-threshold=always for some time, and has gotten testing in that form. However, this option is still unstable, to give an opportunity for wider testing in this form.

Some performance numbers, based on a crate with many dependencies having just one large dependency set to -Z hint-mostly-unused (using Cargo's profile-rustflags option):

A release build went from 4m07s to 2m04s.

A non-release build went from 2m26s to 1m28s.

rustbot · 2025-01-17T21:29:59Z

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
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

rustbot · 2025-01-17T21:30:00Z

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

GuillaumeGomez · 2025-01-17T21:33:02Z

r? compiler

workingjubilee · 2025-01-17T21:44:01Z

This should be added as an unstable option first?

compiler/rustc_interface/src/tests.rs

workingjubilee · 2025-01-17T22:53:27Z

@joshtriplett:

@workingjubilee This option has already existed in nightly as -Zcross-crate-inline-threshold=always for some time, and has gotten testing in that form.

The only difference being made between that option and this one is that this one respects #[inline(never)].

I see. I suppose that makes sense, though it brings these thoughts to mind:

In general, T-compiler has a much lower threshold for unstable flags that are not intended for serious or permanent usage downstream. They're often added as debugging aids. I am not sure if this was intended for public usage when it was originally added.
All inlining annotations are hints, and this is also noted as a hint, yet it changes the behavior of another inlining hint, and in that way deviates from its unstable variation.
Notably, inline(never) is often relied on to some degree by programmers as working.
This describes itself as a hint, but also is motivated on the basis that it will be very impactful, which suggests its behavior will be immediately relied on. The combination of relying-on-inlining-but-also-relying-on-not-inlining makes me wonder if it is definitely correct? There are a lot of weird nuances to our inlining rules.

As a result, I am curious if the rest of T-compiler believes changing the behavior with respect to inline(never) is trivial.

Perhaps this should land with a test that demonstrates that it respects #[inline(never)] correctly, now?

workingjubilee · 2025-01-18T00:13:07Z

( I'm also kinda curious if we should adjust how we handle cross-crate inlining by default, tbh. )

lqd · 2025-01-18T00:24:30Z

You may have missed it Jubilee, so hop on to https://rust-lang.zulipchat.com/#narrow/stream/233931-xxx/topic/Add.20.60-C.20hint-mostly-unused.60.20option.20compiler-team.23829 to ask your cool questions and comments :)

src/doc/rustc/src/codegen-options/index.md

fee1-dead · 2025-01-21T23:15:02Z

r? compiler

…o unused This hint allows the compiler to optimize its operation based on this assumption, in order to compile faster. This is a hint, and does not guarantee any particular behavior. This option can substantially speed up compilation if applied to a large dependency where the majority of the dependency does not get used. This flag may slow down compilation in other cases. Currently, this option makes the compiler defer as much code generation as possible from functions in the crate, until later crates invoke those functions. Functions that never get invoked will never have code generated for them. For instance, if a crate provides thousands of functions, but only a few of them will get called, this flag will result in the compiler only doing code generation for the called functions. (This uses the same mechanisms as cross-crate inlining of functions.) This does not affect `extern` functions, or functions marked as `#[inline(never)]`. Some performance numbers, based on a crate with many dependencies having just *one* large dependency set to `-Z hint-mostly-unused` (using Cargo's `profile-rustflags` option): A release build went from 4m07s to 2m04s. A non-release build went from 2m26s to 1m28s.

joshtriplett · 2025-06-07T02:21:09Z

Based on discussion about this at RustWeek, it sounded like this proposal had given the impression of wanting to rush stabilization, rather than being an unstable option to test and gather experience reports. Based on that discussion, I've reworked this PR and opened a new MCP to make it explicitly clear that this is an unstable option intended for a call for testing and for plumbing as a nightly Cargo option.

I've updated the implementation of this to be a -Z option, and added more documentation for it in the unstable book (including how to use Cargo to selectively enable it for specific crates).

I've also rebased it, re-tested it, and re-benchmarked it.

joshtriplett · 2025-06-08T23:44:38Z

@rustbot ready

saethlin · 2025-06-17T13:50:07Z

@bors r+

bors · 2025-06-17T13:50:09Z

📌 Commit 1b23b64 has been approved by saethlin

It is now in the queue for this repository.

…=saethlin Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused This hint allows the compiler to optimize its operation based on this assumption, in order to compile faster. This is a hint, and does not guarantee any particular behavior. This option can substantially speed up compilation if applied to a large dependency where the majority of the dependency does not get used. This flag may slow down compilation in other cases. Currently, this option makes the compiler defer as much code generation as possible from functions in the crate, until later crates invoke those functions. Functions that never get invoked will never have code generated for them. For instance, if a crate provides thousands of functions, but only a few of them will get called, this flag will result in the compiler only doing code generation for the called functions. (This uses the same mechanisms as cross-crate inlining of functions.) This does not affect `extern` functions, or functions marked as `#[inline(never)]`. This option has already existed in nightly as `-Zcross-crate-inline-threshold=always` for some time, and has gotten testing in that form. However, this option is still unstable, to give an opportunity for wider testing in this form. Some performance numbers, based on a crate with many dependencies having just *one* large dependency set to `-Z hint-mostly-unused` (using Cargo's `profile-rustflags` option): A release build went from 4m07s to 2m04s. A non-release build went from 2m26s to 1m28s.

Rollup of 10 pull requests Successful merges: - #135656 (Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused) - #138237 (Get rid of `EscapeDebugInner`.) - #140772 ({aarch64,x86_64}-pc-windows-gnullvm: build host tools) - #140774 (Affirm `-Cforce-frame-pointers=off` does not override) - #141610 (Stabilize `feature(generic_arg_infer)`) - #141864 (Handle win32 separator for cygwin paths) - #142384 (Bringing `rustc_rayon_core` in tree as `rustc_thread_pool`) - #142502 (rustdoc_json: improve handling of generic args) - #142571 (Reason about borrowed classes in CopyProp.) - #142591 (Add spawn APIs for BootstrapCommand to support deferred command execution) r? `@ghost` `@rustbot` modify labels: rollup

…=saethlin Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused This hint allows the compiler to optimize its operation based on this assumption, in order to compile faster. This is a hint, and does not guarantee any particular behavior. This option can substantially speed up compilation if applied to a large dependency where the majority of the dependency does not get used. This flag may slow down compilation in other cases. Currently, this option makes the compiler defer as much code generation as possible from functions in the crate, until later crates invoke those functions. Functions that never get invoked will never have code generated for them. For instance, if a crate provides thousands of functions, but only a few of them will get called, this flag will result in the compiler only doing code generation for the called functions. (This uses the same mechanisms as cross-crate inlining of functions.) This does not affect `extern` functions, or functions marked as `#[inline(never)]`. This option has already existed in nightly as `-Zcross-crate-inline-threshold=always` for some time, and has gotten testing in that form. However, this option is still unstable, to give an opportunity for wider testing in this form. Some performance numbers, based on a crate with many dependencies having just *one* large dependency set to `-Z hint-mostly-unused` (using Cargo's `profile-rustflags` option): A release build went from 4m07s to 2m04s. A non-release build went from 2m26s to 1m28s.

Rollup of 12 pull requests Successful merges: - #135656 (Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused) - #140774 (Affirm `-Cforce-frame-pointers=off` does not override) - #141610 (Stabilize `feature(generic_arg_infer)`) - #142123 (Implement initial support for timing sections (`--json=timings`)) - #142383 (CodeGen: rework Aggregate implemention for rvalue_creates_operand cases) - #142502 (rustdoc_json: improve handling of generic args) - #142591 (Add spawn APIs for BootstrapCommand to support deferred command execution) - #142606 (AsyncDrop trait without sync Drop generates an error) - #142619 (apply clippy::or_fun_call) - #142624 (Actually take `--build` into account in bootstrap) - #142627 (Add `StepMetadata` to describe steps) - #142660 (remove joboet from review rotation) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 6 pull requests Successful merges: - #135656 (Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused) - #138237 (Get rid of `EscapeDebugInner`.) - #141614 (lint direct use of rustc_type_ir ) - #142123 (Implement initial support for timing sections (`--json=timings`)) - #142377 (Try unremapping compiler sources) - #142674 (remove duplicate crash test) r? `@ghost` `@rustbot` modify labels: rollup

Rollup of 6 pull requests Successful merges: - rust-lang/rust#135656 (Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused) - rust-lang/rust#138237 (Get rid of `EscapeDebugInner`.) - rust-lang/rust#141614 (lint direct use of rustc_type_ir ) - rust-lang/rust#142123 (Implement initial support for timing sections (`--json=timings`)) - rust-lang/rust#142377 (Try unremapping compiler sources) - rust-lang/rust#142674 (remove duplicate crash test) r? `@ghost` `@rustbot` modify labels: rollup

…15643) The rustc `-Zhint-mostly-unused` flag tells rustc that most of a crate will go unused. This is useful for speeding up compilation of large dependencies from which you only use a few items. Plumb that option through as a profile option, to allow specifying it for specific dependencies: ```toml [profile.dev.package.huge-mostly-unused-dependency] hint-mostly-unused = true ``` To enable this feature, pass `-Zprofile-hint-mostly-unused`. However, since this option is a hint, using it without passing `-Zprofile-hint-mostly-unused` will only warn and ignore the profile option. Versions of Cargo prior to the introduction of this feature will give an "unused manifest key" warning, but will otherwise function without erroring. This allows using the hint in a crate's `Cargo.toml` without mandating the use of a newer Cargo to build it. Add a test verifying that the profile option gets ignored with a warning without passing `-Zprofile-hint-mostly-unused`, and another test verifying that it gets handled when passing `-Zprofile-hint-mostly-unused`. ### How to test and review this PR? The tests in the testsuite demonstrate both that the option works as expected and that it gets ignored with a warning if not passing `-Zprofile-hint-mostly-unused`. This will remain a draft until rust-lang/rust#135656 gets merged in rustc; once that happens, the "nightly" jobs will pass in CI.

joshtriplett added I-compiletime Issue: Problems and improvements with respect to compile times. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Jan 17, 2025

rustbot assigned GuillaumeGomez Jan 17, 2025

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 17, 2025

joshtriplett mentioned this pull request Jan 17, 2025

Add -C hint-mostly-unused option rust-lang/compiler-team#829

Closed

3 tasks

rustbot assigned fee1-dead and unassigned GuillaumeGomez Jan 17, 2025

joshtriplett added the relnotes Marks issues that should be documented in the release notes of the next release. label Jan 17, 2025

rustbot mentioned this pull request Jan 17, 2025

Tracking issue for release notes of #135656: Add -C hint-mostly-unused to tell rustc that most of a crate will go unused #135657

Open

3 tasks

This comment was marked as outdated.

Sign in to view

workingjubilee added needs-fcp This change is insta-stable, or significant enough to need a team FCP to proceed. I-compiler-nominated Nominated for discussion during a compiler team meeting. labels Jan 17, 2025

This comment was marked as resolved.

Sign in to view

Urgau reviewed Jan 17, 2025

View reviewed changes

compiler/rustc_interface/src/tests.rs Outdated Show resolved Hide resolved

lqd reviewed Jan 17, 2025

View reviewed changes

compiler/rustc_interface/src/tests.rs Outdated Show resolved Hide resolved

joshtriplett force-pushed the hint-mostly-unused branch from 4d1b2cb to e96e15f Compare January 18, 2025 05:19

joshtriplett removed relnotes Marks issues that should be documented in the release notes of the next release. needs-fcp This change is insta-stable, or significant enough to need a team FCP to proceed. labels Jan 18, 2025

Urgau reviewed Jan 18, 2025

View reviewed changes

src/doc/rustc/src/codegen-options/index.md Outdated Show resolved Hide resolved

rustbot assigned BoxyUwU and unassigned fee1-dead Jan 21, 2025

saethlin added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 7, 2025

joshtriplett force-pushed the hint-mostly-unused branch from d3f3a68 to 0e58964 Compare June 7, 2025 02:09

joshtriplett changed the title ~~Add -C hint-mostly-unused to tell rustc that most of a crate will go unused~~ Add -Z hint-mostly-unused to tell rustc that most of a crate will go unused Jun 7, 2025

joshtriplett force-pushed the hint-mostly-unused branch from 0e58964 to 1b23b64 Compare June 7, 2025 02:12

joshtriplett mentioned this pull request Jun 7, 2025

Add -Z hint-mostly-unused option to hint that most of a crate's API surface will be unused rust-lang/compiler-team#883

Closed

3 tasks

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jun 8, 2025

joshtriplett mentioned this pull request Jun 9, 2025

Plumb rustc -Zhint-mostly-unused flag through as a profile option rust-lang/cargo#15643

Merged

joshtriplett mentioned this pull request Jun 16, 2025

Add [hints] table in Cargo.toml, and a hints.mostly-unused hint rust-lang/cargo#15673

Open

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 17, 2025

jhpratt mentioned this pull request Jun 18, 2025

Rollup of 10 pull requests #142656

Closed

Kobzol mentioned this pull request Jun 18, 2025

Rollup of 12 pull requests #142665

Closed

Urgau mentioned this pull request Jun 18, 2025

Rollup of 6 pull requests #142689

Merged

bors merged commit 33185d3 into rust-lang:master Jun 19, 2025
10 checks passed

rustbot added this to the 1.89.0 milestone Jun 19, 2025

joshtriplett deleted the hint-mostly-unused branch June 19, 2025 03:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused #135656

Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused #135656

joshtriplett commented Jan 17, 2025 •

edited

Loading

Uh oh!

rustbot commented Jan 17, 2025

Uh oh!

rustbot commented Jan 17, 2025

Uh oh!

GuillaumeGomez commented Jan 17, 2025

Uh oh!

workingjubilee commented Jan 17, 2025

Uh oh!

This comment was marked as outdated.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

workingjubilee commented Jan 17, 2025

Uh oh!

workingjubilee commented Jan 18, 2025

Uh oh!

lqd commented Jan 18, 2025

Uh oh!

Uh oh!

fee1-dead commented Jan 21, 2025

Uh oh!

joshtriplett commented Jun 7, 2025 •

edited

Loading

Uh oh!

joshtriplett commented Jun 8, 2025

Uh oh!

saethlin commented Jun 17, 2025

Uh oh!

bors commented Jun 17, 2025

Uh oh!

Uh oh!

Uh oh!

Add -Z hint-mostly-unused to tell rustc that most of a crate will go unused #135656

Add -Z hint-mostly-unused to tell rustc that most of a crate will go unused #135656

Conversation

joshtriplett commented Jan 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jan 17, 2025

Uh oh!

rustbot commented Jan 17, 2025

Uh oh!

GuillaumeGomez commented Jan 17, 2025

Uh oh!

workingjubilee commented Jan 17, 2025

Uh oh!

This comment was marked as outdated.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

Uh oh!

workingjubilee commented Jan 17, 2025

Uh oh!

workingjubilee commented Jan 18, 2025

Uh oh!

lqd commented Jan 18, 2025

Uh oh!

Uh oh!

fee1-dead commented Jan 21, 2025

Uh oh!

joshtriplett commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joshtriplett commented Jun 8, 2025

Uh oh!

saethlin commented Jun 17, 2025

Uh oh!

bors commented Jun 17, 2025

Uh oh!

Uh oh!

Uh oh!

Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused #135656

Add `-Z hint-mostly-unused` to tell rustc that most of a crate will go unused #135656

joshtriplett commented Jan 17, 2025 •

edited

Loading

joshtriplett commented Jun 7, 2025 •

edited

Loading