Unify the format of rustc cli flags

Signed-off-by: xizheyin <[email protected]>

Author: xizheyin

compiler/rustc_session/src/config.rs

@@ -1646,7 +1646,7 @@ The default is {DEFAULT_EDITION} and the latest stable edition is {LATEST_STABLE
 static PRINT_HELP: LazyLock<String> = LazyLock::new(|| {
     format!(
         "Compiler information to print on stdout (or to a file)\n\
-        INFO may be one of ({}).",
+        INFO may be one of <{}>.",
         PRINT_KINDS.iter().map(|(name, _)| format!("{name}")).collect::<Vec<_>>().join("|")
     )
 });
@@ -1679,66 +1679,85 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
             "",
             "cfg",
             "Configure the compilation environment.\n\
-                SPEC supports the syntax `NAME[=\"VALUE\"]`.",
-            "SPEC",
+                SPEC supports the syntax `<NAME>[=\"VALUE\"]`.",
+            "<SPEC>",
         ),
-        opt(Stable, Multi, "", "check-cfg", "Provide list of expected cfgs for checking", "SPEC"),
+        opt(Stable, Multi, "", "check-cfg", "Provide list of expected cfgs for checking", "<SPEC>"),
         opt(
             Stable,
             Multi,
             "L",
             "",
             "Add a directory to the library search path. \
-                The optional KIND can be one of dependency, crate, native, framework, or all (the default).",
-            "[KIND=]PATH",
+                The optional <KIND> can be one of <dependency|crate|native|framework|all> (default: all).",
+            "[<KIND>=]<PATH>",
         ),
         opt(
             Stable,
             Multi,
             "l",
             "",
             "Link the generated crate(s) to the specified native\n\
-                library NAME. The optional KIND can be one of\n\
-                static, framework, or dylib (the default).\n\
-                Optional comma separated MODIFIERS\n\
-                (bundle|verbatim|whole-archive|as-needed)\n\
+                library <NAME>. The optional <KIND> can be one of\n\
+                <static|framework|dylib> (default: dylib).\n\
+                Optional comma separated <MODIFIERS>\n\
+                <bundle|verbatim|whole-archive|as-needed>\n\
                 may be specified each with a prefix of either '+' to\n\
                 enable or '-' to disable.",
-            "[KIND[:MODIFIERS]=]NAME[:RENAME]",
+            "[<KIND>[:<MODIFIERS>]=]<NAME>[:<RENAME>]",
         ),
         make_crate_type_option(),
-        opt(Stable, Opt, "", "crate-name", "Specify the name of the crate being built", "NAME"),
+        opt(Stable, Opt, "", "crate-name", "Specify the name of the crate being built", "<NAME>"),
         opt(Stable, Opt, "", "edition", &EDITION_STRING, EDITION_NAME_LIST),
-        opt(Stable, Multi, "", "emit", &EMIT_HELP, "TYPE[=FILE]"),
+        opt(Stable, Multi, "", "emit", &EMIT_HELP, "<TYPE>[=<FILE>]"),
+        opt(Stable, Multi, "", "print", &PRINT_HELP, "<INFO>[=<FILE>]"),
+        opt(Stable, FlagMulti, "g", "", "Equivalent to -C debuginfo=2", ""),
+        opt(Stable, FlagMulti, "O", "", "Equivalent to -C opt-level=3", ""),
+        opt(Stable, Opt, "o", "", "Write output to <FILENAME>", "<FILENAME>"),
+        opt(
+            Stable,
+            Opt,
+            "",
+            "emit",
+            "Comma separated list of types of output for the compiler to emit",
+            "[asm|llvm-bc|llvm-ir|obj|metadata|link|dep-info|mir]",
+        ),
         opt(Stable, Multi, "", "print", &PRINT_HELP, "INFO[=FILE]"),
         opt(Stable, FlagMulti, "g", "", "Equivalent to -C debuginfo=2", ""),
         opt(Stable, FlagMulti, "O", "", "Equivalent to -C opt-level=3", ""),
-        opt(Stable, Opt, "o", "", "Write output to <filename>", "FILENAME"),
-        opt(Stable, Opt, "", "out-dir", "Write output to compiler-chosen filename in <dir>", "DIR"),
+        opt(Stable, Opt, "o", "", "Write output to <FILENAME>", "<FILENAME>"),
+        opt(
+            Stable,
+            Opt,
+            "",
+            "out-dir",
+            "Write output to compiler-chosen filename in <DIR>",
+            "<DIR>",
+        ),
         opt(
             Stable,
             Opt,
             "",
             "explain",
             "Provide a detailed explanation of an error message",
-            "OPT",
+            "<OPT>",
         ),
         opt(Stable, Flag, "", "test", "Build a test harness", ""),
