Skip to content

Commit eb225e3

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #140152 - xizheyin:issue-140102, r=jieyouxu
Unify the format of rustc cli flags As mentioned in #140102, I unified the format of rustc CLI flags. I use the following rules: 1. `<param>`: Indicates a required parameter 2. `[param]`: Indicates an optional parameter 3. `|`: Indicates a mutually exclusive option 4. `*`: a list element with description Current output: ```bash 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> 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|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|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> Comma separated list of types of crates for the compiler to emit --crate-name <NAME> Specify the name of the crate being built --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>] Comma separated list of types of output for the compiler to emit. Each TYPE has the default FILE name: * asm - CRATE_NAME.s * llvm-bc - CRATE_NAME.bc * dep-info - CRATE_NAME.d * link - (platform and crate-type dependent) * llvm-ir - CRATE_NAME.ll * metadata - libCRATE_NAME.rmeta * 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 --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> Set lint force-warn -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>] Set a codegen option -V, --version Print version info and exit -v, --verbose Use verbose output Additional help: -C help Print codegen options -W help Print 'lint' options and default settings -Z help Print unstable compiler options --help -v Print the full set of options rustc accepts ```
2 parents 394cdca + 999b906 commit eb225e3

File tree

9 files changed

+130
-115
lines changed

9 files changed

+130
-115
lines changed

‎compiler/rustc_session/src/config.rs

