Rename `-Zdebuginfo-for-profiling` switch by zamazan4ik · Pull Request #156887 · rust-lang/rust

zamazan4ik · 2026-05-24T18:12:05Z

The PR was raised from this comment from another stabilization PR: #155942

I renamed -Zdebug-info-for-profiling into -Zdebuginfo-for-profiling before stabilization to be consistent with other debuginfo-related Rustc flags like -C split-debuginfo and -C debuginfo.

One important note is that Clang has the flag under -fdebug-info-for-profiling. I decided that consistency with other Rustc flags is more important here than to be consistent with Clang.

r? folkertdev (as was proposed here)

rustbot · 2026-05-24T18:21:14Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

folkertdev · 2026-05-25T07:42:37Z

Neat! you can rebase the other PR once this merges and then we'll nominate it.

In the meantime, can you clean up the stabilization report over there a bit? the text from the template in quote blocks just makes the report longer for no reason, e.g. the tooling section is irrelevant, etc. The process will go faster if you can succinctly describe what we're actually dealing with.

@bors r+ rollup

rust-bors · 2026-05-25T07:42:39Z

📌 Commit 57e7bf4 has been approved by folkertdev

It is now in the queue for this repository.

zamazan4ik · 2026-05-25T08:42:54Z

Neat! you can rebase the other PR once this merges and then we'll nominate it.

Sure, will do it.

In the meantime, can you clean up the stabilization report over there a bit? the text from the template in quote blocks just makes the report longer for no reason, e.g. the tooling section is irrelevant, etc. The process will go faster if you can succinctly describe what we're actually dealing with.

Sure, no problem. To be honest, I wanted to do it from the start, but in the Stabilization report template there are the following lines:

Not all parts of the template will apply to every stabilization. If a question doesn’t apply, explain briefly why. Copy everything after the separator and edit it as Markdown. Replace each TODO with your answer.

I've interpreted it as "Copy the whole template, remove nothing from template since it can potentially hide something useful for reviewers, place some N/A comments for non-applicable sections". But if I am wrong in my understanding and reviewers are okay with removing unnecessary parts - I'll happily do the refactoring of the report with removing useless stuff and explaining a bit more some missing details.

Thanks a lot for the review!