-        opt(Stable, Opt, "", "target", "Target triple for which the code is compiled", "TARGET"),
-        opt(Stable, Multi, "A", "allow", "Set lint allowed", "LINT"),
-        opt(Stable, Multi, "W", "warn", "Set lint warnings", "LINT"),
-        opt(Stable, Multi, "", "force-warn", "Set lint force-warn", "LINT"),
-        opt(Stable, Multi, "D", "deny", "Set lint denied", "LINT"),
-        opt(Stable, Multi, "F", "forbid", "Set lint forbidden", "LINT"),
+        opt(Stable, Opt, "", "target", "Target triple for which the code is compiled", "<TARGET>"),
+        opt(Stable, Multi, "A", "allow", "Set lint allowed", "<LINT>"),
+        opt(Stable, Multi, "W", "warn", "Set lint warnings", "<LINT>"),
+        opt(Stable, Multi, "", "force-warn", "Set lint force-warn", "<LINT>"),
+        opt(Stable, Multi, "D", "deny", "Set lint denied", "<LINT>"),
+        opt(Stable, Multi, "F", "forbid", "Set lint forbidden", "<LINT>"),
         opt(
             Stable,
             Multi,
             "",
             "cap-lints",
             "Set the most restrictive lint level. More restrictive lints are capped at this level",
-            "LEVEL",
+            "<LEVEL>",
         ),
-        opt(Stable, Multi, "C", "codegen", "Set a codegen option", "OPT[=VALUE]"),
+        opt(Stable, Multi, "C", "codegen", "Set a codegen option", "<OPT>[=<VALUE>]"),
         opt(Stable, Flag, "V", "version", "Print version info and exit", ""),
         opt(Stable, Flag, "v", "verbose", "Use verbose output", ""),
     ];
@@ -1752,47 +1771,47 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
             "",
             "extern",
             "Specify where an external rust library is located",
-            "NAME[=PATH]",
+            "<NAME>[=<PATH>]",
         ),
-        opt(Stable, Opt, "", "sysroot", "Override the system root", "PATH"),
-        opt(Unstable, Multi, "Z", "", "Set unstable / perma-unstable options", "FLAG"),
+        opt(Stable, Opt, "", "sysroot", "Override the system root", "<PATH>"),
+        opt(Unstable, Multi, "Z", "", "Set unstable / perma-unstable options", "<FLAG>"),
         opt(
             Stable,
             Opt,
             "",
             "error-format",
             "How errors and other messages are produced",
-            "human|json|short",
+            "<human|json|short>",
         ),
-        opt(Stable, Multi, "", "json", "Configure the JSON output of the compiler", "CONFIG"),
+        opt(Stable, Multi, "", "json", "Configure the JSON output of the compiler", "<CONFIG>"),
         opt(
             Stable,
             Opt,
             "",
             "color",
             "Configure coloring of output:
-                auto   = colorize, if output goes to a tty (default);
-                always = always colorize output;
-                never  = never colorize output",
-            "auto|always|never",
+                * auto   = colorize, if output goes to a tty (default);
+                * always = always colorize output;
+                * never  = never colorize output",
+            "<auto|always|never>",
         ),
         opt(
             Stable,
             Opt,
             "",
             "diagnostic-width",
             "Inform rustc of the width of the output so that diagnostics can be truncated to fit",
-            "WIDTH",
+            "<WIDTH>",
         ),
         opt(
             Stable,
             Multi,
             "",
             "remap-path-prefix",
             "Remap source names in all output (compiler messages and output files)",
-            "FROM=TO",
+            "<FROM>=<TO>",
         ),
