Skip to content

Consider unifying how rustc cli flag values are presented #140102

Open
@jieyouxu

Description

@jieyouxu
Member

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)

Activity

added
needs-triageThis issue may need triage. Remove it if it has been sufficiently triaged.
on Apr 21, 2025
added
C-enhancementCategory: An issue proposing an enhancement or a PR with one.
A-diagnosticsArea: Messages for errors, warnings, and lints
T-compilerRelevant to the compiler team, which will review and decide on the PR/issue.
A-CLIArea: Command-line interface (CLI) to the compiler
and removed
needs-triageThis issue may need triage. Remove it if it has been sufficiently triaged.
on Apr 21, 2025
clubby789

clubby789 commented on Apr 21, 2025

@clubby789
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

xizheyin commented on Apr 21, 2025

@xizheyin
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

xizheyin commented on Apr 21, 2025

@xizheyin
Contributor

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

That is reasonable to me.

added a commit that references this issue on Apr 25, 2025

Rollup merge of rust-lang#140152 - xizheyin:issue-140102, r=jieyouxu

eb225e3
added a commit that references this issue on Apr 25, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-CLIArea: Command-line interface (CLI) to the compilerA-diagnosticsArea: Messages for errors, warnings, and lintsC-enhancementCategory: An issue proposing an enhancement or a PR with one.T-compilerRelevant to the compiler team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @clubby789@jieyouxu@rustbot@xizheyin

        Issue actions

          Consider unifying how rustc cli flag values are presented · Issue #140102 · rust-lang/rust