Skip to content

Commit 14e7edd

Browse files
LingManLingMan
committed
clap: Show documentation of RegressOn variants in the --help output
Easiest achieved by renaming the variants to match their CLI names and then deriving ValueEnum.
1 parent 5c4c17b commit 14e7edd

File tree

3 files changed

+154
-109
lines changed

3 files changed

+154
-109
lines changed

‎src/main.rs

Lines changed: 43 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ use std::process;
1414
use std::str::FromStr;
1515

1616
use chrono::{Date, Duration, NaiveDate, Utc};
17-
use clap::{ArgAction, Parser, ValueEnum, builder::PossibleValue};
17+
use clap::{ArgAction, Parser, ValueEnum};
1818
use colored::Colorize;
1919
use anyhow::{bail, Context};
2020
use log::debug;
@@ -86,7 +86,7 @@ struct Opts {
8686
long,
8787
help = "Custom regression definition",
8888
value_enum,
89-
default_value_t = RegressOn::ErrorStatus,
89+
default_value_t = RegressOn::Error,
9090
)]
9191
regress: RegressOn,
9292

@@ -272,19 +272,18 @@ impl Config {
272272

273273
let input = (self.args.regress, status.success());
274274
let result = match input {
275-
(RegressOn::ErrorStatus, true) | (RegressOn::SuccessStatus, false) => {
276-
TestOutcome::Baseline
275+
(RegressOn::Error, true) | (RegressOn::Success, false) => TestOutcome::Baseline,
276+
(RegressOn::Error, false) | (RegressOn::Success | RegressOn::NonError, true) => {
277+
TestOutcome::Regressed
277278
}
278-
(RegressOn::ErrorStatus, false)
279-
| (RegressOn::SuccessStatus | RegressOn::NonCleanError, true) => TestOutcome::Regressed,
280-
(RegressOn::IceAlone, _) | (RegressOn::NonCleanError, false) => {
279+
(RegressOn::Ice, _) | (RegressOn::NonError, false) => {
281280
if saw_ice {
282281
TestOutcome::Regressed
283282
} else {
284283
TestOutcome::Baseline
285284
}
286285
}
287-
(RegressOn::NotIce, _) => {
286+
(RegressOn::NonIce, _) => {
288287
if saw_ice {
289288
TestOutcome::Baseline
290289
} else {
@@ -315,87 +314,52 @@ impl Access {
315314
}
316315
}
317316

318-
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
317+
#[derive(Copy, Clone, PartialEq, Eq, Debug, ValueEnum)]
319318
/// Customize what is treated as regression.
320319
enum RegressOn {
321-
/// `ErrorStatus`: Marks test outcome as `Regressed` if and only if
322-
/// the `rustc` process reports a non-success status. This corresponds to
323-
/// when `rustc` has an internal compiler error (ICE) or when it detects an
324-
/// error in the input program.
325-
///
320+
/// Marks test outcome as `Regressed` if and only if the `rustc`
321+
/// process reports a non-success status. This corresponds to when `rustc`
322+
/// has an internal compiler error (ICE) or when it detects an error in the
323+
/// input program.
326324
/// This covers the most common use case for `cargo-bisect-rustc` and is
327325
/// thus the default setting.
328-
///
329-
/// You explicitly opt into this seting via `--regress=error`.
330-
ErrorStatus,
331-
332-
/// `SuccessStatus`: Marks test outcome as `Regressed` if and only
333-
/// if the `rustc` process reports a success status. This corresponds to
334-
/// when `rustc` believes it has successfully compiled the program. This
335-
/// covers the use case for when you want to bisect to see when a bug was
336-
/// fixed.
337-
///
338-
/// You explicitly opt into this seting via `--regress=success`.
339-
SuccessStatus,
340-
341-
/// `IceAlone`: Marks test outcome as `Regressed` if and only if
342-
/// the `rustc` process issues a diagnostic indicating that an internal
326+
Error,
327+
328+
/// Marks test outcome as `Regressed` if and only if the `rustc`
329+
/// process reports a success status. This corresponds to when `rustc`
330+
/// believes it has successfully compiled the program. This covers the use
331+
/// case for when you want to bisect to see when a bug was fixed.
332+
Success,
333+
334+
/// `Ice`: Marks test outcome as `Regressed` if and only if the `rustc`
335+
/// process issues a diagnostic indicating that an internal compiler error
336+
/// (ICE) occurred. This covers the use case for when you want to bisect to
337+
/// see when an ICE was introduced pon a codebase that is meant to produce
338+
/// a clean error.
339+
Ice,
340+
341+
/// `NonIce`: Marks test outcome as `Regressed` if and only if the `rustc`
342+
/// process does not issue a diagnostic indicating that an internal
343343
/// compiler error (ICE) occurred. This covers the use case for when you
344-
/// want to bisect to see when an ICE was introduced pon a codebase that is
345-
/// meant to produce a clean error.
346-
///
347-
/// You explicitly opt into this seting via `--regress=ice`.
348-
IceAlone,
349-
350-
/// `NotIce`: Marks test outcome as `Regressed` if and only if
351-
/// the `rustc` process does not issue a diagnostic indicating that an
352-
/// internal compiler error (ICE) occurred. This covers the use case for
353-
/// when you want to bisect to see when an ICE was fixed.
354-
///
355-
/// You explicitly opt into this setting via `--regress=non-ice`
356-
NotIce,
357-
358-
/// `NonCleanError`: Marks test outcome as `Baseline` if and only
359-
/// if the `rustc` process reports error status and does not issue any
360-
/// diagnostic indicating that an internal compiler error (ICE) occurred.
361-
/// This is the use case if the regression is a case where an ill-formed
362-
/// program has stopped being properly rejected by the compiler.
363-
///
364-
/// (The main difference between this case and `SuccessStatus` is
365-
/// the handling of ICE: `SuccessStatus` assumes that ICE should be
366-
/// considered baseline; `NonCleanError` assumes ICE should be
367-
/// considered a sign of a regression.)
368-
///
369-
/// You explicitly opt into this seting via `--regress=non-error`.
370-
NonCleanError,
371-
}
372-
373-
impl ValueEnum for RegressOn {
374-
fn value_variants<'a>() -> &'a [Self] {
375-
&[
376-
Self::ErrorStatus,
377-
Self::SuccessStatus,
378-
Self::IceAlone,
379-
Self::NotIce,
380-
Self::NonCleanError,
381-
]
382-
}
383-
fn to_possible_value(&self) -> Option<PossibleValue> {
384-
Some(PossibleValue::new(match self {
385-
Self::ErrorStatus => "error",
386-
Self::NonCleanError => "non-error",
387-
Self::IceAlone => "ice",
388-
Self::NotIce => "non-ice",
389-
Self::SuccessStatus => "success",
390-
}))
391-
}
344+
/// want to bisect to see when an ICE was fixed.
345+
NonIce,
346+
347+
/// `NonError`: Marks test outcome as `Baseline` if and only if the `rustc`
348+
/// process reports error status and does not issue any diagnostic
349+
/// indicating that an internal compiler error (ICE) occurred. This is the
350+
/// use case if the regression is a case where an ill-formed program has
351+
/// stopped being properly rejected by the compiler.
352+
/// (The main difference between this case and `Success` is the handling of
353+
/// ICE: `Success` assumes that ICE should be considered baseline;
354+
/// `NonError` assumes ICE should be considered a sign of a regression.)
355+
NonError,
392356
}
393357

394358
impl RegressOn {
395359
fn must_process_stderr(self) -> bool {
396360
match self {
397-
RegressOn::ErrorStatus | RegressOn::SuccessStatus => false,
398-
RegressOn::NonCleanError | RegressOn::IceAlone | RegressOn::NotIce => true,
361+
RegressOn::Error | RegressOn::Success => false,
362+
RegressOn::NonError | RegressOn::Ice | RegressOn::NonIce => true,
399363
}
400364
}
401365
}

‎tests/cmd/h.stdout

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Options:
1414
--end <END> Right bound for search (*with* regression). You can use a date
1515
(YYYY-MM-DD), git tag name (e.g. 1.58.0) or git commit SHA.
1616
--force-install Force installation over existing artifacts
17-
-h, --help Print help information
17+
-h, --help Print help information (use `--help` for more detail)
1818
--host <HOST> Host triple for the compiler [default: x86_64-unknown-linux-gnu]
1919
--install <INSTALL> Install the given artifact
2020
--preserve Preserve the downloaded artifacts

‎tests/cmd/help.stdout

Lines changed: 110 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,37 +3,118 @@ Bisects rustc toolchains with rustup
33
Usage: cargo bisect-rustc [OPTIONS] [-- <COMMAND_ARGS>...]
44

55
Arguments:
6-
[COMMAND_ARGS]... Arguments to pass to cargo or the file specified by --script during tests
6+
[COMMAND_ARGS]...
7+
Arguments to pass to cargo or the file specified by --script during tests
78

89
Options:
9-
-a, --alt Download the alt build instead of normal build
10-
--access <ACCESS> How to access Rust git repository [default: checkout] [possible
11-
values: checkout, github]
12-
--by-commit Bisect via commit artifacts
13-
-c, --component <COMPONENTS> additional components to install
14-
--end <END> Right bound for search (*with* regression). You can use a date
15-
(YYYY-MM-DD), git tag name (e.g. 1.58.0) or git commit SHA.
16-
--force-install Force installation over existing artifacts
17-
-h, --help Print help information
18-
--host <HOST> Host triple for the compiler [default: x86_64-unknown-linux-gnu]
19-
--install <INSTALL> Install the given artifact
20-
--preserve Preserve the downloaded artifacts
21-
--preserve-target Preserve the target directory used for builds
22-
--prompt Manually evaluate for regression with prompts
23-
--regress <REGRESS> Custom regression definition [default: error] [possible values:
24-
error, success, ice, non-ice, non-error]
25-
--script <SCRIPT> Script replacement for `cargo build` command
26-
--start <START> Left bound for search (*without* regression). You can use a date
27-
(YYYY-MM-DD), git tag name (e.g. 1.58.0) or git commit SHA.
28-
-t, --timeout <TIMEOUT> Assume failure after specified number of seconds (for bisecting
29-
hangs)
30-
--target <TARGET> Cross-compilation target platform
31-
--test-dir <TEST_DIR> Root directory for tests [default: .]
32-
-v, --verbose...
33-
-V, --version Print version information
34-
--with-dev Download rustc-dev [default: no download]
35-
--with-src Download rust-src [default: no download]
36-
--without-cargo Do not install cargo [default: install cargo]
10+
-a, --alt
11+
Download the alt build instead of normal build
12+
13+
--access <ACCESS>
14+
How to access Rust git repository
15+
16+
[default: checkout]
17+
[possible values: checkout, github]
18+
19+
--by-commit
20+
Bisect via commit artifacts
21+
22+
-c, --component <COMPONENTS>
23+
additional components to install
24+
25+
--end <END>
26+
Right bound for search (*with* regression). You can use a date (YYYY-MM-DD), git tag name
27+
(e.g. 1.58.0) or git commit SHA.
28+
29+
--force-install
30+
Force installation over existing artifacts
31+
32+
-h, --help
33+
Print help information (use `-h` for a summary)
34+
35+
--host <HOST>
36+
Host triple for the compiler
37+
38+
[default: x86_64-unknown-linux-gnu]
39+
40+
--install <INSTALL>
41+
Install the given artifact
42+
43+
--preserve
44+
Preserve the downloaded artifacts
45+
46+
--preserve-target
47+
Preserve the target directory used for builds
48+
49+
--prompt
50+
Manually evaluate for regression with prompts
51+
52+
--regress <REGRESS>
53+
Custom regression definition
54+
55+
[default: error]
56+
57+
Possible values:
58+
- error:
59+
Marks test outcome as `Regressed` if and only if the `rustc` process reports a
60+
non-success status. This corresponds to when `rustc` has an internal compiler error
61+
(ICE) or when it detects an error in the input program. This covers the most common use
62+
case for `cargo-bisect-rustc` and is thus the default setting
63+
- success:
64+
Marks test outcome as `Regressed` if and only if the `rustc` process reports a success
65+
status. This corresponds to when `rustc` believes it has successfully compiled the
66+
program. This covers the use case for when you want to bisect to see when a bug was
67+
fixed
68+
- ice:
69+
`Ice`: Marks test outcome as `Regressed` if and only if the `rustc` process issues a
70+
diagnostic indicating that an internal compiler error (ICE) occurred. This covers the
71+
use case for when you want to bisect to see when an ICE was introduced pon a codebase
72+
that is meant to produce a clean error
73+
- non-ice:
74+
`NonIce`: Marks test outcome as `Regressed` if and only if the `rustc` process does not
75+
issue a diagnostic indicating that an internal compiler error (ICE) occurred. This
76+
covers the use case for when you want to bisect to see when an ICE was fixed
77+
- non-error:
78+
`NonError`: Marks test outcome as `Baseline` if and only if the `rustc` process reports
79+
error status and does not issue any diagnostic indicating that an internal compiler
80+
error (ICE) occurred. This is the use case if the regression is a case where an
81+
ill-formed program has stopped being properly rejected by the compiler. (The main
82+
difference between this case and `Success` is the handling of ICE: `Success` assumes
83+
that ICE should be considered baseline; `NonError` assumes ICE should be considered a
84+
sign of a regression.)
85+
86+
--script <SCRIPT>
87+
Script replacement for `cargo build` command
88+
89+
--start <START>
90+
Left bound for search (*without* regression). You can use a date (YYYY-MM-DD), git tag
91+
name (e.g. 1.58.0) or git commit SHA.
92+
93+
-t, --timeout <TIMEOUT>
94+
Assume failure after specified number of seconds (for bisecting hangs)
95+
96+
--target <TARGET>
97+
Cross-compilation target platform
98+
99+
--test-dir <TEST_DIR>
100+
Root directory for tests
101+
102+
[default: .]
103+
104+
-v, --verbose...
105+
106+
107+
-V, --version
108+
Print version information
109+
110+
--with-dev
111+
Download rustc-dev [default: no download]
112+
113+
--with-src
114+
Download rust-src [default: no download]
115+
116+
--without-cargo
117+
Do not install cargo [default: install cargo]
37118

38119
Examples:
39120
Run a fully automatic nightly bisect doing `cargo check`:

0 commit comments

Comments
 (0)