-        opt(Unstable, Multi, "", "env-set", "Inject an environment variable", "VAR=VALUE"),
+        opt(Unstable, Multi, "", "env-set", "Inject an environment variable", "<VAR>=<VALUE>"),
     ];
     options.extend(verbose_only.into_iter().map(|mut opt| {
         opt.is_verbose_help_only = true;
@@ -2792,7 +2811,7 @@ pub fn make_crate_type_option() -> RustcOptGroup {
         "crate-type",
         "Comma separated list of types of crates
                                 for the compiler to emit",
-        "[bin|lib|rlib|dylib|cdylib|staticlib|proc-macro]",
+        "<bin|lib|rlib|dylib|cdylib|staticlib|proc-macro>",
     )
 }
 

compiler/rustc_span/src/edition.rs

@@ -45,7 +45,7 @@ pub const ALL_EDITIONS: &[Edition] = &[
     Edition::EditionFuture,
 ];
 
-pub const EDITION_NAME_LIST: &str = "2015|2018|2021|2024";
+pub const EDITION_NAME_LIST: &str = "<2015|2018|2021|2024>";
 
 pub const DEFAULT_EDITION: Edition = Edition::Edition2015;
 

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

@@ -1,22 +1,23 @@
-@@ -63,10 +63,27 @@
+@@ -75,10 +75,28 @@
                          Set a codegen option
      -V, --version       Print version info and exit
      -v, --verbose       Use verbose output
-+        --extern NAME[=PATH]
++        --extern <NAME>[=<PATH>]
 +                        Specify where an external rust library is located
-+        --sysroot PATH  Override the system root
-+        --error-format human|json|short
++        --sysroot <PATH>
++                        Override the system root
++        --error-format <human|json|short>
 +                        How errors and other messages are produced
-+        --json CONFIG   Configure the JSON output of the compiler
-+        --color auto|always|never
++        --json <CONFIG> Configure the JSON output of the compiler
++        --color <auto|always|never>
 +                        Configure coloring of output:
-+                        auto = colorize, if output goes to a tty (default);
-+                        always = always colorize output;
-+                        never = never colorize output
-+        --diagnostic-width WIDTH
++                        * auto = colorize, if output goes to a tty (default);
++                        * always = always colorize output;
++                        * never = never colorize output
++        --diagnostic-width <WIDTH>
 +                        Inform rustc of the width of the output so that
 +                        diagnostics can be truncated to fit
-+        --remap-path-prefix FROM=TO
++        --remap-path-prefix <FROM>=<TO>
 +                        Remap source names in all output (compiler messages
 +                        and output files)
 +    @path               Read newline separated options from `path`

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

@@ -2,31 +2,32 @@ Usage: rustc [OPTIONS] INPUT
 
 Options:
     -h, --help          Display this message
-        --cfg SPEC      Configure the compilation environment.
-                        SPEC supports the syntax `NAME[="VALUE"]`.
-        --check-cfg SPEC
+        --cfg <SPEC>    Configure the compilation environment.
+                        SPEC supports the syntax `<NAME>[="VALUE"]`.
+        --check-cfg <SPEC>
                         Provide list of expected cfgs for checking
-    -L [KIND=]PATH      Add a directory to the library search path. The
-                        optional KIND can be one of dependency, crate, native,
-                        framework, or all (the default).
-    -l [KIND[:MODIFIERS]=]NAME[:RENAME]
+    -L [<KIND>=]<PATH>  Add a directory to the library search path. The
+                        optional <KIND> can be one of
+                        <dependency|crate|native|framework|all> (default:
+                        all).
+    -l [<KIND>[:<MODIFIERS>]=]<NAME>[:<RENAME>]
                         Link the generated crate(s) to the specified native
-                        library NAME. The optional KIND can be one of
-                        static, framework, or dylib (the default).
-                        Optional comma separated MODIFIERS
-                        (bundle|verbatim|whole-archive|as-needed)
+                        library <NAME>. The optional <KIND> can be one of
+                        <static|framework|dylib> (default: dylib).
+                        Optional comma separated <MODIFIERS>
+                        <bundle|verbatim|whole-archive|as-needed>
                         may be specified each with a prefix of either '+' to
                         enable or '-' to disable.
-        --crate-type [bin|lib|rlib|dylib|cdylib|staticlib|proc-macro]
+        --crate-type <bin|lib|rlib|dylib|cdylib|staticlib|proc-macro>
                         Comma separated list of types of crates
                         for the compiler to emit
-        --crate-name NAME
+        --crate-name <NAME>
                         Specify the name of the crate being built
-        --edition 2015|2018|2021|2024
+        --edition <2015|2018|2021|2024>
                         Specify which edition of the compiler to use when
                         compiling code. The default is 2015 and the latest
                         stable edition is 2024.
-        --emit TYPE[=FILE]
+        --emit <TYPE>[=<FILE>]
                         Comma separated list of types of output for the
                         compiler to emit.
                         Each TYPE has the default FILE name:
@@ -39,45 +40,57 @@ Options:
                         * mir - CRATE_NAME.mir
                         * obj - CRATE_NAME.o
                         * thin-link-bitcode - CRATE_NAME.indexing.o
+        --print <INFO>[=<FILE>]
+                        Compiler information to print on stdout (or to a file)
+                        INFO may be one of
+                        <all-target-specs-json|calling-conventions|cfg|check-cfg|code-models|crate-name|crate-root-lint-levels|deployment-target|file-names|host-tuple|link-args|native-static-libs|relocation-models|split-debuginfo|stack-protector-strategies|supported-crate-types|sysroot|target-cpus|target-features|target-libdir|target-list|target-spec-json|tls-models>.
+    -g                  Equivalent to -C debuginfo=2
+    -O                  Equivalent to -C opt-level=3
+    -o <FILENAME>       Write output to <FILENAME>
+        --emit [asm|llvm-bc|llvm-ir|obj|metadata|link|dep-info|mir]
+                        Comma separated list of types of output for the
+                        compiler to emit
         --print INFO[=FILE]
                         Compiler information to print on stdout (or to a file)
                         INFO may be one of
-                        (all-target-specs-json|calling-conventions|cfg|check-cfg|code-models|crate-name|crate-root-lint-levels|deployment-target|file-names|host-tuple|link-args|native-static-libs|relocation-models|split-debuginfo|stack-protector-strategies|supported-crate-types|sysroot|target-cpus|target-features|target-libdir|target-list|target-spec-json|tls-models).
+                        <all-target-specs-json|calling-conventions|cfg|check-cfg|code-models|crate-name|crate-root-lint-levels|deployment-target|file-names|host-tuple|link-args|native-static-libs|relocation-models|split-debuginfo|stack-protector-strategies|supported-crate-types|sysroot|target-cpus|target-features|target-libdir|target-list|target-spec-json|tls-models>.
     -g                  Equivalent to -C debuginfo=2
     -O                  Equivalent to -C opt-level=3
-    -o FILENAME         Write output to <filename>
-        --out-dir DIR   Write output to compiler-chosen filename in <dir>
-        --explain OPT   Provide a detailed explanation of an error message
+    -o <FILENAME>       Write output to <FILENAME>
+        --out-dir <DIR> Write output to compiler-chosen filename in <DIR>
+        --explain <OPT> Provide a detailed explanation of an error message
         --test          Build a test harness
-        --target TARGET Target triple for which the code is compiled
-    -A, --allow LINT    Set lint allowed
-    -W, --warn LINT     Set lint warnings
-        --force-warn LINT
+        --target <TARGET>
+                        Target triple for which the code is compiled
+    -A, --allow <LINT>  Set lint allowed
+    -W, --warn <LINT>   Set lint warnings
+        --force-warn <LINT>
                         Set lint force-warn
-    -D, --deny LINT     Set lint denied
-    -F, --forbid LINT   Set lint forbidden
-        --cap-lints LEVEL
+    -D, --deny <LINT>   Set lint denied
+    -F, --forbid <LINT> Set lint forbidden
+        --cap-lints <LEVEL>
                         Set the most restrictive lint level. More restrictive
                         lints are capped at this level
-    -C, --codegen OPT[=VALUE]
+    -C, --codegen <OPT>[=<VALUE>]
                         Set a codegen option
     -V, --version       Print version info and exit
     -v, --verbose       Use verbose output
-        --extern NAME[=PATH]
+        --extern <NAME>[=<PATH>]
                         Specify where an external rust library is located
-        --sysroot PATH  Override the system root
-        --error-format human|json|short
+        --sysroot <PATH>
+                        Override the system root
+        --error-format <human|json|short>
                         How errors and other messages are produced
-        --json CONFIG   Configure the JSON output of the compiler
-        --color auto|always|never
+        --json <CONFIG> Configure the JSON output of the compiler
+        --color <auto|always|never>
                         Configure coloring of output:
-                        auto = colorize, if output goes to a tty (default);
-                        always = always colorize output;
-                        never = never colorize output
-        --diagnostic-width WIDTH
+                        * auto = colorize, if output goes to a tty (default);
+                        * always = always colorize output;
+                        * never = never colorize output
+        --diagnostic-width <WIDTH>
                         Inform rustc of the width of the output so that
                         diagnostics can be truncated to fit
-        --remap-path-prefix FROM=TO
+        --remap-path-prefix <FROM>=<TO>
                         Remap source names in all output (compiler messages
                         and output files)
     @path               Read newline separated options from `path`