Skip to content

Unify the format of rustc cli flags #140152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 25, 2025
Merged

Unify the format of rustc cli flags #140152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d054690
Unify the format of rustc cli flags
xizheyin Apr 22, 2025
999b906
Add option style comment for `rustc_optgroups`
xizheyin Apr 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 43 additions & 36 deletions compiler/rustc_session/src/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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("|")
)
});
Expand All @@ -1665,6 +1665,13 @@ static EMIT_HELP: LazyLock<String> = LazyLock::new(|| {

/// Returns all rustc command line options, including metadata for
/// each option, such as whether the option is stable.
///
/// # Option style guidelines
///
/// - `<param>`: Indicates a required parameter
/// - `[param]`: Indicates an optional parameter
/// - `|`: Indicates a mutually exclusive option
/// - `*`: a list element with description
pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
use OptionKind::{Flag, FlagMulti, Multi, Opt};
use OptionStability::{Stable, Unstable};
Expand All @@ -1679,18 +1686,18 @@ 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,
Expand All @@ -1699,46 +1706,46 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
"",
"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\
<static|framework|dylib> (default: dylib).\n\
Optional comma separated MODIFIERS\n\
(bundle|verbatim|whole-archive|as-needed)\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, "", "print", &PRINT_HELP, "INFO[=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, "", "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", ""),
];
Expand All @@ -1752,47 +1759,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;
Expand Down Expand Up @@ -2792,7 +2799,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>",
)
}

Expand Down
2 changes: 1 addition & 1 deletion compiler/rustc_span/src/edition.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
23 changes: 12 additions & 11 deletions tests/run-make/rustc-help/help-v.diff
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <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`
Expand Down
75 changes: 39 additions & 36 deletions tests/run-make/rustc-help/help-v.stdout
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
<static|framework|dylib> (default: dylib).
Optional comma separated MODIFIERS
(bundle|verbatim|whole-archive|as-needed)
<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|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 <TYPE>[=<FILE>]
Comma separated list of types of output for the
compiler to emit.
Each TYPE has the default FILE name:
Expand All @@ -39,45 +40,47 @@ Options:
* mir - CRATE_NAME.mir
* obj - CRATE_NAME.o
* thin-link-bitcode - CRATE_NAME.indexing.o
--print INFO[=FILE]
--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`
Expand Down
Loading
Loading