From a19e2c5efdbe6794cfab1bfbe80042fdd47a806e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 26 May 2020 18:21:46 -0700 Subject: [PATCH 1/3] Add some guidelines on the CLI. --- src/SUMMARY.md | 1 + src/cli.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 30 insertions(+) create mode 100644 src/cli.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 94768bc83..19afb765b 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -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) diff --git a/src/cli.md b/src/cli.md new file mode 100644 index 000000000..0e04b3818 --- /dev/null +++ b/src/cli.md @@ -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 From 9e41cb41ab6263c38d4c8d0fd043d95321811301 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 27 May 2020 09:21:23 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Chris Simpkins Co-authored-by: Who? Me?! --- src/cli.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cli.md b/src/cli.md index 0e04b3818..bbb7bae24 100644 --- a/src/cli.md +++ b/src/cli.md @@ -13,14 +13,14 @@ flags should be documented there. Unstable flags should be documented in the 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, + situations, subsequent 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. + flag gives information about the hashes of the compiler code. - Experimental flags and options must be guarded behind the `-Z unstable-options` flag. From 5c06e781de45354ada35976cc567870ecddf8e3a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 27 May 2020 09:24:53 -0700 Subject: [PATCH 3/3] Move CLI to part 3. --- src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 19afb765b..0a9dc7773 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -29,7 +29,6 @@ - [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) @@ -48,6 +47,7 @@ - [Parallel Compilation](./parallel-rustc.md) - [Part 3: Source Code Representations](./part-3-intro.md) + - [Command-line arguments](./cli.md) - [The Rustc Driver and Interface](./rustc-driver.md) - [Rustdoc](./rustdoc.md) - [Ex: Type checking through `rustc_interface`](./rustc-driver-interacting-with-the-ast.md)