+43-36
Original file line numberDiff line numberDiff line change
@@ -1650,7 +1650,7 @@ The default is {DEFAULT_EDITION} and the latest stable edition is {LATEST_STABLE
16501650
static PRINT_HELP: LazyLock<String> = LazyLock::new(|| {
16511651
format!(
16521652
"Compiler information to print on stdout (or to a file)\n\
1653-
INFO may be one of ({}).",
1653+
INFO may be one of <{}>.",
16541654
PRINT_KINDS.iter().map(|(name, _)| format!("{name}")).collect::<Vec<_>>().join("|")
16551655
)
16561656
});
@@ -1669,6 +1669,13 @@ static EMIT_HELP: LazyLock<String> = LazyLock::new(|| {
16691669

16701670
/// Returns all rustc command line options, including metadata for
16711671
/// each option, such as whether the option is stable.
1672+
///
1673+
/// # Option style guidelines
1674+
///
1675+
/// - `<param>`: Indicates a required parameter
1676+
/// - `[param]`: Indicates an optional parameter
1677+
/// - `|`: Indicates a mutually exclusive option
1678+
/// - `*`: a list element with description
16721679
pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
16731680
use OptionKind::{Flag, FlagMulti, Multi, Opt};
16741681
use OptionStability::{Stable, Unstable};
@@ -1683,18 +1690,18 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
16831690
"",
16841691
"cfg",
16851692
"Configure the compilation environment.\n\
1686-
SPEC supports the syntax `NAME[=\"VALUE\"]`.",
1687-
"SPEC",
1693+
SPEC supports the syntax `<NAME>[=\"<VALUE>\"]`.",
1694+
"<SPEC>",
16881695
),
1689-
opt(Stable, Multi, "", "check-cfg", "Provide list of expected cfgs for checking", "SPEC"),
1696+
opt(Stable, Multi, "", "check-cfg", "Provide list of expected cfgs for checking", "<SPEC>"),
16901697
opt(
16911698
Stable,
16921699
Multi,
16931700
"L",
16941701
"",
16951702
"Add a directory to the library search path. \
1696-
The optional KIND can be one of dependency, crate, native, framework, or all (the default).",
1697-
"[KIND=]PATH",
1703+
The optional KIND can be one of <dependency|crate|native|framework|all> (default: all).",
1704+
"[<KIND>=]<PATH>",
16981705
),
16991706
opt(
17001707
Stable,
@@ -1703,46 +1710,46 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
17031710
"",
17041711
"Link the generated crate(s) to the specified native\n\
17051712
library NAME. The optional KIND can be one of\n\
1706-
static, framework, or dylib (the default).\n\
1713+
<static|framework|dylib> (default: dylib).\n\
17071714
Optional comma separated MODIFIERS\n\
1708-
(bundle|verbatim|whole-archive|as-needed)\n\
1715+
<bundle|verbatim|whole-archive|as-needed>\n\
17091716
may be specified each with a prefix of either '+' to\n\
17101717
enable or '-' to disable.",
1711-
"[KIND[:MODIFIERS]=]NAME[:RENAME]",
1718+
"[<KIND>[:<MODIFIERS>]=]<NAME>[:<RENAME>]",
17121719
),
17131720
make_crate_type_option(),
1714-
opt(Stable, Opt, "", "crate-name", "Specify the name of the crate being built", "NAME"),
1721+
opt(Stable, Opt, "", "crate-name", "Specify the name of the crate being built", "<NAME>"),
17151722
opt(Stable, Opt, "", "edition", &EDITION_STRING, EDITION_NAME_LIST),
1716-
opt(Stable, Multi, "", "emit", &EMIT_HELP, "TYPE[=FILE]"),
1717-
opt(Stable, Multi, "", "print", &PRINT_HELP, "INFO[=FILE]"),
1723+
opt(Stable, Multi, "", "emit", &EMIT_HELP, "<TYPE>[=<FILE>]"),
1724+
opt(Stable, Multi, "", "print", &PRINT_HELP, "<INFO>[=<FILE>]"),
17181725
opt(Stable, FlagMulti, "g", "", "Equivalent to -C debuginfo=2", ""),
17191726
opt(Stable, FlagMulti, "O", "", "Equivalent to -C opt-level=3", ""),
1720-
opt(Stable, Opt, "o", "", "Write output to <filename>", "FILENAME"),
1721-
opt(Stable, Opt, "", "out-dir", "Write output to compiler-chosen filename in <dir>", "DIR"),
1727+
opt(Stable, Opt, "o", "", "Write output to FILENAME", "<FILENAME>"),
1728+
opt(Stable, Opt, "", "out-dir", "Write output to compiler-chosen filename in DIR", "<DIR>"),
17221729
opt(
17231730
Stable,
17241731
Opt,
17251732
"",
17261733
"explain",
17271734
"Provide a detailed explanation of an error message",
1728-
"OPT",
1735+
"<OPT>",
17291736
),
17301737
opt(Stable, Flag, "", "test", "Build a test harness", ""),
1731-
opt(Stable, Opt, "", "target", "Target triple for which the code is compiled", "TARGET"),
1732-
opt(Stable, Multi, "A", "allow", "Set lint allowed", "LINT"),
1733-
opt(Stable, Multi, "W", "warn", "Set lint warnings", "LINT"),
1734-
opt(Stable, Multi, "", "force-warn", "Set lint force-warn", "LINT"),
1735-
opt(Stable, Multi, "D", "deny", "Set lint denied", "LINT"),
1736-
opt(Stable, Multi, "F", "forbid", "Set lint forbidden", "LINT"),
1738+
opt(Stable, Opt, "", "target", "Target triple for which the code is compiled", "<TARGET>"),
1739+
opt(Stable, Multi, "A", "allow", "Set lint allowed", "<LINT>"),
1740+
opt(Stable, Multi, "W", "warn", "Set lint warnings", "<LINT>"),
1741+
opt(Stable, Multi, "", "force-warn", "Set lint force-warn", "<LINT>"),
1742+
opt(Stable, Multi, "D", "deny", "Set lint denied", "<LINT>"),
1743+
opt(Stable, Multi, "F", "forbid", "Set lint forbidden", "<LINT>"),
17371744
opt(
17381745
Stable,
17391746
Multi,
17401747
"",
17411748
"cap-lints",
17421749
"Set the most restrictive lint level. More restrictive lints are capped at this level",
1743-
"LEVEL",
1750+
"<LEVEL>",
17441751
),
1745-
opt(Stable, Multi, "C", "codegen", "Set a codegen option", "OPT[=VALUE]"),
1752+
opt(Stable, Multi, "C", "codegen", "Set a codegen option", "<OPT>[=<VALUE>]"),
17461753
opt(Stable, Flag, "V", "version", "Print version info and exit", ""),
17471754
opt(Stable, Flag, "v", "verbose", "Use verbose output", ""),
17481755
];
@@ -1756,47 +1763,47 @@ pub fn rustc_optgroups() -> Vec<RustcOptGroup> {
17561763
"",
17571764
"extern",
17581765
"Specify where an external rust library is located",
1759-
"NAME[=PATH]",
1766+
"<NAME>[=<PATH>]",
17601767
),
1761-
opt(Stable, Opt, "", "sysroot", "Override the system root", "PATH"),
1762-
opt(Unstable, Multi, "Z", "", "Set unstable / perma-unstable options", "FLAG"),
1768+
opt(Stable, Opt, "", "sysroot", "Override the system root", "<PATH>"),
1769+
opt(Unstable, Multi, "Z", "", "Set unstable / perma-unstable options", "<FLAG>"),
17631770
opt(
17641771
Stable,
17651772
Opt,
17661773
"",
17671774
"error-format",
17681775
"How errors and other messages are produced",
1769-
"human|json|short",
1776+
"<human|json|short>",
17701777
),
1771-
opt(Stable, Multi, "", "json", "Configure the JSON output of the compiler", "CONFIG"),
1778+
opt(Stable, Multi, "", "json", "Configure the JSON output of the compiler", "<CONFIG>"),
17721779
opt(
17731780
Stable,
17741781
Opt,
17751782
"",
17761783
"color",
17771784
"Configure coloring of output:
1778-
auto = colorize, if output goes to a tty (default);
1779-
always = always colorize output;
1780-
never = never colorize output",
1781-
"auto|always|never",
1785+
* auto = colorize, if output goes to a tty (default);
1786+
* always = always colorize output;
1787+
* never = never colorize output",
1788+
"<auto|always|never>",
17821789
),
17831790
opt(
17841791
Stable,
17851792
Opt,
17861793
"",
17871794
"diagnostic-width",
17881795
"Inform rustc of the width of the output so that diagnostics can be truncated to fit",
1789-
"WIDTH",
1796+
"<WIDTH>",
17901797
),
17911798
opt(
17921799
Stable,
17931800
Multi,
17941801
"",
17951802
"remap-path-prefix",
17961803
"Remap source names in all output (compiler messages and output files)",
1797-
"FROM=TO",
1804+
"<FROM>=<TO>",
17981805
),
1799-
opt(Unstable, Multi, "", "env-set", "Inject an environment variable", "VAR=VALUE"),
1806+
opt(Unstable, Multi, "", "env-set", "Inject an environment variable", "<VAR>=<VALUE>"),
18001807
];
18011808
options.extend(verbose_only.into_iter().map(|mut opt| {
18021809
opt.is_verbose_help_only = true;
@@ -2796,7 +2803,7 @@ pub fn make_crate_type_option() -> RustcOptGroup {
27962803
"crate-type",
27972804
"Comma separated list of types of crates
27982805
for the compiler to emit",
2799-
"[bin|lib|rlib|dylib|cdylib|staticlib|proc-macro]",
2806+
"<bin|lib|rlib|dylib|cdylib|staticlib|proc-macro>",
28002807
)
28012808
}
28022809

‎compiler/rustc_span/src/edition.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ pub const ALL_EDITIONS: &[Edition] = &[
4545
Edition::EditionFuture,
4646
];
4747

48-
pub const EDITION_NAME_LIST: &str = "2015|2018|2021|2024";
48+
pub const EDITION_NAME_LIST: &str = "<2015|2018|2021|2024|future>";
4949

5050
pub const DEFAULT_EDITION: Edition = Edition::Edition2015;
5151

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

+12-11
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,23 @@
1-
@@ -63,10 +63,27 @@
1+
@@ -65,10 +65,28 @@
22
Set a codegen option
33
-V, --version Print version info and exit
44
-v, --verbose Use verbose output
5-
+ --extern NAME[=PATH]
5+
+ --extern <NAME>[=<PATH>]
66
+ Specify where an external rust library is located
7-
+ --sysroot PATH Override the system root
8-
+ --error-format human|json|short
7+
+ --sysroot <PATH>
8+
+ Override the system root
9+
+ --error-format <human|json|short>
910
+ How errors and other messages are produced
10-
+ --json CONFIG Configure the JSON output of the compiler
11-
+ --color auto|always|never
11+
+ --json <CONFIG> Configure the JSON output of the compiler
12+
+ --color <auto|always|never>
1213
+ Configure coloring of output:
13-
+ auto = colorize, if output goes to a tty (default);
14-
+ always = always colorize output;
15-
+ never = never colorize output
16-
+ --diagnostic-width WIDTH
14+
+ * auto = colorize, if output goes to a tty (default);
15+
+ * always = always colorize output;
16+
+ * never = never colorize output
17+
+ --diagnostic-width <WIDTH>
1718
+ Inform rustc of the width of the output so that
1819
+ diagnostics can be truncated to fit
19-
+ --remap-path-prefix FROM=TO
20+
+ --remap-path-prefix <FROM>=<TO>
2021
+ Remap source names in all output (compiler messages
2122
+ and output files)
2223
+ @path Read newline separated options from `path`

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

+39-36
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,32 @@ Usage: rustc [OPTIONS] INPUT
22

33
Options:
44
-h, --help Display this message
5-
--cfg SPEC Configure the compilation environment.
6-
SPEC supports the syntax `NAME[="VALUE"]`.
7-
--check-cfg SPEC
5+
--cfg <SPEC> Configure the compilation environment.
6+
SPEC supports the syntax `<NAME>[="<VALUE>"]`.
7+
--check-cfg <SPEC>
88
Provide list of expected cfgs for checking
9-
-L [KIND=]PATH Add a directory to the library search path. The
10-
optional KIND can be one of dependency, crate, native,
11-
framework, or all (the default).
12-
-l [KIND[:MODIFIERS]=]NAME[:RENAME]
9+
-L [<KIND>=]<PATH> Add a directory to the library search path. The
10+
optional KIND can be one of
11+
<dependency|crate|native|framework|all> (default:
12+
all).
13+
-l [<KIND>[:<MODIFIERS>]=]<NAME>[:<RENAME>]
1314
Link the generated crate(s) to the specified native
1415
library NAME. The optional KIND can be one of
15-
static, framework, or dylib (the default).
16+
<static|framework|dylib> (default: dylib).
1617
Optional comma separated MODIFIERS
17-
(bundle|verbatim|whole-archive|as-needed)
18+
<bundle|verbatim|whole-archive|as-needed>
1819
may be specified each with a prefix of either '+' to
1920
enable or '-' to disable.
20-
--crate-type [bin|lib|rlib|dylib|cdylib|staticlib|proc-macro]
21+
--crate-type <bin|lib|rlib|dylib|cdylib|staticlib|proc-macro>
2122
Comma separated list of types of crates
2223
for the compiler to emit
23-
--crate-name NAME
24+
--crate-name <NAME>
2425
Specify the name of the crate being built
25-
--edition 2015|2018|2021|2024
26+
--edition <2015|2018|2021|2024|future>
2627
Specify which edition of the compiler to use when
2728
compiling code. The default is 2015 and the latest
2829
stable edition is 2024.
29-
--emit TYPE[=FILE]
30+
--emit <TYPE>[=<FILE>]
3031
Comma separated list of types of output for the
3132
compiler to emit.
3233
Each TYPE has the default FILE name:
@@ -39,45 +40,47 @@ Options:
3940
* mir - CRATE_NAME.mir
4041
* obj - CRATE_NAME.o
4142
* thin-link-bitcode - CRATE_NAME.indexing.o
42-
--print INFO[=FILE]
43+
--print <INFO>[=<FILE>]
4344
Compiler information to print on stdout (or to a file)
4445
INFO may be one of
45-
(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).
46+
<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>.
4647
-g Equivalent to -C debuginfo=2
4748
-O Equivalent to -C opt-level=3
48-
-o FILENAME Write output to <filename>
49-
--out-dir DIR Write output to compiler-chosen filename in <dir>
50-
--explain OPT Provide a detailed explanation of an error message
49+
-o <FILENAME> Write output to FILENAME
50+
--out-dir <DIR> Write output to compiler-chosen filename in DIR
51+
--explain <OPT> Provide a detailed explanation of an error message
5152
--test Build a test harness
52-
--target TARGET Target triple for which the code is compiled
53-
-A, --allow LINT Set lint allowed
54-
-W, --warn LINT Set lint warnings
55-
--force-warn LINT
53+
--target <TARGET>
54+
Target triple for which the code is compiled
55+
-A, --allow <LINT> Set lint allowed
56+
-W, --warn <LINT> Set lint warnings
57+
--force-warn <LINT>
5658
Set lint force-warn
57-
-D, --deny LINT Set lint denied
58-
-F, --forbid LINT Set lint forbidden
59-
--cap-lints LEVEL
59+
-D, --deny <LINT> Set lint denied
60+
-F, --forbid <LINT> Set lint forbidden
61+
--cap-lints <LEVEL>
6062
Set the most restrictive lint level. More restrictive
6163
lints are capped at this level
62-
-C, --codegen OPT[=VALUE]
64+
-C, --codegen <OPT>[=<VALUE>]
6365
Set a codegen option
6466
-V, --version Print version info and exit
6567
-v, --verbose Use verbose output
66-
--extern NAME[=PATH]
68+
--extern <NAME>[=<PATH>]
6769
Specify where an external rust library is located
68-
--sysroot PATH Override the system root
69-
--error-format human|json|short
70+
--sysroot <PATH>
71+
Override the system root
72+
--error-format <human|json|short>
7073
How errors and other messages are produced
71-
--json CONFIG Configure the JSON output of the compiler
72-
--color auto|always|never
74+
--json <CONFIG> Configure the JSON output of the compiler
75+
--color <auto|always|never>
7376
Configure coloring of output:
74-
auto = colorize, if output goes to a tty (default);
75-
always = always colorize output;
76-
never = never colorize output
77-
--diagnostic-width WIDTH
77+
* auto = colorize, if output goes to a tty (default);
78+
* always = always colorize output;
79+
* never = never colorize output
80+
--diagnostic-width <WIDTH>
7881
Inform rustc of the width of the output so that
7982
diagnostics can be truncated to fit
80-
--remap-path-prefix FROM=TO
83+
--remap-path-prefix <FROM>=<TO>
8184
Remap source names in all output (compiler messages
8285
and output files)
8386
@path Read newline separated options from `path`

0 commit comments

Comments
 (0)