From d05469004931c04433465e399f1440fd1b386233 Mon Sep 17 00:00:00 2001 From: xizheyin Date: Tue, 22 Apr 2025 16:10:52 +0800 Subject: [PATCH 1/2] Unify the format of rustc cli flags Signed-off-by: xizheyin --- compiler/rustc_session/src/config.rs | 72 +++++++++--------- compiler/rustc_span/src/edition.rs | 2 +- tests/run-make/rustc-help/help-v.diff | 23 +++--- tests/run-make/rustc-help/help-v.stdout | 75 ++++++++++--------- tests/run-make/rustc-help/help.stdout | 54 ++++++------- .../output-default.stdout | 2 +- .../compile-flags-last.stderr | 2 +- .../emit-output-types-without-args.stderr | 3 +- .../print-without-arg.stderr | 5 +- 9 files changed, 123 insertions(+), 115 deletions(-) diff --git a/compiler/rustc_session/src/config.rs b/compiler/rustc_session/src/config.rs index bc92b95ce7116..c06f3c97da761 100644 --- a/compiler/rustc_session/src/config.rs +++ b/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 = 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::>().join("|") ) }); @@ -1679,18 +1679,18 @@ pub fn rustc_optgroups() -> Vec { "", "cfg", "Configure the compilation environment.\n\ - SPEC supports the syntax `NAME[=\"VALUE\"]`.", - "SPEC", + SPEC supports the syntax `[=\"\"]`.", + "", ), - 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", ""), 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 (default: all).", + "[=]", ), opt( Stable, @@ -1699,46 +1699,46 @@ pub fn rustc_optgroups() -> Vec { "", "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\ + (default: dylib).\n\ Optional comma separated MODIFIERS\n\ - (bundle|verbatim|whole-archive|as-needed)\n\ + \n\ may be specified each with a prefix of either '+' to\n\ enable or '-' to disable.", - "[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", ""), opt(Stable, Opt, "", "edition", &EDITION_STRING, EDITION_NAME_LIST), - opt(Stable, Multi, "", "emit", &EMIT_HELP, "TYPE[=FILE]"), - opt(Stable, Multi, "", "print", &PRINT_HELP, "INFO[=FILE]"), + opt(Stable, Multi, "", "emit", &EMIT_HELP, "[=]"), + opt(Stable, Multi, "", "print", &PRINT_HELP, "[=]"), 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"), - opt(Stable, Opt, "", "out-dir", "Write output to compiler-chosen filename in ", "DIR"), + opt(Stable, Opt, "o", "", "Write output to FILENAME", ""), + opt(Stable, Opt, "", "out-dir", "Write output to compiler-chosen filename in DIR", ""), opt( Stable, Opt, "", "explain", "Provide a detailed explanation of an error message", - "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", ""), + opt(Stable, Multi, "A", "allow", "Set lint allowed", ""), + opt(Stable, Multi, "W", "warn", "Set lint warnings", ""), + opt(Stable, Multi, "", "force-warn", "Set lint force-warn", ""), + opt(Stable, Multi, "D", "deny", "Set lint denied", ""), + opt(Stable, Multi, "F", "forbid", "Set lint forbidden", ""), opt( Stable, Multi, "", "cap-lints", "Set the most restrictive lint level. More restrictive lints are capped at this level", - "LEVEL", + "", ), - opt(Stable, Multi, "C", "codegen", "Set a codegen option", "OPT[=VALUE]"), + opt(Stable, Multi, "C", "codegen", "Set a codegen option", "[=]"), opt(Stable, Flag, "V", "version", "Print version info and exit", ""), opt(Stable, Flag, "v", "verbose", "Use verbose output", ""), ]; @@ -1752,29 +1752,29 @@ pub fn rustc_optgroups() -> Vec { "", "extern", "Specify where an external rust library is located", - "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", ""), + opt(Unstable, Multi, "Z", "", "Set unstable / perma-unstable options", ""), opt( Stable, Opt, "", "error-format", "How errors and other messages are produced", - "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", ""), 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", + "", ), opt( Stable, @@ -1782,7 +1782,7 @@ pub fn rustc_optgroups() -> Vec { "", "diagnostic-width", "Inform rustc of the width of the output so that diagnostics can be truncated to fit", - "WIDTH", + "", ), opt( Stable, @@ -1790,9 +1790,9 @@ pub fn rustc_optgroups() -> Vec { "", "remap-path-prefix", "Remap source names in all output (compiler messages and output files)", - "FROM=TO", + "=", ), - opt(Unstable, Multi, "", "env-set", "Inject an environment variable", "VAR=VALUE"), + opt(Unstable, Multi, "", "env-set", "Inject an environment variable", "="), ]; options.extend(verbose_only.into_iter().map(|mut opt| { opt.is_verbose_help_only = true; @@ -2792,7 +2792,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]", + "", ) } diff --git a/compiler/rustc_span/src/edition.rs b/compiler/rustc_span/src/edition.rs index da298080ed2f6..28335734f4dec 100644 --- a/compiler/rustc_span/src/edition.rs +++ b/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|future>"; pub const DEFAULT_EDITION: Edition = Edition::Edition2015; diff --git a/tests/run-make/rustc-help/help-v.diff b/tests/run-make/rustc-help/help-v.diff index 0ea79f3e55734..60a9dfbe201d9 100644 --- a/tests/run-make/rustc-help/help-v.diff +++ b/tests/run-make/rustc-help/help-v.diff @@ -1,22 +1,23 @@ -@@ -63,10 +63,27 @@ +@@ -65,10 +65,28 @@ Set a codegen option -V, --version Print version info and exit -v, --verbose Use verbose output -+ --extern NAME[=PATH] ++ --extern [=] + Specify where an external rust library is located -+ --sysroot PATH Override the system root -+ --error-format human|json|short ++ --sysroot ++ Override the system root ++ --error-format + How errors and other messages are produced -+ --json CONFIG Configure the JSON output of the compiler -+ --color auto|always|never ++ --json Configure the JSON output of the compiler ++ --color + 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 + Inform rustc of the width of the output so that + diagnostics can be truncated to fit -+ --remap-path-prefix FROM=TO ++ --remap-path-prefix = + Remap source names in all output (compiler messages + and output files) + @path Read newline separated options from `path` diff --git a/tests/run-make/rustc-help/help-v.stdout b/tests/run-make/rustc-help/help-v.stdout index 744453d6e8569..3fc297fb08e7d 100644 --- a/tests/run-make/rustc-help/help-v.stdout +++ b/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 Configure the compilation environment. + SPEC supports the syntax `[=""]`. + --check-cfg 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 [=] Add a directory to the library search path. The + optional KIND can be one of + (default: + all). + -l [[:]=][:] Link the generated crate(s) to the specified native library NAME. The optional KIND can be one of - static, framework, or dylib (the default). + (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 Comma separated list of types of crates for the compiler to emit - --crate-name NAME + --crate-name Specify the name of the crate being built - --edition 2015|2018|2021|2024 + --edition <2015|2018|2021|2024|future> 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 [=] Comma separated list of types of output for the compiler to emit. Each TYPE has the default FILE name: @@ -39,45 +40,47 @@ Options: * mir - CRATE_NAME.mir * obj - CRATE_NAME.o * thin-link-bitcode - CRATE_NAME.indexing.o - --print INFO[=FILE] + --print [=] 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 - --out-dir DIR Write output to compiler-chosen filename in - --explain OPT Provide a detailed explanation of an error message + -o Write output to FILENAME + --out-dir Write output to compiler-chosen filename in DIR + --explain 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 triple for which the code is compiled + -A, --allow Set lint allowed + -W, --warn Set lint warnings + --force-warn Set lint force-warn - -D, --deny LINT Set lint denied - -F, --forbid LINT Set lint forbidden - --cap-lints LEVEL + -D, --deny Set lint denied + -F, --forbid Set lint forbidden + --cap-lints Set the most restrictive lint level. More restrictive lints are capped at this level - -C, --codegen OPT[=VALUE] + -C, --codegen [=] Set a codegen option -V, --version Print version info and exit -v, --verbose Use verbose output - --extern NAME[=PATH] + --extern [=] Specify where an external rust library is located - --sysroot PATH Override the system root - --error-format human|json|short + --sysroot + Override the system root + --error-format How errors and other messages are produced - --json CONFIG Configure the JSON output of the compiler - --color auto|always|never + --json Configure the JSON output of the compiler + --color 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 Inform rustc of the width of the output so that diagnostics can be truncated to fit - --remap-path-prefix FROM=TO + --remap-path-prefix = Remap source names in all output (compiler messages and output files) @path Read newline separated options from `path` diff --git a/tests/run-make/rustc-help/help.stdout b/tests/run-make/rustc-help/help.stdout index 3043755207a64..caffe28f49899 100644 --- a/tests/run-make/rustc-help/help.stdout +++ b/tests/run-make/rustc-help/help.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 Configure the compilation environment. + SPEC supports the syntax `[=""]`. + --check-cfg 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 [=] Add a directory to the library search path. The + optional KIND can be one of + (default: + all). + -l [[:]=][:] Link the generated crate(s) to the specified native library NAME. The optional KIND can be one of - static, framework, or dylib (the default). + (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 Comma separated list of types of crates for the compiler to emit - --crate-name NAME + --crate-name Specify the name of the crate being built - --edition 2015|2018|2021|2024 + --edition <2015|2018|2021|2024|future> 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 [=] Comma separated list of types of output for the compiler to emit. Each TYPE has the default FILE name: @@ -39,27 +40,28 @@ Options: * mir - CRATE_NAME.mir * obj - CRATE_NAME.o * thin-link-bitcode - CRATE_NAME.indexing.o - --print INFO[=FILE] + --print [=] 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 - --out-dir DIR Write output to compiler-chosen filename in - --explain OPT Provide a detailed explanation of an error message + -o Write output to FILENAME + --out-dir Write output to compiler-chosen filename in DIR + --explain 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 triple for which the code is compiled + -A, --allow Set lint allowed + -W, --warn Set lint warnings + --force-warn Set lint force-warn - -D, --deny LINT Set lint denied - -F, --forbid LINT Set lint forbidden - --cap-lints LEVEL + -D, --deny Set lint denied + -F, --forbid Set lint forbidden + --cap-lints Set the most restrictive lint level. More restrictive lints are capped at this level - -C, --codegen OPT[=VALUE] + -C, --codegen [=] Set a codegen option -V, --version Print version info and exit -v, --verbose Use verbose output diff --git a/tests/run-make/rustdoc-default-output/output-default.stdout b/tests/run-make/rustdoc-default-output/output-default.stdout index 01f470f6e162b..3f47623cb031e 100644 --- a/tests/run-make/rustdoc-default-output/output-default.stdout +++ b/tests/run-make/rustdoc-default-output/output-default.stdout @@ -11,7 +11,7 @@ Options: -o, --out-dir PATH which directory to place the output --crate-name NAME specify the name of this crate - --crate-type [bin|lib|rlib|dylib|cdylib|staticlib|proc-macro] + --crate-type Comma separated list of types of crates for the compiler to emit -L, --library-path DIR diff --git a/tests/ui/compiletest-self-test/compile-flags-last.stderr b/tests/ui/compiletest-self-test/compile-flags-last.stderr index 72d92206e2bb4..5a48361cfc0df 100644 --- a/tests/ui/compiletest-self-test/compile-flags-last.stderr +++ b/tests/ui/compiletest-self-test/compile-flags-last.stderr @@ -1,5 +1,5 @@ error: Argument to option 'cap-lints' missing Usage: - --cap-lints LEVEL Set the most restrictive lint level. More restrictive + --cap-lints Set the most restrictive lint level. More restrictive lints are capped at this level diff --git a/tests/ui/invalid-compile-flags/emit-output-types-without-args.stderr b/tests/ui/invalid-compile-flags/emit-output-types-without-args.stderr index 669913b57653e..9e4486a272f9d 100644 --- a/tests/ui/invalid-compile-flags/emit-output-types-without-args.stderr +++ b/tests/ui/invalid-compile-flags/emit-output-types-without-args.stderr @@ -1,6 +1,7 @@ error: Argument to option 'emit' missing Usage: - --emit TYPE[=FILE] Comma separated list of types of output for the + --emit [=] + Comma separated list of types of output for the compiler to emit. Each TYPE has the default FILE name: * asm - CRATE_NAME.s diff --git a/tests/ui/invalid-compile-flags/print-without-arg.stderr b/tests/ui/invalid-compile-flags/print-without-arg.stderr index fd2a36e761bef..3048a59d0d00c 100644 --- a/tests/ui/invalid-compile-flags/print-without-arg.stderr +++ b/tests/ui/invalid-compile-flags/print-without-arg.stderr @@ -1,6 +1,7 @@ error: Argument to option 'print' missing Usage: - --print INFO[=FILE] Compiler information to print on stdout (or to a file) + --print [=] + 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). + . From 999b9069dd1062efa46d893c0024955d499f8cd8 Mon Sep 17 00:00:00 2001 From: xizheyin Date: Fri, 25 Apr 2025 19:37:42 +0800 Subject: [PATCH 2/2] Add option style comment for `rustc_optgroups` Signed-off-by: xizheyin --- compiler/rustc_session/src/config.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/compiler/rustc_session/src/config.rs b/compiler/rustc_session/src/config.rs index c06f3c97da761..cc506b0164eee 100644 --- a/compiler/rustc_session/src/config.rs +++ b/compiler/rustc_session/src/config.rs @@ -1665,6 +1665,13 @@ static EMIT_HELP: LazyLock = LazyLock::new(|| { /// Returns all rustc command line options, including metadata for /// each option, such as whether the option is stable. +/// +/// # Option style guidelines +/// +/// - ``: Indicates a required parameter +/// - `[param]`: Indicates an optional parameter +/// - `|`: Indicates a mutually exclusive option +/// - `*`: a list element with description pub fn rustc_optgroups() -> Vec { use OptionKind::{Flag, FlagMulti, Multi, Opt}; use OptionStability::{Stable, Unstable};