Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -356,7 +356,7 @@ Windows. The Vulkan driver version is not shown.
### Diagnose and fix

```
rocm diagnose [--symptom TEXT] [--top N] [--json] [--distro [NAME] | --report [--send]]
rocm diagnose [--symptom TEXT | --symptom-file PATH] [--top N] [--json] [--distro [NAME] | --report [--send]]
rocm diagnose --model <model> [--context-size N] [--kv-cache-type f16|q8_0|q4_0] [--json]
rocm fix [<fix-id>] [--yes] [--dry-run] [--device-index N] [--json]
```
Expand All @@ -373,7 +373,38 @@ position.

`rocm diagnose` takes these flags:

- `--symptom` takes raw error text to sharpen keyword scoring.
- `--symptom` takes raw error text to sharpen keyword scoring. Your shell
reads that text first: quotes, `$(...)` and a leading `-` in a pasted error
can be changed, run, or taken as a flag.
- `--symptom-file PATH` reads the same text from a file instead, or from
standard input when PATH is `-`, so no quoting is needed. It cannot be
combined with `--symptom`. The text that arrives is matched as `--symptom`
would match it, minus one trailing line break. A UTF-8 byte-order mark is
dropped and a UTF-16 file with a byte-order mark (what Windows PowerShell's
`>` writes) is decoded; anything else must be UTF-8. A file that cannot be
read, input that is not text, or input larger than 16 MiB is a usage error
(exit code 2). With nothing piped in, paste the error at the terminal and
end it with Ctrl-D at the start of a line (Ctrl-Z then Enter on Windows).

```bash
# bash (Linux, WSL): the quoted 'EOF' keeps the shell out of the paste
rocm diagnose --symptom-file - <<'EOF'
<paste the error here>
EOF
```

```powershell
# PowerShell: save the clipboard to a file first. Windows PowerShell 5.1
# pipes text to a program as ASCII, so `Get-Clipboard | rocm ...` would
# turn every non-ASCII character in the error into "?".
Get-Clipboard -Raw > error.txt
rocm diagnose --symptom-file error.txt
```

