Skip to content

Consider unifying how rustc cli flag values are presented #140102

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

Jump to bottom
Open
jieyouxu opened this issue Apr 21, 2025 · 3 comments
Open

Consider unifying how rustc cli flag values are presented #140102

jieyouxu opened this issue Apr 21, 2025 · 3 comments
Labels
A-CLI Area: Command-line interface (CLI) to the compiler A-diagnostics Area: Messages for errors, warnings, and lints C-enhancement Category: An issue proposing an enhancement or a PR with one. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.

Comments

@jieyouxu
Copy link
Member

jieyouxu commented Apr 21, 2025 •
edited by clubby789
Loading

Not necessarily for this PR, but I think we should settle on a consistent way of listing out sets of alternatives like this across our options. We currently have

  • Exhaustively listed in command (--crate-type [bin|lib|rlib|...])
  • Listed in help in parentheses (INFO may be one of (all-target-specs-json|calling-conventions|...))
  • Listed in help as a textual list (The KIND can be one of dependency, crate, native, framework, or all (the default).)
    With this being a fourth potential layout

Originally posted by @clubby789 in #140077 (comment)
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Apr 21, 2025
@jieyouxu jieyouxu added C-enhancement Category: An issue proposing an enhancement or a PR with one. A-diagnostics Area: Messages for errors, warnings, and lints T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. A-CLI Area: Command-line interface (CLI) to the compiler and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Apr 21, 2025
@jieyouxu jieyouxu mentioned this issue Apr 21, 2025
Merged
@clubby789
Copy link
Contributor

For options where output is going to be lengthier (emit, print), perhaps we could explain only the syntax, and leave a link to the relevant reference entry? Alternatively, we could gate full explanations behind --verbose (not sure if this would require refactoring?)

@xizheyin
Copy link
Contributor

There are indeed some inconsistency.

I researched some command line help messages and found the following rules:

  1. Often, pointed brackets<option1|option2|...> indicate required parameters.
  2. [option1|option2|...] is a common way of representing options which is not nessary.
  3. * item - description -Branch list with star is the list of options for which a detailed description applies

So I think there needs to be many places in the current help message where changing [] and () to <> would be clearer. (This also avoids []lists conflicting with TYPE[=FILE])

Reference:

  1. cargo help:
Rust's package manager

Usage: cargo [+toolchain] [OPTIONS] [COMMAND]
       cargo [+toolchain] [OPTIONS] -Zscript <MANIFEST_RS> [ARGS]...

Options:
  -V, --version                  Print version info and exit
      --list                     List installed commands
      --explain <CODE>           Provide a detailed explanation of a rustc error message
  -v, --verbose...               Use verbose output (-vv very verbose/build.rs output)
  -q, --quiet                    Do not print cargo log messages
      --color <WHEN>             Coloring: auto, always, never
  -C <DIRECTORY>                 Change to DIRECTORY before doing anything (nightly-only)
      --locked                   Assert that `Cargo.lock` will remain unchanged
      --offline                  Run without accessing the network
      --frozen                   Equivalent to specifying both --locked and --offline
      --config <KEY=VALUE|PATH>  Override a configuration value
  -Z <FLAG>                      Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
  -h, --help                     Print help
  1. gcc help: https://man7.org/linux/man-pages/man1/gcc.1.html
  2. curl help: https://curl.se/docs/manpage.html

@xizheyin
Copy link
Contributor

Alternatively, we could gate full explanations behind --verbose (not sure if this would require refactoring?)

That is reasonable to me.

@xizheyin xizheyin mentioned this issue Apr 22, 2025
Merged
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Apr 25, 2025
@matthiaskrgr
Rollup merge of rust-lang#140152 - xizheyin:issue-140102, r=jieyouxu
eb225e3 
Unify the format of rustc cli flags

As mentioned in rust-lang#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
```
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Apr 25, 2025
@rust-timer
Unrolled build for rust-lang#140152
1803f09 
Rollup merge of rust-lang#140152 - xizheyin:issue-140102, r=jieyouxu

Unify the format of rustc cli flags

As mentioned in rust-lang#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
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-CLI Area: Command-line interface (CLI) to the compiler A-diagnostics Area: Messages for errors, warnings, and lints C-enhancement Category: An issue proposing an enhancement or a PR with one. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@clubby789 @jieyouxu @rustbot @xizheyin