…ofiling-switch, r=folkertdev Rename `-Zdebuginfo-for-profiling` switch The PR was raised from this [comment](rust-lang#155942 (comment)) from another stabilization PR: rust-lang#155942 I renamed `-Zdebug-info-for-profiling` into `-Zdebuginfo-for-profiling` before stabilization to be consistent with other `debuginfo`-related Rustc flags like `-C split-debuginfo` and `-C debuginfo`. One important note is that Clang has the [flag](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fdebug-info-for-profiling) under `-fdebug-info-for-profiling`. I decided that consistency with other Rustc flags is more important here than to be consistent with Clang. r? folkertdev (as was proposed [here](rust-lang#155942 (comment)))

…uwer Rollup of 3 pull requests Successful merges: - #156900 (stdarch subtree update) - #156887 (Rename `-Zdebuginfo-for-profiling` switch) - #156901 (compiletest: Simplify `//@ needs-asm-mnemonic: ret` to just `//@ needs-asm-ret`)

JonathanBrouwer · 2026-05-25T10:35:05Z

@bors r-
#156907 (comment)

rust-bors · 2026-05-25T10:35:18Z

This pull request was unapproved.

This PR was contained in a rollup (#156907), which was unapproved.

View changes since this unapproval

folkertdev · 2026-05-25T10:53:11Z

Hmm, is it just a target issue (x86_64 behaves differently from aarch64)? We might need to pin the target using --target = ... and use minicore (see other tests) so that we can run it from anywhere

zamazan4ik · 2026-05-25T10:54:38Z

Aha, seems like discriminator-based test is architecture-dependent and the amount of emitted discriminators depends on the target platform.

I can perform tests by myself for x86-64 and ARM architectures and limit the test only for these two archs. Is it okay to resolve this error in this way or we need a more generic solution to test on all architectures somehow?

zamazan4ik · 2026-05-25T10:55:58Z

Hmm, is it just a target issue (x86_64 behaves differently from aarch64)? We might need to pin the target using --target = ... and use minicore (see other tests) so that we can run it from anywhere

Sure, will do it. Do I need to pin to just one architecture or we can enable the test on both - aarch64 and x86-64 as for the most commonly used nowadays.

folkertdev · 2026-05-25T10:58:07Z

you can specify a target per revision, so you'd get

//@ revisions: DEFAULT-X86 DEFAULT-AARCH64 DEBUGINFO_FOR_PROFILING-X86 DEBUGINFO_FOR_PROFILING-AARCH64

etc. Just those targets is fine for now I think, really we're just testing that the flag has an effect.

rustbot · 2026-05-27T00:27:57Z

This PR modifies tests/auxiliary/minicore.rs.

cc @jieyouxu

rust-bors · 2026-05-29T19:17:10Z

💔 Test for 87ead7c failed: CI. Failed job:

try - x86_64-gnu-llvm-21-3 (web logs, enhanced plaintext logs)

folkertdev · 2026-05-29T19:30:19Z

Hmm CI is experiencing some network interruptions (e.g. the tree here is closed https://bors.rust-lang.org/queue/rust) so I'll re-try this once that issue has been resolved.

rust-log-analyzer · 2026-05-29T19:45:02Z

A job failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

================================================================================

/mnt is not a mountpoint
Unable to correct missing packages.
E: Failed to fetch mirror+file:/etc/apt/apt-mirrors.txt/pool/main/o/openjdk-21/openjdk-21-jre-headless_21.0.10%2b7-1%7e24.04_amd64.deb  404  Not Found [IP: 52.252.163.49 80]
E: Unable to correct problems, you have held broken packages.
E: Aborting install.
##[error]Process completed with exit code 100.
##[group]Run echo "disk usage:"
echo "disk usage:"
df -h

folkertdev · 2026-05-30T10:28:24Z

@bors try jobs=x86_64-gnu-llvm-21-3

…tch, r=<try> Rename `-Zdebuginfo-for-profiling` switch try-job: x86_64-gnu-llvm-21-3

rust-bors · 2026-05-30T12:07:09Z

☀️ Try build successful (CI)
Build commit: cad5567 (cad5567abc364e91fc423aa6381b7db74e856387, parent: 6eda7419e71fdbc1185ed5be7e6bff1a474ab5cd)

folkertdev · 2026-05-30T12:15:38Z

Looks good!

@bors r+

rust-bors · 2026-05-30T12:15:41Z

📌 Commit fe17ed5 has been approved by folkertdev

It is now in the queue for this repository.

…ofiling-switch, r=folkertdev Rename `-Zdebuginfo-for-profiling` switch The PR was raised from this [comment](rust-lang#155942 (comment)) from another stabilization PR: rust-lang#155942 I renamed `-Zdebug-info-for-profiling` into `-Zdebuginfo-for-profiling` before stabilization to be consistent with other `debuginfo`-related Rustc flags like `-C split-debuginfo` and `-C debuginfo`. One important note is that Clang has the [flag](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fdebug-info-for-profiling) under `-fdebug-info-for-profiling`. I decided that consistency with other Rustc flags is more important here than to be consistent with Clang. r? folkertdev (as was proposed [here](rust-lang#155942 (comment)))

…uwer Rollup of 8 pull requests Successful merges: - #156863 (Make hint::cold_path #[cold] so that it works even if the MIR inliner can't inline it) - #156875 (Correct and document semantics of `yield` terminator) - #157115 ([rustdoc] Fix foreign items macro expansion) - #157150 (Revert "drop derive helpers during ast lowering" ) - #156887 (Rename `-Zdebuginfo-for-profiling` switch) - #157039 (rustdoc: correctly propagate cfgs for glob reexports) - #157125 (Rewrite the `#[repr]` attribute parser) - #157154 (Revert workaround used to select the gcc codegen in the coretests CI)

Rollup merge of #156887 - zamazan4ik:rename-debuginfo-for-profiling-switch, r=folkertdev Rename `-Zdebuginfo-for-profiling` switch The PR was raised from this [comment](#155942 (comment)) from another stabilization PR: #155942 I renamed `-Zdebug-info-for-profiling` into `-Zdebuginfo-for-profiling` before stabilization to be consistent with other `debuginfo`-related Rustc flags like `-C split-debuginfo` and `-C debuginfo`. One important note is that Clang has the [flag](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fdebug-info-for-profiling) under `-fdebug-info-for-profiling`. I decided that consistency with other Rustc flags is more important here than to be consistent with Clang. r? folkertdev (as was proposed [here](#155942 (comment)))

ojeda · 2026-06-02T10:54:41Z

I renamed -Zdebug-info-for-profiling into -Zdebuginfo-for-profiling before stabilization to be consistent with other debuginfo-related Rustc flags like -C split-debuginfo and -C debuginfo.

I just noticed this in nightly -- is it really worth to do such a change if stabilization will give a chance to change the name anyway?

i.e. if a project out there is using the flag (it has been under that name for almost 5 years now from a quick look), then they may need one more conditional just for an unstable name.

Luckily in the case of Linux, I just added it in my branch, so it is not as bad, i.e. I can add a commit on top to change the name (and hopefully without an extra conditional if it gets stabilized in the same cycle), but others may not be so lucky :)

Thanks!

folkertdev · 2026-06-02T11:04:36Z

I just noticed this in nightly -- is it really worth to do such a change if stabilization will give a chance to change the name anyway?

I understand the sentiment but if you use nightly this is what you sign up for. We really want features to be ready before stabilization, so that the changes in the stabilization PR are just a formality.

ojeda · 2026-06-02T11:42:57Z

I am aware, but there is a difference between a behavioral change that needs testing by users etc. vs. a simple rename of the flag which will be invalidated by the stabilization rename anyway. In addition, the rename was done in the stabilization step anyway in other cases, but perhaps the policy is stricter now?

(By the way, to be clear, at least in the case of Linux, we don't use nightly because we like using it, but because we need it... so we are essentially forced to "sign up for it", i.e. I would be more than happy to not need it! :)

ojeda · 2026-06-02T11:55:23Z

By the way, on the naming itself:

I decided that consistency with other Rustc flags is more important here than to be consistent with Clang.

We have had this discussion in the past (Cc @tomassedovic), and I don't know what is the policy nowadays, but matching GCC/Clang for flags like these can help reduce confusion when dealing with multi-language projects and when searching for context online etc.

For instance, in build systems of mixed language projects, one may place all GCC/Clang/rustc flags close to each other, so seeing the same name makes it very clear what is going on.

(Of course, having the same name with different behavior is way worse!)

Here it is still essentially the same name, so we still mostly keep the advantage, which is good.

zamazan4ik · 2026-06-02T13:00:58Z

@ojeda I am sorry that this change has broken (a little bit but still) Rust-for-Linux build - I don't like to break things either :)

Initially, I also wanted to perform renaming + stabilizing in the same PR but according to Rustc development processes it was recommended to go with other direction with an idea that unstable flags are unstable anyway. I've carefully evaluated all available to me sources, and Rust-for-Linux is the only known -Zdebuginfo-for-profiling public user at the moment. Knowing that Sample PGO is not widely used in the Rust industry nowadays - I think you probably the only user for this flag anyway :) This "breakage" looks especially in question since in #155942 (comment) we decided to go with another direction and stabilize for now only -Cprofile-sample-use without -Zdebuginfo-for-profiling. So the renaming PR was merged it won't be stabilized soon - at least in the way as we initially planned. Our current idea is to evaluate enabling this flag by default for all/some debug level, so will be no need at all to use this flag in the future :) But it requires more research to be done in this area (I already started some initial experiments #t-compiler > Stabilizing Sample PGO (SPGO): `-Zprofile-sample-use` @ 💬)

By the way, on the naming itself

I fully agree with your arguments - I have completely the same reasoning. I just wanted to be consistent with other debuginfo flags in Rustc which are more important for Rust (IMHO) then being consistent with Clang - since it's an external project to Rustc anyway. Since my renaming is just removing one hyphen and not a complete rename - I think is a good tradeoff, and I didn't create too much issues for Rust-for-Linux with that :)

I hope you understand my motivation behind this process.

By the way, to be clear, at least in the case of Linux, we don't use nightly because we like using it, but because we need it... so we are essentially forced to "sign up for it", i.e. I would be more than happy to not need it!

Yes! It's one of my motivation - to simplify Rust users life and not force them to use Rust Nightly if they just want to use Sample PGO with Rust. With stabilizing Sample PGO into -Cprofile-sample-use and stabilzing in the future -Zdebuginfo-for-profiling (as a dedicated flag or even enable it by default for debug) I hope to help to any Rust project, including Rust-for-Linux, to reduce a little bit dependency on Nightly toolchains :)

…1.98 Starting with Rust 1.98.0 (expected 2026-08-20), the `-Zdebug-info-for-profiling` flag has been renamed to `-Zdebuginfo-for-profiling` (i.e. one less dash, to match `debuginfo`s in other flags) [1]. Without this change, one gets in the latest nightlies: error: unknown unstable option: `debug-info-for-profiling` Thus pass the right name. Link: rust-lang/rust#156887 [1] Reviewed-by: Alice Ryhl <aliceryhl@google.com> Acked-by: Nathan Chancellor <nathan@kernel.org> Link: https://patch.msgid.link/20260602151638.14358-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda <ojeda@kernel.org>

…e-use-and-debug-info-for-profiling, r=folkertdev Stabilize `-Zprofile-sample-use` Tracking issue: rust-lang#155668 # Stabilization report ## Summary Sample Profile-Guided Optimization (Sample PGO or SPGO) is an alternative way to perform feedback-directed optimization (FDO). Rustc already supports Instrumented PGO (with the `-Cprofile-generate` / `-Cprofile-use` flags). Downside of the instrumented approach include that it requires a separate compilation and that the instrumentation has significant runtime overhead. SPGO instead uses the output of external profilers like `perf` during the compilation process to perform more aggressive compiler optimizations. This approach is described in [this paper](https://dl.acm.org/doi/abs/10.1145/2854038.2854044). I propose stabilizing `-Zprofile-sample-use` as `-Cprofile-sample-use` More information can be found in the updated by the PR "Profile-guided Optimization" guide or Clang PGO [guide](https://clang.llvm.org/docs/UsersManual.html#using-sampling-profilers). These flags are documented as: > - `profile-sample-use`: > > This flag specifies the profiling data file to be used for sample-based > profile-guided optimization (SPGO). The flag takes a mandatory argument which > is the path to a valid `.prof` file. See the chapter on > [profile-guided optimization] for more information. > The `-Zdebuginfo-for-profiling` flag can be used to > improve the quality of the profiling data. For more details about the flag and their usage - check the Profile-guided Optimization guide [change](https://github.com/rust-lang/rust/pull/155942/changes#diff-da79c0293559274602ced76b0d50ab4d56d4eec4dcbb8b59d515b9ae94f26c42). ### What is stabilized One compiler flag: `-Zprofile-sample-use`. ### What isn't stabilized I think this is the right section to compare Sample-based PGO (SPGO) implementation in Rustc vs its "big brother" - Sample-based PGO in Clang. Besides `-Zprofile-sample-use` in Rustc / `-fprofile_sample_use` in Clang and `-Zdebug-info-for-profiling` in Rustc (which we decided to **not** stabilize at the moment) / `-fdebug-info-for-profiling, -fno-debug-info-for-profiling` in Clang, Clang additionally supports the following SPGO-related switches: * `-fpseudo-probe-for-profiling, -fno-pseudo-probe-for-profiling` [flags](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fpseudo-probe-for-profiling). According to the Clang's PGO [guide](https://clang.llvm.org/docs/UsersManual.html#using-sampling-profilers), this switch is optional for SPGO. This switch has originals from an extension of SPGO that is called "Context-sensitive Sample PGO with Pseudo-Instrumentation" or simply "CSSPGO". Here is original [RFC](https://groups.google.com/g/llvm-dev/c/1p1rdYbL93s?pli=1) for the thing, also I can link some LLVM commits/discussions about the topic. This flag is not required for regular SPGO - it's just an improvement idea over regular SPGO, and could be added later to the Rustc in a different process (initially to unstable, than later promoted to stable). But that's another story and we can consider it later. * `-f[no-]unique-internal-linkage-names` [switch](https://clang.llvm.org/docs/UsersManual.html#cmdoption-f-no-unique-internal-linkage-names) is also mentioned in the Clang PGO guide. I don't think that the switch is applicable to Rustc. Correct me if I am wrong pls. * `-fsample-profile-use-profi, -fno-sample-profile-use-profi` [switch](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fsample-profile-use-profi). This switch is also marked as optional in the Clang PGO guide. This switch is an attempt to improve some inaccuracies in SPGO profile with some heuristics. SPGO in Rustc can be easily stabilized without this flag, since it's just a non-critical for regular SPGO usage heuristic. If we decide to add support for this switch to Rustc too - we can do in a separate activity without blocking with stabilization process. Check rust-lang#156898 for more details. * `-fprofile-sample-accurate, -fauto-profile-accurate, -fno-profile-sample-accurate` [switch](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fprofile-sample-accurate). This switch is not mentioned even by the Clang PGO guide :) This flag resolves [this](llvm/llvm-project#63024) issue/feature request from LLVM upstream in SPGO use case. According to the description from Clang: "Specifies that the sample profile is accurate. If the sample profile is accurate, callsites without profile samples are marked as cold. Otherwise, treat callsites without profile samples as if we have no profile". Since we don't specify the flag in Rustc, branches without profile samples are now considered as branches without a profile and optimized as regular release code. Having support for this in Rustc would be definitely a nice addition to be on par with Clang, since there are good use cases for that. But I do not think that this could be a blocker for stabilization of SPGO in Rustc without this functionality - we can add it later. As a proof that SPGO in Rustc works completely okay without it you can use Rust-for-Linux bench [results](https://lore.kernel.org/rust-for-linux/20260331-autofdo-v2-1-eb5c5964820d@google.com/) with SPGO via AutoFDO. I am not aware about any other SPGO-related flags in Clang. We definitely have a gap in SPGO-related flags in Rustc compared to Clang, but none of these gaps is a blocker for stabilization `-Zprofile-sample-use` right now. However, it would be nice to resolve these gaps later: add them in unstable form, test, and later stabilize them to be on par with Clang from SPGO optimization perspective. Right now all the flags above are missing in Rustc even in the unstable form. Stabilization of `-Zprofile-sample-use` **does not** prevent adding all missing SPGO related features later. ## Design ### RFC history No RFC was created for these options. All original discussions for Unstable were done in the original Unstable PR: rust-lang#87918 ### Post-RFC changes > What other user-visible changes have occurred since the RFC was accepted? Describe both changes that the lang team accepted (and link to those decisions) as well as changes that are being presented to the team for the first time in this stabilization report. Compared to the unstable (RFC-like) state, I've made the following changes: * I extended the Rustc's PGO [guide](https://doc.rust-lang.org/beta/rustc/profile-guided-optimization.html) with Sample-based PGO information and instructions, how to use it. This change will resolve rust-lang#117023 . My changes are highly-inspired / cautiously copy-pasted (only needed parts) from the Clang guide. From licensing perspective it should be fine. If it's a problem in any way - I can do some rewording (but I would like to avoid such things). I decided to do some documentation copy due to Sample-based PGO incompatibilities between Clang and Rustc (Clang supports more options at very least). I believe that current version is more user-friendly and easier to use, compared to just referring to the Clang PGO guide. * I changed help message and corresponding documentation for `-Zdebug_info_for_profiling` switch to be in the same way as Clang already [has](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fdebug-info-for-profiling). It's kinda difficult to describe clearly, what the option does without exposing too much LLVM details - that's why I linked the documentation to the corresponding LLVM pass in the Reference for this option. ### Key points No arguments were raised during stabilization discussion of the feature in any place yet, including Zulip discussion: [#t-compiler > Stabilizing Sample PGO (SPGO): &rust-lang#96;-Zprofile-sample-use&rust-lang#96;](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Stabilizing.20Sample.20PGO.20.28SPGO.29.3A.20.60-Zprofile-sample-use.60/with/590356923) ### Nightly extensions I am not aware of any other unstable SPGO-related switches. ### Doors closed > What doors does this stabilization close for later changes to the language? E.g., does this stabilization make any other RFCs, lang experiments, or known in-flight proposals more difficult or impossible to do later? * Removing Sample-based PGO support from Rustc will be harder. But the technology itself is used on large scales in other ecosystems like Clang (heavily-used in big tech companies internally), and Rust-for-Linux already started to use it even with Rustc. I don't think will be a need to remove it in near future. * Renaming flags will be harder. But current naming is done to be consistent with Clang. Clang proved robustness of this naming, so it shouldn't be a concern either. No other proposals/experiments/etc. are affected. ## Feedback ### Call for testing Call for testing **wasn't** done - it was slightly discussed [#t-compiler > Stabilizing Sample PGO (SPGO): &rust-lang#96;-Zprofile-sample-use&rust-lang#96; @ 💬](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Stabilizing.20Sample.20PGO.20.28SPGO.29.3A.20.60-Zprofile-sample-use.60/near/590581795). However, no negative feedback was received for stabilization of this feature. Right now this feature is already tested personally by me (local experiments with assembly changes verification before/after applying SPGO on an Intel-based (with LBR) Linux machine in some sample apps with `llvm-profgen` tool and by Rust-for-Linux project in this [patch](https://lore.kernel.org/rust-for-linux/20260331-autofdo-v2-1-eb5c5964820d@google.com/). Additionally, this feature was in unstable state for 5 years (since 2021) with no concerns (due to no bugs or no users - who knows. At least it was implemented for a reason 5 years ). I think that's enough verification for such kind of feature. ### Nightly use The only publicly-known user of this feature is Rust-for-Linux project (see [this](https://lore.kernel.org/rust-for-linux/20260331-autofdo-v2-1-eb5c5964820d@google.com/) commit). Besides that, no other users were found on GitHub via GitHub search for `"-Zprofile-sample-use"` query: almost all found entries are various copies of the Unstable book with the documentation for the option, and other places are related to the Linux kernel. Two found issues are related to the tracking [issue](rust-lang#155668) of these two flags, and corresponding tracking [issue](Rust-for-Linux/linux#2) in Rust-for-Linux. I am not personally aware of any closed-source users of this feature. Probably Google (Sampled-based PGO biggest user at least for C++) and other big techs use it somewhere internally too but it's just a guess. ## Implementation ### Major parts - rust-lang#87918 - unstable original implementation - rust-lang#155942 - this PR, stabilization with some minor changes No significant developments on the Rustc side - just propagating in a proper way SPGO profile to the LLVM part of the compiler. ### Coverage * For `-Cprofile-sample-use` we have only UI tests. We haven't implemented e2e tests since it's will be hard to add them to the current test suite (see the [comment](rust-lang#155942 (comment))) ### Breaking changes No breaking changes are expected from this stabilization. ## History - rust-lang#87918 - initial implementation - rust-lang#156887 - renaming `-Zdebug_info_for_profiling` into `-Zdebuginfo_for_profiling` + adding more tests for the feature (left for the history) - rust-lang#155668 - tracking issue ## Acknowledgments * [Michael Benfield](https://github.com/mikebenfield) - author of the original PR for Unstable * [Jakub Beránek](https://github.com/Kobzol/) - the "PGO guy" in Rustc and `cargo-pgo` author * [Miguel Ojeda](https://github.com/ojeda) - Rust-for-Linux maintainer (they already use Sample-based PGO in Rust-for-Linux) * [Alexander Zaitsev](https://github.com/zamazan4ik) - me I am not aware of any person, who is against stabilization of these two flags. ## Open items I am not aware of any open issue, that is a blocker for stabilization of this feature. List of SPGO-related things, which are **not** stabilization blockers in my opinion: * rust-lang#155525 - this could improve SPGO UX with Rustc, but it's not a strict requirement - an externally-installed `llvm-profgen` can be used instead (I've tested it locally by using `llvm-profgen-21` for SPGO with Rustc 1.95, which is LLVM 22-based

Rollup merge of #155942 - zamazan4ik:stabilize-profile-sample-use-and-debug-info-for-profiling, r=folkertdev Stabilize `-Zprofile-sample-use` Tracking issue: #155668 # Stabilization report ## Summary Sample Profile-Guided Optimization (Sample PGO or SPGO) is an alternative way to perform feedback-directed optimization (FDO). Rustc already supports Instrumented PGO (with the `-Cprofile-generate` / `-Cprofile-use` flags). Downside of the instrumented approach include that it requires a separate compilation and that the instrumentation has significant runtime overhead. SPGO instead uses the output of external profilers like `perf` during the compilation process to perform more aggressive compiler optimizations. This approach is described in [this paper](https://dl.acm.org/doi/abs/10.1145/2854038.2854044). I propose stabilizing `-Zprofile-sample-use` as `-Cprofile-sample-use` More information can be found in the updated by the PR "Profile-guided Optimization" guide or Clang PGO [guide](https://clang.llvm.org/docs/UsersManual.html#using-sampling-profilers). These flags are documented as: > - `profile-sample-use`: > > This flag specifies the profiling data file to be used for sample-based > profile-guided optimization (SPGO). The flag takes a mandatory argument which > is the path to a valid `.prof` file. See the chapter on > [profile-guided optimization] for more information. > The `-Zdebuginfo-for-profiling` flag can be used to > improve the quality of the profiling data. For more details about the flag and their usage - check the Profile-guided Optimization guide [change](https://github.com/rust-lang/rust/pull/155942/changes#diff-da79c0293559274602ced76b0d50ab4d56d4eec4dcbb8b59d515b9ae94f26c42). ### What is stabilized One compiler flag: `-Zprofile-sample-use`. ### What isn't stabilized I think this is the right section to compare Sample-based PGO (SPGO) implementation in Rustc vs its "big brother" - Sample-based PGO in Clang. Besides `-Zprofile-sample-use` in Rustc / `-fprofile_sample_use` in Clang and `-Zdebug-info-for-profiling` in Rustc (which we decided to **not** stabilize at the moment) / `-fdebug-info-for-profiling, -fno-debug-info-for-profiling` in Clang, Clang additionally supports the following SPGO-related switches: * `-fpseudo-probe-for-profiling, -fno-pseudo-probe-for-profiling` [flags](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fpseudo-probe-for-profiling). According to the Clang's PGO [guide](https://clang.llvm.org/docs/UsersManual.html#using-sampling-profilers), this switch is optional for SPGO. This switch has originals from an extension of SPGO that is called "Context-sensitive Sample PGO with Pseudo-Instrumentation" or simply "CSSPGO". Here is original [RFC](https://groups.google.com/g/llvm-dev/c/1p1rdYbL93s?pli=1) for the thing, also I can link some LLVM commits/discussions about the topic. This flag is not required for regular SPGO - it's just an improvement idea over regular SPGO, and could be added later to the Rustc in a different process (initially to unstable, than later promoted to stable). But that's another story and we can consider it later. * `-f[no-]unique-internal-linkage-names` [switch](https://clang.llvm.org/docs/UsersManual.html#cmdoption-f-no-unique-internal-linkage-names) is also mentioned in the Clang PGO guide. I don't think that the switch is applicable to Rustc. Correct me if I am wrong pls. * `-fsample-profile-use-profi, -fno-sample-profile-use-profi` [switch](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fsample-profile-use-profi). This switch is also marked as optional in the Clang PGO guide. This switch is an attempt to improve some inaccuracies in SPGO profile with some heuristics. SPGO in Rustc can be easily stabilized without this flag, since it's just a non-critical for regular SPGO usage heuristic. If we decide to add support for this switch to Rustc too - we can do in a separate activity without blocking with stabilization process. Check #156898 for more details. * `-fprofile-sample-accurate, -fauto-profile-accurate, -fno-profile-sample-accurate` [switch](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fprofile-sample-accurate). This switch is not mentioned even by the Clang PGO guide :) This flag resolves [this](llvm/llvm-project#63024) issue/feature request from LLVM upstream in SPGO use case. According to the description from Clang: "Specifies that the sample profile is accurate. If the sample profile is accurate, callsites without profile samples are marked as cold. Otherwise, treat callsites without profile samples as if we have no profile". Since we don't specify the flag in Rustc, branches without profile samples are now considered as branches without a profile and optimized as regular release code. Having support for this in Rustc would be definitely a nice addition to be on par with Clang, since there are good use cases for that. But I do not think that this could be a blocker for stabilization of SPGO in Rustc without this functionality - we can add it later. As a proof that SPGO in Rustc works completely okay without it you can use Rust-for-Linux bench [results](https://lore.kernel.org/rust-for-linux/20260331-autofdo-v2-1-eb5c5964820d@google.com/) with SPGO via AutoFDO. I am not aware about any other SPGO-related flags in Clang. We definitely have a gap in SPGO-related flags in Rustc compared to Clang, but none of these gaps is a blocker for stabilization `-Zprofile-sample-use` right now. However, it would be nice to resolve these gaps later: add them in unstable form, test, and later stabilize them to be on par with Clang from SPGO optimization perspective. Right now all the flags above are missing in Rustc even in the unstable form. Stabilization of `-Zprofile-sample-use` **does not** prevent adding all missing SPGO related features later. ## Design ### RFC history No RFC was created for these options. All original discussions for Unstable were done in the original Unstable PR: #87918 ### Post-RFC changes > What other user-visible changes have occurred since the RFC was accepted? Describe both changes that the lang team accepted (and link to those decisions) as well as changes that are being presented to the team for the first time in this stabilization report. Compared to the unstable (RFC-like) state, I've made the following changes: * I extended the Rustc's PGO [guide](https://doc.rust-lang.org/beta/rustc/profile-guided-optimization.html) with Sample-based PGO information and instructions, how to use it. This change will resolve #117023 . My changes are highly-inspired / cautiously copy-pasted (only needed parts) from the Clang guide. From licensing perspective it should be fine. If it's a problem in any way - I can do some rewording (but I would like to avoid such things). I decided to do some documentation copy due to Sample-based PGO incompatibilities between Clang and Rustc (Clang supports more options at very least). I believe that current version is more user-friendly and easier to use, compared to just referring to the Clang PGO guide. * I changed help message and corresponding documentation for `-Zdebug_info_for_profiling` switch to be in the same way as Clang already [has](https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-fdebug-info-for-profiling). It's kinda difficult to describe clearly, what the option does without exposing too much LLVM details - that's why I linked the documentation to the corresponding LLVM pass in the Reference for this option. ### Key points No arguments were raised during stabilization discussion of the feature in any place yet, including Zulip discussion: [#t-compiler > Stabilizing Sample PGO (SPGO): `-Zprofile-sample-use`](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Stabilizing.20Sample.20PGO.20.28SPGO.29.3A.20.60-Zprofile-sample-use.60/with/590356923) ### Nightly extensions I am not aware of any other unstable SPGO-related switches. ### Doors closed > What doors does this stabilization close for later changes to the language? E.g., does this stabilization make any other RFCs, lang experiments, or known in-flight proposals more difficult or impossible to do later? * Removing Sample-based PGO support from Rustc will be harder. But the technology itself is used on large scales in other ecosystems like Clang (heavily-used in big tech companies internally), and Rust-for-Linux already started to use it even with Rustc. I don't think will be a need to remove it in near future. * Renaming flags will be harder. But current naming is done to be consistent with Clang. Clang proved robustness of this naming, so it shouldn't be a concern either. No other proposals/experiments/etc. are affected. ## Feedback ### Call for testing Call for testing **wasn't** done - it was slightly discussed [#t-compiler > Stabilizing Sample PGO (SPGO): `-Zprofile-sample-use` @ 💬](https://rust-lang.zulipchat.com/#narrow/channel/131828-t-compiler/topic/Stabilizing.20Sample.20PGO.20.28SPGO.29.3A.20.60-Zprofile-sample-use.60/near/590581795). However, no negative feedback was received for stabilization of this feature. Right now this feature is already tested personally by me (local experiments with assembly changes verification before/after applying SPGO on an Intel-based (with LBR) Linux machine in some sample apps with `llvm-profgen` tool and by Rust-for-Linux project in this [patch](https://lore.kernel.org/rust-for-linux/20260331-autofdo-v2-1-eb5c5964820d@google.com/). Additionally, this feature was in unstable state for 5 years (since 2021) with no concerns (due to no bugs or no users - who knows. At least it was implemented for a reason 5 years ). I think that's enough verification for such kind of feature. ### Nightly use The only publicly-known user of this feature is Rust-for-Linux project (see [this](https://lore.kernel.org/rust-for-linux/20260331-autofdo-v2-1-eb5c5964820d@google.com/) commit). Besides that, no other users were found on GitHub via GitHub search for `"-Zprofile-sample-use"` query: almost all found entries are various copies of the Unstable book with the documentation for the option, and other places are related to the Linux kernel. Two found issues are related to the tracking [issue](#155668) of these two flags, and corresponding tracking [issue](Rust-for-Linux/linux#2) in Rust-for-Linux. I am not personally aware of any closed-source users of this feature. Probably Google (Sampled-based PGO biggest user at least for C++) and other big techs use it somewhere internally too but it's just a guess. ## Implementation ### Major parts - #87918 - unstable original implementation - #155942 - this PR, stabilization with some minor changes No significant developments on the Rustc side - just propagating in a proper way SPGO profile to the LLVM part of the compiler. ### Coverage * For `-Cprofile-sample-use` we have only UI tests. We haven't implemented e2e tests since it's will be hard to add them to the current test suite (see the [comment](#155942 (comment))) ### Breaking changes No breaking changes are expected from this stabilization. ## History - #87918 - initial implementation - #156887 - renaming `-Zdebug_info_for_profiling` into `-Zdebuginfo_for_profiling` + adding more tests for the feature (left for the history) - #155668 - tracking issue ## Acknowledgments * [Michael Benfield](https://github.com/mikebenfield) - author of the original PR for Unstable * [Jakub Beránek](https://github.com/Kobzol/) - the "PGO guy" in Rustc and `cargo-pgo` author * [Miguel Ojeda](https://github.com/ojeda) - Rust-for-Linux maintainer (they already use Sample-based PGO in Rust-for-Linux) * [Alexander Zaitsev](https://github.com/zamazan4ik) - me I am not aware of any person, who is against stabilization of these two flags. ## Open items I am not aware of any open issue, that is a blocker for stabilization of this feature. List of SPGO-related things, which are **not** stabilization blockers in my opinion: * #155525 - this could improve SPGO UX with Rustc, but it's not a strict requirement - an externally-installed `llvm-profgen` can be used instead (I've tested it locally by using `llvm-profgen-21` for SPGO with Rustc 1.95, which is LLVM 22-based

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels May 24, 2026

rustbot assigned folkertdev May 24, 2026

This comment has been minimized.

Sign in to view

feat: rename debug-info-for-profiling switch

bcf9001

zamazan4ik force-pushed the rename-debuginfo-for-profiling-switch branch from 1c4094e to 58d2a68 Compare May 24, 2026 18:21

This comment has been minimized.

Sign in to view

zamazan4ik force-pushed the rename-debuginfo-for-profiling-switch branch from 58d2a68 to 57e7bf4 Compare May 24, 2026 19:18

rust-bors Bot 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 May 25, 2026

JonathanBrouwer mentioned this pull request May 25, 2026

Rollup of 3 pull requests #156907

Closed

rust-bors Bot 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-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels May 25, 2026

zamazan4ik force-pushed the rename-debuginfo-for-profiling-switch branch 3 times, most recently from 25ab29c to 9da2655 Compare May 26, 2026 23:24

This comment has been minimized.

Sign in to view

rust-bors Bot pushed a commit that referenced this pull request May 30, 2026

Auto merge of #156887 - zamazan4ik:rename-debuginfo-for-profiling-swi…

cad5567

…tch, r=<try> Rename `-Zdebuginfo-for-profiling` switch try-job: x86_64-gnu-llvm-21-3

rust-bors Bot 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-author Status: This is awaiting some action (such as code changes or more information) from the author. labels May 30, 2026

This was referenced May 30, 2026

Rollup of 4 pull requests #157158

Closed

Rollup of 8 pull requests #157161

Merged

rust-bors Bot merged commit a5f7457 into rust-lang:main May 30, 2026
13 checks passed

rustbot added this to the 1.98.0 milestone May 30, 2026

ojeda mentioned this pull request Jun 2, 2026

Rust unstable features needed for the kernel Rust-for-Linux/linux#2

Open

55 tasks

tomassedovic mentioned this pull request Jun 16, 2026

Stabilize Rust for Linux compiler features rust-lang/goals#407

Open

Uh oh!

Conversation

zamazan4ik commented May 24, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

rustbot commented May 24, 2026

Uh oh!

This comment has been minimized.

folkertdev commented May 25, 2026

Uh oh!

rust-bors Bot commented May 25, 2026

Uh oh!

zamazan4ik commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JonathanBrouwer commented May 25, 2026

Uh oh!

rust-bors Bot commented May 25, 2026

Uh oh!

folkertdev commented May 25, 2026

Uh oh!

zamazan4ik commented May 25, 2026

Uh oh!

zamazan4ik commented May 25, 2026

Uh oh!

folkertdev commented May 25, 2026

Uh oh!

This comment has been minimized.

rustbot commented May 27, 2026

Uh oh!

rust-bors Bot commented May 29, 2026

Uh oh!

folkertdev commented May 29, 2026

Uh oh!

rust-log-analyzer commented May 29, 2026

Uh oh!

folkertdev commented May 30, 2026

Uh oh!

This comment has been minimized.

rust-bors Bot commented May 30, 2026

Uh oh!

folkertdev commented May 30, 2026

Uh oh!

rust-bors Bot commented May 30, 2026

Uh oh!

Uh oh!

ojeda commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

folkertdev commented Jun 2, 2026

Uh oh!

ojeda commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ojeda commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zamazan4ik commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

zamazan4ik commented May 24, 2026 •

edited by rustbot

Loading

zamazan4ik commented May 25, 2026 •

edited

Loading

ojeda commented Jun 2, 2026 •

edited

Loading

ojeda commented Jun 2, 2026 •

edited

Loading

ojeda commented Jun 2, 2026 •

edited

Loading