mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add some guidelines on the CLI.

This commit is contained in:
Eric Huss 2020-05-26 18:21:46 -07:00 committed by Who? Me?!
parent 6d5e0740f5
commit fe96650d1a
2 changed files with 30 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/SUMMARY.md
View File

@ -29,6 +29,7 @@
- [Emitting Errors and other Diagnostics](diagnostics.md)
- [`LintStore`](./diagnostics/lintstore.md)
- [Diagnostic Codes](./diagnostics/diagnostic-codes.md)
- [Command-line arguments](./cli.md)
- [ICE-breaker teams](ice-breaker/about.md)
- ["Cleanup Crew" ICE-breakers](ice-breaker/cleanup-crew.md)
- [LLVM ICE-breakers](ice-breaker/llvm.md)

29
src/cli.md Normal file
View File

@ -0,0 +1,29 @@
# Command-line Arguments
Command-line flags are documented in the [rustc book][cli-docs]. All *stable*
flags should be documented there. Unstable flags should be documented in the
[unstable book].
## Guidelines
- Flags should be orthogonal to each other. For example, if we'd have a
json-emitting variant of multiple actions `foo` and `bar`, an additional
`--json` flag is better than adding `--foo-json` and `--bar-json`.
- Avoid flags with the `no-` prefix. Instead, use the [`parse_bool`] function,
such as `-C embed-bitcode=no`.
- Consider the behavior if the flag is passed multiple times. In some
situations, the values should be accumulated (in order!). In other
situations, subsequence flags should override previous flags (for example,
the lint-level flags). And some flags (like `-o`) should generate an error
if it is too ambiguous what multiple flags would mean.
- Always give options a long descriptive name, if only for more understandable
compiler scripts.
- The `--verbose` flag is for adding verbose information to `rustc` output
when not compiling a program. For example, using it with the `--version`
flag gives information about the hashes of the code.
- Experimental flags and options must be guarded behind the `-Z
unstable-options` flag.
[cli-docs]: https://doc.rust-lang.org/rustc/command-line-arguments.html
[unstable book]: https://doc.rust-lang.org/nightly/unstable-book/
[`parse_bool`]: https://github.com/rust-lang/rust/blob/e5335592e78354e33d798d20c04bcd677c1df62d/src/librustc_session/options.rs#L307-L313