From 88e74050f3f00bf0ec899c1d84b54efeccaae957 Mon Sep 17 00:00:00 2001 From: Herrtian <70463940+Herrtian@users.noreply.github.com> Date: Sun, 31 May 2026 18:03:57 +0200 Subject: [PATCH 1/3] Document adding unstable compiler flags --- src/implementing-new-features.md | 36 ++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/src/implementing-new-features.md b/src/implementing-new-features.md index 4a2318839..0bebce16b 100644 --- a/src/implementing-new-features.md +++ b/src/implementing-new-features.md @@ -228,6 +228,42 @@ The below steps needs to be followed in order to implement a new unstable featur [tracking issue]: #tracking-issues [add-feature-gate]: ./feature-gates.md#adding-a-feature-gate +## Adding unstable compiler flags + +For compiler-internal experiments, diagnostics, debugging aids, and temporary implementation +controls, a `-Z` flag can be more appropriate than a language feature gate. +Feature gates should still be preferred for user-facing language features, +especially when crates need to opt in from source code. + +When adding a new `-Z` flag: + +1. Add the option to `UnstableOptions` in + `compiler/rustc_session/src/options.rs`. + The option name is written as snake_case in the struct and is exposed as + kebab-case on the command line. + Choose the parser, default value, and dependency tracking marker carefully. + Use `[UNTRACKED]` for flags that only affect diagnostics or debugging output, + and use `[TRACKED]` when changing the flag can change compilation results. + +1. Update the option tests in `compiler/rustc_interface/src/tests.rs`. + `options.rs` also has a short checklist near the `UnstableOptions` list for + files that need to stay in sync. + +1. Use the option through `sess.opts.unstable_opts.$flag_name` or + `tcx.sess.opts.unstable_opts.$flag_name`. + If bootstrap or rustdoc needs to pass the flag internally, + thread it through the relevant command construction code as part of the same + change. + +1. Add focused tests for the behavior controlled by the flag. + For example, UI tests can use `//@ compile-flags: -Zyour-flag`, + while rustdoc behavior usually belongs in `tests/rustdoc`. + +1. If the flag is meant for users of nightly rustc or rustdoc, + document it in the unstable book under `src/doc/unstable-book/src/compiler-flags`. + +Before opening the PR, run `./x test tidy` and the narrow test suite that exercises the new flag. + ## Call for testing Once the implementation is complete, From f32afee9c870c68aa4d75b2bba971f173dd385c4 Mon Sep 17 00:00:00 2001 From: Herrtian <70463940+Herrtian@users.noreply.github.com> Date: Mon, 1 Jun 2026 17:03:33 +0200 Subject: [PATCH 2/3] Document compiler flag sign-off guidance --- src/implementing-new-features.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/implementing-new-features.md b/src/implementing-new-features.md index 0bebce16b..46e174267 100644 --- a/src/implementing-new-features.md +++ b/src/implementing-new-features.md @@ -227,6 +227,7 @@ The below steps needs to be followed in order to implement a new unstable featur [here]: ./stabilization-guide.md [tracking issue]: #tracking-issues [add-feature-gate]: ./feature-gates.md#adding-a-feature-gate +[guidance for compiler flags]: https://forge.rust-lang.org/compiler/proposals-and-stabilization.html?highlight=unstable%20flag#compiler-flags ## Adding unstable compiler flags @@ -235,6 +236,10 @@ controls, a `-Z` flag can be more appropriate than a language feature gate. Feature gates should still be preferred for user-facing language features, especially when crates need to opt in from source code. +Before adding a new flag, check the compiler team's [guidance for compiler flags]. +Some flags, especially those intended for direct nightly user workflows or broader +ecosystem use, may need additional sign-off beyond an r+ on the implementation PR. + When adding a new `-Z` flag: 1. Add the option to `UnstableOptions` in From b85bee80a2427337764341726994b66210e9df5f Mon Sep 17 00:00:00 2001 From: Herrtian <70463940+Herrtian@users.noreply.github.com> Date: Tue, 2 Jun 2026 09:44:18 +0200 Subject: [PATCH 3/3] Link UnstableOptions docs --- src/implementing-new-features.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/implementing-new-features.md b/src/implementing-new-features.md index 46e174267..2ff9d6a62 100644 --- a/src/implementing-new-features.md +++ b/src/implementing-new-features.md @@ -228,6 +228,7 @@ The below steps needs to be followed in order to implement a new unstable featur [tracking issue]: #tracking-issues [add-feature-gate]: ./feature-gates.md#adding-a-feature-gate [guidance for compiler flags]: https://forge.rust-lang.org/compiler/proposals-and-stabilization.html?highlight=unstable%20flag#compiler-flags +[`UnstableOptions`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/options/struct.UnstableOptions.html ## Adding unstable compiler flags @@ -242,7 +243,7 @@ ecosystem use, may need additional sign-off beyond an r+ on the implementation P When adding a new `-Z` flag: -1. Add the option to `UnstableOptions` in +1. Add the option to [`UnstableOptions`] in `compiler/rustc_session/src/options.rs`. The option name is written as snake_case in the struct and is exposed as kebab-case on the command line.