diff --git a/README.md b/README.md index f5ffc7b4e..17041648c 100644 --- a/README.md +++ b/README.md @@ -357,10 +357,14 @@ Without `--version`, `rocm install sdk` installs the newest stable release (ROCm 10.1 today) from `stable.repo.amd.com`, and `--channel nightly` installs the newest nightly build from `nightly.repo.amd.com`. Earlier releases stay installable by pinning them: `--version 7.14.1` installs the ROCm 7.14.1 release, +`--version 7.14` the newest release in the 7.14 line, and `--channel nightly --build-date 2026-08-19` installs a nightly from before the nightly channel moved on 2026-08-23. If ROCm CLI can't tell which exact GPU arch this computer has, or you want a different one, also add `--family` with the raw `gfx` code from `rocm examine`. For example: `--family gfx1200`. +A `major.minor` pin such as `--version 10.1` selects the newest stable release in +that line (for example `10.1.0`); a `major.minor.patch` pin such as +`--version 10.1.0` stays exact. On WSL, wheel runtime installs and updates (`rocm install sdk`, `rocm update --apply`) also link `librocdxg.so` to the runtime's own @@ -621,7 +625,7 @@ unknown option `-1`, a usage error that exits 2. ``` rocm install sdk [--channel release|nightly] [--format wheel|tarball] - [--version x.y.z | --build-date YYYY-MM-DD] + [--version x.y[.z] | --build-date YYYY-MM-DD] [--family gfx1100] [--prefix PATH] [--devel] [--dry-run] [--python-version X.Y] [--approve-replacing-active-default] [--yes] @@ -742,7 +746,9 @@ ROCm 10 and newer ship from a different source layout than ROCm 7: stable releases from `stable.repo.amd.com` and nightlies from `nightly.repo.amd.com`. That is the layout an install reads unless it asks for something older. A stable pin of ROCm 10 or newer, a nightly pinned to a build date of 2026-08-23 or later, -and an install with no pin at all all read it. The earlier release stream +and an install with no pin at all all read it. A two-component pin +(`--version 10.1`) is the 10.1 line and installs the newest stable release in it; +`--version 10.1.0` installs that exact release. The earlier release stream (`repo.amd.com`) and the earlier nightly stream (`rocm.nightlies.amd.com`), which stopped receiving builds on 2026-08-22, are read only when you pin something that exists only there: a ROCm 7 release, or a nightly from before 2026-08-23. These @@ -808,6 +814,16 @@ streams no longer publish new builds, so reinstall with `rocm install sdk` to move it. `install sdk` doesn't quietly retry against the other layout when a lookup finds nothing; it tells you what it couldn't find instead. +When a ROCm 10 pin can't be satisfied because that release isn't published, or +has no installable packages for this computer, the error lists the other stable +ROCm 10 releases that source publishes, if any, and suggests one of them to +re-run with, in the same `--format` as the failed request. When `rocm update` +fails the same way, it suggests a whole `rocm install sdk` command that keeps +the runtime's format and `--devel` toolchain. A failure no other version can +fix, such as an unknown GPU arch or a network error, suggests no version, and +neither does a failed `--channel nightly` request, whose builds are not stable +releases. + #### Driver installation `install driver` installs the AMD kernel driver on Linux, using DKMS or a native diff --git a/apps/rocm/src/chat/turn.rs b/apps/rocm/src/chat/turn.rs index fcef7a8b3..ed2849879 100644 --- a/apps/rocm/src/chat/turn.rs +++ b/apps/rocm/src/chat/turn.rs @@ -626,7 +626,7 @@ fn find_ascii_case_insensitive(haystack: &str, needle: &str) -> Option { /// to, and a WSL user was told "on native Windows, vLLM is skipped" while vLLM /// was in fact their supported path. Anything host-dependent now comes from /// [`chat_host_facts::HostFacts`], which knows which machine it is describing. -const ROCM_CHAT_TOOL_SYSTEM_PROMPT: &str = "You are ROCm CLI's local assistant. Speak in simple English for non-technical users. Use the provided ROCm tools when you need to inspect this machine, preview setup, read service logs, check updates, inspect automations, install or start ROCm-managed apps, or request ROCm/TheRock, config, engine, app, and local model server changes. For simple greetings or thanks like hello, hi, hey, ok, or thank you, reply normally; do not inspect ROCm, do not call tools, and do not launch or propose a model server. Tool-use rules: inspect first with read-only tools; call rocm_command only with argv-style args and no shell text; use natural_language_plan for ROCm requests that do not fit another read-only tool; ask for a mutating tool call only after explaining why it is needed; summarize tool results after they are returned. Read-only tools may run immediately. Tools that install, launch, stop, delete, or change state require user approval; request rocm_command and explain why. For 'is X running?', 'what is running?', status, or port questions, inspect before answering and do not start, stop, install, or serve anything. For ComfyUI or port 8188 use [\"comfyui\",\"status\"] or port_status. For vLLM, Lemonade, AIM, qwen, or local model servers use [\"services\",\"list\",\"--all\"] for running state and [\"engines\",\"list\"] for installed/available engine state. Treat ready/running as running, starting/recovering as starting, failed/stopped as not running, and no matching record as unknown or not managed by ROCm CLI. Interpret Examine carefully: active_runtime_status=ready means ROCm CLI has an active managed TheRock/ROCm runtime; legacy_rocm_status=not_detected only means no global system ROCm install was found. If active_runtime_status=ready, tell the user ROCm/TheRock is installed and active for ROCm CLI. For 'is TheRock installed', 'is ROCm installed', or 'which GPU is on this machine', use examine or gpu_snapshot before answering. For 'how do I setup TheRock' or install/setup requests, guide the user to choose an install folder first; do not answer with only a status check. For 'which LLMs can this machine support', use rocm_command args [\"model\"] or natural_language_plan before answering. For TheRock installs, always let the user choose the install folder. If the user names a folder or prefix, preserve that exact folder with [\"--prefix\",\"PATH\"]; you may call path_exists first to check whether that user-provided folder or its parent exists. If the user asks you to install TheRock/ROCm but has not named a folder, ask for the folder or let the guided setup folder picker collect it; do not invent a hidden default folder and do not request an install command without --prefix. Use rocm_command args [\"install\",\"sdk\",\"--channel\",\"release\",\"--format\",\"wheel\",\"--prefix\",\"PATH\"] only when the user asks you to install it and a folder is known; for a requested build date add [\"--build-date\",\"YYYY-MM-DD\"] and for a requested exact version add [\"--version\",\"VERSION\"]. For config changes, inspect with [\"config\",\"show\"] first when useful, then request config subcommands such as [\"config\",\"set-default-engine\",\"lemonade\"], [\"config\",\"set-default-runtime\",\"RUNTIME_KEY\"], or [\"config\",\"set-telemetry\",\"local\"] only after explaining why. For ComfyUI, use rocm_command with args like [\"comfyui\",\"status\"], [\"comfyui\",\"logs\"], [\"comfyui\",\"install\"], [\"comfyui\",\"start\"], or [\"comfyui\",\"stop\"]. First-time setup is the same thing as bootstrap in ROCm CLI; it is a deterministic ROCm setup flow, not a separate model chat. The built-in local assistant is fixed to qwen, which maps to Qwen3-4B-Instruct-2507-GGUF served by Lemonade with gpu_required. vLLM, Lemonade, and AIM (Docker-based) are the general serving engines; inspect or manage them when the user asks about general model serving, but do not switch the built-in assistant away from Lemonade. Use qwen-smoke only for a quick server smoke test. For vLLM management, inspect engines first and use [\"engines\",\"install\",\"vllm\"] or [\"serve\",\"MODEL\",\"--engine\",\"vllm\",\"--device\",\"gpu_required\",\"--managed\"] only where the host supports it. Do not invent shell commands and do not request CPU fallback."; +const ROCM_CHAT_TOOL_SYSTEM_PROMPT: &str = "You are ROCm CLI's local assistant. Speak in simple English for non-technical users. Use the provided ROCm tools when you need to inspect this machine, preview setup, read service logs, check updates, inspect automations, install or start ROCm-managed apps, or request ROCm/TheRock, config, engine, app, and local model server changes. For simple greetings or thanks like hello, hi, hey, ok, or thank you, reply normally; do not inspect ROCm, do not call tools, and do not launch or propose a model server. Tool-use rules: inspect first with read-only tools; call rocm_command only with argv-style args and no shell text; use natural_language_plan for ROCm requests that do not fit another read-only tool; ask for a mutating tool call only after explaining why it is needed; summarize tool results after they are returned. Read-only tools may run immediately. Tools that install, launch, stop, delete, or change state require user approval; request rocm_command and explain why. For 'is X running?', 'what is running?', status, or port questions, inspect before answering and do not start, stop, install, or serve anything. For ComfyUI or port 8188 use [\"comfyui\",\"status\"] or port_status. For vLLM, Lemonade, AIM, qwen, or local model servers use [\"services\",\"list\",\"--all\"] for running state and [\"engines\",\"list\"] for installed/available engine state. Treat ready/running as running, starting/recovering as starting, failed/stopped as not running, and no matching record as unknown or not managed by ROCm CLI. Interpret Examine carefully: active_runtime_status=ready means ROCm CLI has an active managed TheRock/ROCm runtime; legacy_rocm_status=not_detected only means no global system ROCm install was found. If active_runtime_status=ready, tell the user ROCm/TheRock is installed and active for ROCm CLI. For 'is TheRock installed', 'is ROCm installed', or 'which GPU is on this machine', use examine or gpu_snapshot before answering. For 'how do I setup TheRock' or install/setup requests, guide the user to choose an install folder first; do not answer with only a status check. For 'which LLMs can this machine support', use rocm_command args [\"model\"] or natural_language_plan before answering. For TheRock installs, always let the user choose the install folder. If the user names a folder or prefix, preserve that exact folder with [\"--prefix\",\"PATH\"]; you may call path_exists first to check whether that user-provided folder or its parent exists. If the user asks you to install TheRock/ROCm but has not named a folder, ask for the folder or let the guided setup folder picker collect it; do not invent a hidden default folder and do not request an install command without --prefix. Use rocm_command args [\"install\",\"sdk\",\"--channel\",\"release\",\"--format\",\"wheel\",\"--prefix\",\"PATH\"] only when the user asks you to install it and a folder is known; for a requested build date add [\"--build-date\",\"YYYY-MM-DD\"] and for a requested version add [\"--version\",\"VERSION\"] (an exact version such as 10.1.0, or a release line such as 10.1 for its newest stable release). For config changes, inspect with [\"config\",\"show\"] first when useful, then request config subcommands such as [\"config\",\"set-default-engine\",\"lemonade\"], [\"config\",\"set-default-runtime\",\"RUNTIME_KEY\"], or [\"config\",\"set-telemetry\",\"local\"] only after explaining why. For ComfyUI, use rocm_command with args like [\"comfyui\",\"status\"], [\"comfyui\",\"logs\"], [\"comfyui\",\"install\"], [\"comfyui\",\"start\"], or [\"comfyui\",\"stop\"]. First-time setup is the same thing as bootstrap in ROCm CLI; it is a deterministic ROCm setup flow, not a separate model chat. The built-in local assistant is fixed to qwen, which maps to Qwen3-4B-Instruct-2507-GGUF served by Lemonade with gpu_required. vLLM, Lemonade, and AIM (Docker-based) are the general serving engines; inspect or manage them when the user asks about general model serving, but do not switch the built-in assistant away from Lemonade. Use qwen-smoke only for a quick server smoke test. For vLLM management, inspect engines first and use [\"engines\",\"install\",\"vllm\"] or [\"serve\",\"MODEL\",\"--engine\",\"vllm\",\"--device\",\"gpu_required\",\"--managed\"] only where the host supports it. Do not invent shell commands and do not request CPU fallback."; const ROCM_CHAT_TOOL_SKILL: &str = include_str!("../../../../skills/rocm-cli-assistant/SKILL.md"); diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 734cfb00f..90b488d71 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -841,9 +841,13 @@ rocm install sdk --version 10.0.0 --python-version 3.12")] /// Full folder path where the ROCm Python environment should be created. #[arg(long)] prefix: Option, - /// Exact TheRock package version to install; with none, the channel's - /// newest build. An earlier ROCm 7 release such as 7.14.1 is supported, - /// for a wheel install only. + /// TheRock package version to install; with none, the channel's newest + /// build. + /// + /// `major.minor.patch` is exact, including a prerelease suffix. + /// `major.minor` (for example `10.1`) selects the newest stable + /// release in that line. An earlier ROCm 7 release such as 7.14.1 or + /// the 7.14 line is supported, for a wheel install only. #[arg(long, conflicts_with = "build_date")] version: Option, /// Pick the TheRock package built on this date; nightlies from before @@ -1602,6 +1606,46 @@ mod tests { ); } + #[test] + fn install_sdk_version_help_describes_line_and_exact_pins() { + // Wording pin: `--version 10.1` selecting the newest stable 10.1.x, and + // `--version 10.1.0` staying exact, are proven by + // `two_component_version_pin_routes_and_matches_its_release_line` in + // `therock/source.rs` and by scenarios therock-next-24 and -26. This + // only keeps the help that describes them from drifting back to + // "exact version". It reads the `version` argument's own help, so the + // sibling `--build-date` doc cannot satisfy it. + let mut command = Cli::command(); + let sdk = command + .find_subcommand_mut("install") + .expect("install subcommand") + .find_subcommand_mut("sdk") + .expect("install sdk subcommand"); + let version = sdk + .get_arguments() + .find(|arg| arg.get_id() == "version") + .expect("`install sdk` must offer --version"); + let version_help = version + .get_long_help() + .or_else(|| version.get_help()) + .expect("--version must be documented") + .to_string(); + + assert!( + version_help.contains("`major.minor.patch` is exact"), + "`--version` must say a three-component pin is exact:\n{version_help}" + ); + assert!( + version_help.contains("`major.minor` (for example `10.1`) selects the newest stable"), + "`--version` must say a two-component pin selects the newest stable \ + release in that line:\n{version_help}" + ); + assert!( + !version_help.starts_with("Exact"), + "`--version` no longer takes only an exact version:\n{version_help}" + ); + } + #[test] fn install_sdk_help_separates_the_two_consents_yes_carries() { // `--yes` approves two unrelated things: replacing the active default diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index be13d9c63..0b7e08fff 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -243,7 +243,7 @@ pub(crate) fn install_sdk( && layout_serving(channel, Some(selector)) == SourceLayout::Canonical { bail!( - "specific TheRock version selection for tarball installs is supported only for the newer package layout: a stable ROCm 10+ release (e.g. `--version 10.0.0`) or a nightly built on or after {THEROCK_NEXT_NIGHTLY_FIRST_BUILD_DATE}; for any earlier version, use `--format wheel`" + "specific TheRock version selection for tarball installs is supported only for the newer package layout: a stable ROCm 10+ release or release line (e.g. `--version 10.0.0` or `--version 10.1`) or a nightly built on or after {THEROCK_NEXT_NIGHTLY_FIRST_BUILD_DATE}; for any earlier version, use `--format wheel`" ) } install_tarball_runtime( diff --git a/apps/rocm/src/therock/resolve.rs b/apps/rocm/src/therock/resolve.rs index c6b51dbe1..6e6eccf70 100644 --- a/apps/rocm/src/therock/resolve.rs +++ b/apps/rocm/src/therock/resolve.rs @@ -5,10 +5,12 @@ //! How a request is turned into the artifact an install fetches. Only module //! declarations and re-exports live here, no logic: `tarball` resolves the SDK //! tarball from the catalog's index, `wheel` resolves the wheel stack from the -//! wheel indexes (with `uv_access` deciding who may fetch `uv` while it does, -//! and `torchaudio` choosing the torchaudio build a ROCm 10 or newer install -//! pins), and the rest of `therock` reads the names below. +//! wheel indexes (with `uv_access` deciding who may fetch `uv` while it does), +//! `torchaudio` chooses the torchaudio build a ROCm 10 or newer install pins, +//! `next_hint` words what a failed ROCm 10 resolution suggests next, and the +//! rest of `therock` reads the names below. +mod next_hint; mod tarball; mod torchaudio; mod uv_access; diff --git a/apps/rocm/src/therock/resolve/next_hint.rs b/apps/rocm/src/therock/resolve/next_hint.rs new file mode 100644 index 000000000..5ee254c81 --- /dev/null +++ b/apps/rocm/src/therock/resolve/next_hint.rs @@ -0,0 +1,595 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! What a failed ROCm 10 resolution tells the user to do next. +//! +//! Only a failure a different `--version` could clear carries a version +//! suggestion. Such a failure is raised as a [`VersionUnsatisfied`]: the +//! requested release is not published, the release it resolved to has no +//! torchaudio for this Python and platform, or `uv` found no jointly +//! installable package set for it. Every other failure gets no version advice: +//! an undetermined device target, a `uv` that could not be fetched or run, or a +//! listing that could not be read. A different version leaves each of those +//! exactly where it was. +//! +//! [`next_layout_unsatisfied_hint`] writes the suggestion. A pinned install +//! (`rocm install sdk --version …`) is told which `--version`/`--family` to +//! re-run with. `rocm update`, which re-resolves an installed runtime with no +//! pin and has no `--family` or `--version` of its own, is given a whole +//! `rocm install sdk` command that keeps the runtime's format and toolchain +//! extras ([`NextLayoutRecovery`]). +//! +//! A leaf child of `therock/resolve.rs` that builds on `therock/source.rs` and +//! `therock/version.rs`. `wheel.rs` and `tarball.rs` raise the marker and call +//! the hint. + +use super::super::source::{ + RuntimeVersionSelector, SourceLayout, THEROCK_NEXT_MIN_MAJOR, TheRockChannel, layout_serving, +}; +use super::super::version::compare_version_strings; +use rocm_core::runtime_is_windows; +use std::fmt; + +/// A next-layout resolution failure that a different `--version` could clear. +/// +/// `attempted` is the release the request resolved to before it failed, when it +/// resolved to one. The hint leaves that release out, because suggesting it +/// again cannot help. The resolver that picked it records it here. A hint that +/// re-derived it would have to repeat that resolver's ordering (by version for a +/// wheel listing, by upload time for an unpinned tarball pick) and could get it +/// wrong. +/// +/// Its `Display` is the failure's own message, so raising this in place of a +/// plain error leaves what the user reads unchanged. +#[derive(Debug)] +pub(in crate::therock) struct VersionUnsatisfied { + attempted: Option, + message: String, +} + +impl VersionUnsatisfied { + pub(in crate::therock) fn new(attempted: Option<&str>, message: String) -> Self { + Self { + attempted: attempted.map(str::to_owned), + message, + } + } + + pub(in crate::therock) fn attempted(&self) -> Option<&str> { + self.attempted.as_deref() + } + + /// The marker anywhere in `error`'s chain, whatever context was added on top. + pub(in crate::therock) fn find(error: &anyhow::Error) -> Option<&Self> { + error.chain().find_map(|cause| cause.downcast_ref::()) + } +} + +impl fmt::Display for VersionUnsatisfied { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(&self.message) + } +} + +impl std::error::Error for VersionUnsatisfied {} + +/// The artifact kind a failed resolution was for, so a suggested install +/// command installs the same kind. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(in crate::therock) enum RecoveryFormat { + Wheel, + Tarball, +} + +/// What a suggested command has to carry over from the request that failed. +#[derive(Clone, Copy, Debug)] +pub(in crate::therock) struct NextLayoutRecovery<'a> { + /// The channel the failed request read. Only the release channel gets a + /// list of releases to try: see [`NextLayoutRecovery::suggests_releases`]. + pub(in crate::therock) channel: TheRockChannel, + pub(in crate::therock) format: RecoveryFormat, + /// The exact arch the request resolved with, so the command repeats it. + pub(in crate::therock) exact_arch: Option<&'a str>, + /// Whether the runtime has the `devel` toolchain extras. Only an update + /// carries it into the command; a pinned install re-runs its own command, + /// flags included. + pub(in crate::therock) include_devel: bool, +} + +impl NextLayoutRecovery<'_> { + /// Whether a failure on the next layout is followed by + /// [`next_layout_unsatisfied_hint`]. On the release channel a different + /// stable release can clear it. The nightly channel publishes only + /// prerelease builds there, which that hint does not name and which a + /// `--version` re-run on the release channel would leave, so a nightly + /// failure gets its own message and no suggestion. + pub(in crate::therock) fn suggests_releases(&self) -> bool { + self.channel == TheRockChannel::Release + } +} + +/// How many published releases a next-layout failure lists by name. +const NEXT_LAYOUT_HINT_MAX_LISTED: usize = 5; + +/// Recovery guidance when a ROCm >= 10 request cannot be satisfied on the next +/// layout, for a failure raised as a [`VersionUnsatisfied`]. +/// +/// It never offers `--channel nightly`, because that channel refuses these pins. +/// +/// The suggested `--version` is one the next layout publishes and is never the +/// release that just failed. `published` is that layout's version listing +/// (`None` when the listing could not be read), narrowed to one GPU family when +/// `family_scope` names it. `attempted` is the release the failure recorded, +/// and the hint leaves it out. It also leaves out any release +/// [`layout_serving`] would not route back to this layout on the request's +/// channel, so a re-run searches the same layout. Callers reach it only for +/// the release channel ([`NextLayoutRecovery::suggests_releases`]). When nothing else qualifies, the hint says so and +/// names no command. +/// +/// The command depends on the caller: +/// - A pinned install (`version_selector` is `Some`) is told which +/// `--version`/`--family` pair to re-run with. Its other flags are its own. +/// - `rocm update` (`version_selector` is `None`, because an update re-resolves +/// with no pin) has no such flags. It is given the whole `rocm install sdk` +/// command, with the runtime's format and toolchain extras, so following it +/// installs the same kind of runtime. +pub(in crate::therock) fn next_layout_unsatisfied_hint( + version_selector: Option<&RuntimeVersionSelector>, + published: Option<&[String]>, + attempted: Option<&str>, + recovery: NextLayoutRecovery<'_>, + family_scope: Option<&str>, +) -> String { + let layout = format!("the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout"); + let Some(published) = published else { + return format!( + "Could not read the releases {layout} publishes, so no other version can be suggested." + ); + }; + let requested = version_selector.map_or_else( + || "the newest release".to_owned(), + RuntimeVersionSelector::describe, + ); + let scope = family_scope.map_or_else(String::new, |family| format!(" for {family}")); + let lead = match recovery.format { + RecoveryFormat::Wheel => { + format!("No complete compatible package stack was found for {requested} on {layout}.") + } + RecoveryFormat::Tarball => { + format!("No archive{scope} was found for {requested} on {layout}.") + } + }; + let mut alternatives = published + .iter() + .filter(|version| attempted != Some(version.as_str())) + .filter(|version| { + layout_serving( + recovery.channel, + Some(&RuntimeVersionSelector::Version((*version).clone())), + ) == SourceLayout::Next + }) + .map(String::as_str) + .collect::>(); + alternatives.sort_by(|left, right| compare_version_strings(right, left)); + alternatives.dedup(); + let other = if attempted.is_some() { " other" } else { "" }; + let Some(newest) = alternatives.first() else { + return format!( + "{lead} It publishes no{other} stable release{scope}, so no `--version` pin can install from it yet." + ); + }; + let mut listed = alternatives + .iter() + .take(NEXT_LAYOUT_HINT_MAX_LISTED) + .copied() + .collect::>() + .join(", "); + if alternatives.len() > NEXT_LAYOUT_HINT_MAX_LISTED { + let older = alternatives.len() - NEXT_LAYOUT_HINT_MAX_LISTED; + listed.push_str(", and "); + listed.push_str(&older.to_string()); + listed.push_str(" older"); + } + let command = recovery_command(version_selector.is_some(), newest, recovery); + let label = if attempted.is_some() { + "Other stable releases it publishes" + } else { + "Stable releases it publishes" + }; + format!("{lead} {label}{scope}: {listed}. {command}") +} + +/// The sentence naming what to run. `pinned` is whether the failed request +/// carried a `--version`. +fn recovery_command(pinned: bool, version: &str, recovery: NextLayoutRecovery<'_>) -> String { + // A ROCm 10 pin needs an exact arch, so a placeholder stands in only where + // none is known, which a pinned install never reaches: it is refused + // before resolution without one. + let family = recovery.exact_arch.unwrap_or(""); + let placeholder_note = if recovery.exact_arch.is_none() { + ", where `` is the raw `gfx` code `rocm examine` reports" + } else { + "" + }; + if pinned { + return format!( + "Re-run with one of them, for example `--version {version} --family {family}`{placeholder_note}." + ); + } + let format = match recovery.format { + RecoveryFormat::Wheel => "wheel", + RecoveryFormat::Tarball => "tarball", + }; + let devel = if recovery.include_devel { + " --devel" + } else { + "" + }; + let channel = recovery.channel.as_str(); + format!( + "Install one of them, for example `rocm install sdk --channel {channel} --format {format} --version {version} --family {family}{devel}`{placeholder_note}." + ) +} + +/// Recovery guidance appended to family/index resolution failures so a clean +/// first run can recover without the user having to guess a `--family`. +/// +/// `source` is the `FamilyResolution::source` that produced `family`: +/// auto-detected (`host`, `managed-runtime`) versus user-supplied (`manifest` +/// from `--family`, `env` from `ROCM_CLI_THEROCK_FAMILY`). The wording differs +/// so an auto-detected miss points the user at `--family`, while a user-supplied +/// miss confirms the family they already named. Both point at the other channel +/// and, where valid for the platform, the other install format. +pub(super) fn canonical_wheel_resolution_hint(channel: TheRockChannel) -> String { + let other_channel = match channel { + TheRockChannel::Release => "nightly", + TheRockChannel::Nightly => "release", + }; + let mut hint = format!( + "No complete compatible package stack was found in the canonical {} aggregate stream. Try `--channel {other_channel}`", + channel.as_str() + ); + if !runtime_is_windows() { + hint.push_str(" or `--format tarball`"); + } + hint.push('.'); + hint +} + +/// The context added when wheel resolution fails. +/// +/// A ROCm >= 10 pin already refused `--channel nightly` before resolution +/// (`select_source_layout`), so the canonical hint's nightly suggestion must +/// not be what a next-layout failure prints. On the next layout, a nightly +/// failure gets the source line alone (see +/// [`NextLayoutRecovery::suggests_releases`]). On the release channel: +/// - `published` is `None` when the `rocm` listing itself could not be read, +/// and the context says no other version can be suggested. +/// - `unsatisfied` is the [`VersionUnsatisfied`] in the failure's chain. Only +/// such a failure is followed by [`next_layout_unsatisfied_hint`]'s list of +/// releases to try, because only it can be cleared by another `--version`. +/// - Any other failure gets the source line alone. Its own message (an +/// undetermined device target, a `uv` that could not run, an unreachable +/// index) is the advice, and a version suggestion would send the user to a +/// re-run that meets the same failure. +pub(super) fn wheel_resolution_failure_context( + channel: TheRockChannel, + layout: SourceLayout, + index_url: &str, + version_selector: Option<&RuntimeVersionSelector>, + published: Option<&[String]>, + unsatisfied: Option<&VersionUnsatisfied>, + recovery: NextLayoutRecovery<'_>, +) -> String { + let (source_label, hint) = match layout { + SourceLayout::Next => { + let hint = match (published, unsatisfied) { + _ if !recovery.suggests_releases() => None, + (None, _) => Some(next_layout_unsatisfied_hint( + version_selector, + None, + None, + recovery, + None, + )), + (Some(published), Some(unsatisfied)) => Some(next_layout_unsatisfied_hint( + version_selector, + Some(published), + unsatisfied.attempted(), + recovery, + None, + )), + (Some(_), None) => None, + }; + ("next-layout source", hint) + } + SourceLayout::Canonical => ( + "canonical source", + Some(canonical_wheel_resolution_hint(channel)), + ), + }; + let head = format!( + "failed to resolve TheRock {} wheel runtime from {source_label} {index_url}", + channel.as_str() + ); + match hint { + Some(hint) => format!("{head}\n\n{hint}"), + None => head, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn versions(list: &[&str]) -> Vec { + list.iter().map(|version| (*version).to_owned()).collect() + } + + const WHEEL_AT_GFX1200: NextLayoutRecovery<'static> = NextLayoutRecovery { + channel: TheRockChannel::Release, + format: RecoveryFormat::Wheel, + exact_arch: Some("gfx1200"), + include_devel: false, + }; + + /// Every state the hint can be reached in. The rules under test: it never + /// suggests the release the failure recorded, never names a command when + /// the index offers nothing else, and a suggested install command + /// installs the same kind of runtime that failed. + #[test] + fn next_layout_unsatisfied_hint_only_suggests_releases_that_were_not_tried() { + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); + + // A line pin that resolved to 10.1.2 and could not install it: the + // other 10.1 release is still worth trying, 10.1.2 is not. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.0.0", "10.1.0", "10.1.2"])), + Some("10.1.2"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Other stable releases it publishes: 10.1.0, 10.0.0."), + "{hint}" + ); + // A pinned request re-runs its own command with a different + // `--version`, so it is told to re-run, not handed a whole install + // command. The unpinned `rocm update` case below gets the full + // command instead. + assert!( + hint.contains( + "Re-run with one of them, for example `--version 10.1.0 --family gfx1200`." + ), + "{hint}" + ); + assert!(!hint.contains("Install one of them"), "{hint}"); + assert!(!hint.contains("rocm install sdk"), "{hint}"); + assert!(!hint.contains("10.1.2"), "{hint}"); + + // The release the failure recorded is what is left out, not whatever + // version order would pick: an unpinned tarball pick goes by upload + // time, so it can have tried an older release than the newest. + let hint = next_layout_unsatisfied_hint( + None, + Some(&versions(&["10.0.0", "10.1.0", "10.1.2"])), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Other stable releases it publishes: 10.1.2, 10.0.0."), + "{hint}" + ); + + // An exact pin that is published but failed is not suggested again. + let hint = next_layout_unsatisfied_hint( + Some(&exact), + Some(&versions(&["10.0.0", "10.1.0"])), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("`--version 10.0.0 --family gfx1200`"), + "{hint}" + ); + assert!(!hint.contains("--version 10.1.0"), "{hint}"); + + // An exact pin that is the only release: nothing else to suggest, so + // no command is named. + let hint = next_layout_unsatisfied_hint( + Some(&exact), + Some(&versions(&["10.1.0"])), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("It publishes no other stable release"), + "{hint}" + ); + assert!(!hint.contains("--version 10"), "{hint}"); + + // A pin nothing matched: no release was attempted, and none of the + // published ones is "other". + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.0.0"])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Stable releases it publishes: 10.0.0. "), + "{hint}" + ); + + // An index with no stable release at all; prereleases are not offered. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["10.1.0a20260822"])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!(hint.contains("It publishes no stable release"), "{hint}"); + assert!(!hint.contains("10.1.0a20260822"), "{hint}"); + assert!(!hint.contains("--version 10"), "{hint}"); + + // The listing itself could not be read: say that, not "no stack was + // found", and suggest nothing. + let hint = next_layout_unsatisfied_hint(Some(&line), None, None, WHEEL_AT_GFX1200, None); + assert!( + hint.starts_with("Could not read the releases the ROCm 10+ next layout publishes"), + "{hint}" + ); + assert!( + !hint.contains("No complete compatible package stack"), + "{hint}" + ); + assert!(!hint.contains("--version 10"), "{hint}"); + + // Only releases a re-run would route back to this layout are offered. + // A four-component or sub-10 publish would re-resolve against the + // canonical index, so suggesting it could not clear the failure. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&["9.9.0", "10.0.0", "10.0.1.12345"])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("Stable releases it publishes: 10.0.0. "), + "{hint}" + ); + assert!(!hint.contains("10.0.1.12345"), "{hint}"); + assert!(!hint.contains("9.9.0"), "{hint}"); + + // A long listing is capped, newest first. + let hint = next_layout_unsatisfied_hint( + Some(&line), + Some(&versions(&[ + "10.0.0", "10.0.1", "10.0.2", "10.0.3", "10.0.4", "10.0.5", "10.0.6", + ])), + None, + WHEEL_AT_GFX1200, + None, + ); + assert!( + hint.contains("10.0.6, 10.0.5, 10.0.4, 10.0.3, 10.0.2, and 2 older."), + "{hint}" + ); + } + + /// `rocm update` reaches the next layout with no pin. It has no `--family` + /// or `--version` of its own, so the hint names a whole `rocm install sdk` + /// command, and that command installs what the failed runtime was: the same + /// format and the same toolchain extras. + #[test] + fn an_update_is_given_an_install_command_that_keeps_its_format_and_extras() { + let published = versions(&["10.0.0", "10.1.0"]); + + let wheel_with_toolchain = next_layout_unsatisfied_hint( + None, + Some(&published), + Some("10.1.0"), + NextLayoutRecovery { + channel: TheRockChannel::Release, + format: RecoveryFormat::Wheel, + exact_arch: Some("gfx1200"), + include_devel: true, + }, + None, + ); + assert!( + wheel_with_toolchain.contains( + "Install one of them, for example `rocm install sdk --channel release --format wheel --version 10.0.0 --family gfx1200 --devel`." + ), + "{wheel_with_toolchain}" + ); + assert!( + wheel_with_toolchain.contains("for the newest release"), + "{wheel_with_toolchain}" + ); + assert!( + !wheel_with_toolchain.contains("Re-run with one of them"), + "{wheel_with_toolchain}" + ); + assert!( + !wheel_with_toolchain.contains("nightly"), + "{wheel_with_toolchain}" + ); + + let plain_wheel = next_layout_unsatisfied_hint( + None, + Some(&published), + Some("10.1.0"), + WHEEL_AT_GFX1200, + None, + ); + assert!( + plain_wheel.contains( + "`rocm install sdk --channel release --format wheel --version 10.0.0 --family gfx1200`." + ), + "{plain_wheel}" + ); + + // A tarball runtime's update names a tarball install, and the catalog + // it read was the family's, so the hint is about archives, not a + // package stack. A tarball runtime records only its grouped family, so + // no exact arch is known: the command says where to get one, and does + // not claim the update itself takes `--family`. + let tarball = next_layout_unsatisfied_hint( + None, + Some(&published), + None, + NextLayoutRecovery { + channel: TheRockChannel::Release, + format: RecoveryFormat::Tarball, + exact_arch: None, + include_devel: false, + }, + Some("gfx120X-all"), + ); + assert!( + tarball.starts_with( + "No archive for gfx120X-all was found for the newest release on the ROCm 10+ next layout." + ), + "{tarball}" + ); + assert!( + tarball.contains( + "`rocm install sdk --channel release --format tarball --version 10.1.0 --family `, where `` is the raw `gfx` code `rocm examine` reports." + ), + "{tarball}" + ); + assert!(!tarball.contains("package stack"), "{tarball}"); + assert!(!tarball.contains("re-run with `--family`"), "{tarball}"); + } + + /// The marker is found however many context layers sit on top of it, and a + /// failure without one is not mistaken for it. + #[test] + fn the_marker_survives_added_context_and_keeps_its_message() { + let marked = anyhow::Error::new(VersionUnsatisfied::new( + Some("10.1.0"), + "no torchaudio built for ROCm 10.1.0".to_owned(), + )) + .context("failed to resolve") + .context("outer"); + let found = VersionUnsatisfied::find(&marked).expect("marker is in the chain"); + assert_eq!(found.attempted.as_deref(), Some("10.1.0")); + assert!( + format!("{marked:#}").contains("no torchaudio built for ROCm 10.1.0"), + "{marked:#}" + ); + + let plain = anyhow::anyhow!("uv could not be downloaded").context("failed to resolve"); + assert!(VersionUnsatisfied::find(&plain).is_none()); + } +} diff --git a/apps/rocm/src/therock/resolve/tarball.rs b/apps/rocm/src/therock/resolve/tarball.rs index 6a6d093ae..5da76c099 100644 --- a/apps/rocm/src/therock/resolve/tarball.rs +++ b/apps/rocm/src/therock/resolve/tarball.rs @@ -17,11 +17,13 @@ use super::super::family::{family_resolution_hint, resolve_family}; use super::super::fetch::download_text_cached; use super::super::platform_tarball_token; use super::super::source::{ - RuntimeVersionSelector, SourceLayout, TheRockChannel, gate_install_layout, resolve_source, + FamilyResolution, RuntimeVersionSelector, SourceLayout, THEROCK_NEXT_MIN_MAJOR, TheRockChannel, + gate_install_layout, resolve_source, selector_is_release_line, }; use super::super::version::{ compare_version_strings, is_parseable_runtime_version, is_stable_runtime_version, }; +use super::next_hint::{NextLayoutRecovery, RecoveryFormat, next_layout_unsatisfied_hint}; use anyhow::{Context, Result, bail}; use rocm_core::AppPaths; use serde::Deserialize; @@ -93,8 +95,12 @@ pub(in crate::therock) fn resolve_tarball_artifact_with_timeout( )? .text; let files = parse_tarball_index_html(&html).with_context(|| { + let catalog = match layout { + SourceLayout::Canonical => "canonical", + SourceLayout::Next => "next-layout", + }; format!( - "unknown canonical TheRock tarball catalog layout at {}", + "unknown {catalog} TheRock tarball catalog layout at {}", source.tarball_catalog ) })?; @@ -106,15 +112,17 @@ pub(in crate::therock) fn resolve_tarball_artifact_with_timeout( version_selector, ) .with_context(|| { - format!( - "canonical TheRock {} tarball stream is incomplete for the resolved GPU family\n\n{}", - channel.as_str(), - family_resolution_hint( - &family_resolution.source, - &family_resolution.family, - channel, - "tarball", - ) + let published = + tarball_family_candidates(&files, channel, layout, &family_resolution.family) + .into_iter() + .map(|(_, version)| version) + .collect::>(); + tarball_resolution_failure_context( + channel, + layout, + &family_resolution, + version_selector, + &published, ) })?; Ok(TarballArtifact { @@ -148,29 +156,23 @@ fn tarball_family_token(layout: SourceLayout, family: &str) -> &str { } } -/// The newest archive in `files` that this request can actually install. +/// Every archive in `files` this channel can install for `family`, before any +/// version pin narrows them, paired with the version its name carries. /// -/// The next catalogs (release and nightly) publish non-release siblings beside -/// the real dist archive (`...-tests-10.0.0.tar.gz`) whose leftover suffix is not -/// a version at all, and whose mtime is *later* than the archive they shadow, so -/// an unfiltered "newest wins" would pick the wrong file. The release channel's -/// stable-version filter excludes them there; the next layout additionally -/// requires a parseable version on every channel, which covers the nightly -/// catalog's prerelease names. The canonical catalogs publish no such siblings -/// and have never been held to that grammar. -fn select_tarball_candidate( +/// [`select_tarball_candidate`] picks from these. A next-layout failure lists +/// their versions, so the releases it suggests are ones the pick could take. +fn tarball_family_candidates( files: &[TarballIndexFile], channel: TheRockChannel, layout: SourceLayout, family: &str, - version_selector: Option<&RuntimeVersionSelector>, -) -> Option<(TarballIndexFile, String)> { +) -> Vec<(TarballIndexFile, String)> { let prefix = format!( "therock-dist-{}-{}-", platform_tarball_token(), tarball_family_token(layout, family) ); - let mut candidates = files + files .iter() .filter_map(|file| { let version = file @@ -187,22 +189,109 @@ fn select_tarball_candidate( if matches!(layout, SourceLayout::Next) && !is_parseable_runtime_version(&version) { return None; } - if version_selector.is_some_and(|selector| !selector.matches_version(&version)) { - return None; - } Some((file.clone(), version)) }) - .collect::>(); + .collect() +} + +/// The newest archive in `files` that this request can actually install. +/// +/// The next catalogs (release and nightly) publish non-release siblings beside +/// the real dist archive (`...-tests-10.0.0.tar.gz`) whose leftover suffix is not +/// a version at all, and whose mtime is *later* than the archive they shadow, so +/// an unfiltered "newest wins" would pick the wrong file. The release channel's +/// stable-version filter excludes them there; the next layout additionally +/// requires a parseable version on every channel, which covers the nightly +/// catalog's prerelease names. The canonical catalogs publish no such siblings +/// and have never been held to that grammar. +fn select_tarball_candidate( + files: &[TarballIndexFile], + channel: TheRockChannel, + layout: SourceLayout, + family: &str, + version_selector: Option<&RuntimeVersionSelector>, +) -> Option<(TarballIndexFile, String)> { + let mut candidates = tarball_family_candidates(files, channel, layout, family); + if let Some(selector) = version_selector { + candidates.retain(|(_, version)| selector.matches_version(version)); + } + // An unpinned catalog pick is "newest upload". A major.minor line pin is + // "newest stable release in that line", even when an older patch was + // uploaded later. Exact pins match one archive, so the order does not + // change which file they select. + let prefer_newest_line_release = version_selector.is_some_and(selector_is_release_line); candidates.sort_by(|left, right| { - left.0 + let by_mtime = left + .0 .mtime .partial_cmp(&right.0.mtime) - .unwrap_or(Ordering::Equal) - .then_with(|| compare_version_strings(&left.1, &right.1)) + .unwrap_or(Ordering::Equal); + let by_version = compare_version_strings(&left.1, &right.1); + if prefer_newest_line_release { + by_version.then(by_mtime) + } else { + by_mtime.then(by_version) + } }); candidates.pop() } +/// The context added when [`select_tarball_candidate`] finds no archive. +/// +/// That is the only failure it wraps, and on the release channel a different +/// `--version` can clear it, so there the next layout's failure is always +/// followed by the list of releases to try; a nightly one is not (see +/// `NextLayoutRecovery::suggests_releases`). No archive was picked, so no release counts as attempted. The +/// suggested command is a tarball install. It carries no `devel` extras, +/// because a tarball has none. +fn tarball_resolution_failure_context( + channel: TheRockChannel, + layout: SourceLayout, + family_resolution: &FamilyResolution, + version_selector: Option<&RuntimeVersionSelector>, + published: &[String], +) -> String { + let (stream, hint) = match layout { + SourceLayout::Next => { + let recovery = NextLayoutRecovery { + channel, + format: RecoveryFormat::Tarball, + exact_arch: family_resolution.raw_arch.as_deref(), + include_devel: false, + }; + let hint = if recovery.suggests_releases() { + next_layout_unsatisfied_hint( + version_selector, + Some(published), + None, + recovery, + Some(&family_resolution.family), + ) + } else { + format!( + "No {} archive for {} matched this request on the ROCm {THEROCK_NEXT_MIN_MAJOR}+ next layout.", + channel.as_str(), + family_resolution.family + ) + }; + ("next-layout", hint) + } + SourceLayout::Canonical => ( + "canonical", + family_resolution_hint( + &family_resolution.source, + &family_resolution.family, + channel, + "tarball", + ), + ), + }; + format!( + "{stream} TheRock {} tarball stream is incomplete for the resolved GPU family\n\n{hint}", + channel.as_str() + ) +} + fn parse_tarball_index_html(html: &str) -> Result> { let start = html .find("const files = ") @@ -266,6 +355,7 @@ fn validate_tarball_file_name(name: &str) -> Result<()> { #[cfg(test)] mod tests { + use super::super::super::test_support::family_for_test; use super::*; use rocm_core::normalize_therock_family; @@ -449,6 +539,160 @@ mod tests { ); } + #[test] + fn release_line_pin_prefers_the_newest_stable_tarball_in_the_line() { + let platform = platform_tarball_token(); + let files = vec![ + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.1.0.tar.gz"), + mtime: 5.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.1.2.tar.gz"), + mtime: 1.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.1.0a20260822.tar.gz"), + mtime: 9.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-10.0.0.tar.gz"), + mtime: 8.0, + }, + TarballIndexFile { + name: format!("therock-dist-{platform}-gfx120X-all-tests-10.1.3.tar.gz"), + mtime: 9.0, + }, + ]; + let line = RuntimeVersionSelector::version("10.1").unwrap(); + assert_eq!( + select_tarball_candidate( + &files, + TheRockChannel::Release, + SourceLayout::Next, + "gfx120X-all", + Some(&line), + ) + .map(|(_, version)| version), + Some("10.1.2".to_owned()) + ); + + let exact = RuntimeVersionSelector::version("10.1.0").unwrap(); + assert_eq!( + select_tarball_candidate( + &files, + TheRockChannel::Release, + SourceLayout::Next, + "gfx120X-all", + Some(&exact), + ) + .map(|(_, version)| version), + Some("10.1.0".to_owned()) + ); + + // Unpinned, the same catalog keeps "newest upload wins": 10.0.0 was + // uploaded after both 10.1 releases, so it is the pick even though + // its version is lower. Only a line pin orders by version first. + assert_eq!( + select_tarball_candidate( + &files, + TheRockChannel::Release, + SourceLayout::Next, + "gfx120X-all", + None, + ) + .map(|(_, version)| version), + Some("10.0.0".to_owned()) + ); + } + + #[test] + fn tarball_failure_on_next_layout_suggests_a_published_release() { + let family = family_for_test("gfx120X-all", Some("gfx1200")); + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let next = tarball_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + &family, + Some(&line), + &["10.0.0".to_owned()], + ); + assert!( + next.starts_with("next-layout TheRock release tarball"), + "{next}" + ); + assert!( + next.contains("`--version 10.0.0 --family gfx1200`"), + "{next}" + ); + assert!(!next.contains("nightly"), "{next}"); + // An archive catalog has no package stack to speak of. + assert!( + next.contains("No archive for gfx120X-all was found for version 10.1"), + "{next}" + ); + assert!(!next.contains("package stack"), "{next}"); + + // `rocm update` re-resolves a tarball runtime with no pin. The command + // it is given installs a tarball, not the default wheel. + let update = tarball_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + &family, + None, + &["10.0.0".to_owned()], + ); + assert!( + update.contains( + "`rocm install sdk --channel release --format tarball --version 10.0.0 --family gfx1200`" + ), + "{update}" + ); + + // A nightly request on the next layout gets no release list and no + // command: that catalog publishes prerelease archives, which the + // stable-release hint cannot name, and a `--channel release` command + // would move the user off the channel they asked for. + let nightly = tarball_resolution_failure_context( + TheRockChannel::Nightly, + SourceLayout::Next, + &family, + None, + &["10.3.0a20261111".to_owned()], + ); + assert!( + nightly.starts_with("next-layout TheRock nightly tarball"), + "{nightly}" + ); + assert!( + nightly.contains( + "No nightly archive for gfx120X-all matched this request on the ROCm 10+ next layout." + ), + "{nightly}" + ); + for absent in [ + "--version", + "--channel", + "rocm install sdk", + "stable release", + ] { + assert!(!nightly.contains(absent), "{nightly} contains {absent}"); + } + + let canonical = tarball_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Canonical, + &family, + None, + &[], + ); + assert!( + canonical.starts_with("canonical TheRock release tarball"), + "{canonical}" + ); + assert!(canonical.contains("--channel nightly"), "{canonical}"); + } + /// The next nightly catalog lists `-tests-` beside the real archive with a /// later mtime; its prerelease version must still select the real one. #[test] diff --git a/apps/rocm/src/therock/resolve/torchaudio.rs b/apps/rocm/src/therock/resolve/torchaudio.rs index 9abc0a2b5..5609c7522 100644 --- a/apps/rocm/src/therock/resolve/torchaudio.rs +++ b/apps/rocm/src/therock/resolve/torchaudio.rs @@ -2,17 +2,27 @@ // // SPDX-License-Identifier: MIT -//! Which torchaudio build a ROCm 10 or newer install pins, and why. The wheel -//! indexes publish torchaudio rebuilds under one `+rocm` label that -//! nothing in their metadata tells apart, so `wheel` asks `torchaudio_pin` for -//! the build instead of leaving it to `uv`: the hardware-verified release when -//! the index publishes it, the newest build for that ROCm build otherwise. The -//! `TorchaudioPin` it returns carries the reason, and the plan line and the -//! install-log note are both derived from it. Depends on `wheel` for the PEP 440 -//! ordering of package versions. +//! Which torchaudio build a ROCm 10 wheel stack pins, and why. +//! +//! `torchaudio_pin` picks the build for one ROCm release. It prefers the +//! hardware-verified release the vLLM engine records for that ROCm line, and +//! falls back to the newest build (`latest_build_for_rocm`) when none is +//! recorded or it is not published here. `TorchaudioPin` carries the choice +//! and its basis, and `describe` words it. The plan's `torchaudio_selection:` +//! line and `unverified_torchaudio_note`'s install-log note both come from +//! `describe`, so what is printed follows from the decision. A ROCm release +//! with no torchaudio for this Python and platform fails as a +//! `VersionUnsatisfied`, because another release may publish one. +//! +//! A leaf child of `therock/resolve.rs`, split out of `wheel.rs` to keep that +//! module within the size limit. It reads the PEP 440 helpers +//! (`package_release_key`, `package_rocm_suffix`, +//! `package_versions_matching_rocm`) from `wheel.rs`, and `wheel.rs` calls +//! `torchaudio_pin` while resolving the next layout. +use super::next_hint::VersionUnsatisfied; use super::wheel::{package_release_key, package_rocm_suffix, package_versions_matching_rocm}; -use anyhow::{Context, Result, bail}; +use anyhow::{Context, Result}; /// The torchaudio build pinned for a ROCm 10 install, and why it was chosen. /// The plan line and install-log note are both [`TorchaudioPin::describe`], so @@ -117,9 +127,15 @@ pub(super) fn torchaudio_pin( ) -> Result { let built_for_rocm = package_versions_matching_rocm(published, rocm_version); if built_for_rocm.is_empty() { - bail!( - "no torchaudio built for ROCm {rocm_version} is published for this Python and platform in {index_url}" - ); + // Another ROCm release can publish a torchaudio this host can install, + // so a different `--version` can clear this one. + return Err(VersionUnsatisfied::new( + Some(rocm_version), + format!( + "no torchaudio built for ROCm {rocm_version} is published for this Python and platform in {index_url}" + ), + ) + .into()); } let pin = |version, basis| TorchaudioPin { version, diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index 381929ba0..1dd9752fa 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -50,6 +50,9 @@ use super::super::source::{ use super::super::version::{ ParsedVersion, compare_version_strings, is_stable_runtime_version, parse_version, }; +use super::next_hint::{ + NextLayoutRecovery, RecoveryFormat, VersionUnsatisfied, wheel_resolution_failure_context, +}; use super::torchaudio::{TorchaudioPin, torchaudio_pin}; use super::uv_access::{ UvAccess, UvPolicy, VersionResolution, plan_version_resolution, uv_for_compile, @@ -58,7 +61,7 @@ use crate::runtime_registry::WheelRuntimeComposition; use anyhow::{Context, Result, bail}; use rocm_core::{ AppPaths, detect_host_gfx_target, ensure_uv_binary, extract_first_gfx_token, find_uv_binary, - normalize_therock_family, runtime_is_windows, uv_command_env, + normalize_therock_family, uv_command_env, }; use std::io::Write; use std::path::Path; @@ -782,8 +785,12 @@ fn resolve_pip_runtime_plan( let root_html = download_text_cached(paths, &root_cache_key, &root_url, download_timeout_secs)?.text; validate_aggregate_index_layout(&root_html).with_context(|| { + let source_label = match layout { + SourceLayout::Canonical => "canonical source", + SourceLayout::Next => "next-layout source", + }; format!( - "failed to resolve TheRock {} wheel runtime from canonical source {}", + "failed to resolve TheRock {} wheel runtime from {source_label} {}", channel.as_str(), source.wheel_index ) @@ -808,24 +815,55 @@ fn resolve_pip_runtime_plan( ), published_device_targets, }; + // Loaded here rather than inside `resolve_pip_runtime_from_index` so a + // failure further down can name the releases this index does publish. + let recovery = NextLayoutRecovery { + channel, + format: RecoveryFormat::Wheel, + exact_arch: family_resolution.raw_arch.as_deref(), + include_devel, + }; + let rocm_versions = load_simple_index_versions( + paths, + &source.index_url, + "rocm", + None, + download_timeout_secs, + ) + .with_context(|| { + wheel_resolution_failure_context( + channel, + layout, + &source.index_url, + version_selector, + None, + None, + recovery, + ) + })?; resolve_pip_runtime_from_index( paths, channel, &family_resolution, &source, + &rocm_versions, wheel_compatibility, version_selector, include_devel, download_timeout_secs, &uv, ) - .with_context(|| { - format!( - "failed to resolve TheRock {} wheel runtime from canonical source {}\n\n{}", - channel.as_str(), - source.index_url, - canonical_wheel_resolution_hint(channel) - ) + .map_err(|error| { + let context = wheel_resolution_failure_context( + channel, + layout, + &source.index_url, + version_selector, + Some(&rocm_versions), + VersionUnsatisfied::find(&error), + recovery, + ); + error.context(context) }) } @@ -838,6 +876,7 @@ fn resolve_pip_runtime_from_index( channel: TheRockChannel, family_resolution: &FamilyResolution, source: &ResolvedAggregateWheelSource, + rocm_versions: &[String], wheel_compatibility: &WheelCompatibility, version_selector: Option<&RuntimeVersionSelector>, include_devel: bool, @@ -847,8 +886,6 @@ fn resolve_pip_runtime_from_index( let index_url = source.index_url.as_str(); let mut version_resolution_specs = None; let mut torchaudio_selection = None; - let rocm_versions = - load_simple_index_versions(paths, index_url, "rocm", None, download_timeout_secs)?; if matches!(channel, TheRockChannel::Release) && version_selector.is_none() && !rocm_versions @@ -863,7 +900,7 @@ fn resolve_pip_runtime_from_index( // Only meaningful when we auto-selected "latest" (no explicit request), so a // caller can warn when that newest version has no installable wheels. let newest_repo_version = if version_selector.is_none() { - channel_rocm_candidates(&rocm_versions, channel) + channel_rocm_candidates(rocm_versions, channel) .into_iter() .last() } else { @@ -895,7 +932,7 @@ fn resolve_pip_runtime_from_index( )?; select_matching_pip_package_versions( channel, - &rocm_versions, + rocm_versions, &torch_versions, &torchvision_versions, &torchaudio_versions, @@ -950,7 +987,7 @@ fn resolve_pip_runtime_from_index( download_timeout_secs, )?; rocm_versions_with_full_stack( - &rocm_versions, + rocm_versions, [&torch_versions, &torchvision_versions, &torchaudio_versions], ) } else { @@ -962,25 +999,42 @@ fn resolve_pip_runtime_from_index( // torchaudio by name; a missing torch or torchvision fails in // `uv pip compile`. let installable_rocm_versions = if with_full_stack.is_empty() { - &rocm_versions + rocm_versions } else { - &with_full_stack + with_full_stack.as_slice() }; let rocm_version = select_rocm_version(channel, installable_rocm_versions, version_selector) - .with_context(|| { + .ok_or_else(|| { let requested = version_selector.map_or_else( || "latest compatible version".to_owned(), RuntimeVersionSelector::describe, ); - format!("no TheRock rocm package was found for {requested} in {index_url}") + VersionUnsatisfied::new( + None, + format!( + "no TheRock rocm package was found for {requested} in {index_url}" + ), + ) })?; let pin = torchaudio_pin( &torchaudio_versions, &rocm_version, rocm_engine_vllm::verified_torchaudio_release(&rocm_version), index_url, - )?; + ) + .map_err(|error| { + // With no pin, the build was taken from those with a full stack, + // so a build without torchaudio means none has one (the full list + // is the fallback). Another `--version` fails the same way, so + // the failure must not carry the marker that triggers a + // suggestion. + if version_selector.is_none() && with_full_stack.is_empty() { + anyhow::anyhow!("{error:#}") + } else { + error + } + })?; let requirements = published_pip_requirements( &rocm_version, &pin.version, @@ -1017,6 +1071,7 @@ fn resolve_pip_runtime_from_index( let versions = resolve_published_pip_package_versions( paths, &compile_uv, + &rocm_version, index_url, &requirements, wheel_compatibility, @@ -1149,6 +1204,7 @@ fn parse_uv_compiled_package_versions(output: &str) -> Result anyhow::Error { + let detail = stderr.trim(); + let message = format!("published ROCm X package metadata is not jointly installable: {detail}"); + if detail.contains("No solution found") { + VersionUnsatisfied::new(Some(rocm_version), message).into() + } else { + anyhow::Error::msg(message) + } +} + fn select_matching_pip_package_versions( channel: TheRockChannel, rocm_versions: &[String], @@ -1391,36 +1466,16 @@ fn highest_candidate_needs_next_python( .is_some_and(|parsed| parsed.major >= THEROCK_NEXT_MIN_MAJOR) } -/// Recovery guidance appended to family/index resolution failures so a clean -/// first run can recover without the user having to guess a `--family`. -/// -/// `source` is the [`FamilyResolution::source`] that produced `family`: -/// auto-detected (`host`, `managed-runtime`) versus user-supplied (`manifest` -/// from `--family`, `env` from `ROCM_CLI_THEROCK_FAMILY`). The wording differs -/// so an auto-detected miss points the user at `--family`, while a user-supplied -/// miss confirms the family they already named. Both point at the other channel -/// and, where valid for the platform, the other install format. -fn canonical_wheel_resolution_hint(channel: TheRockChannel) -> String { - let other_channel = match channel { - TheRockChannel::Release => "nightly", - TheRockChannel::Nightly => "release", - }; - let mut hint = format!( - "No complete compatible package stack was found in the canonical {} aggregate stream. Try `--channel {other_channel}`", - channel.as_str() - ); - if !runtime_is_windows() { - hint.push_str(" or `--format tarball`"); - } - hint.push('.'); - hint -} - #[cfg(test)] mod tests { + use super::super::super::source::{ + THEROCK_NEXT_PIP_INDEX_BASE, THEROCK_RELEASE_PIP_INDEX_BASE, + }; use super::super::super::test_support::test_runtime_manifest; + use super::super::next_hint::canonical_wheel_resolution_hint; use super::*; use crate::runtime_registry::{InstalledRuntimeManifest, wheel_composition_includes_devel}; + use rocm_core::runtime_is_windows; use std::path::PathBuf; /// A representative slice of what the canonical aggregate index publishes. @@ -2331,11 +2386,17 @@ mod tests { find_present: &find_present, acquire: &acquire, }; + // `resolve_pip_runtime_plan` reads the `rocm` listing before it + // calls this, so the test does too. + let rocm_versions = + load_simple_index_versions(&paths, &source.index_url, "rocm", None, None) + .expect("the fixture index lists rocm"); let plan = resolve_pip_runtime_from_index( &paths, TheRockChannel::Release, &super::super::super::test_support::family_for_test("gfx1200", Some("gfx1200")), &source, + &rocm_versions, &compatibility, None, false, @@ -2911,4 +2972,190 @@ sdk install ); } } + + const WHEEL_AT_GFX1201: NextLayoutRecovery<'static> = NextLayoutRecovery { + channel: TheRockChannel::Release, + format: RecoveryFormat::Wheel, + exact_arch: Some("gfx1201"), + include_devel: false, + }; + + /// The wording is produced by [`wheel_resolution_failure_context`], which + /// `resolve_pip_runtime_plan` appends when resolution fails. The + /// install that prints it, and the re-run that proves its suggestion + /// clears the failure, is `@id:therock-next-25-unsatisfied-line-pin-skips-nightly`. + #[test] + fn unsatisfied_rocm_10_line_pin_does_not_suggest_nightly() { + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let published = vec!["10.0.0".to_owned()]; + let unsatisfied = + VersionUnsatisfied::new(None, "no TheRock rocm package was found".to_owned()); + let message = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, + Some(&line), + Some(&published), + Some(&unsatisfied), + WHEEL_AT_GFX1201, + ); + assert!( + !message.contains("nightly"), + "a ROCm 10 pin must not be told to try nightly: {message}" + ); + assert!(message.contains("next layout"), "{message}"); + assert!(message.contains(THEROCK_NEXT_PIP_INDEX_BASE), "{message}"); + assert!( + message.contains("`--version 10.0.0 --family gfx1201`"), + "the suggestion must name a published release and the arch the request used: {message}" + ); + assert!( + !message.contains("--version 10.1"), + "the index publishes no 10.1 release, so none may be suggested: {message}" + ); + + // Canonical misses keep the other-channel hint. The 10.1 advice is the + // next-layout branch, not a rewrite of every resolution error. + let canonical = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Canonical, + THEROCK_RELEASE_PIP_INDEX_BASE, + None, + Some(&published), + None, + WHEEL_AT_GFX1201, + ); + assert!(canonical.contains("--channel nightly"), "{canonical}"); + assert!(canonical.contains("canonical source"), "{canonical}"); + } + + /// A next-layout failure a different `--version` cannot clear gets no + /// version advice: only the source it searched. An undetermined device + /// target, a `uv` that could not be fetched and an unreachable index each + /// fail again on any release, so naming one would send the user to a + /// re-run that meets the same error. The end-to-end case, an update whose + /// runtime records no exact arch, is therock-next-28. + #[test] + fn a_next_layout_failure_no_version_can_clear_suggests_no_version() { + let line = RuntimeVersionSelector::version("10.1").unwrap(); + let published = vec!["10.0.0".to_owned(), "10.1.0".to_owned()]; + let context = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, + Some(&line), + Some(&published), + None, + WHEEL_AT_GFX1201, + ); + assert_eq!( + context, + format!( + "failed to resolve TheRock release wheel runtime from next-layout source {THEROCK_NEXT_PIP_INDEX_BASE}" + ) + ); + + // The listing itself could not be read: say so, still without a version. + let unreadable = wheel_resolution_failure_context( + TheRockChannel::Release, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, + Some(&line), + None, + None, + WHEEL_AT_GFX1201, + ); + assert!( + unreadable.contains("so no other version can be suggested"), + "{unreadable}" + ); + assert!(!unreadable.contains("--version"), "{unreadable}"); + } + + /// A nightly request reads the next layout too, but that layout publishes + /// only prerelease builds for it, which the stable-release hint cannot name. + /// Even a failure another release could clear gets no release list and no + /// `--channel release` command, which would move the user off the channel + /// they asked for. + #[test] + fn a_nightly_next_layout_failure_suggests_no_release() { + let nightly = NextLayoutRecovery { + channel: TheRockChannel::Nightly, + ..WHEEL_AT_GFX1201 + }; + let published = vec!["10.3.0a20261110".to_owned(), "10.3.0a20261111".to_owned()]; + let unsatisfied = VersionUnsatisfied::new( + Some("10.3.0a20261111"), + "no torchaudio built for ROCm 10.3.0a20261111 is published".to_owned(), + ); + for (selector, listing) in [(None, Some(published.as_slice())), (None, None)] { + let context = wheel_resolution_failure_context( + TheRockChannel::Nightly, + SourceLayout::Next, + THEROCK_NEXT_PIP_INDEX_BASE, + selector, + listing, + Some(&unsatisfied), + nightly, + ); + assert_eq!( + context, + format!( + "failed to resolve TheRock nightly wheel runtime from next-layout source {THEROCK_NEXT_PIP_INDEX_BASE}" + ) + ); + } + } + + /// The three failures a different release can clear are raised as the + /// marker, each recording the release it tried where there was one, and + /// each keeping its own message. + #[test] + fn the_version_clearable_failures_are_marked_and_the_rest_are_not() { + // No torchaudio for this release on this platform. + let error = torchaudio_pin( + &["2.11.0+rocm10.1.0".to_owned()], + "10.0.0", + None, + "https://index.test", + ) + .expect_err("no torchaudio is built for ROCm 10.0.0"); + let marker = VersionUnsatisfied::find(&error).expect("a missing torchaudio is marked"); + assert_eq!(marker.attempted(), Some("10.0.0")); + assert!( + error + .to_string() + .starts_with("no torchaudio built for ROCm 10.0.0 is published"), + "{error}" + ); + + // `uv` found no solution for the release: marked. + let unsatisfiable = uv_compile_failure( + "10.1.0", + " x No solution found when resolving dependencies:\n torch==2.11.0 is unavailable\n", + ); + assert_eq!( + VersionUnsatisfied::find(&unsatisfiable).and_then(VersionUnsatisfied::attempted), + Some("10.1.0") + ); + assert!( + unsatisfiable.to_string().starts_with( + "published ROCm X package metadata is not jointly installable: x No solution found" + ), + "{unsatisfiable}" + ); + + // `uv` could not reach the index: not marked, same message shape. + let unreachable = uv_compile_failure( + "10.1.0", + "error: Failed to fetch: `http://127.0.0.1:9/next/torch/`\n Connection refused\n", + ); + assert!(VersionUnsatisfied::find(&unreachable).is_none()); + assert!( + unreachable + .to_string() + .starts_with("published ROCm X package metadata is not jointly installable: error: Failed to fetch"), + "{unreachable}" + ); + } } diff --git a/apps/rocm/src/therock/source.rs b/apps/rocm/src/therock/source.rs index 29147bfff..cbb61436b 100644 --- a/apps/rocm/src/therock/source.rs +++ b/apps/rocm/src/therock/source.rs @@ -14,19 +14,20 @@ use super::version::{ VersionStage, normalize_requested_build_date, parse_version, runtime_version_build_date, + stable_release_line_pin, version_request_matches, }; use anyhow::{Result, bail}; use rocm_core::detect_host_gpu_diagnostics; const THEROCK_NIGHTLY_PIP_INDEX_BASE: &str = "https://rocm.nightlies.amd.com/whl-multi-arch"; -const THEROCK_RELEASE_PIP_INDEX_BASE: &str = "https://repo.amd.com/rocm/whl-multi-arch"; +pub(super) const THEROCK_RELEASE_PIP_INDEX_BASE: &str = "https://repo.amd.com/rocm/whl-multi-arch"; const THEROCK_RELEASE_TARBALL_BASE: &str = "https://repo.amd.com/rocm/tarball/"; const THEROCK_NIGHTLY_TARBALL_BASE: &str = "https://rocm.nightlies.amd.com/tarball/"; /// The next layout's stable aggregate pip index. Same simple-index shape the /// canonical multi-arch stream publishes, on a separate host, with its own /// package generation; it is not a mirror of, or a fallback for, the canonical /// index. -const THEROCK_NEXT_PIP_INDEX_BASE: &str = "https://stable.repo.amd.com/rocm/whl-next"; +pub(super) const THEROCK_NEXT_PIP_INDEX_BASE: &str = "https://stable.repo.amd.com/rocm/whl-next"; /// The next layout's stable tarball catalog. Same scrapeable listing the /// canonical catalog uses, but it publishes non-release sibling archives beside /// the real dist archive (see `select_tarball_candidate` in `resolve/tarball.rs`). @@ -150,12 +151,21 @@ impl RuntimeVersionSelector { pub(super) fn matches_version(&self, version: &str) -> bool { match self { - Self::Version(requested) => version == requested, + Self::Version(requested) => version_request_matches(requested, version), Self::BuildDate(date) => runtime_version_build_date(version).as_deref() == Some(date), } } } +/// Whether `selector` pins a `major.minor` release line rather than one +/// release. +pub(super) fn selector_is_release_line(selector: &RuntimeVersionSelector) -> bool { + matches!( + selector, + RuntimeVersionSelector::Version(version) if stable_release_line_pin(version).is_some() + ) +} + impl TheRockChannel { pub(super) fn parse(value: &str) -> Result { match value.trim().to_ascii_lowercase().as_str() { @@ -255,6 +265,8 @@ pub(super) fn resolve_source(channel: TheRockChannel, layout: SourceLayout) -> R /// channel names a release, so it routes to the next layout, where /// [`select_source_layout`] refuses it. /// +/// A `major.minor` pin (`10.1`) is a release pin for that line and routes as +/// its stable releases do; a prerelease of it never reads as a line. /// A pin this CLI cannot read stays canonical: nothing can be said about where /// it lives, and the canonical lookup fails on it as it always has. pub(super) fn layout_serving( @@ -275,11 +287,17 @@ pub(super) fn layout_serving( (TheRockChannel::Nightly, RuntimeVersionSelector::BuildDate(date)) => by_build_date(date), (TheRockChannel::Release, RuntimeVersionSelector::BuildDate(_)) => SourceLayout::Canonical, (_, RuntimeVersionSelector::Version(version)) => { - let Some(parsed) = parse_version(version) else { - return SourceLayout::Canonical; + // `parse_version` reads only `major.minor.patch`; a `major.minor` + // line pin (`10.1`) is a stable release pin too, routed by its major. + let stable_next = match parse_version(version) { + Some(parsed) => { + parsed.stage == VersionStage::Stable && parsed.major >= THEROCK_NEXT_MIN_MAJOR + } + None => match stable_release_line_pin(version) { + Some((major, _)) => major >= THEROCK_NEXT_MIN_MAJOR, + None => return SourceLayout::Canonical, + }, }; - let stable_next = - parsed.stage == VersionStage::Stable && parsed.major >= THEROCK_NEXT_MIN_MAJOR; match channel { TheRockChannel::Release if stable_next => SourceLayout::Next, TheRockChannel::Release => SourceLayout::Canonical, @@ -310,12 +328,10 @@ pub(super) fn select_source_layout( } if let Some(RuntimeVersionSelector::Version(version)) = version_selector && matches!(channel, TheRockChannel::Nightly) - && let Some(parsed) = parse_version(version) - && parsed.stage == VersionStage::Stable + && let Some(major) = stable_pin_major(version) { bail!( - "ROCm {} and newer stable releases are published only on the release channel; re-run `rocm install sdk --channel release --version {version}`", - parsed.major + "ROCm {major} and newer stable releases are published only on the release channel; re-run `rocm install sdk --channel release --version {version}`" ); } if family_resolution.raw_arch.is_none() { @@ -331,6 +347,17 @@ pub(super) fn select_source_layout( Ok(SourceLayout::Next) } +/// The major of a stable pin: an exact `major.minor.patch` stable release or a +/// `major.minor` line. A `parse_version` miss falls to the line parser, so an +/// `11.2` request is told ROCm 11, not the minimum next-layout major. `None` +/// for a prerelease or anything unreadable. +fn stable_pin_major(version: &str) -> Option { + match parse_version(version) { + Some(parsed) => (parsed.stage == VersionStage::Stable).then_some(parsed.major), + None => stable_release_line_pin(version).map(|(major, _)| major), + } +} + /// One real arch that `family` groups, for the remediation text. `None` for a /// family with no entry here, which the caller words as a placeholder rather /// than naming an arch from a different family. @@ -392,6 +419,7 @@ pub(super) fn requested_source_layout( mod tests { use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; + use crate::therock::resolve::select_rocm_version; use crate::therock::test_support::family_for_test; /// Which layout serves a request, for every shape of request on both @@ -783,4 +811,206 @@ mod tests { SourceLayout::Next ); } + + /// `--version 10.1` is a stable 10.1 line, not a failed parse and not the + /// literal `10.1.0`. It must take the next layout, the same exact-arch + /// gate as `10.1.0`, and the newest stable release in that line. A + /// three-component pin stays exact, a prerelease is not a line pin, and + /// an unpinned request reads the newest layout. + #[test] + fn two_component_version_pin_routes_and_matches_its_release_line() { + let exact = family_for_test("gfx120X-all", Some("gfx1200")); + let grouped = family_for_test("gfx120X-all", None); + let line = RuntimeVersionSelector::version("10.1").unwrap(); + + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&line)).unwrap(), + SourceLayout::Next, + "a ROCm 10.1 line pin must leave the canonical index" + ); + assert_eq!( + requested_source_layout(TheRockChannel::Release, None, Some(&line)), + SourceLayout::Next + ); + assert!( + line.matches_version("10.1.0"), + "10.1 must match the published 10.1.0 release" + ); + assert!(line.matches_version("10.1.2")); + assert!( + !line.matches_version("10.1.0a20260822"), + "a line pin must not swallow a prerelease in that line" + ); + assert!(!line.matches_version("10.0.0")); + assert!( + !line.matches_version("10.10.0"), + "10.1 must not prefix-match 10.10" + ); + // Same minor, another major: only the major check rejects these. + assert!( + !line.matches_version("11.1.0"), + "10.1 must not match a later major's 1 line" + ); + assert!(!line.matches_version("9.1.0")); + + let selected = select_rocm_version( + TheRockChannel::Release, + &[ + "10.0.0".to_owned(), + "10.1.0".to_owned(), + "10.1.0a20260822".to_owned(), + "10.1.2".to_owned(), + "10.10.0".to_owned(), + "7.14.1".to_owned(), + ], + Some(&line), + ); + assert_eq!(selected.as_deref(), Some("10.1.2")); + + let grouped_error = select_source_layout(TheRockChannel::Release, &grouped, Some(&line)) + .expect_err("a 10.1 line pin still requires an exact arch") + .to_string(); + assert!( + grouped_error.contains("requires an exact GPU arch"), + "{grouped_error}" + ); + assert!( + grouped_error.contains("--family gfx1200"), + "{grouped_error}" + ); + + let nightly_error = select_source_layout(TheRockChannel::Nightly, &exact, Some(&line)) + .expect_err("a 10.1 line pin has no nightly stream") + .to_string(); + assert!( + nightly_error.contains("--channel release"), + "{nightly_error}" + ); + assert!( + !nightly_error.contains("try `--channel nightly`"), + "{nightly_error}" + ); + + // A post-release is not a release of the line: the release channel + // installs only `X.Y.Z` stables (`is_stable_runtime_version`), and a + // line pin must not reach what an unpinned pick on that channel skips. + assert!(!line.matches_version("10.1.0.post1")); + assert_eq!( + select_rocm_version( + TheRockChannel::Release, + &["10.1.0".to_owned(), "10.1.0.post1".to_owned()], + Some(&line), + ) + .as_deref(), + Some("10.1.0") + ); + + // PEP 440 reads release components as integers, so `10.01` is `10.1`, + // as `uv` and pip read it. It routes and matches as the 10.1 line. + let zero_padded = RuntimeVersionSelector::version("10.01").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&zero_padded)).unwrap(), + SourceLayout::Next + ); + assert!(zero_padded.matches_version("10.1.2")); + assert!(!zero_padded.matches_version("10.10.0")); + + // A line pin's refusals name its own major, not the ROCm 10 floor. + let later_line = RuntimeVersionSelector::version("11.2").unwrap(); + let later_nightly_error = + select_source_layout(TheRockChannel::Nightly, &exact, Some(&later_line)) + .expect_err("an 11.2 line pin has no nightly stream") + .to_string(); + assert!( + later_nightly_error.starts_with("ROCm 11 and newer stable releases are published only"), + "{later_nightly_error}" + ); + + // A component past u32 is not a line pin. Truncating 2^32 + 10 would + // read it as the ROCm 10 line and leave the canonical index. + let overflowing = RuntimeVersionSelector::version("4294967306.1").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&overflowing)).unwrap(), + SourceLayout::Canonical + ); + assert!(!overflowing.matches_version("10.1.0")); + + // Routes that already worked must not move. + let exact_next = RuntimeVersionSelector::version("10.1.0").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&exact_next)).unwrap(), + SourceLayout::Next + ); + assert!(exact_next.matches_version("10.1.0")); + assert!(!exact_next.matches_version("10.1.2")); + assert!(!exact_next.matches_version("10.1")); + + let older = RuntimeVersionSelector::version("7.14.1").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&older)).unwrap(), + SourceLayout::Canonical + ); + assert!(older.matches_version("7.14.1")); + assert!(!older.matches_version("7.14.0")); + assert!(!older.matches_version("7.14.2")); + + let older_line = RuntimeVersionSelector::version("7.14").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&older_line)).unwrap(), + SourceLayout::Canonical, + "a two-component pin below ROCm 10 stays on the canonical index" + ); + assert!(older_line.matches_version("7.14.0")); + assert!(older_line.matches_version("7.14.1")); + assert!(!older_line.matches_version("7.15.0")); + assert_eq!( + select_rocm_version( + TheRockChannel::Release, + &[ + "7.14.0".to_owned(), + "7.14.1".to_owned(), + "7.15.0".to_owned() + ], + Some(&older_line), + ) + .as_deref(), + Some("7.14.1") + ); + + // A four-component publish is still a stable release of its line. + let four_component_line = RuntimeVersionSelector::version("7.2").unwrap(); + assert!(four_component_line.matches_version("7.2.4.70204")); + assert!(!four_component_line.matches_version("7.20.4.70204")); + assert!(!four_component_line.matches_version("7.2.4.70204rc1")); + assert_eq!( + select_rocm_version( + TheRockChannel::Release, + &["7.2.3".to_owned(), "7.2.4.70204".to_owned()], + Some(&four_component_line), + ) + .as_deref(), + Some("7.2.4.70204") + ); + + let prerelease = RuntimeVersionSelector::version("10.1.0a20260822").unwrap(); + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, Some(&prerelease)).unwrap(), + SourceLayout::Canonical, + "a prerelease must not be read as a stable two-component pin" + ); + assert_eq!( + select_source_layout(TheRockChannel::Nightly, &exact, Some(&prerelease)).unwrap(), + SourceLayout::Canonical + ); + + assert_eq!( + select_source_layout(TheRockChannel::Release, &exact, None).unwrap(), + SourceLayout::Next, + "an unpinned request reads the newest layout" + ); + assert_eq!( + requested_source_layout(TheRockChannel::Release, None, None), + SourceLayout::Next + ); + } } diff --git a/apps/rocm/src/therock/version.rs b/apps/rocm/src/therock/version.rs index 33e086fd0..0e6c82887 100644 --- a/apps/rocm/src/therock/version.rs +++ b/apps/rocm/src/therock/version.rs @@ -4,9 +4,11 @@ //! Version grammar for TheRock runtimes: the strict gate an install is routed //! on ([`parse_version`]), the PEP 440 ordering used to pick the newest build -//! ([`compare_version_strings`], [`version_relation`]), the host-version -//! reader, and the build-date helpers behind `--build-date` and the version -//! display. +//! ([`compare_version_strings`], [`version_relation`]), the `--version` +//! request grammar (an exact `major.minor.patch`, or a `major.minor` line pin +//! read by [`stable_release_line_pin`] that matches the stable releases of that +//! line), the host-version reader, and the build-date helpers behind +//! `--build-date` and the version display. //! //! A leaf of the `therock` module: nothing here depends on the rest of it. @@ -70,7 +72,10 @@ pub(super) enum VersionStage { /// Total order over published version strings — the total order used for /// sorting candidates in the `therock` module's "which build does the user get?" /// decisions. It is not always the first key: `select_tarball_candidate` (in -/// `resolve/tarball.rs`) orders by upload time first and uses this only to break ties. +/// `resolve/tarball.rs`) orders an unpinned catalog by upload time first and +/// uses this only to break ties. A `major.minor` line pin orders by this key +/// first, so the newest stable release in the line wins even when an older +/// patch was uploaded later. /// /// Ordering is PEP 440's, because these strings come from a Python simple /// index: within one release `7.0.0.dev1` < `7.0.0a1` < `7.0.0b1` < @@ -248,6 +253,52 @@ pub(super) fn parse_version_for_ordering(value: &str) -> Option }) } +/// Whether a requested version string selects the published `version`. +/// +/// A stable two-component pin (`10.1`) selects every stable release in that +/// major.minor line. Callers that want one of them take the newest. A +/// three-component pin, including a prerelease suffix, stays an exact string +/// match: `10.1.0` does not select `10.1.1`, and `10.1.0a20260822` is not the +/// `10.1` line. +pub(super) fn version_request_matches(requested: &str, published: &str) -> bool { + if let Some((major, minor)) = stable_release_line_pin(requested) { + return published_in_stable_line(published, major, minor); + } + published == requested +} + +/// A stable `major.minor` pin: two numeric components and nothing after them. +/// +/// `10.1` names the 10.1 line. `10.1.0` is an exact pin. `10.1.0a20260822` is +/// a prerelease, so it is not this shape and a line pin's parser cannot +/// retarget it onto the next layout. +pub(super) fn stable_release_line_pin(value: &str) -> Option<(u32, u32)> { + let (major, rest) = split_u32_prefix(value)?; + let rest = rest.strip_prefix('.')?; + let (minor, rest) = split_u32_prefix(rest)?; + rest.is_empty().then_some((major, minor)) +} + +fn split_u32_prefix(value: &str) -> Option<(u32, &str)> { + let (number, rest) = split_leading_number(value)?; + Some((u32::try_from(number).ok()?, rest)) +} + +/// Whether `published` is a stable release of the `major.minor` line. +/// +/// Reads `published` with the lenient [`parse_version_for_ordering`], not the +/// strict three-component [`parse_version`], because an index can publish a +/// four-component release such as `7.2.4.70204`, and that is still a stable +/// release of the 7.2 line. The ordering key drops trailing zeros, so a +/// missing minor component reads as zero, as PEP 440 pads it. +fn published_in_stable_line(published: &str, major: u32, minor: u32) -> bool { + parse_version_for_ordering(published).is_some_and(|key| { + key.stage == VersionStage::Stable + && key.release.first().copied().unwrap_or(0) == u64::from(major) + && key.release.get(1).copied().unwrap_or(0) == u64::from(minor) + }) +} + /// Split a leading run of ASCII digits off `value`, returning it and the rest. /// `None` when `value` does not start with a digit, or the digits overflow. fn split_leading_number(value: &str) -> Option<(u64, &str)> { diff --git a/docs/architecture.md b/docs/architecture.md index 75d87bf0e..ea2e9502f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -144,14 +144,15 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`therock/python.rs`](../apps/rocm/src/therock/python.rs) | The Python an install runs on: finding or provisioning an interpreter (`resolve_python_launcher`, `plan_python_launcher`), narrowing the requirement to an explicit `--python-version` or a runtime's recorded wheel tag, the wheel tags it accepts, and the runtime's virtual environment. | domain | | [`therock/python_config_props.rs`](../apps/rocm/src/therock/python_config_props.rs) | Property tests for how the managed-Python step, a `config.json` writer, treats a `config.json` it cannot read (it never replaces one with defaults, and creates a missing one), and for the legacy rocm-dash tick migration that could produce one. Declared from [`therock/python.rs`](../apps/rocm/src/therock/python.rs). | flat | | [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) | Module declarations and re-exports for artifact resolution under `therock/resolve/`; holds no logic. | domain | -| [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) | Resolving the SDK tarball a request installs from the catalog's index (`resolve_tarball_artifact`). | domain | +| [`therock/resolve/next_hint.rs`](../apps/rocm/src/therock/resolve/next_hint.rs) | What a failed ROCm 10 resolution suggests next: a failure a different `--version` can clear is a `VersionUnsatisfied` carrying the release attempted, and the hint lists the other stable releases the next layout publishes, with the caller's `--format`; `wheel_resolution_failure_context` words the whole wheel failure for both layouts. | domain | +| [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) | Resolving the SDK tarball a request installs from the catalog's index (`resolve_tarball_artifact`); a `major.minor` line pin takes the newest stable release in the line, an unpinned pick the newest upload. | domain | | [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) | Who may fetch `uv` while a wheel stack is resolved (`UvAccess`, `plan_version_resolution`), as a pure decision over layout, access and whether `uv` is present. | domain | -| [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) | Resolving the wheel stack (`rocm`, `torch`, `torchvision`, `torchaudio`) and device payload a request installs (`resolve_pip_runtime`, `preview_pip_runtime`); on the next layout it drops a `rocm` build that lacks a framework package (`rocm_versions_with_full_stack`) before pinning torchaudio. | domain | +| [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) | Resolving the wheel stack (`rocm`, `torch`, `torchvision`, `torchaudio`) and device payload a request installs (`resolve_pip_runtime`, `preview_pip_runtime`); on the next layout it drops a `rocm` build that lacks a framework package (`rocm_versions_with_full_stack`) before pinning torchaudio; a `major.minor` pin matches the newest release in that line. | domain | | [`therock/resolve/torchaudio.rs`](../apps/rocm/src/therock/resolve/torchaudio.rs) | Which torchaudio build a ROCm 10 or newer install pins, and why (`torchaudio_pin`, `TorchaudioPin`); the plan line and install-log note derive from the same pin. | domain | -| [`therock/source.rs`](../apps/rocm/src/therock/source.rs) | Where an install reads from: channel, hosting layout (the next layout's `stable.repo.amd.com`/`nightly.repo.amd.com`, or the earlier stream kept for pins that exist only there) and artifact bases (with the opt-in base override), the one routing rule `layout_serving` and its refusals (`select_source_layout`, `gate_install_layout`), plus the pinned version selector and the resolved family. | domain | +| [`therock/source.rs`](../apps/rocm/src/therock/source.rs) | Where an install reads from: channel, hosting layout (the next layout's `stable.repo.amd.com`/`nightly.repo.amd.com`, or the earlier stream kept for pins that exist only there) and artifact bases (with the opt-in base override), the one routing rule `layout_serving` (which routes a `major.minor` line pin by its major, as it does an exact stable release) and its refusals (`select_source_layout`, `gate_install_layout`), plus the pinned version selector and the resolved family. | domain | | [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) | Test-only fixtures shared by the `therock/` children's tests and the tests left in [`therock.rs`](../apps/rocm/src/therock.rs). | flat | | [`therock/update.rs`](../apps/rocm/src/therock/update.rs) | Whether an installed runtime has something newer (`runtime_update_plan`, `runtime_update_check`), the update report and JSON, and the bounded startup check. | domain | -| [`therock/version.rs`](../apps/rocm/src/therock/version.rs) | Version grammar for TheRock runtimes: the strict install gate (`parse_version`), PEP 440 ordering, host-version parsing and the build-date helpers. | domain | +| [`therock/version.rs`](../apps/rocm/src/therock/version.rs) | Version grammar for TheRock runtimes: the strict install gate (`parse_version`), PEP 440 ordering, the `--version` request grammar (an exact release, or a `major.minor` line pin matching that line's stable releases), host-version parsing and the build-date helpers. | domain | | [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) | The `sdk install` plan a wheel install prints, from one writer for a preview and a real install, resolved or not. | domain | | [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs) | Property tests for version ordering, update verdicts and update-source selection, declared from [`therock.rs`](../apps/rocm/src/therock.rs). | flat | | [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) | The chat assistant's tool-call policy: which `rocm` commands and bridge tools a model may request, which run at once, which need approval, and the validators that refuse unsafe calls. | flat | diff --git a/docs/manual-testing.md b/docs/manual-testing.md index f7bab1843..3d5b9051d 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -295,6 +295,23 @@ Use `--family` only when a test needs a fixed package family. Do not use it for normal user setup. The script checks the default install; add `--devel` to check the opt-in compiler toolchain path instead. +Version pins, checked with `--dry-run`: + +- `rocm install sdk --version 10.1 --family --dry-run` previews the + newest stable 10.1.x from the ROCm 10 source (`source_layout_generation: + next-v1`), and `--version 10.1.0` previews exactly 10.1.0. +- `--version 7.14 --dry-run` previews the newest stable 7.14.x from the + canonical index. +- A ROCm 10 pin the source cannot satisfy fails with a list of the other + stable ROCm 10 releases it publishes, if any, and a `--version` to try. Running that suggestion + must succeed, and the error must not suggest `--channel nightly`. +- A `rocm update --apply` of a ROCm 10 runtime that fails the same way + suggests a whole `rocm install sdk` command with the runtime's `--format` + and, for a `--devel` runtime, `--devel`. Running that command with + `--dry-run` must succeed. A failure no other version can clear, such as an + unknown device target, must suggest no version, and so must a failed + `--channel nightly` install or update. + ### 2a. A GPU target with no ROCm build Any machine can run this one; it needs no particular GPU. `gfx90c` is the Vega diff --git a/docs/testing.md b/docs/testing.md index 9c42bb5fd..b9b5de860 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1365,6 +1365,49 @@ Then it verifies: `rocm_sdk.find_libraries("amdhip64", "hipblas")` - vLLM adapter discovery of the managed TheRock runtime environment +`--version` accepts a `major.minor` line as well as an exact +`major.minor.patch`. `--version 10.1` resolves the newest stable 10.1.x on the +ROCm 10 next layout, and `--version 7.14` the newest stable 7.14.x on the +canonical index. A `major.minor.patch` pin stays exact. When a ROCm 10 pin +cannot be satisfied because no release matches, the release has no torchaudio +for this Python and platform, or `uv` finds no installable package set for it, +the error lists the other stable ROCm 10 releases that layout publishes, if +any, and suggests one of them, never the release that just failed and never +`--channel nightly`. An install is told which `--version`/`--family` to re-run +with. `rocm update`, which has neither flag, is given a whole +`rocm install sdk` command with the runtime's `--format` and `--devel`. Any +other failure, such as an unknown device target, a `uv` that could not be +fetched or an unreachable index, suggests no version, because no release can +clear it. A nightly request that fails on the ROCm 10 layout gets no +suggestion either: that layout publishes only prerelease builds for the +nightly channel, which the stable-release list cannot name. + +Loopback-fixture scenarios in +[therock_next_generation.feature](../tests/e2e-cucumber/features/therock_next_generation.feature) +cover this: + +- `therock-next-24`: a wheel line pin takes the line's newest stable build, + not an older one, a prerelease or a `10.10` build. +- `therock-next-25`: an unsatisfied wheel pin. The scenario re-runs the + suggested command to prove it succeeds. +- `therock-next-26`: a tarball line pin takes the newest release in the line, + not the newest upload. +- `therock-next-27`: an unsatisfied tarball pin lists the archives the catalog + publishes. The scenario re-runs the suggestion. +- `therock-next-28`: an update whose runtime records no exact arch gets no + version or `--family` advice. +- `therock-next-29`: an exact pin ignores later patches. +- `therock-next-30`: a canonical `7.14` line pin. +- `therock-next-31`: an unpinned install where no build has an installable + torchaudio fails with no version suggested, because another version would + fail the same way. +- `therock-next-32`: an update whose newest release has no installable package + set (a real `uv pip compile` reports no solution) suggests an install that + keeps the runtime's format and toolchain. The scenario runs that command. + +They run in the default e2e lane. `therock-next-26` and `therock-next-27` are +Linux-only, because Windows refuses tarball installs. + Run the full live test with auto-detected GPU family: ```bash @@ -3544,10 +3587,15 @@ compare them in one PEP 440 order over published version strings (`7.9` < `7.10.0`, `7.0.0b1` < `7.0.0rc1` < `7.0.0` < `7.0.0.post1`, `7.2.4.70204` above `7.2.4`). That covers picking the newest ROCm version from a wheel index, breaking ties between tarball builds uploaded at the same time, and the -update-or-not verdict. It does not decide everything on its own: tarball builds -are picked by upload time first, and on the release channel only a stable -version in the strict `X.Y.Z` shape is a candidate at all, so a four-component -release such as `7.2.4.70204` is never picked there. The property tests check +update-or-not verdict. It does not decide everything on its own: an unpinned +tarball pick goes by upload time first (a `major.minor` line pin such as +`--version 10.1` goes by this order first), and without a `--version` pin the +release channel takes only a stable version in the strict `X.Y.Z` shape, so an +unpinned pick never lands on a four-component release such as `7.2.4.70204`. +A wheel line pin is different: `--version 7.2` selects the newest stable +release in the 7.2 line, `7.2.4.70204` included. The tarball catalog still +requires the strict shape, so the same line pin cannot pick that release +there. The property tests check that the order is total, that picks do not depend on the order the index lists versions in, and that the update verdict points the same way as the order. Two spellings of one version (`7.0.0-rc1` and `7.0.0rc1`) are not offered as an diff --git a/tests/e2e-cucumber/features/therock_next_generation.feature b/tests/e2e-cucumber/features/therock_next_generation.feature index 6e38e6c1f..b559f6300 100644 --- a/tests/e2e-cucumber/features/therock_next_generation.feature +++ b/tests/e2e-cucumber/features/therock_next_generation.feature @@ -378,3 +378,111 @@ Feature: TheRock "next" ROCm 10 install layout When the user tries to preview a nightly tarball SDK install for arch gfx1200 pinned to the earlier stream's last build date Then the install fails And the failure names the first build date of the newer layout and points to a wheel install that resolves that earlier nightly + + # `--version 10.1` is the 10.1 line, not a failed parse of `10.1.0` and not + # an exact pin. The fixture publishes the 10.1 line's 10.1.0 and 10.1.2 beside + # a 10.1.3rc1 prerelease, a 10.10.0 and a 10.0.0, so the pin must take + # 10.1.2: the oldest of the line, an exact `10.1.0`, a prerelease and a + # `10.10` prefix match would each pick something else. It must also leave the + # canonical 7.x index. Needs no uv: the version is chosen before `uv` runs. + @id:therock-next-24-two-component-line-pin + Scenario: therock-next-24 - A ROCm 10.1 line pin installs the newest stable build in that line + Given a ROCm 10 pip index fixture that publishes several 10.1 builds, a 10.1 prerelease and a 10.10 build + When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.1 + Then the preview resolves the ROCm 10 pip index for ROCm 10.1.2, the newest stable build of the 10.1 line + And the preview reports the next source layout generation + + # The same pin against a next index that only publishes 10.0.0 cannot be + # satisfied. The refusal must name the next layout and suggest a release that + # index does publish, with the arch the request used. It must not offer + # `--channel nightly` (that channel refuses ROCm 10) or a 10.1 version (the + # index has none), because neither suggestion can succeed. Running the + # suggested command proves the advice clears the failure. + @id:therock-next-25-unsatisfied-line-pin-skips-nightly + Scenario: therock-next-25 - An unsatisfied ROCm 10.1 line pin suggests a published release, not the nightly channel + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + When the user tries to preview a wheel SDK install for arch gfx1200 pinned to ROCm 10.1 + Then the install fails + And the failure suggests the published ROCm 10.0.0 for arch gfx1200, without suggesting nightly or a 10.1 version + When the user re-runs the preview with the version and arch the failure suggested + Then the preview resolves the ROCm 10 pip index + + # On the tarball catalog an unpinned pick is "newest upload". A line pin is + # "newest stable release in the line": the fixture uploads 10.1.0 AFTER + # 10.1.2, so upload order alone would pick the older patch. + @id:therock-next-26-tarball-line-pin-takes-newest-release @requires-os:linux + Scenario: therock-next-26 - A ROCm 10.1 line pin on the tarball catalog takes the newest 10.1 release, not the newest upload + Given a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last + When the user previews a tarball SDK install for arch gfx1200 pinned to ROCm 10.1 + Then the preview selects the ROCm 10.1.2 tarball, not the later-uploaded 10.1.0 + + # A line pin that matches nothing on the tarball catalog. The refusal names + # the archives that catalog does publish for the family, newest first, and a + # `--version`/`--family` pair to re-run with. It says archive, not package + # stack, and offers no nightly. Re-running the suggestion proves it clears + # the failure. + @id:therock-next-27-unsatisfied-tarball-line-pin-suggests-a-published-archive @requires-os:linux + Scenario: therock-next-27 - An unsatisfied ROCm 10 tarball pin suggests an archive the catalog publishes + Given a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last + When the user tries to preview a tarball SDK install for arch gfx1200 pinned to ROCm 10.2 + Then the install fails + And the failure lists the published ROCm 10 archives for gfx120X-all and suggests 10.1.2 for arch gfx1200 + When the user re-runs the tarball preview with the version and arch the failure suggested + Then the preview selects the ROCm 10.1.2 tarball, not the later-uploaded 10.1.0 + + # `rocm update` re-resolves an installed runtime with no `--version` and has + # no `--family`. A ROCm 10 runtime whose manifest records only its grouped + # family has no exact arch, so its update cannot resolve a device payload on + # any release. That failure must say so and must not send the user to a + # `--version` or tell them to re-run the update with `--family`, which it + # does not accept. + @id:therock-next-28-update-with-no-exact-arch-gets-no-version-advice + Scenario: therock-next-28 - An update that cannot resolve a device target is not told to change its version + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + And a registered ROCm 10 wheel runtime that records no exact arch + When the user tries to preview applying the pending update to that runtime + Then the install fails + And the failure says no exact device target is known, without suggesting a version or a --family re-run + + # A `major.minor.patch` pin stays exact even when later patches of its line + # are published: `--version 10.1.0` must not drift to 10.1.2. + @id:therock-next-29-exact-pin-ignores-later-patches + Scenario: therock-next-29 - An exact ROCm 10.1.0 pin installs 10.1.0 even when a later 10.1 patch is published + Given a ROCm 10 pip index fixture that publishes several 10.1 builds, a 10.1 prerelease and a 10.10 build + When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.1.0 + Then the preview resolves the ROCm 10 pip index for exactly ROCm 10.1.0, not the later 10.1.2 + + # A line pin below ROCm 10 stays on the canonical index and takes the newest + # stable release of its line: 7.14.1, not 7.14.0, the 7.14.2rc1 prerelease or + # 7.15.0. + @id:therock-next-30-canonical-line-pin + Scenario: therock-next-30 - A ROCm 7.14 line pin installs the newest stable 7.14 build from the canonical index + Given a canonical release pip index fixture that publishes several 7.14 builds, a 7.14 prerelease and a 7.15 build + When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 7.14 + Then the preview resolves the canonical release pip index for ROCm 7.14.1 + And the preview never mentions the ROCm 10 pip index + + # With no pin the install takes the newest build that has a full stack, so a + # failure on torchaudio means no build has one. Another `--version` would + # fail the same way, so the failure must not suggest one. + @id:therock-next-31-unpinned-install-with-no-installable-torchaudio-suggests-no-version + Scenario: therock-next-31 - An unpinned ROCm 10 install where no build has an installable torchaudio suggests no other version + Given a ROCm 10 pip index fixture where no build has a torchaudio this host can install + When the user tries to preview a wheel SDK install for arch gfx1200 with no version pin + Then the install fails + And the failure names the missing torchaudio without suggesting another version + + # An update has no `--version` to change. When the newest release has every + # package listed but no installable set (`uv pip compile` finds no + # solution), the failure names a whole `rocm install sdk` command for the + # other release, keeping the runtime's format and toolchain extras. Running + # that command proves it exists, accepts those flags, and resolves. + @id:therock-next-32-failed-update-suggests-an-install-that-keeps-its-extras + Scenario: therock-next-32 - A ROCm 10 update with no installable package set suggests an install command that keeps the runtime's format and toolchain + Given a ROCm 10 pip index fixture whose newest build has no installable package set + And a registered ROCm 10 wheel runtime with a grouped family + When the user tries to preview applying the pending update to that runtime + Then the install fails + And the failure suggests installing the other published ROCm 10.0.0 as a wheel for arch gfx1200 with the toolchain + When the user previews the install command the failure suggested + Then the preview resolves ROCm 10.0.0 with the gfx1200 device extras and the toolchain diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index f96f4f26d..878ddd411 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -408,6 +408,18 @@ fn arm_pip_fixture_env(world: &mut E2eWorld) { /// nothing in its metadata ties it to a build. `torchaudio` lists the /// torchaudio builds the index publishes, each with its wheel tag. fn serve_two_next_builds(world: &mut E2eWorld, torchaudio: &[(&str, &str)]) { + serve_two_next_builds_where_newer_torch_requires(world, torchaudio, NEWER_NEXT_ROCM_VERSION); +} + +/// [`serve_two_next_builds`], with the newer build's torch requiring +/// `rocm=={newer_torch_rocm}` instead of its own `rocm` build. Naming a `rocm` +/// the index does not publish leaves that build with every package listed but +/// no installable set, which `uv pip compile` reports as "No solution found". +fn serve_two_next_builds_where_newer_torch_requires( + world: &mut E2eWorld, + torchaudio: &[(&str, &str)], + newer_torch_rocm: &str, +) { let served = root(world).join("therock-pip-fixtures").join("next"); write_fixture(&served.join("index.html"), &aggregate_root_html()); let builds = [ @@ -424,7 +436,14 @@ fn serve_two_next_builds(world: &mut E2eWorld, torchaudio: &[(&str, &str)]) { ]; let rocm = builds.map(|(rocm, ..)| (rocm, ANY_WHEEL_TAG, Vec::new())); let mut torch = builds - .map(|(rocm, torch, _)| (torch, ANY_WHEEL_TAG, vec![format!("rocm=={rocm}")])) + .map(|(rocm, torch, _)| { + let requires = if rocm == NEWER_NEXT_ROCM_VERSION { + newer_torch_rocm + } else { + rocm + }; + (torch, ANY_WHEEL_TAG, vec![format!("rocm=={requires}")]) + }) .to_vec(); // A torch newer than the one torchvision was built against, for the same // `rocm` build, as the live index published for ROCm 10.1.0. @@ -467,6 +486,118 @@ fn serve_two_next_builds_with_torchaudio_rebuilds(world: &mut E2eWorld) { serve_two_next_builds(world, &torchaudio); } +/// One build of each stack package per `rocm` version in `builds`, every one +/// labelled for its `rocm` build and requiring it the way the live index does: +/// torch its exact `rocm`, torchvision and torchaudio their exact torch. The +/// torch and torchvision releases are any pair the canonical matcher accepts; +/// what a scenario reads is which `rocm` build was chosen. +fn write_line_builds(served: &Path, builds: &[&str], torch: &str, torchvision: &str) { + write_fixture(&served.join("index.html"), &aggregate_root_html()); + let torch_of = |rocm: &str| format!("{torch}+rocm{rocm}"); + let rocm = builds + .iter() + .map(|rocm| (*rocm, ANY_WHEEL_TAG, Vec::new())) + .collect::>(); + let torch_versions = builds.iter().map(|rocm| torch_of(rocm)).collect::>(); + let torchvision_versions = builds + .iter() + .map(|rocm| format!("{torchvision}+rocm{rocm}")) + .collect::>(); + let torch_builds = builds + .iter() + .zip(&torch_versions) + .map(|(rocm, torch)| (torch.as_str(), ANY_WHEEL_TAG, vec![format!("rocm=={rocm}")])) + .collect::>(); + let torchvision_builds = torchvision_versions + .iter() + .zip(&torch_versions) + .map(|(torchvision, torch)| { + ( + torchvision.as_str(), + ANY_WHEEL_TAG, + vec![format!("torch=={torch}")], + ) + }) + .collect::>(); + // torchaudio shares torch's release number and build label. + let torchaudio_builds = torch_versions + .iter() + .map(|torch| { + ( + torch.as_str(), + ANY_WHEEL_TAG, + vec![format!("torch=={torch}")], + ) + }) + .collect::>(); + write_wheel_index_builds(&served.join("rocm"), "rocm", &rocm); + write_wheel_index_builds(&served.join("torch"), "torch", &torch_builds); + write_wheel_index_builds( + &served.join("torchvision"), + "torchvision", + &torchvision_builds, + ); + write_wheel_index_builds(&served.join("torchaudio"), "torchaudio", &torchaudio_builds); +} + +/// The 10.1 line's newest stable build: what `--version 10.1` must select. +const NEXT_LINE_NEWEST_VERSION: &str = "10.1.2"; +/// A prerelease above it, a `10.10` build a prefix match would take, an older +/// build of the line and a build of the previous line. +const NEXT_LINE_BUILDS: [&str; 5] = [ + "10.0.0", + "10.1.0", + NEXT_LINE_NEWEST_VERSION, + "10.1.3rc1", + "10.10.0", +]; + +#[given( + "a ROCm 10 pip index fixture that publishes several 10.1 builds, a 10.1 prerelease and a 10.10 build" +)] +async fn pip_index_fixture_with_next_line_builds(world: &mut E2eWorld) { + let served = root(world).join("therock-pip-fixtures").join("next"); + write_line_builds(&served, &NEXT_LINE_BUILDS, "2.11.0", "0.26.0"); + serve_pip_fixtures(world); +} + +/// The 7.14 line's newest stable build: what `--version 7.14` must select. +const CANONICAL_LINE_NEWEST_VERSION: &str = "7.14.1"; +const CANONICAL_LINE_BUILDS: [&str; 4] = [ + "7.14.0", + CANONICAL_LINE_NEWEST_VERSION, + "7.14.2rc1", + "7.15.0", +]; + +#[given( + "a canonical release pip index fixture that publishes several 7.14 builds, a 7.14 prerelease and a 7.15 build" +)] +async fn pip_index_fixture_with_canonical_line_builds(world: &mut E2eWorld) { + let served = root(world).join("therock-pip-fixtures").join("current"); + write_line_builds(&served, &CANONICAL_LINE_BUILDS, "2.9.0", "0.24.0"); + serve_pip_fixtures(world); +} + +/// A `rocm` build no fixture publishes, so a torch that requires it cannot be +/// installed. +const UNPUBLISHED_NEXT_ROCM_VERSION: &str = "10.9.9"; + +/// Both builds list every package, so an unpinned resolution takes the newer +/// one, but its torch requires a `rocm` that is not published: `uv pip +/// compile` finds no solution for it, and a different release (the older +/// build) can still install. +#[given("a ROCm 10 pip index fixture whose newest build has no installable package set")] +async fn pip_index_fixture_with_unsolvable_newest_build(world: &mut E2eWorld) { + let mut torchaudio = vec![(NEXT_TORCHAUDIO_VERSION, ANY_WHEEL_TAG)]; + torchaudio.extend(NEWER_NEXT_TORCHAUDIO_VERSIONS.map(|version| (version, ANY_WHEEL_TAG))); + serve_two_next_builds_where_newer_torch_requires( + world, + &torchaudio, + UNPUBLISHED_NEXT_ROCM_VERSION, + ); +} + #[given("a ROCm 10 pip index fixture that also publishes a newer ROCm 10 build")] async fn pip_index_fixture_with_newer_next_build(world: &mut E2eWorld) { serve_two_next_builds_with_torchaudio_rebuilds(world); @@ -481,6 +612,19 @@ async fn pip_index_fixture_with_torchaudio_rebuilds_sharing_a_label(world: &mut serve_two_next_builds_with_torchaudio_rebuilds(world); } +/// Every build's only torchaudio is a wheel this host cannot install, so no +/// build has a full stack and nothing else is worth suggesting. +#[given("a ROCm 10 pip index fixture where no build has a torchaudio this host can install")] +async fn pip_index_fixture_without_any_torchaudio(world: &mut E2eWorld) { + serve_two_next_builds( + world, + &[ + (NEXT_TORCHAUDIO_FOREIGN_WHEEL_VERSION, FOREIGN_WHEEL_TAG), + (NEWER_NEXT_TORCHAUDIO_ORIGINAL_VERSION, FOREIGN_WHEEL_TAG), + ], + ); +} + /// The pinned build's only torchaudio is a wheel this host cannot install, so /// for this Python and platform it publishes none; the newer build publishes /// installable ones. @@ -510,6 +654,22 @@ const NEXT_GROUPED_FAMILY_RUNTIME_KEY: &str = "release-wheel-next-v1-gfx120x-all /// `source_layout_generation`, not derived from the version string. #[given("a registered ROCm 10 wheel runtime with a grouped family")] async fn registered_next_wheel_runtime_with_grouped_family(world: &mut E2eWorld) { + plant_next_wheel_runtime(world, Some(RAW_ARCH)); +} + +/// The same runtime from before ROCm CLI recorded the exact arch: no +/// `rocm_sdk_target`, and no `device-*` extra in its specs to recover one from, +/// so only the grouped family is known. +#[given("a registered ROCm 10 wheel runtime that records no exact arch")] +async fn registered_next_wheel_runtime_without_exact_arch(world: &mut E2eWorld) { + plant_next_wheel_runtime(world, None); +} + +fn plant_next_wheel_runtime(world: &mut E2eWorld, exact_arch: Option<&str>) { + let rocm_extras = exact_arch.map_or_else( + || "libraries,devel".to_owned(), + |arch| format!("libraries,devel,device-{arch}"), + ); let install_root = root(world).join("runtime-next-grouped-family"); std::fs::create_dir_all(&install_root).expect("failed to create install root"); @@ -530,12 +690,12 @@ async fn registered_next_wheel_runtime_with_grouped_family(world: &mut E2eWorld) "wheel_composition": { "source_layout_generation": "next-v1", "package_specs": [ - format!("rocm[libraries,devel,device-{RAW_ARCH}]==9.0.0"), + format!("rocm[{rocm_extras}]==9.0.0"), "torch==2.9.0+rocm9.0.0", "torchvision==0.24.0+rocm9.0.0", "torchaudio==2.9.0+rocm9.0.0", ], - "rocm_sdk_target": RAW_ARCH, + "rocm_sdk_target": exact_arch, }, "installed_at_unix_ms": 1_700_000_000_000u64, })) @@ -754,6 +914,20 @@ async fn preview_apply_pending_update(world: &mut E2eWorld) { ); } +#[when("the user tries to preview applying the pending update to that runtime")] +async fn try_preview_apply_pending_update(world: &mut E2eWorld) { + preview( + world, + &[ + "update", + "--apply", + "--dry-run", + "--runtime", + NEXT_GROUPED_FAMILY_RUNTIME_KEY, + ], + ); +} + #[given("an untrusted ROCm 10 pip base override")] async fn untrusted_pip_index_fixture(world: &mut E2eWorld) { let served = root(world).join("untrusted-therock-pip-fixture"); @@ -802,6 +976,45 @@ async fn tarball_index_fixtures(world: &mut E2eWorld) { .push(("ROCM_CLI_THEROCK_NEXT_TARBALL_BASE", next.into())); } +/// The newer 10.1 patch, uploaded first. +const NEXT_LINE_NEWEST_TARBALL: &str = "therock-dist-linux-gfx120X-all-10.1.2.tar.gz"; +/// The older 10.1 patch, uploaded last: newest by mtime, not by version. +const NEXT_LINE_LATEST_UPLOAD_TARBALL: &str = "therock-dist-linux-gfx120X-all-10.1.0.tar.gz"; + +/// Queue the env that points the next `rocm` run at the served tarball +/// catalogs. Each run consumes `command_env`, so a second run calls this again. +fn point_at_tarball_fixtures(world: &mut E2eWorld) { + allow_base_overrides(world); + let base = server_base(world); + let next = next_tarball_base(world); + world.command_env.push(( + "ROCM_CLI_THEROCK_RELEASE_TARBALL_BASE", + format!("{base}/tarball/current/").into(), + )); + world + .command_env + .push(("ROCM_CLI_THEROCK_NEXT_TARBALL_BASE", next.into())); +} + +#[given("a ROCm 10 tarball fixture whose older 10.1 patch was uploaded last")] +async fn tarball_line_fixture(world: &mut E2eWorld) { + let served = root(world).join("therock-tarball-fixtures"); + write_fixture( + &served.join("tarball").join("current").join("index.html"), + &tarball_index_html(&[(CURRENT_TARBALL, 1_787_000_000.0)]), + ); + write_fixture( + &served.join("tarball").join("next").join("index.html"), + &tarball_index_html(&[ + (NEXT_REAL_TARBALL, 1_787_500_000.0), + (NEXT_LINE_NEWEST_TARBALL, 1_787_600_000.0), + (NEXT_LINE_LATEST_UPLOAD_TARBALL, 1_787_700_000.0), + ]), + ); + world.artifact_server = Some(LoopbackServer::start(&served)); + point_at_tarball_fixtures(world); +} + /// Size and pacing for the paced tarball fixture below: large enough (versus /// the chunk size) that several chunk boundaries — and therefore several /// observable progress frames — land before the transfer completes, and slow @@ -1043,6 +1256,24 @@ async fn preview_unpinned_wheel_install(world: &mut E2eWorld) { ); } +#[when("the user tries to preview a wheel SDK install for arch gfx1200 with no version pin")] +async fn try_preview_unpinned_wheel_install(world: &mut E2eWorld) { + preview( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--dry-run", + ], + ); +} + /// A release pin below ROCm 10 is the one request that still reads the earlier /// (canonical) release stream, so the scenarios whose subject is that stream /// say so with a pin instead of leaning on a default that now reads the newest @@ -1330,6 +1561,46 @@ async fn preview_newer_pinned_wheel_install(world: &mut E2eWorld) { ); } +#[when("the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.1")] +async fn preview_line_pinned_wheel_install(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + "10.1", + "--dry-run", + ], + ); +} + +#[when("the user tries to preview a wheel SDK install for arch gfx1200 pinned to ROCm 10.1")] +async fn try_preview_line_pinned_wheel_install(world: &mut E2eWorld) { + preview( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + "10.1", + "--dry-run", + ], + ); +} + #[when("the user tries to preview a wheel SDK install for arch gfx1200 pinned to ROCm 10.0.0")] async fn try_preview_pinned_wheel_install(world: &mut E2eWorld) { preview( @@ -1456,6 +1727,66 @@ async fn preview_pinned_tarball_install(world: &mut E2eWorld) { ); } +#[when("the user previews a tarball SDK install for arch gfx1200 pinned to ROCm 10.1")] +async fn preview_line_pinned_tarball_install(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "tarball", + "--family", + RAW_ARCH, + "--version", + "10.1", + "--dry-run", + ], + ); +} + +#[when("the user tries to preview a tarball SDK install for arch gfx1200 pinned to ROCm 10.2")] +async fn try_preview_unpublished_line_tarball_install(world: &mut E2eWorld) { + preview( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "tarball", + "--family", + RAW_ARCH, + "--version", + "10.2", + "--dry-run", + ], + ); +} + +#[when("the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 7.14")] +async fn preview_canonical_line_pinned_wheel_install(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + "7.14", + "--dry-run", + ], + ); +} + #[when("the user previews a tarball SDK install for family gfx120X-all pinned to ROCm 10.0.0")] async fn preview_pinned_tarball_install_with_group_family(world: &mut E2eWorld) { preview( @@ -1902,6 +2233,91 @@ async fn preview_resolves_next_pip_index(world: &mut E2eWorld) { ); } +/// The `selected_rocm_version:` line names `expected` and none of the other +/// builds the fixture publishes. +fn assert_selected_rocm_version(world: &E2eWorld, expected: &str, published: &[&str]) { + assert_contains( + world, + &format!("selected_rocm_version: {expected}\n"), + "selected ROCm build", + ); + for other in published.iter().filter(|version| **version != expected) { + assert!( + !stdout(world).contains(&format!("selected_rocm_version: {other}\n")), + "the preview selected {other} instead of {expected}:\n{}", + stdout(world) + ); + } +} + +#[then( + "the preview resolves the ROCm 10 pip index for ROCm 10.1.2, the newest stable build of the 10.1 line" +)] +async fn preview_resolves_next_pip_index_for_rocm_10_1_line(world: &mut E2eWorld) { + let base = next_pip_base(world); + assert_contains(world, &format!("canonical_source: {base}"), "next source"); + assert_contains( + world, + "requested: version 10.1", + "the pin that selected the line", + ); + assert_selected_rocm_version(world, NEXT_LINE_NEWEST_VERSION, &NEXT_LINE_BUILDS); + // What `uv` would be asked to install: the line's newest build, whole. + assert_contains( + world, + &format!("rocm[libraries,device-{RAW_ARCH}]=={NEXT_LINE_NEWEST_VERSION} "), + "line build in the requirements", + ); + assert!( + !stdout(world).contains(¤t_pip_base(world)), + "a 10.1 line pin resolved the canonical index:\n{}", + stdout(world) + ); +} + +#[then("the preview resolves the ROCm 10 pip index for exactly ROCm 10.1.0, not the later 10.1.2")] +async fn preview_resolves_exact_pin_despite_later_patch(world: &mut E2eWorld) { + assert_contains( + world, + &format!("canonical_source: {}", next_pip_base(world)), + "next source", + ); + assert_selected_rocm_version(world, NEWER_NEXT_ROCM_VERSION, &NEXT_LINE_BUILDS); +} + +#[then("the preview resolves the canonical release pip index for ROCm 7.14.1")] +async fn preview_resolves_canonical_line(world: &mut E2eWorld) { + assert_contains( + world, + &format!("canonical_source: {}", current_pip_base(world)), + "canonical source", + ); + assert_contains( + world, + "requested: version 7.14", + "the pin that selected the line", + ); + assert_selected_rocm_version(world, CANONICAL_LINE_NEWEST_VERSION, &CANONICAL_LINE_BUILDS); + // The device extra on the canonical layout follows the GPU this host + // reports, so only the versions are asserted: the whole stack is the + // line's newest build. + assert_contains( + world, + &format!("latest_compatible_version: {CANONICAL_LINE_NEWEST_VERSION}\n"), + "canonical line version", + ); + assert_contains( + world, + &format!("]=={CANONICAL_LINE_NEWEST_VERSION} torch[device-"), + "canonical line install plan", + ); + assert_contains( + world, + &format!("torchaudio==2.9.0+rocm{CANONICAL_LINE_NEWEST_VERSION}\n"), + "canonical line torchaudio", + ); +} + #[then("the preview resolves the default ROCm 10 pip index")] async fn preview_resolves_default_next_pip_index(world: &mut E2eWorld) { assert_contains( @@ -2078,6 +2494,22 @@ async fn preview_selects_real_tarball(world: &mut E2eWorld) { ); } +#[then("the preview selects the ROCm 10.1.2 tarball, not the later-uploaded 10.1.0")] +async fn preview_selects_newest_line_tarball(world: &mut E2eWorld) { + let base = next_tarball_base(world); + assert_contains( + world, + &format!("tarball_url: {base}{NEXT_LINE_NEWEST_TARBALL}"), + "newest 10.1 release", + ); + assert_contains(world, "latest_version: 10.1.2", "selected line version"); + assert!( + !stdout(world).contains(NEXT_LINE_LATEST_UPLOAD_TARBALL), + "a 10.1 line pin took the latest upload instead of the newest release:\n{}", + stdout(world) + ); +} + #[then("the preview does not select the tests artifact")] async fn preview_does_not_select_tests_tarball(world: &mut E2eWorld) { assert!( @@ -2134,6 +2566,249 @@ async fn failure_names_the_missing_torchaudio_build(world: &mut E2eWorld) { ); } +fn reported_output(world: &E2eWorld) -> String { + format!( + "{}\n{}", + stdout(world), + world.cli_stderr.as_deref().unwrap_or_default() + ) +} + +#[then( + "the failure suggests the published ROCm 10.0.0 for arch gfx1200, without suggesting nightly or a 10.1 version" +)] +async fn failure_suggests_published_next_release(world: &mut E2eWorld) { + let reported = reported_output(world); + assert!( + reported.contains(&next_pip_base(world)), + "the refusal did not search the ROCm 10 next layout:\n{reported}" + ); + assert!( + !reported.contains(¤t_pip_base(world)), + "the refusal searched the canonical index:\n{reported}" + ); + assert!( + reported.contains("next layout"), + "the refusal did not name the next layout:\n{reported}" + ); + assert!( + reported.contains(&format!( + "`--version {NEXT_ROCM_VERSION} --family {RAW_ARCH}`" + )), + "the refusal did not suggest the published {NEXT_ROCM_VERSION} with the requested arch:\n{reported}" + ); + assert!( + !reported.contains("--version 10.1"), + "the refusal suggested a 10.1 version the index does not publish:\n{reported}" + ); + assert!( + !reported.contains("--channel nightly"), + "the refusal told the user to try nightly:\n{reported}" + ); + assert!( + !reported.contains("package_specs:"), + "the refusal still printed an install plan:\n{reported}" + ); +} + +/// Runs exactly the `--version`/`--family` pair the previous failure printed, +/// so the scenario proves the advice clears the failure rather than only +/// pinning its wording. +#[when("the user re-runs the preview with the version and arch the failure suggested")] +async fn rerun_with_suggested_version(world: &mut E2eWorld) { + let reported = reported_output(world); + let suggested = reported + .split('`') + .find(|chunk| chunk.starts_with("--version ")) + .unwrap_or_else(|| panic!("the failure suggested no `--version` command:\n{reported}")) + .to_owned(); + let mut args = vec![ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + ]; + args.extend(suggested.split_whitespace()); + args.push("--dry-run"); + arm_pip_fixture_env(world); + preview_ok(world, &args); +} + +#[then( + "the failure lists the published ROCm 10 archives for gfx120X-all and suggests 10.1.2 for arch gfx1200" +)] +async fn failure_lists_published_next_archives(world: &mut E2eWorld) { + let reported = reported_output(world); + assert!( + reported.contains("next-layout TheRock release tarball stream is incomplete"), + "the refusal did not name the next-layout catalog:\n{reported}" + ); + assert!( + reported.contains(&format!( + "No archive for {GROUP_FAMILY} was found for version 10.2 on the ROCm 10+ next layout. \ + Stable releases it publishes for {GROUP_FAMILY}: 10.1.2, 10.1.0, 10.0.0. \ + Re-run with one of them, for example `--version 10.1.2 --family {RAW_ARCH}`." + )), + "the refusal did not list the published archives and suggest the newest:\n{reported}" + ); + for absent in ["nightly", "package stack", "tarball_url:"] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +/// The tarball twin of [`rerun_with_suggested_version`]. +#[when("the user re-runs the tarball preview with the version and arch the failure suggested")] +async fn rerun_tarball_with_suggested_version(world: &mut E2eWorld) { + let reported = reported_output(world); + let suggested = reported + .split('`') + .find(|chunk| chunk.starts_with("--version ")) + .unwrap_or_else(|| panic!("the failure suggested no `--version` command:\n{reported}")) + .to_owned(); + let mut args = vec![ + "install", + "sdk", + "--channel", + "release", + "--format", + "tarball", + ]; + args.extend(suggested.split_whitespace()); + args.push("--dry-run"); + point_at_tarball_fixtures(world); + preview_ok(world, &args); +} + +#[then( + "the failure says no exact device target is known, without suggesting a version or a --family re-run" +)] +async fn failure_names_missing_device_target_without_version_advice(world: &mut E2eWorld) { + let reported = reported_output(world); + assert!( + reported.contains("without an exact device target"), + "the refusal did not say the device target is unknown:\n{reported}" + ); + assert!( + reported.contains(&format!("from next-layout source {}", next_pip_base(world))), + "the refusal did not name the next-layout source:\n{reported}" + ); + // No release can clear this, and `rocm update` takes no `--family`. + for absent in [ + "--version", + "re-run with `--family`", + "Install one of them", + "Re-run with one of them", + "nightly", + ] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +#[then("the failure names the missing torchaudio without suggesting another version")] +async fn failure_names_missing_torchaudio_without_version_advice(world: &mut E2eWorld) { + let reported = reported_output(world); + assert!( + reported.contains(&format!( + "no torchaudio built for ROCm {NEWER_NEXT_ROCM_VERSION} is published for this Python and platform" + )), + "the refusal did not say why {NEWER_NEXT_ROCM_VERSION} failed:\n{reported}" + ); + for absent in [ + "--version", + "Install one of them", + "Re-run with one of them", + "nightly", + ] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +/// The install command a failed update suggests for its runtime: a wheel with +/// the toolchain extras the runtime had, at the exact arch it recorded. +fn suggested_update_install(version: &str) -> String { + format!( + "rocm install sdk --channel release --format wheel --version {version} --family {RAW_ARCH} --devel" + ) +} + +#[then( + "the failure suggests installing the other published ROCm 10.0.0 as a wheel for arch gfx1200 with the toolchain" +)] +async fn failure_suggests_install_that_keeps_extras(world: &mut E2eWorld) { + let reported = reported_output(world); + // The real `uv pip compile` output: the CLI classifies the failure as one + // another release can clear by finding this phrase, so a `uv` that reworded + // it would fail this step instead of silently dropping the suggestion. + for expected in [ + "published ROCm X package metadata is not jointly installable", + "No solution found", + UNPUBLISHED_NEXT_ROCM_VERSION, + ] { + assert!( + reported.contains(expected), + "the refusal did not carry `{expected}` from uv's failure:\n{reported}" + ); + } + // 10.1.0 is the release that failed, so it is not offered again. + assert!( + reported.contains(&format!( + "Other stable releases it publishes: {NEXT_ROCM_VERSION}." + )), + "the refusal did not list only the release that was not tried:\n{reported}" + ); + assert!( + reported.contains(&format!( + "Install one of them, for example `{}`.", + suggested_update_install(NEXT_ROCM_VERSION) + )), + "the refusal did not suggest an install that keeps the runtime's format and extras:\n{reported}" + ); + for absent in ["Re-run with one of them", "nightly", "package_specs:"] { + assert!( + !reported.contains(absent), + "the refusal contains `{absent}`:\n{reported}" + ); + } +} + +/// Runs exactly the `rocm install sdk` command the previous failure printed, as +/// a preview, so the scenario proves the command exists, accepts those flags +/// and resolves. +#[when("the user previews the install command the failure suggested")] +async fn preview_suggested_install_command(world: &mut E2eWorld) { + let reported = reported_output(world); + let suggested = reported + .split('`') + .find(|chunk| chunk.starts_with("rocm install sdk ")) + .unwrap_or_else(|| panic!("the failure suggested no install command:\n{reported}")) + .to_owned(); + let mut args = suggested.split_whitespace().skip(1).collect::>(); + args.push("--dry-run"); + arm_pip_fixture_env(world); + preview_ok(world, &args); +} + +#[then("the preview resolves ROCm 10.0.0 with the gfx1200 device extras and the toolchain")] +async fn preview_resolves_suggested_install(world: &mut E2eWorld) { + assert_contains( + world, + &format!("selected_rocm_version: {NEXT_ROCM_VERSION}\n"), + "suggested release", + ); + assert_version_resolution_extras(world, true); +} + #[then("the failure asks for an exact GPU arch and names --family gfx1200")] async fn failure_names_the_exact_arch_flag(world: &mut E2eWorld) { // Both streams: what matters is that the user is told how to fix it, not