```bat
:: cmd.exe: save the error to a file first
rocm diagnose --symptom-file error.txt
```
- On Windows, `diagnose` also checks the age of the Visual C++ runtime, not
only whether it is there. The runtime in `System32` must be 14.40 or newer
(`fix-21-msvc-redist-outdated`). Programs built with a recent toolset, such
Expand Down
48 changes: 47 additions & 1 deletion apps/rocm/src/advised_commands.rs
Original file line number Diff line number Diff line change
Expand Up @@ -640,6 +640,13 @@ fn split_shell_list(text: &str) -> Vec<String> {
}
match ch {
'"' | '\'' => quote = Some(ch),
// `<<` starts a heredoc, a redirection, not a `<placeholder>`:
// taken whole, so neither `<` opens one.
'<' if next == Some('<') => {
current.push_str("<<");
index += 2;
continue;
}
// `<` opens a placeholder only at a word start and before a
// non-space: ` < file` is a redirection.
'<' if at_word_start && next.is_some_and(|c| !c.is_whitespace()) => closers.push('>'),
Expand Down Expand Up @@ -677,7 +684,7 @@ pub(crate) fn command_parts(raw: &str) -> Vec<String> {
}
let mut command = command.to_owned();
for marker in [
" >> ", " > ", " < ", " 2>", " (", " —", " –", " → ", " before ", " then ",
" >> ", " > ", " <<", " < ", " 2>", " (", " —", " –", " → ", " before ", " then ",
] {
if let Some(position) = command.find(marker) {
command.truncate(position);
Expand Down Expand Up @@ -2109,6 +2116,45 @@ fn every_command_in_a_shell_list_is_checked() {
);
}

/// A heredoc is a redirection like ` < file`: `rocm diagnose --symptom-file -
/// <<'EOF'` hands the command a paste on standard input, so the `<<` and its
/// delimiter are not arguments.
#[test]
fn a_heredoc_ends_the_command() {
for raw in [
"rocm diagnose --symptom-file - <<'EOF'",
"rocm diagnose --symptom-file - <<\"EOF\"",
"rocm diagnose --symptom-file - << EOF",
"rocm diagnose --symptom-file - <<EOF",
] {
assert_eq!(
command_parts(raw),
vec!["rocm diagnose --symptom-file -"],
"{raw}"
);
assert!(
findings(&[fixture(raw, Surface::CommandLine)]).is_empty(),
"{raw}"
);
}
// A heredoc's `<<` is not a `<placeholder>`, so a command after it in the
// same list is still split off and checked.
for raw in [
"rocm diagnose --symptom-file - <<'EOF' && rocm frobnicate --x",
"rocm diagnose --symptom-file - <<EOF; rocm frobnicate --x",
"rocm diagnose --symptom-file - << EOF || rocm frobnicate --x",
] {
assert_eq!(
command_parts(raw),
vec!["rocm diagnose --symptom-file -", "rocm frobnicate --x"],
"{raw}"
);
let found = findings(&[fixture(raw, Surface::CommandLine)]);
assert_eq!(found.len(), 1, "{raw}: {}", render_findings(&found));
assert_eq!(found[0].argv[1], "frobnicate", "{raw}");
}
}

/// Prose may follow a command after an em dash, an en dash or an arrow
/// (`rocm examine — check the host first`). Each marker ends the command, so
/// the description is not read as arguments; dropping any one of them from
Expand Down
55 changes: 54 additions & 1 deletion apps/rocm/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -96,8 +96,29 @@ pub(crate) enum Command {
/// takes the id, not the position.
Diagnose {
/// Raw error text from the user; sharpens keyword scoring.
#[arg(long)]
///
/// A shell reads this text before `rocm` does, so quotes, `$(...)`
/// and a leading `-` in a pasted error can be changed, run, or taken
/// as a flag. Use `--symptom-file` to hand over a paste untouched.
#[arg(long, value_name = "TEXT")]
symptom: Option<String>,
/// Read the error text from a file instead, or from standard input
/// when PATH is `-`, so no shell quoting is needed.
///
/// The text that arrives is matched as `--symptom` would match it,
/// with one trailing line break removed (shells and editors add one).
/// A UTF-8 byte-order mark is dropped, and a file with a UTF-16
/// byte-order mark, as Windows PowerShell's `>` writes, is decoded;
/// anything else must be UTF-8. An unreadable file, input that is not
/// text, or input larger than 16 MiB is a usage error (exit code 2).
/// For example: `rocm diagnose --symptom-file error.txt`. In
/// PowerShell, save the clipboard first
/// (`Get-Clipboard -Raw > error.txt`): Windows PowerShell 5.1 pipes
/// text to a program as ASCII, turning any other character into `?`.
/// With nothing piped in, paste the text at the terminal and end it
/// with Ctrl-D at the start of a line (Ctrl-Z then Enter on Windows).
#[arg(long, value_name = "PATH", conflicts_with = "symptom")]
symptom_file: Option<PathBuf>,
/// Show at most this many matches (default 5).
#[arg(long, default_value_t = 5)]
top: usize,
Expand Down Expand Up @@ -1894,6 +1915,38 @@ mod tests {
Cli::try_parse_from(argv)
}

// `--symptom-file` exists because a pasted error does not survive the shell
// as an argument: one starting with `-` is not even accepted as
// `--symptom`'s value. The file form takes `-` (stdin) and any path, and
// the two sources cannot both be given.
#[test]
fn diagnose_takes_the_symptom_from_a_file_or_stdin_but_not_with_symptom() {
assert!(
parse_diagnose(&["--symptom", "-x HIP error"]).is_err(),
"a leading minus is read as a flag, which is what --symptom-file avoids"
);
for path in ["-", "error.txt"] {
match parse_diagnose(&["--symptom-file", path]) {
Ok(Cli {
command:
Some(Command::Diagnose {
symptom,
symptom_file,
..
}),
..
}) => {
assert_eq!(symptom, None);
assert_eq!(symptom_file, Some(PathBuf::from(path)));
}
other => panic!("expected diagnose for {path:?}, got {other:?}"),
}
}
let error = parse_diagnose(&["--symptom", "oom", "--symptom-file", "-"])
.expect_err("--symptom and --symptom-file are exclusive");
assert_eq!(error.kind(), clap::error::ErrorKind::ArgumentConflict);
}

// The context options describe the model being asked about, so without
// `--model` they would be accepted and silently do nothing.
#[test]
Expand Down
4 changes: 4 additions & 0 deletions apps/rocm/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ mod services_text;
mod setup_cmd;
mod shell_quote;
mod storage;
mod symptom_input;
mod system_packages;
#[cfg(test)]
mod test_support;
Expand Down Expand Up @@ -659,6 +660,7 @@ fn dispatch(cli: Cli) -> Result<()> {
Some(Command::Examine { json, framework }) => examine(json, framework.into()),
Some(Command::Diagnose {
symptom,
symptom_file,
top,
json,
distro,
Expand All @@ -668,6 +670,8 @@ fn dispatch(cli: Cli) -> Result<()> {
report,
send,
}) => {
let symptom = symptom_input::resolve(symptom, symptom_file.as_deref())
.map_err(|error| clap_exit_code(symptom_input::usage_error(&error)))?;
let model = model.map(|model_ref| {
diagnose_model::ModelQuery::new(model_ref, context_size, kv_cache_type)
});
Expand Down
Loading
Loading