Unify the format of rustc cli flags

[xizheyin]

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:

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

[rustbot]

r? @jieyouxu

rustbot has assigned @jieyouxu.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

This PR modifies run-make tests.

cc @jieyouxu

[jieyouxu]

I'll review this after #140077 merges. Afterwards, can you double-check if the rustc book and the unstable book has places that still use the previous styles? Don't need to rush to change those yet, I haven't looked closely if the proposed scheme

<param>: Indicates a required parameter
[param]: Indicates an optional parameter
|: Indicates a mutually exclusive option

has any conflicts or whatever.

[jieyouxu]

Please flip this PR back to ready once #140077 merges.

@rustbot blocked (#140077)

[jieyouxu]

Just kidding, it just merged.
@rustbot review

[xizheyin]

haha, it's a bit of a coincidence. I will resolve the conflicts.

[xizheyin]

@rustbot author

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[xizheyin]

I resolved the conflicts, and checked through the rustc book and the unstable book.

There are two flags in rustc book following the old styles(if I didn't ignore any places):

1. https://doc.rust-lang.org/rustc/command-line-arguments.html#-l-link-the-generated-crate-to-a-native-library
2. https://doc.rust-lang.org/rustc/command-line-arguments.html#--extern-specify-where-an-external-library-is-located

Flags in unstable book are almostly in line with this spec, such as 1 and 2. They are not presented as the HELP style, while in the style presenting some example, such as -Z patchable-function-entry=total_nops,prefix_nops.

@rustbot ready

[jieyouxu]

Thanks, I think this is a nice consistency improvement. One comment nit.

[jieyouxu]

@rustbot author

[xizheyin]

No problem, I added doc comment.
@rustbot ready

[jieyouxu]

Thanks

[jieyouxu]

@bors r+ rollup

[bors]

📌 Commit 999b906 has been approved by jieyouxu

It is now in the queue for this repository.