[rustc.git] / src / doc / rustc-dev-guide / src / cli.md

# 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].

See the [forge guide for new options] for details on the *procedure* for
adding a new command-line argument.

## 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, 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. For example, using it with the `--version`
  flag gives information about the hashes of the compiler 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
[forge guide for new options]: https://forge.rust-lang.org/compiler/new_option.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
Commit	Line	Data
6a06907d XL	1	# Command-line Arguments
	2
	3	Command-line flags are documented in the [rustc book][cli-docs]. All stable
	4	flags should be documented there. Unstable flags should be documented in the
	5	[unstable book].
	6
	7	See the [forge guide for new options] for details on the procedure for
	8	adding a new command-line argument.
	9
	10	## Guidelines
	11
	12	- Flags should be orthogonal to each other. For example, if we'd have a
	13	json-emitting variant of multiple actions `foo` and `bar`, an additional
	14	`--json` flag is better than adding `--foo-json` and `--bar-json`.
	15	- Avoid flags with the `no-` prefix. Instead, use the [`parse_bool`] function,
	16	such as `-C embed-bitcode=no`.
	17	- Consider the behavior if the flag is passed multiple times. In some
	18	situations, the values should be accumulated (in order!). In other
	19	situations, subsequent flags should override previous flags (for example,
	20	the lint-level flags). And some flags (like `-o`) should generate an error
	21	if it is too ambiguous what multiple flags would mean.
	22	- Always give options a long descriptive name, if only for more understandable
	23	compiler scripts.
	24	- The `--verbose` flag is for adding verbose information to `rustc`
	25	output. For example, using it with the `--version`
	26	flag gives information about the hashes of the compiler code.
	27	- Experimental flags and options must be guarded behind the `-Z
	28	unstable-options` flag.
	29
	30	[cli-docs]: https://doc.rust-lang.org/rustc/command-line-arguments.html
	31	[forge guide for new options]: https://forge.rust-lang.org/compiler/new_option.html
	32	[unstable book]: https://doc.rust-lang.org/nightly/unstable-book/
	33	[`parse_bool`]: https://github.com/rust-lang/rust/blob/e5335592e78354e33d798d20c04bcd677c1df62d/src/librustc_session/options.rs#L307-L313