Improve unstable option diagnostics

compiler/rustc_driver_impl/src/lib.rs

@@ -925,13 +925,9 @@ pub fn version_at_macro_invocation(
     }
 }
 
-fn usage(verbose: bool, include_unstable_options: bool, nightly_build: bool) {
+fn usage(verbose: bool, nightly_build: bool) {
     let mut options = getopts::Options::new();
-    for option in config::rustc_optgroups()
-        .iter()
-        .filter(|x| verbose || !x.is_verbose_help_only)
-        .filter(|x| include_unstable_options || x.is_stable())
-    {
+    for option in config::rustc_optgroups().iter().filter(|x| verbose || !x.is_verbose_help_only) {
         option.apply(&mut options);
     }
     let message = "Usage: rustc [OPTIONS] INPUT";
@@ -1304,10 +1300,8 @@ pub fn handle_help(matches: &getopts::Matches, args: &[String]) -> bool {
     let zhelp_pos = opt_help_pos("Z");
     let chelp_pos = opt_help_pos("C");
     let print_help = || {
-        // Only show unstable options in --help if we accept unstable options.
-        let unstable_enabled = nightly_options::unstable_options_enabled(&matches);
         let nightly_build = nightly_options::match_is_nightly_build(&matches);
-        usage(matches.opt_present("verbose"), unstable_enabled, nightly_build);
+        usage(matches.opt_present("verbose"), nightly_build);
     };
 
     let mut helps = [

compiler/rustc_session/src/config.rs

@@ -1,6 +1,7 @@
 //! Contains infrastructure for configuring the compiler, including parsing
 //! command-line options.
 
+use std::borrow::Cow;
 use std::collections::btree_map::{
     Iter as BTreeMapIter, Keys as BTreeMapKeysIter, Values as BTreeMapValuesIter,
 };
@@ -2009,11 +2010,18 @@ impl RustcOptGroup {
 
     pub fn apply(&self, options: &mut getopts::Options) {
         let &Self { short_name, long_name, desc, value_hint, .. } = self;
+
+        let desc = if self.is_stable() {
+            Cow::Borrowed(desc)
+        } else {
+            Cow::Owned(format!("{desc} (unstable)"))
+        };
+
         match self.kind {
-            OptionKind::Opt => options.optopt(short_name, long_name, desc, value_hint),
-            OptionKind::Multi => options.optmulti(short_name, long_name, desc, value_hint),
-            OptionKind::Flag => options.optflag(short_name, long_name, desc),
-            OptionKind::FlagMulti => options.optflagmulti(short_name, long_name, desc),
+            OptionKind::Opt => options.optopt(short_name, long_name, &desc, value_hint),
+            OptionKind::Multi => options.optmulti(short_name, long_name, &desc, value_hint),
+            OptionKind::Flag => options.optflag(short_name, long_name, &desc),
+            OptionKind::FlagMulti => options.optflagmulti(short_name, long_name, &desc),
         };
     }
 
@@ -3289,10 +3297,12 @@ pub mod nightly_options {
             if !matches.opt_present(opt.name) {
                 continue;
             }
-            if opt.name != "Z" && !has_z_unstable_option {
+            if opt.name != "Z"
+                && !has_z_unstable_option
+                && unstable_features.allow_unstable_compiler_flag(opt.name)
+            {
                 early_dcx.early_fatal(format!(
-                    "the `-Z unstable-options` flag must also be passed to enable \
-                         the flag `{}`",
+                    "the `-Z unstable-options` flag must also be passed to enable the flag `{}`",
                     opt.name
                 ));
             }

tests/run-make/rustc-help/help-v.diff

@@ -1,11 +1,12 @@
-@@ -65,10 +65,31 @@
+@@ -65,10 +65,42 @@
                          Set a codegen option
      -V, --version       Print version info and exit
      -v, --verbose       Use verbose output
 +        --extern <NAME>[=<PATH>]
 +                        Specify where an external rust library is located
 +        --sysroot <PATH>
 +                        Override the system root
++    -Z <FLAG>           Set unstable / perma-unstable options (unstable)
 +        --error-format <human|json|short>
 +                        How errors and other messages are produced
 +        --json <CONFIG> Configure the JSON output of the compiler
@@ -23,6 +24,16 @@
 +        --remap-path-scope <macro,diagnostics,debuginfo,coverage,object,all>
 +                        Defines which scopes of paths should be remapped by
 +                        `--remap-path-prefix`
++    -j, --jobs <N>      Limit on the number of used parallel jobs (unstable)
++        --jobs-frontend <N>
++                        Limit on the number of parallel jobs used by frontend
++                        (unstable)
++        --jobs-backend <N>
++                        Limit on the number of parallel jobs used by backend
++                        (unstable)
++        --jobs-linker <N>
++                        Limit on the number of parallel jobs used by linker
++                        (unstable)
 +    @path               Read newline separated options from `path`
 
  Additional help:

tests/run-make/rustc-help/help-v.stdout

@@ -69,6 +69,7 @@ Options:
                         Specify where an external rust library is located
         --sysroot <PATH>
                         Override the system root
+    -Z <FLAG>           Set unstable / perma-unstable options (unstable)
         --error-format <human|json|short>
                         How errors and other messages are produced
         --json <CONFIG> Configure the JSON output of the compiler
@@ -86,6 +87,16 @@ Options:
         --remap-path-scope <macro,diagnostics,debuginfo,coverage,object,all>
                         Defines which scopes of paths should be remapped by
                         `--remap-path-prefix`
+    -j, --jobs <N>      Limit on the number of used parallel jobs (unstable)
+        --jobs-frontend <N>
+                        Limit on the number of parallel jobs used by frontend
+                        (unstable)
+        --jobs-backend <N>
+                        Limit on the number of parallel jobs used by backend
+                        (unstable)
+        --jobs-linker <N>
+                        Limit on the number of parallel jobs used by linker
+                        (unstable)
     @path               Read newline separated options from `path`
 
 Additional help:

tests/run-make/rustdoc/default-output/output-default.stdout

@@ -23,16 +23,16 @@ Options:
         --extern-html-root-url NAME=URL
                         base URL to use for dependencies; for example,
                         "std=/doc" links std::vec::Vec to
-                        /doc/std/vec/struct.Vec.html
+                        /doc/std/vec/struct.Vec.html (unstable)
         --extern-html-root-takes-precedence 
                         give precedence to `--extern-html-root-url`, not
-                        `html_root_url`
+                        `html_root_url` (unstable)
     -C, --codegen OPT[=VALUE]
                         pass a codegen option to rustc
         --document-private-items 
                         document private items
         --document-hidden-items 
-                        document items that have doc(hidden)
+                        document items that have doc(hidden) (unstable)
         --test          run code examples as tests
         --test-args ARGS
                         arguments to pass to the test runner
@@ -55,10 +55,11 @@ Options:
         --markdown-before-content FILES
                         files to include inline between <body> and the content
                         of a rendered Markdown file or generated documentation
+                        (unstable)
         --markdown-after-content FILES
                         files to include inline between the content and
                         </body> of a rendered Markdown file or generated
-                        documentation
+                        documentation (unstable)
         --markdown-playground-url URL
                         URL to send code snippets to
         --markdown-no-toc 
@@ -69,22 +70,22 @@ Options:
                         break if the rustdoc's generated HTML changes, so be
                         careful!
     -Z FLAG             unstable / perma-unstable options (only on nightly
-                        build)
+                        build) (unstable)
         --sysroot PATH  Override the system root
         --playground-url URL
                         URL to send code snippets to, may be reset by
                         --markdown-playground-url or
-                        `#![doc(html_playground_url=...)]`
+                        `#![doc(html_playground_url=...)]` (unstable)
         --display-doctest-warnings 
-                        show warnings that originate in doctests
+                        show warnings that originate in doctests (unstable)
         --crate-version VERSION
                         crate version to print into documentation
         --sort-modules-by-appearance 
                         sort modules by where they appear in the program,
-                        rather than alphabetically
+                        rather than alphabetically (unstable)
         --crate-list-heading TEXT
                         heading under which to list this crate in the sidebar
-                        crate list
+                        crate list (unstable)
         --default-theme THEME
                         Set the default theme. THEME should be the theme name,
                         generally lowercase. If an unknown default theme is
@@ -96,14 +97,15 @@ Options:
                         "rustdoc-SETTING" is absent from web browser Local
                         Storage). If VALUE is not supplied, "true" is used.
                         Supported SETTINGs and VALUEs are not documented and
-                        not stable.
+                        not stable. (unstable)
         --theme FILES   additional themes which will be added to the generated
                         docs
         --check-theme FILES
                         check if given theme is valid
         --resource-suffix PATH
                         suffix to add to CSS and JavaScript files, e.g.,
                         "search-index.js" will become "search-index-suffix.js"
+                        (unstable)
         --edition EDITION
                         edition to use when compiling rust code (default:
                         2015)
@@ -131,80 +133,86 @@ Options:
         --remap-path-prefix FROM=TO
                         Remap source names in compiler messages
         --index-page PATH
-                        Markdown file to be used as index page
+                        Markdown file to be used as index page (unstable)
         --enable-index-page 
-                        To enable generation of the index page
+                        To enable generation of the index page (unstable)
         --static-root-path PATH
                         Path string to force loading static files from in
                         output pages. If not set, uses combinations of '../'
-                        to reach the documentation root.
+                        to reach the documentation root. (unstable)
         --persist-doctests PATH
                         Directory to persist doctest executables into
+                        (unstable)
         --show-coverage 
                         calculate percentage of public items with
-                        documentation
+                        documentation (unstable)
         --test-runtool The tool to run tests with when building for a different target than host
 
         --test-runtool-arg One argument (of possibly many) to pass to the runtool
 
         --test-builder PATH
                         The rustc-like binary to use as the test builder
+                        (unstable)
         --test-builder-wrapper PATH
                         Wrapper program to pass test-builder and arguments
-        --check         Run rustdoc checks
+                        (unstable)
+        --check         Run rustdoc checks (unstable)
         --generate-redirect-map 
                         Generate JSON file at the top level instead of
-                        generating HTML redirection files
+                        generating HTML redirection files (unstable)
         --emit [html-static-files,html-non-static-files,dep-info]
                         Comma separated list of types of output for rustdoc to
                         emit
         --print <INFO>[=<FILE>]
                         Rustdoc information to print on stdout (or to a file)
-        --no-run        Compile doctests without running them
+                        (unstable)
+        --no-run        Compile doctests without running them (unstable)
         --merge-doctests yes|no|auto
                         Force all doctests to be compiled as a single binary,
                         instead of one binary per test. If merging fails,
-                        rustdoc will emit a hard error.
+                        rustdoc will emit a hard error. (unstable)
         --remap-path-scope [macro,diagnostics,debuginfo,coverage,object,all]
                         Defines which scopes of paths should be remapped by
-                        `--remap-path-prefix`
+                        `--remap-path-prefix` (unstable)
         --show-type-layout 
                         Include the memory layout of types in the docs
-        --no-capture    Don't capture stdout and stderr of tests
+                        (unstable)
+        --no-capture    Don't capture stdout and stderr of tests (unstable)
         --generate-link-to-definition 
                         Make the identifiers in the HTML source code pages
-                        navigable
+                        navigable (unstable)
         --scrape-examples-output-path collect function call information and output at the given path
-
+                        (unstable)
         --scrape-examples-target-crate collect function call information for functions from the target crate
-
-        --scrape-tests  Include test code when scraping examples
+                        (unstable)
+        --scrape-tests  Include test code when scraping examples (unstable)
         --with-examples path to function call information (for displaying examples in the documentation)
-
+                        (unstable)
         --write-doc-meta-dir path/to/doc.meta
                         Writes trait implementations and other info for the
-                        current crate to provided path
+                        current crate to provided path (unstable)
         --read-doc-meta-dir path/to/doc.meta
                         Includes trait implementations and other crate info
-                        from provided path
+                        from provided path (unstable)
         --parts-out-dir path/to/doc.meta
-                        Deprecated synonym of write-doc-meta-dir
+                        Deprecated synonym of write-doc-meta-dir (unstable)
         --include-parts-dir path/to/doc.meta
-                        Deprecated synonym of read-doc-meta-dir
+                        Deprecated synonym of read-doc-meta-dir (unstable)
         --merge none, shared, finalize
                         Deprecated option to specify read/write-doc-meta-dir
-                        mode
+                        mode (unstable)
         --html-no-source 
-                        Disable HTML source code pages generation
+                        Disable HTML source code pages generation (unstable)
         --doctest-build-arg ARG
                         One argument (of possibly many) to be used when
-                        compiling doctests
+                        compiling doctests (unstable)
         --disable-minification 
                         disable the minification of CSS/JS files
                         (perma-unstable, do not use with cached files)
+                        (unstable)
         --generate-macro-expansion 
                         Add possibility to expand macros in the HTML source
-                        code pages
+                        code pages (unstable)
         --plugin-path DIR
                         removed, see issue #44136
                         <https://github.com/rust-lang/rust/issues/44136> for

tests/run-make/rustdoc/unstable-option-diagnostics/missing-opt-in.stderr

@@ -0,0 +1,2 @@
+error: the `-Z unstable-options` flag must also be passed to enable the flag `no-run`
+

tests/run-make/rustdoc/unstable-option-diagnostics/requires-nightly.stderr

@@ -0,0 +1,8 @@
+error: the option `no-run` is only accepted on the nightly compiler
+
+error: 1 nightly option was parsed
+  |
+  = help: consider switching to a nightly toolchain: `rustup default nightly`
+  = note: selecting a toolchain with `+toolchain` arguments require a rustup proxy; see <https://rust-lang.github.io/rustup/concepts/index.html>
+  = note: for more information about Rust's stability policy, see <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html#unstable-features>
+

tests/run-make/rustdoc/unstable-option-diagnostics/rmake.rs

@@ -0,0 +1,50 @@
+// Regression test for https://github.com/rust-lang/rust/issues/88426.
+use run_make_support::{bare_rustdoc, diff};
+
+fn main() {
+    for bootstrap in ["-1", "1"] {
+        let output = bare_rustdoc().env("RUSTC_BOOTSTRAP", bootstrap).arg("--help").run();
+
+        output.assert_stderr_equals("");
+        let help = output.stdout_utf8();
+
+        let no_run = help.lines().find(|line| line.trim_start().starts_with("--no-run ")).unwrap();
+        assert!(no_run.contains("(unstable)"));
+
+        let help_option = help.lines().find(|line| line.contains("--help ")).unwrap();
+        assert!(!help_option.contains("(unstable)"));
+    }
+
+    // Simulate stable restrictions: requesting an unusable opt-in is misleading.
+    let output =
+        bare_rustdoc().env("RUSTC_BOOTSTRAP", "-1").args(["--no-run", "--help"]).run_fail();
+
+    output.assert_exit_code(1);
+    output
+        .assert_stderr_contains("the option `no-run` is only accepted on the nightly compiler")
+        .assert_stderr_not_contains("must also be passed");
+
+    diff()
+        .expected_file("requires-nightly.stderr")
+        .actual_text("rustdoc stderr", output.stderr_utf8())
+        .run();
+
+    // Allow unstable options, but do not supply the required opt-in.
+    let output = bare_rustdoc().env("RUSTC_BOOTSTRAP", "1").args(["--no-run", "--help"]).run_fail();
+
+    output.assert_exit_code(1);
+    output.assert_stderr_contains("`-Z unstable-options` flag must also be passed");
+
+    diff()
+        .expected_file("missing-opt-in.stderr")
+        .actual_text("rustdoc stderr", output.stderr_utf8())
+        .run();
+
+    // With permission and opt-in, argument checking should succeed.
+    let output = bare_rustdoc()
+        .env("RUSTC_BOOTSTRAP", "1")
+        .args(["--no-run", "-Zunstable-options", "--help"])
+        .run();
+
+    output.assert_stderr_equals("");
+}

tests/ui/compile-flags/jobs/jobs-fail-range.j.stderr

@@ -1,4 +1,4 @@
 error: Argument to option 'jobs' missing
        Usage:
-           -j, --jobs <N>      Limit on the number of used parallel jobs
+           -j, --jobs <N>      Limit on the number of used parallel jobs (unstable)