From 9119af7f9caf9e47d19cf1bdbc8b8fbebdaa3f63 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 10:26:41 +0000 Subject: [PATCH 01/25] fix(install): preview an SDK install without preparing Python On a host with no usable Python, rocm install sdk --dry-run (and the install_sdk_dry_run assistant tool) went on to download a managed uv, have it install Python and save that Python's path in the config before printing a plan, although a preview promises to change nothing. The preview only needs the interpreter's wheel tags, so it now reports that a real install would prepare a managed Python (python_note) and prepares nothing; every refusal the real resolution raises is raised for the preview too. A real install resolves and prepares exactly as before. Adds unit tests for the no-Python, PATH Python, saved Python, stale saved Python and bootstrap-disabled cases, and scenario runtime-22, which checks the preview's note together with the empty tools, cache and config folders and a recording uv that is never run. Signed-off-by: Jussi Elo --- apps/rocm/src/therock.rs | 65 +- apps/rocm/src/therock/python.rs | 591 +++++++++++++++++- crates/rocm-dash-tui/src/agent/tools.rs | 12 +- docs/manual-testing.md | 8 + docs/testing.md | 11 + .../features/runtime_setup.feature | 31 + tests/e2e-cucumber/src/bin/fake-uv.rs | 14 + tests/e2e-cucumber/tests/e2e/therock_steps.rs | 127 ++++ 8 files changed, 815 insertions(+), 44 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 90f15479e8..f719fa2e3b 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -41,8 +41,7 @@ pub(crate) use self::probe::{ }; use self::process::{extract_tarball_and_discard_archive, progress_line, run_uv_progress_command}; use self::python::{ - ensure_uv_venv, managed_python_version, python_requirement, resolve_python_launcher, - wheel_compatibility_for_python, + PlannedPython, ensure_uv_venv, managed_python_version, python_for_install, python_requirement, }; use self::resolve::{ AggregateDeviceTarget, canonical_auto_select_needs_next_python, resolve_pip_runtime, @@ -363,29 +362,37 @@ fn install_wheel_runtime( } }; progress_line(format!( - "Checking Python for the ROCm install; if needed, ROCm CLI will prepare Python {}.", + "Checking Python for the ROCm install; if needed, {} Python {}.", + if dry_run { + "a real install would prepare" + } else { + "ROCm CLI will prepare" + }, managed_python_version(python_requirement) )); - let python_launcher = resolve_python_launcher(paths, python_requirement)?; - progress_line(match python_launcher.source { - "path" => format!( - "Using Python from PATH: {}.", - python_launcher.executable.display() - ), - "env" => format!( - "Using Python from ROCM_CLI_PYTHON: {}.", - python_launcher.executable.display() - ), - "managed" => format!( - "Using ROCm CLI's portable Python: {}.", - python_launcher.executable.display() - ), - _ => format!( - "Using Python from {}.", - python_launcher.executable.display() + // A preview must not prepare the Python it reports: resolving one can + // download a managed `uv` and Python and save the result in the + // configuration. It asks what a real install would do instead and prints + // that. A real install resolves, and so prepares, exactly as it always did. + let python = python_for_install(paths, python_requirement, dry_run)?; + progress_line(match &python { + PlannedPython::Ready(launcher) => match launcher.source { + "path" => format!("Using Python from PATH: {}.", launcher.executable.display()), + "env" => format!( + "Using Python from ROCM_CLI_PYTHON: {}.", + launcher.executable.display() + ), + "managed" => format!( + "Using ROCm CLI's portable Python: {}.", + launcher.executable.display() + ), + _ => format!("Using Python from {}.", launcher.executable.display()), + }, + PlannedPython::WouldPrepareManaged { version, .. } => format!( + "No usable Python found; a real install would prepare Python {version}. This preview does not." ), }); - let wheel_compatibility = wheel_compatibility_for_python(&python_launcher.executable)?; + let wheel_compatibility = python.wheel_compatibility()?; progress_line(format!( "Checking TheRock {} packages for this AMD GPU...", channel.as_str() @@ -477,12 +484,11 @@ fn install_wheel_runtime( ); let _ = writeln!(output, " target: {}", install_root.display()); let _ = writeln!(output, " runtime_key: {runtime_key}"); - let _ = writeln!( - output, - " python_launcher: {}", - python_launcher.executable.display() - ); - let _ = writeln!(output, " python_source: {}", python_launcher.source); + let _ = writeln!(output, " python_launcher: {}", python.launcher_display()); + let _ = writeln!(output, " python_source: {}", python.source()); + if let Some(note) = python.note() { + let _ = writeln!(output, " python_note: {note}"); + } let _ = writeln!( output, " python_wheel_tag: {}", @@ -537,7 +543,7 @@ fn install_wheel_runtime( install_args.extend(["--prerelease".to_owned(), "allow".to_owned()]); } install_args.extend(wheel_composition.package_specs.iter().cloned()); - let venv_args = uv_venv_args(&python_launcher.executable, &install_root); + let venv_args = uv_venv_args(&python.venv_python_arg(), &install_root); let venv_args_display = venv_args .iter() .map(|arg| quote_display_arg(arg)) @@ -561,6 +567,9 @@ fn install_wheel_runtime( return Ok(SdkInstallResult::plan(output)); } + // Only a preview returns above with an interpreter it has not prepared. + let python_launcher = python.into_launcher()?; + // Requirement: surface the "newest version has no wheels" case as a warning // on the real install path too, not only in the dry-run plan. if let Some(warning) = no_wheel_warning.as_deref() { diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 1a887a7ed7..1c1a498270 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -455,28 +455,190 @@ pub(super) fn resolve_python_launcher( resolve_python_launcher_in(paths, &env, requirement) } +/// The interpreter an install of the wheel runtime goes on with, or, for a dry +/// run, the one it would. +/// +/// The single place the install decides between the two, so a dry run cannot +/// reach [`resolve_python_launcher`]'s preparation by a path of its own. +pub(super) fn python_for_install( + paths: &AppPaths, + requirement: PythonRequirement, + dry_run: bool, +) -> Result { + if dry_run { + plan_python_launcher(paths, requirement) + } else { + resolve_python_launcher(paths, requirement).map(PlannedPython::Ready) + } +} + +/// The interpreter a *preview* of the install reports, found without preparing +/// one. +/// +/// [`resolve_python_launcher`] ends by downloading a managed `uv`, having it +/// install Python, and saving that Python's path in the configuration when no +/// interpreter on the host will do. A dry run promises to change nothing, so it +/// asks this instead: an interpreter that is usable now comes back as +/// [`PlannedPython::Ready`], exactly as the real install would pick it, and a +/// host that has none comes back as [`PlannedPython::WouldPrepareManaged`], the +/// step a real install would take, left untaken. Every error the real +/// resolution raises before that step (an unusable `ROCM_CLI_PYTHON`, a +/// disabled managed bootstrap) is raised here too, so a preview never succeeds +/// on a host where the install would refuse. +fn plan_python_launcher(paths: &AppPaths, requirement: PythonRequirement) -> Result { + let env = python_resolver_env_override().unwrap_or_else(PythonResolverEnv::from_process_env); + plan_python_launcher_in(paths, &env, requirement) +} + +fn plan_python_launcher_in( + paths: &AppPaths, + env: &PythonResolverEnv, + requirement: PythonRequirement, +) -> Result { + let lookup = find_python_launcher_in(paths, env, requirement, LookupPurpose::Preview)?; + Ok(match lookup { + PythonLookup::Found(launcher) => PlannedPython::Ready(launcher), + PythonLookup::NeedsManagedBootstrap => PlannedPython::WouldPrepareManaged { + version: managed_python_version(requirement), + requirement, + }, + }) +} + +/// What [`plan_python_launcher`] found. +#[derive(Debug, Clone)] +pub(super) enum PlannedPython { + /// An interpreter that is usable as it stands. + Ready(PythonLauncher), + /// No interpreter is usable. A real install would prepare managed Python + /// `version`; this preview has not. + WouldPrepareManaged { + version: String, + requirement: PythonRequirement, + }, +} + +impl PlannedPython { + /// The `python_launcher:` line's value: the interpreter's path, or, when + /// none exists yet, a statement that none was prepared rather than a path + /// that would be a guess. + pub(super) fn launcher_display(&self) -> String { + match self { + Self::Ready(launcher) => launcher.executable.display().to_string(), + Self::WouldPrepareManaged { .. } => "not prepared by this preview".to_owned(), + } + } + + /// The `python_source:` line's value. + pub(super) const fn source(&self) -> &'static str { + match self { + Self::Ready(launcher) => launcher.source, + Self::WouldPrepareManaged { .. } => "managed", + } + } + + /// What `uv venv --python` is handed in the printed command: the + /// interpreter's path, or the version that would be prepared, which `uv` + /// resolves to the managed Python the real install prepares. + pub(super) fn venv_python_arg(&self) -> PathBuf { + match self { + Self::Ready(launcher) => launcher.executable.clone(), + Self::WouldPrepareManaged { version, .. } => PathBuf::from(version), + } + } + + /// The `python_note:` line, present only when something was left undone. + /// Written from the same value the branch was taken on, so it cannot name a + /// version the install will not prepare. + pub(super) fn note(&self) -> Option { + match self { + Self::Ready(_) => None, + Self::WouldPrepareManaged { version, .. } => Some(format!( + "no usable Python was found; a real install would use uv to install managed Python {version} and save its path in the configuration, which this preview did not do" + )), + } + } + + /// The wheel tags the install will select packages by. An interpreter that + /// exists is asked; one that does not yet is the one the layout requires, + /// because a real install refuses to go on with any other (see + /// `python_launcher_install_ready`). + pub(super) fn wheel_compatibility(&self) -> Result { + match self { + Self::Ready(launcher) => wheel_compatibility_for_python(&launcher.executable), + Self::WouldPrepareManaged { requirement, .. } => Ok(WheelCompatibility { + python_tag: requirement.tag.to_owned(), + platform_tags: current_platform_wheel_tags()?, + }), + } + } + + /// The interpreter a real install runs with. A preview never reaches here + /// with an interpreter it has not prepared. + pub(super) fn into_launcher(self) -> Result { + match self { + Self::Ready(launcher) => Ok(launcher), + Self::WouldPrepareManaged { version, .. } => bail!( + "internal error: Python {version} was not prepared before the install needed it" + ), + } + } +} + +/// Whether a search for an interpreter is for an install or a preview of one. +/// It changes only the wording of the progress line about a saved Python that +/// turned out unusable: a preview must not say it is preparing one. +#[derive(Clone, Copy)] +enum LookupPurpose { + Install, + Preview, +} + +/// Where the search for an interpreter ended. +enum PythonLookup { + /// An interpreter that is usable as it stands. + Found(PythonLauncher), + /// Nothing is usable and the managed bootstrap is allowed: the next step is + /// [`ensure_managed_python`], which downloads and writes. + NeedsManagedBootstrap, +} + fn resolve_python_launcher_in( paths: &AppPaths, env: &PythonResolverEnv, requirement: PythonRequirement, ) -> Result { + match find_python_launcher_in(paths, env, requirement, LookupPurpose::Install)? { + PythonLookup::Found(launcher) => Ok(launcher), + PythonLookup::NeedsManagedBootstrap => ensure_managed_python(paths, requirement), + } +} + +/// Everything [`resolve_python_launcher_in`] does short of preparing a managed +/// Python: it reads the host and the saved manifest and writes nothing. +fn find_python_launcher_in( + paths: &AppPaths, + env: &PythonResolverEnv, + requirement: PythonRequirement, + purpose: LookupPurpose, +) -> Result { if let Some(value) = env.python_override.as_deref() { python_launcher_install_ready(Path::new(value), requirement) .with_context(|| format!("ROCM_CLI_PYTHON is not usable for ROCm setup: {value}"))?; - return Ok(PythonLauncher { + return Ok(PythonLookup::Found(PythonLauncher { executable: PathBuf::from(value), source: "env", - }); + })); } let mut skipped_path_python = false; for candidate in python_path_candidates(&env.search_dirs) { match python_launcher_install_ready(&candidate, requirement) { Ok(()) => { - return Ok(PythonLauncher { + return Ok(PythonLookup::Found(PythonLauncher { executable: candidate, source: "path", - }); + })); } Err(_) => { skipped_path_python = true; @@ -485,8 +647,12 @@ fn resolve_python_launcher_in( } if skipped_path_python { progress_line(format!( - "Python from PATH is not usable for this ROCm install ({} is required); using ROCm CLI's managed Python.", - requirement.tag + "Python from PATH is not usable for this ROCm install ({} is required); {} ROCm CLI's managed Python.", + requirement.tag, + match purpose { + LookupPurpose::Install => "using", + LookupPurpose::Preview => "a real install would use", + } )); } @@ -494,14 +660,18 @@ fn resolve_python_launcher_in( && manifest.executable.is_file() { if python_launcher_install_ready(&manifest.executable, requirement).is_ok() { - return Ok(PythonLauncher { + return Ok(PythonLookup::Found(PythonLauncher { executable: manifest.executable, source: "managed", - }); + })); } progress_line(format!( - "Saved managed Python is not usable for this ROCm install ({} is required); preparing Python again.", - requirement.tag + "Saved managed Python is not usable for this ROCm install ({} is required); {}.", + requirement.tag, + match purpose { + LookupPurpose::Install => "preparing Python again", + LookupPurpose::Preview => "a real install would prepare Python again", + } )); } @@ -510,7 +680,7 @@ fn resolve_python_launcher_in( "unable to locate Python, and managed Python bootstrap is disabled by ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP" ); } - ensure_managed_python(paths, requirement) + Ok(PythonLookup::NeedsManagedBootstrap) } fn python_path_candidates(search_dirs: &[PathBuf]) -> Vec { @@ -1016,6 +1186,405 @@ exit 1 ); } + // ---- a dry run prepares no Python ---------------------------------------- + + /// Process environment variables set for one test and restored on drop. + /// Every caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds this. + #[cfg(unix)] + struct RestoredEnv(Vec<(&'static str, Option)>); + + #[cfg(unix)] + impl RestoredEnv { + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + fn set(vars: &[(&'static str, Option<&Path>)]) -> Self { + let saved = vars + .iter() + .map(|(key, _)| (*key, std::env::var_os(key))) + .collect(); + for (key, value) in vars { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + Self(saved) + } + } + + #[cfg(unix)] + impl Drop for RestoredEnv { + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + fn drop(&mut self) { + for (key, value) in self.0.drain(..) { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + } + } + + /// A `uv` that records its arguments in `marker` and then fails. A host that + /// reaches it has gone on to prepare a managed Python; failing keeps a test + /// that does reach it from going on to the network. + #[cfg(unix)] + fn write_recording_uv(dir: &Path, marker: &Path) -> Result { + use rocm_core::fake_executable::write_fake_executable; + let path = dir.join("uv"); + write_fake_executable( + &path, + format!("#!/bin/sh\necho \"$@\" >> '{}'\nexit 1\n", marker.display()), + )?; + Ok(path) + } + + /// Every path under the three folders a command may write to, sorted. Empty + /// when none of them exists, so "nothing was created" and "something empty + /// was created" are different answers. + #[cfg(unix)] + fn snapshot(paths: &AppPaths) -> Vec { + fn walk(dir: &Path, out: &mut Vec) { + let Ok(entries) = fs::read_dir(dir) else { + return; + }; + for entry in entries.flatten() { + out.push(entry.path()); + walk(&entry.path(), out); + } + } + let mut out = Vec::new(); + for dir in [&paths.config_dir, &paths.data_dir, &paths.cache_dir] { + if dir.exists() { + out.push(dir.clone()); + } + walk(dir, &mut out); + } + out.sort(); + out + } + + /// A host with no usable Python: an empty search folder and no saved Python, + /// unless the test adds one. `uv` is a recording stand-in, so a code path that + /// prepares Python is visible as a marker instead of a download. + #[cfg(unix)] + struct PythonHost { + root: PathBuf, + paths: AppPaths, + search_dir: PathBuf, + uv_marker: PathBuf, + _env: RestoredEnv, + _lock: std::sync::MutexGuard<'static, ()>, + } + + #[cfg(unix)] + impl PythonHost { + fn new(name: &str) -> Result { + let lock = PROCESS_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = test_paths(name); + let search_dir = root.join("search"); + fs::create_dir_all(&search_dir)?; + let uv_marker = root.join("uv-was-run"); + let tools = root.join("tools"); + fs::create_dir_all(&tools)?; + let uv = write_recording_uv(&tools, &uv_marker)?; + let env = RestoredEnv::set(&[ + ("ROCM_CLI_UV_BINARY", Some(&uv)), + ("ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP", None), + ("ROCM_CLI_MANAGED_PYTHON_VERSION", None), + ]); + Ok(Self { + root, + paths, + search_dir, + uv_marker, + _env: env, + _lock: lock, + }) + } + + /// What an install (`dry_run: false`) or its preview (`true`) goes on + /// with, searching only this host's folder. + fn python_for_install(&self, dry_run: bool) -> Result { + let _resolver = OverridePythonResolverEnv::new(PythonResolverEnv { + python_override: None, + search_dirs: vec![self.search_dir.clone()], + }); + python_for_install( + &self.paths, + python_requirement(SourceLayout::Canonical), + dry_run, + ) + } + + fn uv_was_run(&self) -> bool { + self.uv_marker.exists() + } + + fn save_managed_python(&self, executable: PathBuf) -> Result> { + save_managed_python_manifest( + &self.paths, + &ManagedPythonManifest { + executable, + version: DEFAULT_MANAGED_PYTHON_VERSION.to_owned(), + installed_at_unix_ms: 123, + }, + )?; + Ok(fs::read(managed_python_manifest_path(&self.paths))?) + } + } + + #[cfg(unix)] + impl Drop for PythonHost { + fn drop(&mut self) { + fs::remove_dir_all(&self.root).ok(); + } + } + + /// The bug: a dry run on a host with no usable Python went on to prepare one. + /// Preparing means a managed `uv` and Python are downloaded and the Python's + /// path is saved in the configuration, all before a plan is printed. + /// + /// Asserts the preview's answer and the state it leaves together (the message + /// claims nothing was prepared, so the folders have to agree), and that the + /// same host DOES reach `uv` when the install is real, so an empty marker + /// means the preview stayed out of it rather than that the stand-in is not + /// wired up. The Gherkin scenario `runtime-22` drives the same case through + /// the built binary. + #[cfg(unix)] + #[test] + fn a_dry_run_with_no_usable_python_prepares_nothing() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-dry-run-none")?; + assert!( + snapshot(&host.paths).is_empty(), + "the fixture must start with the config, data and cache folders absent" + ); + + let planned = host.python_for_install(true)?; + + let PlannedPython::WouldPrepareManaged { + ref version, + requirement, + } = planned + else { + panic!("a host with no Python must be planned as needing one, got {planned:?}"); + }; + assert_eq!(version, DEFAULT_MANAGED_PYTHON_VERSION); + assert_eq!(requirement, python_requirement(SourceLayout::Canonical)); + let note = planned + .note() + .expect("a preview that skipped a step says so"); + assert!( + note.contains("would use uv to install managed Python 3.12") + && note.ends_with("which this preview did not do"), + "{note}" + ); + // What the note says was not done, was not done. + assert!(!host.uv_was_run(), "the dry run ran uv"); + assert!( + !host.paths.config_path().exists(), + "the dry run saved a Python path in the configuration" + ); + assert!( + !managed_python_manifest_path(&host.paths).exists(), + "the dry run saved a managed Python manifest" + ); + assert_eq!( + snapshot(&host.paths), + Vec::::new(), + "the dry run created files or folders under the config, data or cache folder" + ); + + // Control: the real install on the same host does reach `uv`. + assert!(host.python_for_install(false).is_err()); + assert!( + host.uv_was_run(), + "the stand-in uv is not reachable, so the checks above prove nothing" + ); + Ok(()) + } + + /// A Python on the search path is used by the preview exactly as by the + /// install, and costs nothing: no `uv`, nothing written. + #[cfg(unix)] + #[test] + fn a_dry_run_reports_a_usable_path_python_and_prepares_nothing() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-dry-run-path")?; + let python = write_fake_python_with_venv(&host.search_dir, "python3")?; + + let planned = host.python_for_install(true)?; + + let PlannedPython::Ready(launcher) = planned else { + panic!("a usable PATH Python must be reported as ready, got {planned:?}"); + }; + assert_eq!(launcher.source, "path"); + assert_eq!(launcher.executable, python); + assert!(!host.uv_was_run()); + assert_eq!(snapshot(&host.paths), Vec::::new()); + Ok(()) + } + + /// A saved managed Python that still works is reported, and left as it was. + #[cfg(unix)] + #[test] + fn a_dry_run_reports_a_usable_saved_managed_python_and_changes_nothing() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-dry-run-saved")?; + let managed_dir = host.paths.data_dir.join("tools").join("python"); + fs::create_dir_all(&managed_dir)?; + let managed = write_fake_python_with_venv(&managed_dir, "python")?; + let manifest = host.save_managed_python(managed.clone())?; + let before = snapshot(&host.paths); + + let planned = host.python_for_install(true)?; + + let PlannedPython::Ready(launcher) = planned else { + panic!("a usable saved Python must be reported as ready, got {planned:?}"); + }; + assert_eq!(launcher.source, "managed"); + assert_eq!(launcher.executable, managed); + assert!(!host.uv_was_run()); + assert!( + !host.paths.config_path().exists(), + "reporting a saved Python must not re-save it in the configuration" + ); + assert_eq!( + fs::read(managed_python_manifest_path(&host.paths))?, + manifest + ); + assert_eq!(snapshot(&host.paths), before); + Ok(()) + } + + /// A saved managed Python that no longer works is a host with none: the + /// preview says one would be prepared, and leaves the stale record alone + /// rather than clearing or rewriting it. + #[cfg(unix)] + #[test] + fn a_dry_run_with_an_unusable_saved_python_prepares_nothing() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-dry-run-stale")?; + let managed_dir = host.paths.data_dir.join("tools").join("python"); + fs::create_dir_all(&managed_dir)?; + let broken = managed_dir.join("python"); + fs::write(&broken, "not an interpreter")?; + let manifest = host.save_managed_python(broken)?; + let before = snapshot(&host.paths); + + let planned = host.python_for_install(true)?; + + assert!( + matches!(planned, PlannedPython::WouldPrepareManaged { .. }), + "{planned:?}" + ); + assert!(!host.uv_was_run()); + assert!(!host.paths.config_path().exists()); + assert_eq!( + fs::read(managed_python_manifest_path(&host.paths))?, + manifest + ); + assert_eq!(snapshot(&host.paths), before); + Ok(()) + } + + /// Where an install refuses, the preview refuses too, with the same message: + /// a preview that printed a plan for an install that cannot happen would be + /// a false promise. + #[cfg(unix)] + #[test] + fn a_dry_run_refuses_where_the_install_does_when_managed_python_is_disabled() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-dry-run-disabled")?; + let _disabled = RestoredEnv::set(&[( + "ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP", + Some(Path::new("1")), + )]); + + let preview = host.python_for_install(true).unwrap_err().to_string(); + let install = host.python_for_install(false).unwrap_err().to_string(); + + assert!( + preview.contains("managed Python bootstrap is disabled"), + "{preview}" + ); + assert_eq!(preview, install); + assert!(!host.uv_was_run()); + Ok(()) + } + + /// An interpreter that has not been prepared yet is described by the one the + /// layout requires: that is what a real install insists on (see + /// `python_launcher_install_ready`), so it is what wheels must be chosen for. + #[test] + fn an_unprepared_python_is_described_by_the_interpreter_the_layout_requires() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + for (layout, tag, version) in [ + (SourceLayout::Canonical, "cp312", "3.12"), + (SourceLayout::Next, "cp314", "3.14"), + ] { + let requirement = python_requirement(layout); + let planned = PlannedPython::WouldPrepareManaged { + version: requirement.version.to_owned(), + requirement, + }; + + let compatibility = planned.wheel_compatibility()?; + assert_eq!(compatibility.python_tag, tag); + assert!(compatibility.platform_tags.contains(&"any".to_owned())); + assert_eq!(planned.source(), "managed"); + assert_eq!(planned.launcher_display(), "not prepared by this preview"); + assert_eq!(planned.venv_python_arg(), PathBuf::from(version)); + assert!( + planned + .note() + .is_some_and(|note| note.contains(&format!("managed Python {version}"))), + "{planned:?}" + ); + assert!( + planned.into_launcher().is_err(), + "an install must never proceed on a Python that was only planned" + ); + } + Ok(()) + } + + /// A ready interpreter prints as it always did: its path and its source, no + /// note. + #[test] + fn a_ready_python_prints_its_path_and_source() { + let planned = PlannedPython::Ready(PythonLauncher { + executable: PathBuf::from("/usr/bin/python3"), + source: "path", + }); + assert_eq!(planned.launcher_display(), "/usr/bin/python3"); + assert_eq!(planned.source(), "path"); + assert_eq!(planned.venv_python_arg(), PathBuf::from("/usr/bin/python3")); + assert!(planned.note().is_none()); + assert_eq!( + planned.into_launcher().unwrap().executable, + PathBuf::from("/usr/bin/python3") + ); + } + #[test] #[cfg(unix)] fn ensure_uv_venv_recreates_on_interpreter_tag_mismatch() { diff --git a/crates/rocm-dash-tui/src/agent/tools.rs b/crates/rocm-dash-tui/src/agent/tools.rs index 113ece0518..7a28e07aaf 100644 --- a/crates/rocm-dash-tui/src/agent/tools.rs +++ b/crates/rocm-dash-tui/src/agent/tools.rs @@ -202,11 +202,13 @@ pub const SKILL_NAMES: [&str; 4] = [ // whose state changed (and drops the endpoint key of a service whose requested // stop has finished). `doctor`/`examine` can re-register the configured setup // runtime in the runtime registry when its entry is missing. `update_check` and -// `install_sdk_dry_run` cache package-index metadata under the cache folder -// and, on a host with no usable Python on PATH, can download a managed `uv` and -// Python into the data folder and record that Python in the saved config. The -// boundary type (`SharedRocmToolExecutor`) is plain data — importing it does NOT -// pull `rocm-core` into this crate; the `agent` module stays the sole `rig` namer. +// `install_sdk_dry_run` cache package-index metadata under the cache folder. +// `update_check` can also, on a host with no usable Python on PATH, download a +// managed `uv` and Python into the data folder and record that Python in the +// saved config; `install_sdk_dry_run` does not: on such a host it reports the +// Python a real install would prepare and prepares none. The boundary type +// (`SharedRocmToolExecutor`) is plain data — importing it does NOT pull +// `rocm-core` into this crate; the `agent` module stays the sole `rig` namer. // --------------------------------------------------------------------------- /// Shared body for every read-only ROCm tool: forward the intent to the injected diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 6b18e694a1..a4830033bd 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -158,6 +158,14 @@ Expected result: asking and prints a line crediting that flag by name — not `--yes`. - `rocm install sdk ... --dry-run` never prompts or refuses, whatever the active default is: the preview stops before the gate. +- On a host with no usable Python (a minimal container; run with `PATH` pointing + at an empty folder and no `ROCM_CLI_PYTHON`) and a clean data folder, + `rocm install sdk ... --dry-run` still prints a plan. Its `python_launcher:` + line says `not prepared by this preview`, `python_source:` says `managed`, + and a `python_note:` line says a real install would use `uv` to install the + managed Python. Afterwards the data folder has no `tools` folder and the + config folder has no `config.json`: the preview downloaded no `uv` or Python + and saved no Python path. A real install on the same host does both. - rocm-cli creates or reuses a rocm-cli managed Python venv. - pip installs pinned `rocm`, `torch`, and `torchvision` requirements with exactly one `device-` extra (`rocm` also requests diff --git a/docs/testing.md b/docs/testing.md index 525cb9fb99..464ccdb3e8 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -508,6 +508,17 @@ The preview path is unaffected: `--dry-run` returns before the gate is consulted, so `rocm install sdk --channel release --format wheel --dry-run` never prompts and never refuses, whatever the active default is. +The preview also prepares no Python. On a host with no usable Python, a real +install downloads a managed `uv`, has it install Python, and saves that Python's +path in the config; `--dry-run` instead prints a `python_note:` line saying so +and does none of it. Scenario `runtime-22` checks the note and the empty +managed-tools, cache-tools and config folders together, with a recording `uv` +standing in for the download. It runs on Linux; the decision itself is +unit-tested on Unix hosts (the Python stand-ins are shell scripts, as in the +other resolver tests) by `a_dry_run_with_no_usable_python_prepares_nothing` in +[python.rs](../apps/rocm/src/therock/python.rs). The preview does still write +its package-index cache under the cache folder. + Then it verifies: - runtime manifest metadata diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 6e9e51e819..71a34c7e7d 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -451,3 +451,34 @@ Feature: Runtime configuration When the user previews a tarball SDK install Then the preview selects the newest SDK in the catalog And the preview does not claim the host's ROCm is newer + + # A preview is a promise that nothing on the machine changes. On a host with + # no usable Python the install needs one, and the preview used to go and get + # it: it downloaded a managed `uv`, had `uv` install Python, and saved that + # Python's path in the configuration, all before printing a plan. The assistant's + # `install_sdk_dry_run` tool reaches the same code. Now the preview reports that + # a managed Python would be prepared and prepares nothing. + # + # The preview's own note says it prepared nothing, so the Then checks that note + # and the state together: no `uv` invocation, no managed tools folder, no + # downloaded tool archive and no saved configuration. The recording `uv` is what + # makes "no download" observable without the network: the CLI reaches it only by + # going on to prepare a Python. The first Then shows the preview still got as far + # as a plan, so the empty folders are not just a command that stopped early. + # + # Linux only: the empty-`PATH` host is built for the Linux search order. The + # decision itself is unit-tested on Unix hosts against an injected search path + # (`a_dry_run_with_no_usable_python_prepares_nothing` in + # `apps/rocm/src/therock/python.rs`); the Windows search order and a Windows + # run of this preview are not covered by a test. + # + # Technical details: the fixture serves one canonical release index, `PATH` is a + # single empty folder, and `ROCM_CLI_UV_BINARY` names a stand-in that appends + # its arguments to a log file. + @id:runtime-install-preview-prepares-no-python @requires-os:linux + Scenario: runtime-22 - Previewing an SDK install on a host with no usable Python prepares no Python + Given a canonical release pip index fixture + And a host with no usable Python and a recording uv + When the user previews a wheel SDK install for arch gfx1200 with no version pin + Then the preview says a real install would prepare a managed Python + And the preview prepared no Python, as it says diff --git a/tests/e2e-cucumber/src/bin/fake-uv.rs b/tests/e2e-cucumber/src/bin/fake-uv.rs index 110890919b..3227ae5abc 100644 --- a/tests/e2e-cucumber/src/bin/fake-uv.rs +++ b/tests/e2e-cucumber/src/bin/fake-uv.rs @@ -10,11 +10,25 @@ //! //! `FAKE_UV_STDOUT` — a line to print to stdout before exiting (unset: none). //! `FAKE_UV_EXIT_CODE` — the exit code to return (unset: `0`). +//! `FAKE_UV_LOG` — a file to append one line per invocation to, holding the +//! arguments it was given (unset: nothing is written). A scenario that must +//! show `uv` was never run asserts the file does not exist. //! //! A Rust binary rather than a shell script so the scenarios run on Windows //! too. fn main() { + if let Some(log) = std::env::var_os("FAKE_UV_LOG").map(std::path::PathBuf::from) { + use std::io::Write as _; + let args: Vec = std::env::args().skip(1).collect(); + let mut file = std::fs::OpenOptions::new() + .create(true) + .append(true) + .open(&log) + .unwrap_or_else(|e| panic!("failed to open FAKE_UV_LOG {}: {e}", log.display())); + writeln!(file, "{}", args.join(" ")) + .unwrap_or_else(|e| panic!("failed to write FAKE_UV_LOG {}: {e}", log.display())); + } if let Ok(line) = std::env::var("FAKE_UV_STDOUT") { println!("{line}"); } diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 9104b50b09..6962f5fdbb 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -233,6 +233,68 @@ fn allow_base_overrides(world: &mut E2eWorld) { .push(("ROCM_CLI_THEROCK_ALLOW_BASE_OVERRIDE", "1".into())); } +/// Only the canonical release index, for a scenario that never pins ROCm 10 and +/// so never reaches the next layout. +#[given("a canonical release pip index fixture")] +async fn canonical_pip_index_fixture(world: &mut E2eWorld) { + let served = root(world).join("therock-pip-fixtures"); + write_pip_index( + &served.join("current"), + [ + ("rocm", CURRENT_ROCM_VERSION), + ("torch", CURRENT_TORCH_VERSION), + ("torchvision", CURRENT_TORCHVISION_VERSION), + ("torchaudio", CURRENT_TORCHAUDIO_VERSION), + ], + ); + serve_pip_fixtures(world); +} + +/// File the recording `uv` appends to, one line per invocation. +const UV_INVOCATION_LOG: &str = "uv-invocations.log"; + +/// A host where the CLI can find no Python: `PATH` is one empty folder, so the +/// search comes up empty and no managed Python has been saved. `uv` is a +/// recording stand-in named through `ROCM_CLI_UV_BINARY`, so a CLI that goes on +/// to prepare a managed Python reaches it, instead of downloading the real one, +/// and leaves a line behind. +/// +/// Relies on the ambient environment not naming a Python: a set +/// `ROCM_CLI_PYTHON` would answer the search before it looks at `PATH`, and a +/// set `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP` would turn the case this +/// scenario is about into an error. Either would make the scenario pass or fail +/// for a reason it does not name, so they are refused up front. +#[given("a host with no usable Python and a recording uv")] +async fn host_with_no_python_and_recording_uv(world: &mut E2eWorld) { + for var in [ + "ROCM_CLI_PYTHON", + "ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP", + ] { + assert!( + std::env::var_os(var).is_none(), + "{var} is set in the environment running the suite, which would change what this \ + scenario exercises; unset it" + ); + } + let scenario_root = root(world).to_path_buf(); + let empty_path = scenario_root.join("no-python-on-path"); + std::fs::create_dir_all(&empty_path).expect("failed to create the empty PATH folder"); + let uv = scenario_root + .join("recording-uv-bin") + .join(e2e_cucumber::fixture_binary::fixture_target_name("uv")); + crate::install_fixture_binary("fake-uv", &uv); + world + .command_env + .push(("PATH", empty_path.into_os_string())); + world + .command_env + .push(("ROCM_CLI_UV_BINARY", uv.into_os_string())); + world.command_env.push(( + "FAKE_UV_LOG", + scenario_root.join(UV_INVOCATION_LOG).into_os_string(), + )); +} + #[given("a canonical release pip index fixture and a ROCm 10 pip index fixture")] async fn pip_index_fixtures(world: &mut E2eWorld) { let served = root(world).join("therock-pip-fixtures"); @@ -990,6 +1052,71 @@ fn assert_contains(world: &E2eWorld, needle: &str, what: &str) { ); } +/// The managed interpreter the canonical layout needs. Keep in step with +/// `DEFAULT_MANAGED_PYTHON_VERSION` in `apps/rocm/src/therock/python.rs`. +const CANONICAL_MANAGED_PYTHON: &str = "3.12"; + +#[then("the preview says a real install would prepare a managed Python")] +async fn preview_says_managed_python_would_be_prepared(world: &mut E2eWorld) { + assert_contains(world, "python_source: managed", "python source"); + assert_contains( + world, + "python_launcher: not prepared by this preview", + "python launcher", + ); + assert_contains( + world, + &format!("would use uv to install managed Python {CANONICAL_MANAGED_PYTHON}"), + "python note", + ); +} + +/// The preview says it prepared no Python, and the state it left agrees. The +/// claim and the filesystem are checked together: the note alone would pass +/// with the bug present, and so would the empty folders alone if the preview +/// had simply stopped before it got to the Python. +#[then("the preview prepared no Python, as it says")] +async fn preview_prepared_no_python(world: &mut E2eWorld) { + assert_contains( + world, + "which this preview did not do", + "the note about what the preview skipped", + ); + assert_contains( + world, + &format!( + "a real install would prepare Python {CANONICAL_MANAGED_PYTHON}. This preview does not." + ), + "the progress line about what the preview skipped", + ); + let paths = world.app_paths(); + let scenario_root = root(world).to_path_buf(); + let uv_log = scenario_root.join(UV_INVOCATION_LOG); + assert!( + !uv_log.exists(), + "the preview ran uv, which it says it did not:\n{}", + std::fs::read_to_string(&uv_log).unwrap_or_default() + ); + let tools = rocm_core::managed_tools_dir(&paths.data_dir); + assert!( + !tools.exists(), + "the preview created the managed tools folder {}, which would hold a managed uv and Python", + tools.display() + ); + assert!( + !paths.cache_dir.join("tools").exists(), + "the preview downloaded a tool archive into {}", + paths.cache_dir.join("tools").display() + ); + let config = paths.config_path(); + assert!( + !config.exists(), + "the preview saved a configuration at {}, which would record a managed Python: {}", + config.display(), + std::fs::read_to_string(&config).unwrap_or_default() + ); +} + #[then("the preview resolves the canonical release pip index")] async fn preview_resolves_canonical_pip_index(world: &mut E2eWorld) { let base = current_pip_base(world); From e8a29221a570857a27c8498454f31d985d084dc9 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 11:35:05 +0000 Subject: [PATCH 02/25] fix(install): refuse a dry run for a managed Python the install would refuse With ROCM_CLI_MANAGED_PYTHON_VERSION naming a version whose wheel tag is not the one the layout needs (3.13 against cp312), a dry run on a host with no usable Python said it would prepare that Python, but a real install prepares it, finds the wrong tag and refuses. The preview now applies the same tag rule, shared with the check an existing interpreter must pass, and fails with the install's message instead. A version whose tag cannot be read off its name is announced as before. Adds a unit test and scenario runtime-23, which asserts the refusal together with the empty tools, cache and config folders. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 112 ++++++++++++++++-- docs/testing.md | 11 +- .../features/runtime_setup.feature | 20 ++++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 50 +++++++- 4 files changed, 181 insertions(+), 12 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 1c1a498270..b29a81dcfe 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -498,10 +498,26 @@ fn plan_python_launcher_in( let lookup = find_python_launcher_in(paths, env, requirement, LookupPurpose::Preview)?; Ok(match lookup { PythonLookup::Found(launcher) => PlannedPython::Ready(launcher), - PythonLookup::NeedsManagedBootstrap => PlannedPython::WouldPrepareManaged { - version: managed_python_version(requirement), - requirement, - }, + PythonLookup::NeedsManagedBootstrap => { + let version = managed_python_version(requirement); + // `ROCM_CLI_MANAGED_PYTHON_VERSION` can name a version other than the + // one the wheels need. A real install prepares it, finds it reports + // the wrong tag and refuses (see `ensure_managed_python`), so the + // preview refuses by the same rule rather than announce a plan the + // install would not carry out. A version whose tag cannot be read + // off its name is announced as is: only installing it would tell. + if let Some(tag) = python_tag_for_version(&version) { + ensure_python_tag_matches(&tag, requirement).with_context(|| { + format!( + "a real install would prepare managed Python {version}, whose wheel tag it would then refuse" + ) + })?; + } + PlannedPython::WouldPrepareManaged { + version, + requirement, + } + } }) } @@ -734,14 +750,32 @@ pub(super) fn python_launcher_install_ready( requirement: PythonRequirement, ) -> Result<()> { let compatibility = wheel_compatibility_for_python(program)?; - if compatibility.python_tag != requirement.tag { + ensure_python_tag_matches(&compatibility.python_tag, requirement)?; + verify_python_can_create_venv(program).context("Python could not create a virtual environment") +} + +/// The one rule an interpreter must meet to serve an install: its wheel tag is +/// the one the layout requires. [`python_launcher_install_ready`] applies it to +/// an interpreter that exists, and a preview applies it to the managed Python it +/// would prepare, so the two cannot disagree about what the install accepts. +fn ensure_python_tag_matches(python_tag: &str, requirement: PythonRequirement) -> Result<()> { + if python_tag != requirement.tag { bail!( - "Python wheel tag {} is not supported by this ROCm install; {} is required", - compatibility.python_tag, + "Python wheel tag {python_tag} is not supported by this ROCm install; {} is required", requirement.tag ); } - verify_python_can_create_venv(program).context("Python could not create a virtual environment") + Ok(()) +} + +/// The wheel tag a managed Python requested as `version` reports (`3.13` and +/// `3.13.1` both give `cp313`), or `None` when `version` is not a plain +/// `major.minor[.patch]` and the tag cannot be told without installing it. +fn python_tag_for_version(version: &str) -> Option { + let mut parts = version.trim().split('.'); + let major = parts.next()?.parse::().ok()?; + let minor = parts.next()?.parse::().ok()?; + Some(format!("cp{major}{minor}")) } fn verify_python_can_create_venv(program: &Path) -> Result<()> { @@ -1529,6 +1563,68 @@ exit 1 Ok(()) } + /// `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version whose wheel tag is not + /// the one the layout needs: a real install prepares it and then refuses it, + /// so the preview refuses too, by the same rule, and prepares nothing. A + /// version the layout does accept (a patch release of its own minor) is still + /// announced as before. + #[cfg(unix)] + #[test] + fn a_dry_run_refuses_a_managed_python_version_the_install_would_refuse() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-dry-run-version-override")?; + let overridden = + RestoredEnv::set(&[("ROCM_CLI_MANAGED_PYTHON_VERSION", Some(Path::new("3.13")))]); + + let error = format!("{:#}", host.python_for_install(true).unwrap_err()); + + assert!( + error.contains("would prepare managed Python 3.13") + && error.contains("Python wheel tag cp313 is not supported") + && error.contains("cp312 is required"), + "{error}" + ); + assert!(!host.uv_was_run()); + assert_eq!(snapshot(&host.paths), Vec::::new()); + drop(overridden); + + // A patch release of the required minor is what the install accepts. + let _patch = + RestoredEnv::set(&[("ROCM_CLI_MANAGED_PYTHON_VERSION", Some(Path::new("3.12.4")))]); + let planned = host.python_for_install(true)?; + assert!( + matches!(&planned, PlannedPython::WouldPrepareManaged { version, .. } if version == "3.12.4"), + "{planned:?}" + ); + assert!(!host.uv_was_run()); + Ok(()) + } + + /// The version-to-tag reading the preview's refusal rests on, and that it is + /// the same rule `python_launcher_install_ready` applies (same message). + #[test] + fn a_managed_python_version_is_read_as_the_wheel_tag_it_reports() { + assert_eq!(python_tag_for_version("3.12").as_deref(), Some("cp312")); + assert_eq!(python_tag_for_version(" 3.14.1 ").as_deref(), Some("cp314")); + assert_eq!(python_tag_for_version("3.9").as_deref(), Some("cp39")); + // Not a plain major.minor: only installing it would say what it reports. + for unreadable in ["", "3", "3.x", "cpython-3.13", "3.13t", "latest"] { + assert_eq!(python_tag_for_version(unreadable), None, "{unreadable:?}"); + } + + let required = python_requirement(SourceLayout::Canonical); + assert!(ensure_python_tag_matches("cp312", required).is_ok()); + let error = ensure_python_tag_matches("cp313", required) + .unwrap_err() + .to_string(); + assert_eq!( + error, + "Python wheel tag cp313 is not supported by this ROCm install; cp312 is required" + ); + } + /// An interpreter that has not been prepared yet is described by the one the /// layout requires: that is what a real install insists on (see /// `python_launcher_install_ready`), so it is what wheels must be chosen for. diff --git a/docs/testing.md b/docs/testing.md index 464ccdb3e8..fb62a42c7c 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -513,9 +513,14 @@ install downloads a managed `uv`, has it install Python, and saves that Python's path in the config; `--dry-run` instead prints a `python_note:` line saying so and does none of it. Scenario `runtime-22` checks the note and the empty managed-tools, cache-tools and config folders together, with a recording `uv` -standing in for the download. It runs on Linux; the decision itself is -unit-tested on Unix hosts (the Python stand-ins are shell scripts, as in the -other resolver tests) by `a_dry_run_with_no_usable_python_prepares_nothing` in +standing in for the download. It does not announce a Python the install would +refuse either: with `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version whose +wheel tag is not the layout's (3.13 for the canonical cp312 layout) the preview +fails with the install's own message, which scenario `runtime-23` checks. Both +run on Linux; the decisions themselves are unit-tested on Unix hosts (the Python +stand-ins are shell scripts, as in the other resolver tests) by +`a_dry_run_with_no_usable_python_prepares_nothing` and +`a_dry_run_refuses_a_managed_python_version_the_install_would_refuse` in [python.rs](../apps/rocm/src/therock/python.rs). The preview does still write its package-index cache under the cache folder. diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 71a34c7e7d..0013da21c0 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -482,3 +482,23 @@ Feature: Runtime configuration When the user previews a wheel SDK install for arch gfx1200 with no version pin Then the preview says a real install would prepare a managed Python And the preview prepared no Python, as it says + + # A preview must not announce a plan the install would refuse. + # `ROCM_CLI_MANAGED_PYTHON_VERSION` can name a Python other than the one the + # wheels need (3.12 for this layout); a real install prepares it, finds its + # wheel tag is wrong and refuses. The preview refuses by the same rule instead + # of saying it would prepare 3.13, and still prepares nothing on the way to + # refusing, which the last Then checks against the folders, as runtime-22 does. + # + # Linux only, for the same empty-`PATH` host as runtime-22. The tag rule is + # unit-tested on every platform + # (`a_managed_python_version_is_read_as_the_wheel_tag_it_reports` in + # `apps/rocm/src/therock/python.rs`). + @id:runtime-install-preview-refuses-unusable-managed-python @requires-os:linux + Scenario: runtime-23 - Previewing an SDK install is refused when the install would refuse the managed Python version + Given a canonical release pip index fixture + And a host with no usable Python and a recording uv + And the managed Python version is overridden to 3.13 + When the user tries to preview a wheel SDK install for arch gfx1200 with no version pin + Then the install fails + And the preview is refused because the install would refuse that Python diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 6962f5fdbb..3ad9a6b084 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -252,7 +252,6 @@ async fn canonical_pip_index_fixture(world: &mut E2eWorld) { /// File the recording `uv` appends to, one line per invocation. const UV_INVOCATION_LOG: &str = "uv-invocations.log"; - /// A host where the CLI can find no Python: `PATH` is one empty folder, so the /// search comes up empty and no managed Python has been saved. `uv` is a /// recording stand-in named through `ROCM_CLI_UV_BINARY`, so a CLI that goes on @@ -1089,6 +1088,12 @@ async fn preview_prepared_no_python(world: &mut E2eWorld) { ), "the progress line about what the preview skipped", ); + assert_no_python_prepared(world); +} + +/// The state half of the claim: no `uv` run, no managed tools folder, no +/// downloaded tool archive, no saved configuration. +fn assert_no_python_prepared(world: &E2eWorld) { let paths = world.app_paths(); let scenario_root = root(world).to_path_buf(); let uv_log = scenario_root.join(UV_INVOCATION_LOG); @@ -1117,6 +1122,49 @@ async fn preview_prepared_no_python(world: &mut E2eWorld) { ); } +#[given("the managed Python version is overridden to 3.13")] +async fn managed_python_version_overridden(world: &mut E2eWorld) { + world + .command_env + .push(("ROCM_CLI_MANAGED_PYTHON_VERSION", "3.13".into())); +} + +#[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", + ], + ); +} + +/// The refusal names the version and the tag rule, as a real install would +/// meet it, and the state agrees that nothing was prepared on the way to it. +#[then("the preview is refused because the install would refuse that Python")] +async fn preview_refused_for_python_version(world: &mut E2eWorld) { + let stderr = world.cli_stderr.clone().unwrap_or_default(); + for needle in [ + "would prepare managed Python 3.13", + "Python wheel tag cp313 is not supported", + "cp312 is required", + ] { + assert!( + stderr.contains(needle), + "expected {needle:?} in the refusal:\n{stderr}" + ); + } + assert_no_python_prepared(world); +} + #[then("the preview resolves the canonical release pip index")] async fn preview_resolves_canonical_pip_index(world: &mut E2eWorld) { let base = current_pip_base(world); From 1936bcef144532625f9b6f5ae4968b2664daf8a8 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 11:40:51 +0000 Subject: [PATCH 03/25] test(e2e): give runtime-22 and runtime-23 a cache folder of their own The harness points the CLI at a cache shared across scenarios and, on CI, across runs. runtime-22 asserted that the preview had downloaded no tool archive by looking in that shared folder, so a uv archive left by an earlier run failed it although the preview downloaded nothing. The scenarios now set ROCM_CLI_CACHE_DIR to a folder under the scenario root and assert against it. Signed-off-by: Jussi Elo --- .../features/runtime_setup.feature | 6 ++++-- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 20 +++++++++++++++++-- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 0013da21c0..b091f0722f 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -473,8 +473,10 @@ Feature: Runtime configuration # run of this preview are not covered by a test. # # Technical details: the fixture serves one canonical release index, `PATH` is a - # single empty folder, and `ROCM_CLI_UV_BINARY` names a stand-in that appends - # its arguments to a log file. + # single empty folder, `ROCM_CLI_UV_BINARY` names a stand-in that appends its + # arguments to a log file, and `ROCM_CLI_CACHE_DIR` is a folder of this + # scenario's own, so a tool archive left in the cache the suite shares across + # scenarios and runs is not mistaken for one this preview downloaded. @id:runtime-install-preview-prepares-no-python @requires-os:linux Scenario: runtime-22 - Previewing an SDK install on a host with no usable Python prepares no Python Given a canonical release pip index fixture diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 3ad9a6b084..281f7b7883 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -252,6 +252,10 @@ async fn canonical_pip_index_fixture(world: &mut E2eWorld) { /// File the recording `uv` appends to, one line per invocation. const UV_INVOCATION_LOG: &str = "uv-invocations.log"; + +/// The per-scenario cache folder, under the scenario root. +const SCRATCH_CACHE_DIR: &str = "scratch-cache"; + /// A host where the CLI can find no Python: `PATH` is one empty folder, so the /// search comes up empty and no managed Python has been saved. `uv` is a /// recording stand-in named through `ROCM_CLI_UV_BINARY`, so a CLI that goes on @@ -285,6 +289,15 @@ async fn host_with_no_python_and_recording_uv(world: &mut E2eWorld) { world .command_env .push(("PATH", empty_path.into_os_string())); + // A cache folder of this scenario's own. The harness otherwise points the + // CLI at a cache shared across scenarios and, on CI, across runs, where a + // tool archive an earlier scenario downloaded would be mistaken for one the + // preview downloaded. Overrides the shared one for this scenario only. + let scratch_cache = scenario_root.join(SCRATCH_CACHE_DIR); + std::fs::create_dir_all(&scratch_cache).expect("failed to create the scratch cache folder"); + world + .command_env + .push(("ROCM_CLI_CACHE_DIR", scratch_cache.into_os_string())); world .command_env .push(("ROCM_CLI_UV_BINARY", uv.into_os_string())); @@ -1108,10 +1121,13 @@ fn assert_no_python_prepared(world: &E2eWorld) { "the preview created the managed tools folder {}, which would hold a managed uv and Python", tools.display() ); + // The scenario's own cache folder (see the Given), not `paths.cache_dir`, + // which is the shared one where a run's leftovers would already be. + let cache_tools = scenario_root.join(SCRATCH_CACHE_DIR).join("tools"); assert!( - !paths.cache_dir.join("tools").exists(), + !cache_tools.exists(), "the preview downloaded a tool archive into {}", - paths.cache_dir.join("tools").display() + cache_tools.display() ); let config = paths.config_path(); assert!( From 2b1fd044fb5d7e0616d63534834418509b1047c8 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 13:08:09 +0000 Subject: [PATCH 04/25] fix(install): read every spelling of a managed Python version in a dry run The dry run's check of ROCM_CLI_MANAGED_PYTHON_VERSION read only plain major.minor versions, so 3.13t, cpython-3.13 and cpython@3.13 were announced as a plan although the installed interpreter reports cp313 and the real install refuses it. The version is now read in those spellings. A version whose tag still cannot be read is announced as unchecked, in both the note and the progress line, rather than as a promise. The progress line before the search no longer says a real install would prepare a Python, since the search can end in a refusal; the line naming the Python, or the refusal, follows it. runtime-23 asserts the whole output: no promise before the refusal. Signed-off-by: Jussi Elo --- apps/rocm/src/therock.rs | 26 +-- apps/rocm/src/therock/python.rs | 191 ++++++++++++++++-- docs/testing.md | 14 +- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 17 ++ 4 files changed, 218 insertions(+), 30 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index f719fa2e3b..4645410211 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -361,15 +361,17 @@ fn install_wheel_runtime( } } }; - progress_line(format!( - "Checking Python for the ROCm install; if needed, {} Python {}.", - if dry_run { - "a real install would prepare" - } else { - "ROCm CLI will prepare" - }, - managed_python_version(python_requirement) - )); + // A preview promises nothing here: whether a Python would be prepared, and + // which, is only known once the search below has run (a version override can + // make the answer a refusal), and is reported then. + progress_line(if dry_run { + "Checking Python for the ROCm install.".to_owned() + } else { + format!( + "Checking Python for the ROCm install; if needed, ROCm CLI will prepare Python {}.", + managed_python_version(python_requirement) + ) + }); // A preview must not prepare the Python it reports: resolving one can // download a managed `uv` and Python and save the result in the // configuration. It asks what a real install would do instead and prints @@ -388,9 +390,9 @@ fn install_wheel_runtime( ), _ => format!("Using Python from {}.", launcher.executable.display()), }, - PlannedPython::WouldPrepareManaged { version, .. } => format!( - "No usable Python found; a real install would prepare Python {version}. This preview does not." - ), + PlannedPython::WouldPrepareManaged { .. } => { + python.skipped_preparation_line().unwrap_or_default() + } }); let wheel_compatibility = python.wheel_compatibility()?; progress_line(format!( diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index b29a81dcfe..0da4b15243 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -505,9 +505,11 @@ fn plan_python_launcher_in( // the wrong tag and refuses (see `ensure_managed_python`), so the // preview refuses by the same rule rather than announce a plan the // install would not carry out. A version whose tag cannot be read - // off its name is announced as is: only installing it would tell. - if let Some(tag) = python_tag_for_version(&version) { - ensure_python_tag_matches(&tag, requirement).with_context(|| { + // off its name is announced as unchecked: only installing it would + // tell. + let tag = python_tag_for_version(&version); + if let Some(tag) = tag.as_deref() { + ensure_python_tag_matches(tag, requirement).with_context(|| { format!( "a real install would prepare managed Python {version}, whose wheel tag it would then refuse" ) @@ -516,6 +518,7 @@ fn plan_python_launcher_in( PlannedPython::WouldPrepareManaged { version, requirement, + tag_checked: tag.is_some(), } } }) @@ -527,10 +530,13 @@ pub(super) enum PlannedPython { /// An interpreter that is usable as it stands. Ready(PythonLauncher), /// No interpreter is usable. A real install would prepare managed Python - /// `version`; this preview has not. + /// `version`; this preview has not. `tag_checked` is whether the wheel tag + /// `version` reports could be read off its name and matched against the + /// requirement; when it could not, only installing it would say. WouldPrepareManaged { version: String, requirement: PythonRequirement, + tag_checked: bool, }, } @@ -569,9 +575,47 @@ impl PlannedPython { pub(super) fn note(&self) -> Option { match self { Self::Ready(_) => None, - Self::WouldPrepareManaged { version, .. } => Some(format!( - "no usable Python was found; a real install would use uv to install managed Python {version} and save its path in the configuration, which this preview did not do" - )), + Self::WouldPrepareManaged { + version, + requirement, + tag_checked, + } => { + let unchecked = if *tag_checked { + String::new() + } else { + format!( + " (its wheel tag cannot be checked until it is installed; {} is required)", + requirement.tag + ) + }; + Some(format!( + "no usable Python was found; a real install would use uv to install managed Python {version}{unchecked} and save its path in the configuration, which this preview did not do" + )) + } + } + } + + /// The progress line a preview prints when it reaches a host with no usable + /// Python, in place of the interpreter line. Built from the same fields as + /// [`Self::note`], so the two cannot differ about the version or whether its + /// tag was checked. + pub(super) fn skipped_preparation_line(&self) -> Option { + match self { + Self::Ready(_) => None, + Self::WouldPrepareManaged { + version, + requirement, + tag_checked, + } => Some(if *tag_checked { + format!( + "No usable Python found; a real install would prepare Python {version}. This preview does not." + ) + } else { + format!( + "No usable Python found; a real install would prepare Python {version}, whose wheel tag cannot be checked until it is installed ({} is required). This preview does not.", + requirement.tag + ) + }), } } @@ -768,13 +812,30 @@ fn ensure_python_tag_matches(python_tag: &str, requirement: PythonRequirement) - Ok(()) } -/// The wheel tag a managed Python requested as `version` reports (`3.13` and -/// `3.13.1` both give `cp313`), or `None` when `version` is not a plain -/// `major.minor[.patch]` and the tag cannot be told without installing it. +/// The wheel tag a managed Python requested as `version` reports, or `None` +/// when it cannot be told without installing it. +/// +/// `uv` is what reads `version` (it is passed through to `uv python install`), +/// and this repo has no parser of its own to share, so this reads the spellings +/// `uv` accepts for a CPython release that name a major and a minor: `3.13`, +/// `3.13.1`, `3.13t` (free-threaded, which still reports `cp313`), and any of +/// those after `cpython-` or `cpython@`. Anything else (another implementation, +/// a range, a wildcard, a pre-release spelled on the minor) yields `None`. fn python_tag_for_version(version: &str) -> Option { - let mut parts = version.trim().split('.'); + let version = version.trim(); + let version = ["cpython-", "cpython@"] + .iter() + .find_map(|prefix| version.strip_prefix(prefix)) + .unwrap_or(version); + let mut parts = version.split('.'); let major = parts.next()?.parse::().ok()?; - let minor = parts.next()?.parse::().ok()?; + let minor = parts.next()?; + // Only a free-threaded marker may follow the minor's digits. + let minor = minor + .strip_suffix('t') + .unwrap_or(minor) + .parse::() + .ok()?; Some(format!("cp{major}{minor}")) } @@ -1407,12 +1468,14 @@ exit 1 let PlannedPython::WouldPrepareManaged { ref version, requirement, + tag_checked, } = planned else { panic!("a host with no Python must be planned as needing one, got {planned:?}"); }; assert_eq!(version, DEFAULT_MANAGED_PYTHON_VERSION); assert_eq!(requirement, python_requirement(SourceLayout::Canonical)); + assert!(tag_checked, "the default version's tag is readable"); let note = planned .note() .expect("a preview that skipped a step says so"); @@ -1602,6 +1665,80 @@ exit 1 Ok(()) } + /// The same refusal for every spelling `uv` accepts for that release: a + /// free-threaded `3.13t` and the `cpython-` and `cpython@` forms report + /// `cp313` once installed just as `3.13` does, so a preview that did not read + /// them would promise a plan the install refuses. A spelling whose tag + /// cannot be read is announced as unchecked, not as a promise. + #[cfg(unix)] + #[test] + fn a_dry_run_reads_every_spelling_of_a_managed_python_version_the_same_way() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-dry-run-version-spellings")?; + for spelling in ["3.13t", "cpython-3.13", "cpython@3.13"] { + let _version = + RestoredEnv::set(&[("ROCM_CLI_MANAGED_PYTHON_VERSION", Some(Path::new(spelling)))]); + let error = format!("{:#}", host.python_for_install(true).unwrap_err()); + assert!( + error.contains(&format!("would prepare managed Python {spelling}")) + && error.contains("Python wheel tag cp313 is not supported") + && error.contains("cp312 is required"), + "{spelling}: {error}" + ); + } + for accepted in ["cpython-3.12", "cpython@3.12.4"] { + let _version = + RestoredEnv::set(&[("ROCM_CLI_MANAGED_PYTHON_VERSION", Some(Path::new(accepted)))]); + let planned = host.python_for_install(true)?; + assert!( + matches!( + &planned, + PlannedPython::WouldPrepareManaged { + tag_checked: true, + .. + } + ), + "{accepted}: {planned:?}" + ); + } + + let _unreadable = RestoredEnv::set(&[( + "ROCM_CLI_MANAGED_PYTHON_VERSION", + Some(Path::new("pypy@3.10")), + )]); + let planned = host.python_for_install(true)?; + assert!( + matches!( + &planned, + PlannedPython::WouldPrepareManaged { + tag_checked: false, + .. + } + ), + "{planned:?}" + ); + let note = planned + .note() + .expect("a preview that skipped a step says so"); + assert!( + note.contains("managed Python pypy@3.10 (its wheel tag cannot be checked until it is installed; cp312 is required)") + && note.ends_with("which this preview did not do"), + "{note}" + ); + let line = planned + .skipped_preparation_line() + .expect("a preview that skipped a step says so"); + assert_eq!( + line, + "No usable Python found; a real install would prepare Python pypy@3.10, whose wheel tag cannot be checked until it is installed (cp312 is required). This preview does not." + ); + assert!(!host.uv_was_run()); + assert_eq!(snapshot(&host.paths), Vec::::new()); + Ok(()) + } + /// The version-to-tag reading the preview's refusal rests on, and that it is /// the same rule `python_launcher_install_ready` applies (same message). #[test] @@ -1609,8 +1746,33 @@ exit 1 assert_eq!(python_tag_for_version("3.12").as_deref(), Some("cp312")); assert_eq!(python_tag_for_version(" 3.14.1 ").as_deref(), Some("cp314")); assert_eq!(python_tag_for_version("3.9").as_deref(), Some("cp39")); - // Not a plain major.minor: only installing it would say what it reports. - for unreadable in ["", "3", "3.x", "cpython-3.13", "3.13t", "latest"] { + // Spellings `uv` accepts for the same CPython release read the same. + assert_eq!(python_tag_for_version("3.13t").as_deref(), Some("cp313")); + assert_eq!(python_tag_for_version("3.13.1").as_deref(), Some("cp313")); + assert_eq!(python_tag_for_version("3.13.*").as_deref(), Some("cp313")); + assert_eq!( + python_tag_for_version("cpython-3.13").as_deref(), + Some("cp313") + ); + assert_eq!( + python_tag_for_version("cpython@3.13").as_deref(), + Some("cp313") + ); + assert_eq!( + python_tag_for_version("cpython-3.12.4").as_deref(), + Some("cp312") + ); + // Anything else: only installing it would say what it reports. + for unreadable in [ + "", + "3", + "3.x", + "latest", + "pypy@3.10", + "3.13rc1", + ">=3.12", + "cpython-", + ] { assert_eq!(python_tag_for_version(unreadable), None, "{unreadable:?}"); } @@ -1641,6 +1803,7 @@ exit 1 let planned = PlannedPython::WouldPrepareManaged { version: requirement.version.to_owned(), requirement, + tag_checked: true, }; let compatibility = planned.wheel_compatibility()?; diff --git a/docs/testing.md b/docs/testing.md index fb62a42c7c..4c1cf0afcb 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -514,13 +514,19 @@ path in the config; `--dry-run` instead prints a `python_note:` line saying so and does none of it. Scenario `runtime-22` checks the note and the empty managed-tools, cache-tools and config folders together, with a recording `uv` standing in for the download. It does not announce a Python the install would -refuse either: with `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version whose -wheel tag is not the layout's (3.13 for the canonical cp312 layout) the preview -fails with the install's own message, which scenario `runtime-23` checks. Both +refuse either: with `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version that reads +as a wheel tag other than the layout's (`3.13`, `3.13t`, `cpython-3.13` or +`cpython@3.13` for the canonical cp312 layout) the preview fails with the +install's own message, before it prints any plan or a line saying it would +prepare that Python, which scenario `runtime-23` checks for `3.13`. A version +whose tag cannot be read off its name (`pypy@3.10`, a range) is announced as +unchecked: the note and the progress line say its tag cannot be checked until it +is installed. Both scenarios run on Linux; the decisions themselves are unit-tested on Unix hosts (the Python stand-ins are shell scripts, as in the other resolver tests) by `a_dry_run_with_no_usable_python_prepares_nothing` and -`a_dry_run_refuses_a_managed_python_version_the_install_would_refuse` in +`a_dry_run_refuses_a_managed_python_version_the_install_would_refuse` and +`a_dry_run_reads_every_spelling_of_a_managed_python_version_the_same_way` in [python.rs](../apps/rocm/src/therock/python.rs). The preview does still write its package-index cache under the cache folder. diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 281f7b7883..9197e54fea 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -1178,6 +1178,23 @@ async fn preview_refused_for_python_version(world: &mut E2eWorld) { "expected {needle:?} in the refusal:\n{stderr}" ); } + // The progress lines must not promise what the refusal then takes back: the + // output holds no "would prepare Python 3.13" and no plan. + let out = stdout(world); + assert!( + out.contains("Checking Python for the ROCm install.\n"), + "expected the neutral Python check line:\n{out}" + ); + for promise in [ + "would prepare Python 3.13", + "ROCm CLI will prepare", + "sdk install", + ] { + assert!( + !out.contains(promise), + "the output promised {promise:?} before refusing:\n{out}" + ); + } assert_no_python_prepared(world); } From 794081a431a719b983dbede4598eea12c0ebd647 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 13:09:54 +0000 Subject: [PATCH 05/25] test(e2e): present the uv log, not the cache folder, as runtime-22's evidence ROCM_CLI_UV_BINARY makes the CLI return the recording uv before any download could begin, so the check for a tool archive in the scenario's cache cannot fail by itself. It stays as a backstop and says so; the scenario comments and docs/testing.md now name the uv log as what shows nothing was prepared. Signed-off-by: Jussi Elo --- docs/testing.md | 17 +++++++++-------- .../e2e-cucumber/features/runtime_setup.feature | 15 +++++++++------ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 17 +++++++++++------ 3 files changed, 29 insertions(+), 20 deletions(-) diff --git a/docs/testing.md b/docs/testing.md index 4c1cf0afcb..91d7ecb177 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -511,20 +511,21 @@ never prompts and never refuses, whatever the active default is. The preview also prepares no Python. On a host with no usable Python, a real install downloads a managed `uv`, has it install Python, and saves that Python's path in the config; `--dry-run` instead prints a `python_note:` line saying so -and does none of it. Scenario `runtime-22` checks the note and the empty -managed-tools, cache-tools and config folders together, with a recording `uv` -standing in for the download. It does not announce a Python the install would -refuse either: with `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version that reads +and does none of it. Scenario `runtime-22` checks the note against the state it +left: a recording `uv` standing in for the download was never run (that log is +the evidence; no network is involved), and there is no managed-tools folder and +no saved config. It also looks for a tool archive in its own cache folder, but +only as a backstop: the stand-in `uv` is returned before a download could start. +The preview does not announce a Python the install would refuse either: with `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version that reads as a wheel tag other than the layout's (`3.13`, `3.13t`, `cpython-3.13` or `cpython@3.13` for the canonical cp312 layout) the preview fails with the install's own message, before it prints any plan or a line saying it would prepare that Python, which scenario `runtime-23` checks for `3.13`. A version whose tag cannot be read off its name (`pypy@3.10`, a range) is announced as unchecked: the note and the progress line say its tag cannot be checked until it -is installed. Both scenarios -run on Linux; the decisions themselves are unit-tested on Unix hosts (the Python -stand-ins are shell scripts, as in the other resolver tests) by -`a_dry_run_with_no_usable_python_prepares_nothing` and +is installed. Both scenarios run on Linux; the decisions themselves are +unit-tested on Unix hosts (the Python stand-ins are shell scripts, as in the +other resolver tests) by `a_dry_run_with_no_usable_python_prepares_nothing`, `a_dry_run_refuses_a_managed_python_version_the_install_would_refuse` and `a_dry_run_reads_every_spelling_of_a_managed_python_version_the_same_way` in [python.rs](../apps/rocm/src/therock/python.rs). The preview does still write diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index b091f0722f..496b7543b6 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -460,11 +460,14 @@ Feature: Runtime configuration # a managed Python would be prepared and prepares nothing. # # The preview's own note says it prepared nothing, so the Then checks that note - # and the state together: no `uv` invocation, no managed tools folder, no - # downloaded tool archive and no saved configuration. The recording `uv` is what - # makes "no download" observable without the network: the CLI reaches it only by - # going on to prepare a Python. The first Then shows the preview still got as far - # as a plan, so the empty folders are not just a command that stopped early. + # and the state together. The evidence is the recording `uv`: the CLI reaches + # it only by going on to prepare a Python, so its log not existing means no + # preparation was attempted, with no network needed. Beside it the Then checks + # that no managed tools folder and no configuration exist; a tool archive in the + # scenario's cache is checked too, but only as a backstop, since the stand-in + # `uv` is returned before any download could start. The first Then shows the + # preview still got as far as a plan, so the absences are not just a command + # that stopped early. # # Linux only: the empty-`PATH` host is built for the Linux search order. The # decision itself is unit-tested on Unix hosts against an injected search path @@ -476,7 +479,7 @@ Feature: Runtime configuration # single empty folder, `ROCM_CLI_UV_BINARY` names a stand-in that appends its # arguments to a log file, and `ROCM_CLI_CACHE_DIR` is a folder of this # scenario's own, so a tool archive left in the cache the suite shares across - # scenarios and runs is not mistaken for one this preview downloaded. + # scenarios and runs cannot trip the backstop check. @id:runtime-install-preview-prepares-no-python @requires-os:linux Scenario: runtime-22 - Previewing an SDK install on a host with no usable Python prepares no Python Given a canonical release pip index fixture diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 9197e54fea..287067b417 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -291,8 +291,8 @@ async fn host_with_no_python_and_recording_uv(world: &mut E2eWorld) { .push(("PATH", empty_path.into_os_string())); // A cache folder of this scenario's own. The harness otherwise points the // CLI at a cache shared across scenarios and, on CI, across runs, where a - // tool archive an earlier scenario downloaded would be mistaken for one the - // preview downloaded. Overrides the shared one for this scenario only. + // tool archive an earlier run left would trip the backstop check for one in + // the cache. Overrides the shared one for this scenario only. let scratch_cache = scenario_root.join(SCRATCH_CACHE_DIR); std::fs::create_dir_all(&scratch_cache).expect("failed to create the scratch cache folder"); world @@ -1104,8 +1104,9 @@ async fn preview_prepared_no_python(world: &mut E2eWorld) { assert_no_python_prepared(world); } -/// The state half of the claim: no `uv` run, no managed tools folder, no -/// downloaded tool archive, no saved configuration. +/// The state half of the claim: the recording `uv` was never run (the evidence +/// that nothing was prepared), no managed tools folder, no saved configuration, +/// and, as a backstop only, no tool archive in the scenario's cache. fn assert_no_python_prepared(world: &E2eWorld) { let paths = world.app_paths(); let scenario_root = root(world).to_path_buf(); @@ -1121,8 +1122,12 @@ fn assert_no_python_prepared(world: &E2eWorld) { "the preview created the managed tools folder {}, which would hold a managed uv and Python", tools.display() ); - // The scenario's own cache folder (see the Given), not `paths.cache_dir`, - // which is the shared one where a run's leftovers would already be. + // A backstop, not the detector. `ROCM_CLI_UV_BINARY` makes `ensure_uv_binary` + // return the recording `uv` before any download could begin, so this folder + // stays empty even if the preview did go on to prepare a Python; the `uv` + // log above is what shows that. It is the scenario's own cache folder (see + // the Given), not `paths.cache_dir`, which is the shared one where a run's + // leftovers would already be. let cache_tools = scenario_root.join(SCRATCH_CACHE_DIR).join("tools"); assert!( !cache_tools.exists(), From 1177a6b0b1eed545687521d7109a1ffa117717eb Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 15:22:06 +0000 Subject: [PATCH 06/25] fix(install): print a dry run's Python prediction only after the decision With an unusable PATH Python, no usable saved interpreter and managed Python disabled, the preview said a real install would use managed Python and then refused; the saved-interpreter line made the same premature claim. The two lines now state only what was found. The one line that predicts the preparation is built from the decision itself and printed by python_for_install, so it exists only for a decision that passed the bootstrap policy and the version check; the Using lines moved there with it. A real install prints exactly what it did. Adds a state-matrix unit test over PATH Python, saved Python, bootstrap policy and version override that asserts each row's whole output and the state left behind, and scenario runtime-25 for the policy refusal. Signed-off-by: Jussi Elo --- apps/rocm/src/therock.rs | 20 +- apps/rocm/src/therock/python.rs | 336 +++++++++++++++--- .../features/runtime_setup.feature | 29 ++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 49 ++- 4 files changed, 373 insertions(+), 61 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index c12b59638b..caa2ed0dcb 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -41,7 +41,7 @@ pub(crate) use self::probe::{ }; use self::process::{extract_tarball_and_discard_archive, progress_line, run_uv_progress_command}; use self::python::{ - PlannedPython, ensure_uv_venv, managed_python_version, python_for_install, python_requirement, + ensure_uv_venv, managed_python_version, python_for_install, python_requirement, }; use self::resolve::{ AggregateDeviceTarget, canonical_auto_select_needs_next_python, resolve_pip_runtime, @@ -377,24 +377,8 @@ fn install_wheel_runtime( // download a managed `uv` and Python and save the result in the // configuration. It asks what a real install would do instead and prints // that. A real install resolves, and so prepares, exactly as it always did. + // It also prints the line naming the interpreter, once the decision is made. let python = python_for_install(paths, python_requirement, dry_run)?; - progress_line(match &python { - PlannedPython::Ready(launcher) => match launcher.source { - "path" => format!("Using Python from PATH: {}.", launcher.executable.display()), - "env" => format!( - "Using Python from ROCM_CLI_PYTHON: {}.", - launcher.executable.display() - ), - "managed" => format!( - "Using ROCm CLI's portable Python: {}.", - launcher.executable.display() - ), - _ => format!("Using Python from {}.", launcher.executable.display()), - }, - PlannedPython::WouldPrepareManaged { .. } => { - python.skipped_preparation_line().unwrap_or_default() - } - }); let wheel_compatibility = python.wheel_compatibility()?; progress_line(format!( "Checking TheRock {} packages for this AMD GPU...", diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 2d343f7d4a..817e93180b 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -460,16 +460,24 @@ pub(super) fn resolve_python_launcher( /// /// The single place the install decides between the two, so a dry run cannot /// reach [`resolve_python_launcher`]'s preparation by a path of its own. +/// +/// It also prints the line that says which interpreter was chosen, once the +/// choice is made. A preview's line is built from the same value the decision +/// returned ([`PlannedPython::progress_text`]), so a line that says what a real +/// install would do cannot be printed on a path that ends in a refusal: the +/// refusal returns before any such line exists. pub(super) fn python_for_install( paths: &AppPaths, requirement: PythonRequirement, dry_run: bool, ) -> Result { - if dry_run { - plan_python_launcher(paths, requirement) + let python = if dry_run { + plan_python_launcher(paths, requirement)? } else { - resolve_python_launcher(paths, requirement).map(PlannedPython::Ready) - } + PlannedPython::Ready(resolve_python_launcher(paths, requirement)?) + }; + progress_line(python.progress_text()); + Ok(python) } /// The interpreter a *preview* of the install reports, found without preparing @@ -595,27 +603,43 @@ impl PlannedPython { } } - /// The progress line a preview prints when it reaches a host with no usable - /// Python, in place of the interpreter line. Built from the same fields as - /// [`Self::note`], so the two cannot differ about the version or whether its - /// tag was checked. - pub(super) fn skipped_preparation_line(&self) -> Option { + /// The progress line that names the chosen interpreter: the one an install + /// goes on with, or, for a preview on a host with no usable Python, what a + /// real install would prepare. It is the only line that predicts the + /// preparation, and it exists only for a decision that has already passed the + /// bootstrap policy and the version check, so the two cannot disagree. Built + /// from the same fields as [`Self::note`], so the two cannot differ about the + /// version or whether its tag was checked. + pub(super) fn progress_text(&self) -> String { match self { - Self::Ready(_) => None, + Self::Ready(launcher) => match launcher.source { + "path" => format!("Using Python from PATH: {}.", launcher.executable.display()), + "env" => format!( + "Using Python from ROCM_CLI_PYTHON: {}.", + launcher.executable.display() + ), + "managed" => format!( + "Using ROCm CLI's portable Python: {}.", + launcher.executable.display() + ), + _ => format!("Using Python from {}.", launcher.executable.display()), + }, Self::WouldPrepareManaged { version, requirement, tag_checked, - } => Some(if *tag_checked { - format!( - "No usable Python found; a real install would prepare Python {version}. This preview does not." - ) - } else { - format!( - "No usable Python found; a real install would prepare Python {version}, whose wheel tag cannot be checked until it is installed ({} is required). This preview does not.", - requirement.tag - ) - }), + } => { + if *tag_checked { + format!( + "No usable Python found; a real install would prepare Python {version}. This preview does not." + ) + } else { + format!( + "No usable Python found; a real install would prepare Python {version}, whose wheel tag cannot be checked until it is installed ({} is required). This preview does not.", + requirement.tag + ) + } + } } } @@ -646,8 +670,9 @@ impl PlannedPython { } /// Whether a search for an interpreter is for an install or a preview of one. -/// It changes only the wording of the progress line about a saved Python that -/// turned out unusable: a preview must not say it is preparing one. +/// It changes only the wording of the two progress lines about a Python that +/// turned out unusable: an install says what it goes on to do, a preview states +/// the finding and leaves the prediction to the decision's own line. #[derive(Clone, Copy)] enum LookupPurpose { Install, @@ -705,15 +730,22 @@ fn find_python_launcher_in( } } } + // A preview states only what it found here. What a real install would then + // do depends on the saved Python, the bootstrap policy and the version, none + // of which is known yet, so the prediction waits for + // `PlannedPython::progress_text`, after the decision. An install's wording is + // unchanged. if skipped_path_python { - progress_line(format!( - "Python from PATH is not usable for this ROCm install ({} is required); {} ROCm CLI's managed Python.", - requirement.tag, - match purpose { - LookupPurpose::Install => "using", - LookupPurpose::Preview => "a real install would use", - } - )); + progress_line(match purpose { + LookupPurpose::Install => format!( + "Python from PATH is not usable for this ROCm install ({} is required); using ROCm CLI's managed Python.", + requirement.tag + ), + LookupPurpose::Preview => format!( + "Python from PATH is not usable for this ROCm install ({} is required).", + requirement.tag + ), + }); } if let Some(manifest) = load_managed_python_manifest(paths)? @@ -725,14 +757,16 @@ fn find_python_launcher_in( source: "managed", })); } - progress_line(format!( - "Saved managed Python is not usable for this ROCm install ({} is required); {}.", - requirement.tag, - match purpose { - LookupPurpose::Install => "preparing Python again", - LookupPurpose::Preview => "a real install would prepare Python again", - } - )); + progress_line(match purpose { + LookupPurpose::Install => format!( + "Saved managed Python is not usable for this ROCm install ({} is required); preparing Python again.", + requirement.tag + ), + LookupPurpose::Preview => format!( + "Saved managed Python is not usable for this ROCm install ({} is required).", + requirement.tag + ), + }); } if managed_python_bootstrap_disabled() { @@ -1665,6 +1699,227 @@ exit 1 Ok(()) } + // ---- the preview's output, row by row ------------------------------------- + // + // State matrix for what a dry run prints about Python and what it leaves + // behind. A preview line that says what a real install would do must exist + // only where the install would do it, so every row below is the whole output + // of the decision, not a spot check of one line. + // + // PATH Python usable | unusable | absent + // saved Python usable | unusable | absent + // bootstrap enabled | disabled (ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP) + // version default | accepted patch release | unreadable | refused tag + // + // Expected output by row (cp312 required; `P`, `S` are the PATH and saved + // interpreters): + // PATH usable -> `Using Python from PATH: P.`; nothing else + // PATH unusable, saved usable -> PATH finding, `Using ROCm CLI's portable Python: S.` + // neither usable, bootstrap off -> findings only, then the refusal; no promise + // neither usable, version refused -> findings only, then the refusal; no promise + // neither usable, otherwise -> findings, then the one promise + // `No usable Python found; a real install + // would prepare Python V.` (V checked or not) + // A finding is `Python from PATH is not usable ... (cp312 is required).` or + // `Saved managed Python is not usable ... (cp312 is required).`, printed only + // for a PATH or saved Python that exists and fails. Every row leaves the + // config, data and cache folders as they were and never runs `uv`. + + #[cfg(unix)] + #[derive(Clone, Copy, Debug)] + enum PathPython { + Usable, + Unusable, + Absent, + } + + #[cfg(unix)] + #[derive(Clone, Copy, Debug)] + enum SavedPython { + Usable, + Unusable, + Absent, + } + + #[cfg(unix)] + #[derive(Clone, Copy, Debug)] + enum VersionOverride { + Default, + Accepted, + Unreadable, + RefusedTag, + } + + /// Runs one row of the matrix and checks the preview's complete output and + /// the state it leaves against what the row's description above says. + #[cfg(unix)] + fn check_preview_matrix_row( + path: PathPython, + saved: SavedPython, + bootstrap_disabled: bool, + version: VersionOverride, + ) -> Result<()> { + use super::super::process::PROGRESS_LINE_SINK; + + let row = format!( + "{path:?} PATH / {saved:?} saved / disabled={bootstrap_disabled} / {version:?}" + ); + let host = PythonHost::new("python-dry-run-matrix")?; + let path_python = match path { + PathPython::Usable => Some(write_fake_python_with_venv(&host.search_dir, "python3")?), + PathPython::Unusable => { + write_fake_python_reporting(&host.search_dir, "python3", "cp311", "Python 3.11.0")?; + None + } + PathPython::Absent => None, + }; + let managed_dir = host.paths.data_dir.join("tools").join("python"); + let saved_python = match saved { + SavedPython::Usable => { + fs::create_dir_all(&managed_dir)?; + let python = write_fake_python_with_venv(&managed_dir, "python")?; + host.save_managed_python(python.clone())?; + Some(python) + } + SavedPython::Unusable => { + fs::create_dir_all(&managed_dir)?; + let broken = managed_dir.join("python"); + fs::write(&broken, "not an interpreter")?; + host.save_managed_python(broken)?; + None + } + SavedPython::Absent => None, + }; + let (version_value, version_name) = match version { + VersionOverride::Default => (None, "3.12"), + VersionOverride::Accepted => (Some("3.12.4"), "3.12.4"), + VersionOverride::Unreadable => (Some("pypy@3.10"), "pypy@3.10"), + VersionOverride::RefusedTag => (Some("3.13"), "3.13"), + }; + let _env = RestoredEnv::set(&[ + ( + "ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP", + bootstrap_disabled.then_some(Path::new("1")), + ), + ( + "ROCM_CLI_MANAGED_PYTHON_VERSION", + version_value.map(Path::new), + ), + ]); + let before = snapshot(&host.paths); + + // What the row's description says, written out independently of the code. + let path_finding = + "Python from PATH is not usable for this ROCm install (cp312 is required)."; + let saved_finding = + "Saved managed Python is not usable for this ROCm install (cp312 is required)."; + let mut expected: Vec = Vec::new(); + let mut expected_error: Option<&str> = None; + let mut expected_promise = false; + if let Some(python) = &path_python { + expected.push(format!("Using Python from PATH: {}.", python.display())); + } else { + if matches!(path, PathPython::Unusable) { + expected.push(path_finding.to_owned()); + } + if let Some(python) = &saved_python { + expected.push(format!( + "Using ROCm CLI's portable Python: {}.", + python.display() + )); + } else { + if matches!(saved, SavedPython::Unusable) { + expected.push(saved_finding.to_owned()); + } + if bootstrap_disabled { + expected_error = Some("managed Python bootstrap is disabled"); + } else if matches!(version, VersionOverride::RefusedTag) { + expected_error = Some("Python wheel tag cp313 is not supported"); + } else { + expected_promise = true; + expected.push(if matches!(version, VersionOverride::Unreadable) { + format!("No usable Python found; a real install would prepare Python {version_name}, whose wheel tag cannot be checked until it is installed (cp312 is required). This preview does not.") + } else { + format!("No usable Python found; a real install would prepare Python {version_name}. This preview does not.") + }); + } + } + } + + PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().clear()); + let result = host.python_for_install(true); + let lines = PROGRESS_LINE_SINK.with(|sink| sink.borrow().clone()); + + assert_eq!(lines, expected, "{row}: the preview's progress lines"); + // No line that predicts the install may exist unless the row ends in + // the promise: a refusal is known before any such line is built. + let predictions = lines + .iter() + .filter(|line| line.contains("a real install would")) + .count(); + assert_eq!( + predictions, + usize::from(expected_promise), + "{row}: lines that predict the install: {lines:?}" + ); + match (&result, expected_error) { + (Err(error), Some(expected)) => { + assert!(format!("{error:#}").contains(expected), "{row}: {error:#}"); + } + (Ok(planned), None) => { + assert_eq!( + planned.note().is_some(), + expected_promise, + "{row}: the note goes with the promise" + ); + if expected_promise { + assert!( + planned.note().is_some_and( + |note| note.contains(&format!("managed Python {version_name}")) + ), + "{row}: {planned:?}" + ); + } + } + (result, expected) => panic!("{row}: got {result:?}, expected error {expected:?}"), + } + // State: nothing was prepared and nothing was written. + assert!(!host.uv_was_run(), "{row}: the preview ran uv"); + assert!( + !host.paths.config_path().exists(), + "{row}: a config was written" + ); + assert_eq!(snapshot(&host.paths), before, "{row}: files changed"); + Ok(()) + } + + #[cfg(unix)] + #[test] + fn a_dry_runs_whole_python_output_follows_one_decision_in_every_state() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + for path in [PathPython::Usable, PathPython::Unusable, PathPython::Absent] { + for saved in [ + SavedPython::Usable, + SavedPython::Unusable, + SavedPython::Absent, + ] { + for bootstrap_disabled in [false, true] { + for version in [ + VersionOverride::Default, + VersionOverride::Accepted, + VersionOverride::Unreadable, + VersionOverride::RefusedTag, + ] { + check_preview_matrix_row(path, saved, bootstrap_disabled, version)?; + } + } + } + } + Ok(()) + } + /// The same refusal for every spelling `uv` accepts for that release: a /// free-threaded `3.13t` and the `cpython-` and `cpython@` forms report /// `cp313` once installed just as `3.13` does, so a preview that did not read @@ -1727,11 +1982,8 @@ exit 1 && note.ends_with("which this preview did not do"), "{note}" ); - let line = planned - .skipped_preparation_line() - .expect("a preview that skipped a step says so"); assert_eq!( - line, + planned.progress_text(), "No usable Python found; a real install would prepare Python pypy@3.10, whose wheel tag cannot be checked until it is installed (cp312 is required). This preview does not." ); assert!(!host.uv_was_run()); diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 42304c073a..4c1f3085a7 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -491,6 +491,11 @@ Feature: Runtime configuration # preview still got as far as a plan, so the absences are not just a command # that stopped early. # + # The guarantee is the canonical layout's. A preview of a ROCm 10 or newer wheel + # resolves its package versions with `uv pip compile` and so can fetch the + # managed `uv` (creating the `tools` folder) on a clean host, though it still + # prepares no Python; this scenario is not that case and does not claim it. + # # Linux only: the empty-`PATH` host is built for the Linux search order. The # decision itself is unit-tested on Unix hosts against an injected search path # (`a_dry_run_with_no_usable_python_prepares_nothing` in @@ -529,3 +534,27 @@ Feature: Runtime configuration When the user tries to preview a wheel SDK install for arch gfx1200 with no version pin Then the install fails And the preview is refused because the install would refuse that Python + + # The sibling of runtime-24 for the policy refusal. A preview must not say what + # a real install would do on a path where it would do nothing. Here the host's + # only Python cannot serve the install and managed Python is switched off with + # `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP`, so a real install refuses; the + # preview used to print that it would use ROCm CLI's managed Python first. It + # now prints the finding about the PATH Python, neutrally, and then the same + # refusal as the install, with no line predicting anything. The state is checked + # as in runtime-23. Every other combination of PATH Python, saved Python, + # bootstrap policy and version override is pinned by the unit test + # `a_dry_runs_whole_python_output_follows_one_decision_in_every_state` in + # `apps/rocm/src/therock/python.rs`, which asserts each row's complete output. + # + # Linux only, for the same empty-`PATH` host as runtime-23, with `fake-python` + # planted on it as the unusable interpreter. + @id:runtime-install-preview-refuses-disabled-managed-python @requires-os:linux + Scenario: runtime-25 - Previewing an SDK install is refused when managed Python is disabled and the host's Python is unusable + Given a canonical release pip index fixture + And a host with no usable Python and a recording uv + And the only Python on the host's path is not usable + And managed Python bootstrap is disabled + When the user tries to preview a wheel SDK install for arch gfx1200 with no version pin + Then the install fails + And the preview is refused because managed Python is disabled, without a promise diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 475efcd437..d07a243d34 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -1156,7 +1156,10 @@ async fn preview_prepared_no_python(world: &mut E2eWorld) { /// The state half of the claim: the recording `uv` was never run (the evidence /// that nothing was prepared), no managed tools folder, no saved configuration, -/// and, as a backstop only, no tool archive in the scenario's cache. +/// and, as a backstop only, no tool archive in the scenario's cache. Every +/// scenario that calls this previews the canonical layout (no ROCm 10 pin), the +/// only layout whose preview needs no `uv`; a ROCm 10 preview can legitimately +/// create the managed tools folder to resolve package versions. fn assert_no_python_prepared(world: &E2eWorld) { let paths = world.app_paths(); let scenario_root = root(world).to_path_buf(); @@ -1193,6 +1196,50 @@ fn assert_no_python_prepared(world: &E2eWorld) { ); } +/// Plants an interpreter on the empty `PATH` folder that cannot serve the +/// install: `fake-python` answers the wheel-tag probe with `{}`, which is not +/// the tag the layout needs, so the search finds a Python and rejects it. +#[given("the only Python on the host's path is not usable")] +async fn only_unusable_python_on_path(world: &mut E2eWorld) { + let python = root(world).join("no-python-on-path").join("python3"); + crate::install_fixture_binary("fake-python", &python); +} + +#[given("managed Python bootstrap is disabled")] +async fn managed_python_bootstrap_disabled(world: &mut E2eWorld) { + world + .command_env + .push(("ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP", "1".into())); +} + +/// The refusal is the whole story: the output states the finding about the +/// `PATH` Python and the policy refusal, and no line says what a real install +/// would go on to do, since it would do nothing. +#[then("the preview is refused because managed Python is disabled, without a promise")] +async fn preview_refused_for_disabled_bootstrap(world: &mut E2eWorld) { + let stderr = world.cli_stderr.clone().unwrap_or_default(); + assert!( + stderr.contains("managed Python bootstrap is disabled"), + "expected the policy refusal:\n{stderr}" + ); + let out = stdout(world); + assert!( + out.contains("Python from PATH is not usable for this ROCm install (cp312 is required).\n"), + "expected the finding about the PATH Python:\n{out}" + ); + for promise in [ + "a real install would", + "ROCm CLI will prepare", + "sdk install", + ] { + assert!( + !out.contains(promise), + "the output promised {promise:?} before refusing:\n{out}" + ); + } + assert_no_python_prepared(world); +} + #[given("the managed Python version is overridden to 3.13")] async fn managed_python_version_overridden(world: &mut E2eWorld) { world From 72551d70654d8ac6927c2cf0a4791182596f9d02 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 15:23:23 +0000 Subject: [PATCH 07/25] docs: limit the dry run's no-uv guarantee to the canonical layout A preview of a ROCm 10 or newer wheel resolves its package versions with uv pip compile, so on a clean host it can still download the managed uv and create the data folder's tools folder, although it prepares no Python. docs/testing.md, docs/manual-testing.md and the dash-TUI tool-group comment now say so, and describe the state matrix and the refusal scenarios the preview is checked by. Signed-off-by: Jussi Elo --- crates/rocm-dash-tui/src/agent/tools.rs | 6 ++- docs/manual-testing.md | 12 +++++- docs/testing.md | 54 ++++++++++++++++--------- 3 files changed, 51 insertions(+), 21 deletions(-) diff --git a/crates/rocm-dash-tui/src/agent/tools.rs b/crates/rocm-dash-tui/src/agent/tools.rs index 6e8e321c7c..3b4a0a6512 100644 --- a/crates/rocm-dash-tui/src/agent/tools.rs +++ b/crates/rocm-dash-tui/src/agent/tools.rs @@ -210,8 +210,10 @@ pub const SKILL_NAMES: [&str; 4] = [ // `install_sdk_dry_run` cache package-index metadata under the cache folder. // `update_check` can also, on a host with no usable Python on PATH, download a // managed `uv` and Python into the data folder and record that Python in the -// saved config; `install_sdk_dry_run` does not: on such a host it reports the -// Python a real install would prepare and prepares none. The boundary type +// saved config; `install_sdk_dry_run` prepares no Python and saves no Python +// path: on such a host it reports the Python a real install would prepare. (A +// ROCm 10 preview still resolves package versions with `uv` and can fetch the +// managed `uv` into the data folder.) The boundary type // (`SharedRocmToolExecutor`) is plain data — importing it does NOT pull // `rocm-core` into this crate; the `agent` module stays the sole `rig` namer. // --------------------------------------------------------------------------- diff --git a/docs/manual-testing.md b/docs/manual-testing.md index a4830033bd..e05e5bcb80 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -165,7 +165,17 @@ Expected result: and a `python_note:` line says a real install would use `uv` to install the managed Python. Afterwards the data folder has no `tools` folder and the config folder has no `config.json`: the preview downloaded no `uv` or Python - and saved no Python path. A real install on the same host does both. + and saved no Python path. A real install on the same host does both. This + holds for the canonical layout. A preview pinned to ROCm 10 or newer + (`--version 10.0.0 --family gfx1200`) still needs `uv` to resolve the package + versions, so on a clean host it can download the managed `uv` and create the + `tools` folder, although it prepares no Python and saves no Python path. +- With `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP=1`, or a + `ROCM_CLI_MANAGED_PYTHON_VERSION` whose Python the layout does not accept + (such as `3.13` for the canonical layout), on the same host the preview fails + with the install's own message. Its output before the failure states only + what was found (for example that the `PATH` Python is not usable) and never + says a real install would prepare or use a managed Python. - rocm-cli creates or reuses a rocm-cli managed Python venv. - pip installs pinned `rocm`, `torch`, and `torchvision` requirements with exactly one `device-` extra (`rocm` also requests diff --git a/docs/testing.md b/docs/testing.md index 50dd87192d..86e1de5c06 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -511,25 +511,43 @@ never prompts and never refuses, whatever the active default is. The preview also prepares no Python. On a host with no usable Python, a real install downloads a managed `uv`, has it install Python, and saves that Python's path in the config; `--dry-run` instead prints a `python_note:` line saying so -and does none of it. Scenario `runtime-23` checks the note against the state it -left: a recording `uv` standing in for the download was never run (that log is -the evidence; no network is involved), and there is no managed-tools folder and -no saved config. It also looks for a tool archive in its own cache folder, but -only as a backstop: the stand-in `uv` is returned before a download could start. -The preview does not announce a Python the install would refuse either: with `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version that reads -as a wheel tag other than the layout's (`3.13`, `3.13t`, `cpython-3.13` or -`cpython@3.13` for the canonical cp312 layout) the preview fails with the -install's own message, before it prints any plan or a line saying it would -prepare that Python, which scenario `runtime-24` checks for `3.13`. A version -whose tag cannot be read off its name (`pypy@3.10`, a range) is announced as -unchecked: the note and the progress line say its tag cannot be checked until it -is installed. Both scenarios run on Linux; the decisions themselves are -unit-tested on Unix hosts (the Python stand-ins are shell scripts, as in the -other resolver tests) by `a_dry_run_with_no_usable_python_prepares_nothing`, +and does not prepare Python or save a Python path. Scenario `runtime-23` checks +the note against the state it left: a recording `uv` standing in for the download +was never run (that log is the evidence; no network is involved), and there is no +managed-tools folder and no saved config. It also looks for a tool archive in its +own cache folder, but only as a backstop: the stand-in `uv` is returned before a +download could start. That scenario is a canonical-layout preview. A preview of a +ROCm 10 or newer wheel (a `--version` pin of 10 or later) does still need `uv`: +it resolves the published package versions with `uv pip compile`, so on a clean +host it can download the managed `uv` and create the data folder's `tools` +folder, although it still prepares no Python. The "no `uv`, no `tools` folder" +guarantee is therefore the canonical layout's only. + +The preview does not announce a Python the install would refuse either, and it +prints nothing that predicts what a real install would do on a path that ends in +a refusal. With `ROCM_CLI_MANAGED_PYTHON_VERSION` naming a version that reads as +a wheel tag other than the layout's (`3.13`, `3.13t`, `cpython-3.13` or +`cpython@3.13` for the canonical cp312 layout), and with managed Python disabled +by `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP`, the preview fails with the +install's own message after stating only what it found (for example that the +`PATH` Python is not usable); the single line saying a real install would +prepare a managed Python appears only for a decision that passed both checks. +Scenarios `runtime-24` (the `3.13` refusal) and `runtime-25` (policy refusal with +an unusable `PATH` Python) check this on the whole output. A version whose tag +cannot be read off its name (`pypy@3.10`, a range) is announced as unchecked: the +note and the progress line say its tag cannot be checked until it is installed. +The scenarios run on Linux; the decisions themselves are unit-tested on Unix +hosts (the Python stand-ins are shell scripts, as in the other resolver tests). +`a_dry_runs_whole_python_output_follows_one_decision_in_every_state` in +[python.rs](../apps/rocm/src/therock/python.rs) is the state matrix: every +combination of `PATH` Python (usable, unusable, absent), saved Python (usable, +unusable, absent), bootstrap policy (enabled, disabled) and version override +(default, accepted, unreadable, refused tag), each asserting the complete +progress output and that `uv` was not run and no file was written. Beside it are +`a_dry_run_with_no_usable_python_prepares_nothing`, `a_dry_run_refuses_a_managed_python_version_the_install_would_refuse` and -`a_dry_run_reads_every_spelling_of_a_managed_python_version_the_same_way` in -[python.rs](../apps/rocm/src/therock/python.rs). The preview does still write -its package-index cache under the cache folder. +`a_dry_run_reads_every_spelling_of_a_managed_python_version_the_same_way`. The +preview does still write its package-index cache under the cache folder. Then it verifies: From 4ef1703793d55c5b4605a3331f668bc90b7f2652 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 09:43:50 +0000 Subject: [PATCH 08/25] docs(install): make python_tag_for_version's comment match what it reads The doc comment said a wildcard yields None, but "3.13.*" reads as cp313: whatever follows the minor is not validated, because the major and minor alone decide the wheel tag. A wildcard that leaves the minor open ("3.*", "*") is what yields None. Reword the comment to say so and pin both unreadable wildcards in the existing reader test. Also say in the comment that this hand-rolled reader can drift from what uv accepts, and that the failure is benign: an unreadable spelling is announced as unchecked rather than refused. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 817e93180b..9e28f68e3f 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -852,9 +852,20 @@ fn ensure_python_tag_matches(python_tag: &str, requirement: PythonRequirement) - /// `uv` is what reads `version` (it is passed through to `uv python install`), /// and this repo has no parser of its own to share, so this reads the spellings /// `uv` accepts for a CPython release that name a major and a minor: `3.13`, -/// `3.13.1`, `3.13t` (free-threaded, which still reports `cp313`), and any of -/// those after `cpython-` or `cpython@`. Anything else (another implementation, -/// a range, a wildcard, a pre-release spelled on the minor) yields `None`. +/// `3.13.1`, `3.13.*`, `3.13t` (free-threaded, which still reports `cp313`), and +/// any of those after `cpython-` or `cpython@`. Whatever follows the minor is +/// not validated, because only the major and minor decide the wheel tag. +/// Anything that leaves the minor open or names something else (another +/// implementation, a range, a wildcard such as `3.*`, a pre-release spelled on +/// the minor) yields `None`. +/// +/// This reader is a hand-rolled approximation of what `uv` accepts and can drift +/// from it in either direction: a spelling `uv` takes may read as `None`, and one +/// `uv` would reject may read as a tag. Both are benign. A `None` is announced +/// as unchecked (the preview still prints a plan and says the tag cannot be +/// checked until the Python is installed), never refused, and a tag read off a +/// spelling `uv` then rejects is only a preview that predicted an install that +/// fails at `uv python install`, with `uv`'s own error, as it always did. fn python_tag_for_version(version: &str) -> Option { let version = version.trim(); let version = ["cpython-", "cpython@"] @@ -2019,6 +2030,8 @@ exit 1 "", "3", "3.x", + "3.*", + "*", "latest", "pypy@3.10", "3.13rc1", From 148f9fb8123be0b62b95b636cf34b8e2d5114e81 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 09:52:24 +0000 Subject: [PATCH 09/25] refactor(install): word a preview's unchecked-tag caveat in one place A preview that would prepare a managed Python whose wheel tag cannot be read off its name said so twice, in the python_note line and in the progress line, each with its own sentence. Build the caveat from one function so the two cannot drift. The note is unchanged; the progress line now reads "... would prepare Python pypy@3.10 (its wheel tag cannot be checked until it is installed; cp312 is required). This preview does not." instead of using a "whose ... " clause. The unit tests that pin both lines are updated to match. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 53 ++++++++++++++++----------------- 1 file changed, 26 insertions(+), 27 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 9e28f68e3f..b5a40bafc7 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -587,19 +587,10 @@ impl PlannedPython { version, requirement, tag_checked, - } => { - let unchecked = if *tag_checked { - String::new() - } else { - format!( - " (its wheel tag cannot be checked until it is installed; {} is required)", - requirement.tag - ) - }; - Some(format!( - "no usable Python was found; a real install would use uv to install managed Python {version}{unchecked} and save its path in the configuration, which this preview did not do" - )) - } + } => Some(format!( + "no usable Python was found; a real install would use uv to install managed Python {version}{} and save its path in the configuration, which this preview did not do", + unchecked_tag_caveat(*tag_checked, *requirement) + )), } } @@ -628,18 +619,10 @@ impl PlannedPython { version, requirement, tag_checked, - } => { - if *tag_checked { - format!( - "No usable Python found; a real install would prepare Python {version}. This preview does not." - ) - } else { - format!( - "No usable Python found; a real install would prepare Python {version}, whose wheel tag cannot be checked until it is installed ({} is required). This preview does not.", - requirement.tag - ) - } - } + } => format!( + "No usable Python found; a real install would prepare Python {version}{}. This preview does not.", + unchecked_tag_caveat(*tag_checked, *requirement) + ), } } @@ -669,6 +652,22 @@ impl PlannedPython { } } +/// The parenthetical a preview adds after the Python it would prepare when that +/// version's wheel tag could not be read off its name, and nothing when it +/// could. One function for [`PlannedPython::note`] and +/// [`PlannedPython::progress_text`], so the two cannot word the same caveat +/// differently. +fn unchecked_tag_caveat(tag_checked: bool, requirement: PythonRequirement) -> String { + if tag_checked { + String::new() + } else { + format!( + " (its wheel tag cannot be checked until it is installed; {} is required)", + requirement.tag + ) + } +} + /// Whether a search for an interpreter is for an install or a preview of one. /// It changes only the wording of the two progress lines about a Python that /// turned out unusable: an install says what it goes on to do, a preview states @@ -1849,7 +1848,7 @@ exit 1 } else { expected_promise = true; expected.push(if matches!(version, VersionOverride::Unreadable) { - format!("No usable Python found; a real install would prepare Python {version_name}, whose wheel tag cannot be checked until it is installed (cp312 is required). This preview does not.") + format!("No usable Python found; a real install would prepare Python {version_name} (its wheel tag cannot be checked until it is installed; cp312 is required). This preview does not.") } else { format!("No usable Python found; a real install would prepare Python {version_name}. This preview does not.") }); @@ -1995,7 +1994,7 @@ exit 1 ); assert_eq!( planned.progress_text(), - "No usable Python found; a real install would prepare Python pypy@3.10, whose wheel tag cannot be checked until it is installed (cp312 is required). This preview does not." + "No usable Python found; a real install would prepare Python pypy@3.10 (its wheel tag cannot be checked until it is installed; cp312 is required). This preview does not." ); assert!(!host.uv_was_run()); assert_eq!(snapshot(&host.paths), Vec::::new()); From c5ea04f27abea65c4847cd33ac5d025da807901d Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 09:54:32 +0000 Subject: [PATCH 10/25] refactor(install): name a Python launcher's source with an enum PythonLauncher::source was a bare &'static str ("env", "path", "managed", "manifest") that three places matched or compared by spelling, with a catch-all arm in the progress line that would hide a new spelling. Make it a PythonSource enum with an as_str for the install plan's python_source line, and match it exhaustively in the progress text. The printed output is unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/therock.rs | 2 +- apps/rocm/src/therock/python.rs | 71 +++++++++++++++++++++++---------- apps/rocm/src/therock/update.rs | 6 +-- 3 files changed, 55 insertions(+), 24 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index caa2ed0dcb..e31b255aac 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -472,7 +472,7 @@ fn install_wheel_runtime( let _ = writeln!(output, " target: {}", install_root.display()); let _ = writeln!(output, " runtime_key: {runtime_key}"); let _ = writeln!(output, " python_launcher: {}", python.launcher_display()); - let _ = writeln!(output, " python_source: {}", python.source()); + let _ = writeln!(output, " python_source: {}", python.source().as_str()); if let Some(note) = python.note() { let _ = writeln!(output, " python_note: {note}"); } diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index b5a40bafc7..cb3f25c960 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -43,10 +43,35 @@ pub(super) struct WheelCompatibility { pub(super) platform_tags: Vec, } +/// Where an interpreter came from. `as_str` is what the install plan prints on +/// its `python_source:` line. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum PythonSource { + /// `ROCM_CLI_PYTHON`. + Env, + /// Found on `PATH`. + Path, + /// The managed Python ROCm CLI prepares. + Managed, + /// The interpreter an installed runtime's manifest recorded. + Manifest, +} + +impl PythonSource { + pub(super) const fn as_str(self) -> &'static str { + match self { + Self::Env => "env", + Self::Path => "path", + Self::Managed => "managed", + Self::Manifest => "manifest", + } + } +} + #[derive(Debug, Clone)] pub(super) struct PythonLauncher { pub(super) executable: PathBuf, - pub(super) source: &'static str, + pub(super) source: PythonSource, } #[derive(Debug, Clone, Serialize, Deserialize)] @@ -283,7 +308,7 @@ fn ensure_managed_python( let _ = record_managed_python_config(paths, &manifest.executable); return Ok(PythonLauncher { executable: manifest.executable, - source: "managed", + source: PythonSource::Managed, }); } @@ -357,7 +382,7 @@ fn ensure_managed_python( )); Ok(PythonLauncher { executable, - source: "managed", + source: PythonSource::Managed, }) } @@ -560,10 +585,10 @@ impl PlannedPython { } /// The `python_source:` line's value. - pub(super) const fn source(&self) -> &'static str { + pub(super) const fn source(&self) -> PythonSource { match self { Self::Ready(launcher) => launcher.source, - Self::WouldPrepareManaged { .. } => "managed", + Self::WouldPrepareManaged { .. } => PythonSource::Managed, } } @@ -604,16 +629,20 @@ impl PlannedPython { pub(super) fn progress_text(&self) -> String { match self { Self::Ready(launcher) => match launcher.source { - "path" => format!("Using Python from PATH: {}.", launcher.executable.display()), - "env" => format!( + PythonSource::Path => { + format!("Using Python from PATH: {}.", launcher.executable.display()) + } + PythonSource::Env => format!( "Using Python from ROCM_CLI_PYTHON: {}.", launcher.executable.display() ), - "managed" => format!( + PythonSource::Managed => format!( "Using ROCm CLI's portable Python: {}.", launcher.executable.display() ), - _ => format!("Using Python from {}.", launcher.executable.display()), + PythonSource::Manifest => { + format!("Using Python from {}.", launcher.executable.display()) + } }, Self::WouldPrepareManaged { version, @@ -711,7 +740,7 @@ fn find_python_launcher_in( .with_context(|| format!("ROCM_CLI_PYTHON is not usable for ROCm setup: {value}"))?; return Ok(PythonLookup::Found(PythonLauncher { executable: PathBuf::from(value), - source: "env", + source: PythonSource::Env, })); } @@ -721,7 +750,7 @@ fn find_python_launcher_in( Ok(()) => { return Ok(PythonLookup::Found(PythonLauncher { executable: candidate, - source: "path", + source: PythonSource::Path, })); } Err(_) => { @@ -753,7 +782,7 @@ fn find_python_launcher_in( if python_launcher_install_ready(&manifest.executable, requirement).is_ok() { return Ok(PythonLookup::Found(PythonLauncher { executable: manifest.executable, - source: "managed", + source: PythonSource::Managed, })); } progress_line(match purpose { @@ -1098,7 +1127,7 @@ exit 1 }, python_requirement(SourceLayout::Canonical), )?; - assert_eq!(launcher.source, "path"); + assert_eq!(launcher.source, PythonSource::Path); assert!( launcher.executable.is_absolute(), "PATH launcher should resolve to an absolute executable: {}", @@ -1201,7 +1230,7 @@ exit 1 python_requirement(SourceLayout::Canonical), )?; - assert_eq!(launcher.source, "path"); + assert_eq!(launcher.source, PythonSource::Path); assert!(path_python.exists()); fs::remove_dir_all(root).ok(); Ok(()) @@ -1268,7 +1297,8 @@ exit 1 }; assert_eq!( - launcher.source, "path", + launcher.source, + PythonSource::Path, "resolve_python_launcher must consult the test override, not the real environment" ); assert!(launcher.executable.starts_with(&bin_dir)); @@ -1569,7 +1599,7 @@ exit 1 let PlannedPython::Ready(launcher) = planned else { panic!("a usable PATH Python must be reported as ready, got {planned:?}"); }; - assert_eq!(launcher.source, "path"); + assert_eq!(launcher.source, PythonSource::Path); assert_eq!(launcher.executable, python); assert!(!host.uv_was_run()); assert_eq!(snapshot(&host.paths), Vec::::new()); @@ -1595,7 +1625,7 @@ exit 1 let PlannedPython::Ready(launcher) = planned else { panic!("a usable saved Python must be reported as ready, got {planned:?}"); }; - assert_eq!(launcher.source, "managed"); + assert_eq!(launcher.source, PythonSource::Managed); assert_eq!(launcher.executable, managed); assert!(!host.uv_was_run()); assert!( @@ -2073,7 +2103,8 @@ exit 1 let compatibility = planned.wheel_compatibility()?; assert_eq!(compatibility.python_tag, tag); assert!(compatibility.platform_tags.contains(&"any".to_owned())); - assert_eq!(planned.source(), "managed"); + assert_eq!(planned.source(), PythonSource::Managed); + assert_eq!(planned.source().as_str(), "managed"); assert_eq!(planned.launcher_display(), "not prepared by this preview"); assert_eq!(planned.venv_python_arg(), PathBuf::from(version)); assert!( @@ -2096,10 +2127,10 @@ exit 1 fn a_ready_python_prints_its_path_and_source() { let planned = PlannedPython::Ready(PythonLauncher { executable: PathBuf::from("/usr/bin/python3"), - source: "path", + source: PythonSource::Path, }); assert_eq!(planned.launcher_display(), "/usr/bin/python3"); - assert_eq!(planned.source(), "path"); + assert_eq!(planned.source().as_str(), "path"); assert_eq!(planned.venv_python_arg(), PathBuf::from("/usr/bin/python3")); assert!(planned.note().is_none()); assert_eq!( diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index 22b4e3c96a..662b306b65 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -25,8 +25,8 @@ use super::family::family_override_or_recovered_arch; use super::io::write_file_atomically; use super::process::SuppressProgressOutput; use super::python::{ - PythonLauncher, python_launcher_install_ready, python_requirement, resolve_python_launcher, - wheel_compatibility_for_python, + PythonLauncher, PythonSource, python_launcher_install_ready, python_requirement, + resolve_python_launcher, wheel_compatibility_for_python, }; use super::resolve::{ AggregateDeviceTarget, resolve_pip_runtime_with_timeout, resolve_tarball_artifact_with_timeout, @@ -434,7 +434,7 @@ fn resolve_latest_for_manifest( .filter(|path| python_launcher_install_ready(path, requirement).is_ok()) .map(|executable| PythonLauncher { executable, - source: "manifest", + source: PythonSource::Manifest, }); let python_executable = match manifest_python { Some(python) => python, From 41f30a13de54ae747b51b874d4b4b62625769e2e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 11:38:54 +0000 Subject: [PATCH 11/25] refactor(install): let the Python resolver's environment carry the managed-Python policy PythonResolverEnv already injects the two inputs that locate an interpreter (ROCM_CLI_PYTHON and the search directories), but the two inputs that decide what happens when none is found were still read from the process environment inside the decision: whether the managed bootstrap is disabled and which managed Python version is requested. A test of that decision therefore had to mutate process-wide environment variables under a lock. Both now travel in PythonResolverEnv (read once by from_process_env, which the real resolver still uses), and find_python_launcher_in, plan_python_launcher_in and the real install's ensure_managed_python take them from it, so a preview and an install made from one environment cannot disagree about the version or the policy. managed_python_version keeps its signature for the progress line in therock.rs and still reads the process environment. No behaviour change: the existing tests, which build an environment from the process one, pass unchanged. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 46 ++++++++++++++++++++++++++------- apps/rocm/src/therock/update.rs | 1 + 2 files changed, 38 insertions(+), 9 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index cb3f25c960..0edf378062 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -274,18 +274,22 @@ pub(super) const fn python_requirement(layout: SourceLayout) -> PythonRequiremen } } +fn managed_python_version_override() -> Option { + std::env::var("ROCM_CLI_MANAGED_PYTHON_VERSION").ok() +} + +/// The managed Python version a bootstrap prepares under the process +/// environment. A decision made from an injected [`PythonResolverEnv`] asks +/// [`PythonResolverEnv::managed_python_version`] instead. pub(super) fn managed_python_version(requirement: PythonRequirement) -> String { - std::env::var("ROCM_CLI_MANAGED_PYTHON_VERSION") - .ok() - .filter(|value| !value.trim().is_empty()) - .unwrap_or_else(|| requirement.version.to_owned()) + PythonResolverEnv::from_process_env().managed_python_version(requirement) } fn ensure_managed_python( paths: &AppPaths, requirement: PythonRequirement, + version: String, ) -> Result { - let version = managed_python_version(requirement); progress_line(format!("Preparing Python {version}...")); let uv = ensure_uv_binary(paths)?; @@ -402,17 +406,33 @@ pub(super) struct PythonResolverEnv { pub(super) python_override: Option, /// The directories to search for an interpreter, in `PATH` order. pub(super) search_dirs: Vec, + /// `ROCM_CLI_MANAGED_PYTHON_VERSION`: the version a managed bootstrap + /// prepares in place of the layout's own, when set and not blank. + pub(super) managed_python_version: Option, + /// `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP`: whether a host with no usable + /// interpreter is refused instead of bootstrapped. + pub(super) managed_bootstrap_disabled: bool, } impl PythonResolverEnv { - fn from_process_env() -> Self { + pub(super) fn from_process_env() -> Self { Self { python_override: std::env::var("ROCM_CLI_PYTHON").ok(), search_dirs: std::env::var_os("PATH") .map(|value| split_runtime_path(&value)) .unwrap_or_default(), + managed_python_version: managed_python_version_override(), + managed_bootstrap_disabled: managed_python_bootstrap_disabled(), } } + + /// The managed Python version a bootstrap under this environment prepares. + fn managed_python_version(&self, requirement: PythonRequirement) -> String { + self.managed_python_version + .clone() + .filter(|value| !value.trim().is_empty()) + .unwrap_or_else(|| requirement.version.to_owned()) + } } // Lets a test steer `resolve_python_launcher` at a fixed `PythonResolverEnv` @@ -532,7 +552,7 @@ fn plan_python_launcher_in( Ok(match lookup { PythonLookup::Found(launcher) => PlannedPython::Ready(launcher), PythonLookup::NeedsManagedBootstrap => { - let version = managed_python_version(requirement); + let version = env.managed_python_version(requirement); // `ROCM_CLI_MANAGED_PYTHON_VERSION` can name a version other than the // one the wheels need. A real install prepares it, finds it reports // the wrong tag and refuses (see `ensure_managed_python`), so the @@ -723,7 +743,9 @@ fn resolve_python_launcher_in( ) -> Result { match find_python_launcher_in(paths, env, requirement, LookupPurpose::Install)? { PythonLookup::Found(launcher) => Ok(launcher), - PythonLookup::NeedsManagedBootstrap => ensure_managed_python(paths, requirement), + PythonLookup::NeedsManagedBootstrap => { + ensure_managed_python(paths, requirement, env.managed_python_version(requirement)) + } } } @@ -797,7 +819,7 @@ fn find_python_launcher_in( }); } - if managed_python_bootstrap_disabled() { + if env.managed_bootstrap_disabled { bail!( "unable to locate Python, and managed Python bootstrap is disabled by ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP" ); @@ -1124,6 +1146,7 @@ exit 1 &PythonResolverEnv { python_override: None, search_dirs: vec![bin_dir], + ..PythonResolverEnv::from_process_env() }, python_requirement(SourceLayout::Canonical), )?; @@ -1226,6 +1249,7 @@ exit 1 &PythonResolverEnv { python_override: None, search_dirs: vec![bin_dir], + ..PythonResolverEnv::from_process_env() }, python_requirement(SourceLayout::Canonical), )?; @@ -1292,6 +1316,7 @@ exit 1 let _guard = OverridePythonResolverEnv::new(PythonResolverEnv { python_override: None, search_dirs: vec![bin_dir.clone()], + ..PythonResolverEnv::from_process_env() }); resolve_python_launcher(&paths, python_requirement(SourceLayout::Canonical))? }; @@ -1319,6 +1344,7 @@ exit 1 let _outer = OverridePythonResolverEnv::new(PythonResolverEnv { python_override: Some("outer".to_owned()), search_dirs: vec![], + ..PythonResolverEnv::from_process_env() }); assert_eq!( python_resolver_env_override() @@ -1331,6 +1357,7 @@ exit 1 let _inner = OverridePythonResolverEnv::new(PythonResolverEnv { python_override: Some("inner".to_owned()), search_dirs: vec![], + ..PythonResolverEnv::from_process_env() }); assert_eq!( python_resolver_env_override() @@ -1483,6 +1510,7 @@ exit 1 let _resolver = OverridePythonResolverEnv::new(PythonResolverEnv { python_override: None, search_dirs: vec![self.search_dir.clone()], + ..PythonResolverEnv::from_process_env() }); python_for_install( &self.paths, diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index 662b306b65..3b203c3e2d 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -775,6 +775,7 @@ mod tests { let resolver_env_guard = OverridePythonResolverEnv::new(PythonResolverEnv { python_override: None, search_dirs: vec![bin_dir], + ..PythonResolverEnv::from_process_env() }); PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().clear()); From 8f93821aecd6a2d81199b8fa8e421d56b5250505 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 11:49:15 +0000 Subject: [PATCH 12/25] test(install): run the preview's Python decision on every platform The tests of what a dry run decides about Python drive it with shell-script interpreters and are cfg(unix), and the scenarios that cover it are Linux-only, so the Windows CI job ran none of it although a fresh Windows install is one of the hosts the preview is for. The decision needs no interpreter: with nothing to find, python_for_install is a function of the resolver environment (now carrying the managed-Python policy) and the dry_run flag. The new test builds that environment directly and runs python_for_install through it, so it runs on the Windows job. It asserts, per row, the preview's complete progress output together with the state it leaves behind (no config, manifest, or folder created): the default, a patch release, a blank override and an unreadable spelling are announced (the last as unchecked); a version whose wheel tag is not the layout's is refused in every spelling that reads as one; a disabled bootstrap is refused with the install's own message. A control runs the real install on the same host and checks it reaches the managed uv, which is a file that cannot be launched, so nothing is downloaded or run and the preview's silence about uv is shown to mean something. The search order (python3 before python on Linux, python, python3, py with PATHEXT on Windows) and the interpreter probes are still covered by the Unix tests only. RestoredEnv and snapshot lose their cfg(unix) because the new test shares them. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 142 +++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 4 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 0edf378062..379d484438 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -1386,10 +1386,8 @@ exit 1 /// Process environment variables set for one test and restored on drop. /// Every caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds this. - #[cfg(unix)] struct RestoredEnv(Vec<(&'static str, Option)>); - #[cfg(unix)] impl RestoredEnv { #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 fn set(vars: &[(&'static str, Option<&Path>)]) -> Self { @@ -1409,7 +1407,6 @@ exit 1 } } - #[cfg(unix)] impl Drop for RestoredEnv { #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 fn drop(&mut self) { @@ -1441,7 +1438,6 @@ exit 1 /// Every path under the three folders a command may write to, sorted. Empty /// when none of them exists, so "nothing was created" and "something empty /// was created" are different answers. - #[cfg(unix)] fn snapshot(paths: &AppPaths) -> Vec { fn walk(dir: &Path, out: &mut Vec) { let Ok(entries) = fs::read_dir(dir) else { @@ -1611,6 +1607,144 @@ exit 1 Ok(()) } + /// The preview's decision, made from an injected environment, on every + /// platform. + /// + /// The tests around it drive the decision with shell-script interpreters and + /// run on Unix only. The decision itself (what a host with no usable Python + /// is told, which managed version is announced or refused, what the bootstrap + /// policy does) needs no interpreter: a [`PythonResolverEnv`] with nothing to + /// find and the policy written into it exercises `python_for_install` + /// end to end, so this one runs on the Windows CI job as well. The search + /// order and the interpreter probes stay Unix-only, as the PR text says. + /// + /// Each row asserts the whole progress output and the state left behind + /// together. The control at the end is the install on the same host: it + /// reaches the managed `uv` (a file that cannot be launched, so nothing is + /// downloaded or run), which shows the preview's silence about `uv` means it + /// stayed out of it, not that the stand-in was never wired up. + #[test] + fn a_dry_run_decides_from_an_injected_environment_on_every_platform() -> Result<()> { + use super::super::process::PROGRESS_LINE_SINK; + + let _lock = PROCESS_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = test_paths("python-dry-run-injected"); + let tools = root.join("tools"); + fs::create_dir_all(&tools)?; + // Present but not executable, on every platform: `ensure_uv_binary` + // returns it as the override, and launching it fails. + let uv = tools.join("uv"); + fs::write(&uv, "not an executable")?; + let _uv = RestoredEnv::set(&[("ROCM_CLI_UV_BINARY", Some(&uv))]); + assert!(snapshot(&paths).is_empty()); + + let requirement = python_requirement(SourceLayout::Canonical); + let run = |version: Option<&str>, disabled: bool, dry_run: bool| { + let _resolver = OverridePythonResolverEnv::new(PythonResolverEnv { + python_override: None, + search_dirs: Vec::new(), + managed_python_version: version.map(str::to_owned), + managed_bootstrap_disabled: disabled, + }); + PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().clear()); + let result = python_for_install(&paths, requirement, dry_run); + let lines = PROGRESS_LINE_SINK.with(|sink| sink.borrow().clone()); + (result, lines) + }; + let promise = |version: &str, caveat: &str| { + format!( + "No usable Python found; a real install would prepare Python {version}{caveat}. This preview does not." + ) + }; + + // Announced: the default, a patch release of the required minor, a + // blank override (read as unset) and a version whose tag cannot be read. + for (version, announced, checked) in [ + (None, "3.12", true), + (Some("3.12.4"), "3.12.4", true), + (Some("cpython@3.12"), "cpython@3.12", true), + (Some(" "), "3.12", true), + (Some("pypy@3.10"), "pypy@3.10", false), + ] { + let (result, lines) = run(version, false, true); + let planned = result.unwrap_or_else(|error| panic!("{version:?}: {error:#}")); + let PlannedPython::WouldPrepareManaged { + version: planned_version, + tag_checked, + .. + } = &planned + else { + panic!( + "{version:?}: a host with no Python must be planned as needing one, got {planned:?}" + ); + }; + assert_eq!(planned_version, announced, "{version:?}"); + assert_eq!(*tag_checked, checked, "{version:?}"); + let caveat = if checked { + "" + } else { + " (its wheel tag cannot be checked until it is installed; cp312 is required)" + }; + assert_eq!(lines, vec![promise(announced, caveat)], "{version:?}"); + assert!( + planned.note().is_some_and(|note| note.contains(&format!( + "install managed Python {announced}{caveat} and save" + ))), + "{version:?}: {planned:?}" + ); + } + + // Refused: a version whose wheel tag is not the layout's, in every + // spelling that reads as one, and a host where the bootstrap is + // disabled. Nothing is promised, so no line predicts the install. + for version in ["3.13", "3.13t", "cpython-3.13", "cpython@3.13"] { + let (result, lines) = run(Some(version), false, true); + let error = format!("{:#}", result.unwrap_err()); + assert!( + error.contains(&format!("would prepare managed Python {version}")) + && error.contains("Python wheel tag cp313 is not supported") + && error.contains("cp312 is required"), + "{version}: {error}" + ); + assert_eq!(lines, Vec::::new(), "{version}"); + } + let (preview, lines) = run(None, true, true); + let preview = preview.unwrap_err().to_string(); + let (install, _) = run(None, true, false); + assert!( + preview.contains("managed Python bootstrap is disabled"), + "{preview}" + ); + assert_eq!(preview, install.unwrap_err().to_string()); + assert_eq!(lines, Vec::::new()); + + // State: every preview above left the config, data and cache folders as + // they were, which for this host is absent. + assert!(!paths.config_path().exists()); + assert!(!managed_python_manifest_path(&paths).exists()); + assert_eq!(snapshot(&paths), Vec::::new()); + + // Control: the real install on the same host goes on to prepare Python, + // which reaches the managed `uv`. + let (install, lines) = run(None, false, false); + let error = format!("{:#}", install.unwrap_err()); + assert!( + error.contains("failed to launch uv python install"), + "the install did not reach uv, so the previews above prove nothing: {error}" + ); + assert_eq!( + lines, + vec![ + "Preparing Python 3.12...".to_owned(), + "Installing Python 3.12 via uv...".to_owned() + ] + ); + fs::remove_dir_all(&root).ok(); + Ok(()) + } + /// A Python on the search path is used by the preview exactly as by the /// install, and costs nothing: no `uv`, nothing written. #[cfg(unix)] From 869b8cbf8b2983d28a9541410a89bd3aceaaa9b0 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 11:55:11 +0000 Subject: [PATCH 13/25] refactor(install): name whether a preview could check a Python's wheel tag PlannedPython::WouldPrepareManaged carried a tag_checked bool next to the requirement it was checked against. The bool is one of two named cases, so it is now a TagCheck enum (Checked, Unchecked), and unchecked_tag_caveat matches on it. The preview's note and progress line are unchanged; the existing tests, updated to the enum, pass as before. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 80 ++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 30 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 379d484438..e88229356d 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -571,7 +571,11 @@ fn plan_python_launcher_in( PlannedPython::WouldPrepareManaged { version, requirement, - tag_checked: tag.is_some(), + tag_check: if tag.is_some() { + TagCheck::Checked + } else { + TagCheck::Unchecked + }, } } }) @@ -583,16 +587,28 @@ pub(super) enum PlannedPython { /// An interpreter that is usable as it stands. Ready(PythonLauncher), /// No interpreter is usable. A real install would prepare managed Python - /// `version`; this preview has not. `tag_checked` is whether the wheel tag + /// `version`; this preview has not. `tag_check` says whether the wheel tag /// `version` reports could be read off its name and matched against the /// requirement; when it could not, only installing it would say. WouldPrepareManaged { version: String, requirement: PythonRequirement, - tag_checked: bool, + tag_check: TagCheck, }, } +/// Whether a version a preview would prepare could be matched against the +/// wheel tag the layout requires before it is installed. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) enum TagCheck { + /// The tag was read off the version's name and matches the requirement. + Checked, + /// The tag cannot be read off the version's name (another implementation, a + /// range, a wildcard that leaves the minor open): only installing it would + /// tell. + Unchecked, +} + impl PlannedPython { /// The `python_launcher:` line's value: the interpreter's path, or, when /// none exists yet, a statement that none was prepared rather than a path @@ -631,10 +647,10 @@ impl PlannedPython { Self::WouldPrepareManaged { version, requirement, - tag_checked, + tag_check, } => Some(format!( "no usable Python was found; a real install would use uv to install managed Python {version}{} and save its path in the configuration, which this preview did not do", - unchecked_tag_caveat(*tag_checked, *requirement) + unchecked_tag_caveat(*tag_check, *requirement) )), } } @@ -667,10 +683,10 @@ impl PlannedPython { Self::WouldPrepareManaged { version, requirement, - tag_checked, + tag_check, } => format!( "No usable Python found; a real install would prepare Python {version}{}. This preview does not.", - unchecked_tag_caveat(*tag_checked, *requirement) + unchecked_tag_caveat(*tag_check, *requirement) ), } } @@ -706,14 +722,13 @@ impl PlannedPython { /// could. One function for [`PlannedPython::note`] and /// [`PlannedPython::progress_text`], so the two cannot word the same caveat /// differently. -fn unchecked_tag_caveat(tag_checked: bool, requirement: PythonRequirement) -> String { - if tag_checked { - String::new() - } else { - format!( +fn unchecked_tag_caveat(tag_check: TagCheck, requirement: PythonRequirement) -> String { + match tag_check { + TagCheck::Checked => String::new(), + TagCheck::Unchecked => format!( " (its wheel tag cannot be checked until it is installed; {} is required)", requirement.tag - ) + ), } } @@ -1566,14 +1581,18 @@ exit 1 let PlannedPython::WouldPrepareManaged { ref version, requirement, - tag_checked, + tag_check, } = planned else { panic!("a host with no Python must be planned as needing one, got {planned:?}"); }; assert_eq!(version, DEFAULT_MANAGED_PYTHON_VERSION); assert_eq!(requirement, python_requirement(SourceLayout::Canonical)); - assert!(tag_checked, "the default version's tag is readable"); + assert_eq!( + tag_check, + TagCheck::Checked, + "the default version's tag is readable" + ); let note = planned .note() .expect("a preview that skipped a step says so"); @@ -1661,18 +1680,18 @@ exit 1 // Announced: the default, a patch release of the required minor, a // blank override (read as unset) and a version whose tag cannot be read. - for (version, announced, checked) in [ - (None, "3.12", true), - (Some("3.12.4"), "3.12.4", true), - (Some("cpython@3.12"), "cpython@3.12", true), - (Some(" "), "3.12", true), - (Some("pypy@3.10"), "pypy@3.10", false), + for (version, announced, tag_check) in [ + (None, "3.12", TagCheck::Checked), + (Some("3.12.4"), "3.12.4", TagCheck::Checked), + (Some("cpython@3.12"), "cpython@3.12", TagCheck::Checked), + (Some(" "), "3.12", TagCheck::Checked), + (Some("pypy@3.10"), "pypy@3.10", TagCheck::Unchecked), ] { let (result, lines) = run(version, false, true); let planned = result.unwrap_or_else(|error| panic!("{version:?}: {error:#}")); let PlannedPython::WouldPrepareManaged { version: planned_version, - tag_checked, + tag_check: planned_check, .. } = &planned else { @@ -1681,11 +1700,12 @@ exit 1 ); }; assert_eq!(planned_version, announced, "{version:?}"); - assert_eq!(*tag_checked, checked, "{version:?}"); - let caveat = if checked { - "" - } else { - " (its wheel tag cannot be checked until it is installed; cp312 is required)" + assert_eq!(*planned_check, tag_check, "{version:?}"); + let caveat = match tag_check { + TagCheck::Checked => "", + TagCheck::Unchecked => { + " (its wheel tag cannot be checked until it is installed; cp312 is required)" + } }; assert_eq!(lines, vec![promise(announced, caveat)], "{version:?}"); assert!( @@ -2153,7 +2173,7 @@ exit 1 matches!( &planned, PlannedPython::WouldPrepareManaged { - tag_checked: true, + tag_check: TagCheck::Checked, .. } ), @@ -2170,7 +2190,7 @@ exit 1 matches!( &planned, PlannedPython::WouldPrepareManaged { - tag_checked: false, + tag_check: TagCheck::Unchecked, .. } ), @@ -2259,7 +2279,7 @@ exit 1 let planned = PlannedPython::WouldPrepareManaged { version: requirement.version.to_owned(), requirement, - tag_checked: true, + tag_check: TagCheck::Checked, }; let compatibility = planned.wheel_compatibility()?; From 93c69082cff552c5371048d5b676f203eb007a80 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 11:58:53 +0000 Subject: [PATCH 14/25] test(install): pin the wording of the unusable-Python findings for an install and a preview An install and a preview word the two findings about a PATH Python and a saved managed Python that cannot serve the install differently (the install says what it goes on to do, the preview states the finding only), but only the preview's wording was pinned, by the state matrix on Unix hosts. This pins both, on every platform, before the two parallel match blocks that print them are merged into one. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 78 ++++++++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index e88229356d..5c9661587e 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -736,7 +736,7 @@ fn unchecked_tag_caveat(tag_check: TagCheck, requirement: PythonRequirement) -> /// It changes only the wording of the two progress lines about a Python that /// turned out unusable: an install says what it goes on to do, a preview states /// the finding and leaves the prediction to the decision's own line. -#[derive(Clone, Copy)] +#[derive(Clone, Copy, Debug)] enum LookupPurpose { Install, Preview, @@ -1765,6 +1765,82 @@ exit 1 Ok(()) } + /// The two lines about a Python that exists but cannot serve the install are + /// worded for the purpose of the search: an install says what it goes on to + /// do, a preview states only the finding (what a real install would then do + /// is decided afterwards, and said by the decision's own line). Pinned here + /// as they are printed, so that the two wordings stay what they are as the + /// code that prints them changes; the decisions those lines sit in are + /// covered by `a_dry_runs_whole_python_output_follows_one_decision_in_every_state` + /// and `a_dry_run_decides_from_an_injected_environment_on_every_platform`. + /// + /// A text file stands for the unusable interpreters (neither the PATH one nor + /// the saved one can be launched), so this runs on every platform. Bootstrap is + /// disabled in the injected environment so both searches end in a refusal + /// before anything could be prepared. + #[test] + fn the_findings_about_an_unusable_python_are_worded_for_the_purpose_of_the_search() -> Result<()> + { + use super::super::process::PROGRESS_LINE_SINK; + + let (root, paths) = test_paths("python-unusable-findings"); + let search_dir = root.join("search"); + fs::create_dir_all(&search_dir)?; + fs::write(search_dir.join("python3"), "not an interpreter")?; + let saved_dir = paths.data_dir.join("tools").join("python"); + fs::create_dir_all(&saved_dir)?; + let saved = saved_dir.join("python"); + fs::write(&saved, "not an interpreter")?; + save_managed_python_manifest( + &paths, + &ManagedPythonManifest { + executable: saved, + version: DEFAULT_MANAGED_PYTHON_VERSION.to_owned(), + installed_at_unix_ms: 123, + }, + )?; + let env = PythonResolverEnv { + python_override: None, + search_dirs: vec![search_dir], + managed_python_version: None, + managed_bootstrap_disabled: true, + }; + let requirement = python_requirement(SourceLayout::Canonical); + + for (purpose, expected) in [ + ( + LookupPurpose::Install, + [ + "Python from PATH is not usable for this ROCm install (cp312 is required); using ROCm CLI's managed Python.", + "Saved managed Python is not usable for this ROCm install (cp312 is required); preparing Python again.", + ], + ), + ( + LookupPurpose::Preview, + [ + "Python from PATH is not usable for this ROCm install (cp312 is required).", + "Saved managed Python is not usable for this ROCm install (cp312 is required).", + ], + ), + ] { + PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().clear()); + let outcome = find_python_launcher_in(&paths, &env, requirement, purpose); + let lines = PROGRESS_LINE_SINK.with(|sink| sink.borrow().clone()); + assert_eq!(lines, expected, "{purpose:?}"); + let error = outcome + .err() + .expect("bootstrap is disabled, so the search refuses"); + assert!( + error + .to_string() + .contains("managed Python bootstrap is disabled"), + "{purpose:?}: {error:#}" + ); + } + fs::remove_dir_all(&root).ok(); + Ok(()) + } + /// A Python on the search path is used by the preview exactly as by the /// install, and costs nothing: no `uv`, nothing written. #[cfg(unix)] From 6176347b5cd8a80c037499ed1194982b61ea9a66 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 12:07:14 +0000 Subject: [PATCH 15/25] refactor(install): print the unusable-Python findings from one place find_python_launcher_in printed the finding about a PATH Python and the one about a saved managed Python from two parallel Install/Preview match blocks that differed only in a trailing clause. LookupPurpose::unusable_python_line now builds both lines: both purposes state the finding, an install adds what it goes on to do. The output is byte-identical, as the test added in the previous commit pins for both purposes. Signed-off-by: Jussi Elo --- apps/rocm/src/therock/python.rs | 51 ++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 5c9661587e..43b38f0261 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -742,6 +742,27 @@ enum LookupPurpose { Preview, } +impl LookupPurpose { + /// The progress line for an interpreter (`subject`) that exists but cannot + /// serve the install. Both purposes state the finding; an install then says + /// what it goes on to do (`install_next_step`) and a preview stops. + fn unusable_python_line( + self, + subject: &str, + requirement: PythonRequirement, + install_next_step: &str, + ) -> String { + let finding = format!( + "{subject} is not usable for this ROCm install ({} is required)", + requirement.tag + ); + match self { + Self::Install => format!("{finding}; {install_next_step}."), + Self::Preview => format!("{finding}."), + } + } +} + /// Where the search for an interpreter ended. enum PythonLookup { /// An interpreter that is usable as it stands. @@ -801,16 +822,11 @@ fn find_python_launcher_in( // `PlannedPython::progress_text`, after the decision. An install's wording is // unchanged. if skipped_path_python { - progress_line(match purpose { - LookupPurpose::Install => format!( - "Python from PATH is not usable for this ROCm install ({} is required); using ROCm CLI's managed Python.", - requirement.tag - ), - LookupPurpose::Preview => format!( - "Python from PATH is not usable for this ROCm install ({} is required).", - requirement.tag - ), - }); + progress_line(purpose.unusable_python_line( + "Python from PATH", + requirement, + "using ROCm CLI's managed Python", + )); } if let Some(manifest) = load_managed_python_manifest(paths)? @@ -822,16 +838,11 @@ fn find_python_launcher_in( source: PythonSource::Managed, })); } - progress_line(match purpose { - LookupPurpose::Install => format!( - "Saved managed Python is not usable for this ROCm install ({} is required); preparing Python again.", - requirement.tag - ), - LookupPurpose::Preview => format!( - "Saved managed Python is not usable for this ROCm install ({} is required).", - requirement.tag - ), - }); + progress_line(purpose.unusable_python_line( + "Saved managed Python", + requirement, + "preparing Python again", + )); } if env.managed_bootstrap_disabled { From afbb38cfb1b1ca7154fb0e85ba20506000ebcefc Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 12:08:18 +0000 Subject: [PATCH 16/25] docs: say which lane covers the Windows preview and that the previewed uv venv line is not verbatim docs/testing.md and the runtime-23 scenario comment now name the unit test that runs the preview's Python decision on every platform, the Windows CI job included, and say what stays uncovered (the Windows search order and any Windows run of the preview). docs/testing.md and docs/manual-testing.md also say that the plan's command line prints uv venv --python 3.12, a version rather than a path, so it is not copy-pasteable verbatim: uv resolves 3.12 itself and may choose a different Python 3.12 than the managed one a real install prepares. Signed-off-by: Jussi Elo --- docs/manual-testing.md | 7 +++++-- docs/testing.md | 18 +++++++++++++++--- .../features/runtime_setup.feature | 9 +++++---- 3 files changed, 25 insertions(+), 9 deletions(-) diff --git a/docs/manual-testing.md b/docs/manual-testing.md index e05e5bcb80..2848c5e39e 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -165,8 +165,11 @@ Expected result: and a `python_note:` line says a real install would use `uv` to install the managed Python. Afterwards the data folder has no `tools` folder and the config folder has no `config.json`: the preview downloaded no `uv` or Python - and saved no Python path. A real install on the same host does both. This - holds for the canonical layout. A preview pinned to ROCm 10 or newer + and saved no Python path. A real install on the same host does both. The + plan's `command:` line shows `uv venv --python 3.12 ...` (a version, as no + interpreter path exists yet), so it is not copy-pasteable verbatim: `uv` + resolves `3.12` itself and may pick a different Python 3.12 than the managed + one a real install prepares. This holds for the canonical layout. A preview pinned to ROCm 10 or newer (`--version 10.0.0 --family gfx1200`) still needs `uv` to resolve the package versions, so on a clean host it can download the managed `uv` and create the `tools` folder, although it prepares no Python and saves no Python path. diff --git a/docs/testing.md b/docs/testing.md index 86e1de5c06..8f1541e871 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -516,7 +516,11 @@ the note against the state it left: a recording `uv` standing in for the downloa was never run (that log is the evidence; no network is involved), and there is no managed-tools folder and no saved config. It also looks for a tool archive in its own cache folder, but only as a backstop: the stand-in `uv` is returned before a -download could start. That scenario is a canonical-layout preview. A preview of a +download could start. The printed `command:` line then shows `uv venv --python 3.12 ...` (a version, +because no interpreter path exists yet), so it is not copy-pasteable verbatim: +`uv` resolves `3.12` itself, and on a host with a different Python 3.12 it can +choose that one rather than the managed one a real install prepares. +That scenario is a canonical-layout preview. A preview of a ROCm 10 or newer wheel (a `--version` pin of 10 or later) does still need `uv`: it resolves the published package versions with `uv pip compile`, so on a clean host it can download the managed `uv` and create the data folder's `tools` @@ -536,8 +540,16 @@ Scenarios `runtime-24` (the `3.13` refusal) and `runtime-25` (policy refusal wit an unusable `PATH` Python) check this on the whole output. A version whose tag cannot be read off its name (`pypy@3.10`, a range) is announced as unchecked: the note and the progress line say its tag cannot be checked until it is installed. -The scenarios run on Linux; the decisions themselves are unit-tested on Unix -hosts (the Python stand-ins are shell scripts, as in the other resolver tests). +The scenarios run on Linux. The preview's decision (what a host with no usable +Python is told, which managed version is announced or refused, what the +bootstrap policy does) is unit-tested on every platform, including the Windows +CI job, by `a_dry_run_decides_from_an_injected_environment_on_every_platform`: +it hands `python_for_install` a resolver environment that carries the policy and +finds nothing, so it needs no interpreter. What stays Unix-only is the search +order and the interpreter probes, whose stand-ins are shell scripts as in the +other resolver tests, and no end-to-end run covers the Windows preview, so the +Windows search order (`python`, `python3`, `py` with `PATHEXT`) is not covered +by any test. `a_dry_runs_whole_python_output_follows_one_decision_in_every_state` in [python.rs](../apps/rocm/src/therock/python.rs) is the state matrix: every combination of `PATH` Python (usable, unusable, absent), saved Python (usable, diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 4c1f3085a7..d3b93cf112 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -497,10 +497,11 @@ Feature: Runtime configuration # prepares no Python; this scenario is not that case and does not claim it. # # Linux only: the empty-`PATH` host is built for the Linux search order. The - # decision itself is unit-tested on Unix hosts against an injected search path - # (`a_dry_run_with_no_usable_python_prepares_nothing` in - # `apps/rocm/src/therock/python.rs`); the Windows search order and a Windows - # run of this preview are not covered by a test. + # decision itself is unit-tested against an injected resolver environment on + # every platform, the Windows CI job included + # (`a_dry_run_decides_from_an_injected_environment_on_every_platform` in + # `apps/rocm/src/therock/python.rs`, which needs no interpreter); the Windows + # search order and a Windows run of this preview are not covered by a test. # # Technical details: the fixture serves one canonical release index, `PATH` is a # single empty folder, `ROCM_CLI_UV_BINARY` names a stand-in that appends its From fc2fa6ef2fda522f943fd71e55873d2bdc88c493 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 13:09:12 +0000 Subject: [PATCH 17/25] docs: wrap two over-long lines in the install sdk dry-run notes Re-wrap the manual-testing bullet and the testing.md paragraph on the dry-run Python preview to the surrounding 80-column style. No words change. Signed-off-by: Jussi Elo --- docs/manual-testing.md | 9 +++++---- docs/testing.md | 20 ++++++++++---------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 2848c5e39e..5941e47310 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -169,10 +169,11 @@ Expected result: plan's `command:` line shows `uv venv --python 3.12 ...` (a version, as no interpreter path exists yet), so it is not copy-pasteable verbatim: `uv` resolves `3.12` itself and may pick a different Python 3.12 than the managed - one a real install prepares. This holds for the canonical layout. A preview pinned to ROCm 10 or newer - (`--version 10.0.0 --family gfx1200`) still needs `uv` to resolve the package - versions, so on a clean host it can download the managed `uv` and create the - `tools` folder, although it prepares no Python and saves no Python path. + one a real install prepares. This holds for the canonical layout. A preview + pinned to ROCm 10 or newer (`--version 10.0.0 --family gfx1200`) still needs + `uv` to resolve the package versions, so on a clean host it can download the + managed `uv` and create the `tools` folder, although it prepares no Python and + saves no Python path. - With `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP=1`, or a `ROCM_CLI_MANAGED_PYTHON_VERSION` whose Python the layout does not accept (such as `3.13` for the canonical layout), on the same host the preview fails diff --git a/docs/testing.md b/docs/testing.md index 8f1541e871..01b6a93fd4 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -516,16 +516,16 @@ the note against the state it left: a recording `uv` standing in for the downloa was never run (that log is the evidence; no network is involved), and there is no managed-tools folder and no saved config. It also looks for a tool archive in its own cache folder, but only as a backstop: the stand-in `uv` is returned before a -download could start. The printed `command:` line then shows `uv venv --python 3.12 ...` (a version, -because no interpreter path exists yet), so it is not copy-pasteable verbatim: -`uv` resolves `3.12` itself, and on a host with a different Python 3.12 it can -choose that one rather than the managed one a real install prepares. -That scenario is a canonical-layout preview. A preview of a -ROCm 10 or newer wheel (a `--version` pin of 10 or later) does still need `uv`: -it resolves the published package versions with `uv pip compile`, so on a clean -host it can download the managed `uv` and create the data folder's `tools` -folder, although it still prepares no Python. The "no `uv`, no `tools` folder" -guarantee is therefore the canonical layout's only. +download could start. The printed `command:` line then shows +`uv venv --python 3.12 ...` (a version, because no interpreter path exists yet), +so it is not copy-pasteable verbatim: `uv` resolves `3.12` itself, and on a host +with a different Python 3.12 it can choose that one rather than the managed one +a real install prepares. That scenario is a canonical-layout preview. A preview +of a ROCm 10 or newer wheel (a `--version` pin of 10 or later) does still +need `uv`: it resolves the published package versions with `uv pip compile`, so +on a clean host it can download the managed `uv` and create the data folder's +`tools` folder, although it still prepares no Python. The "no `uv`, no `tools` +folder" guarantee is therefore the canonical layout's only. The preview does not announce a Python the install would refuse either, and it prints nothing that predicts what a real install would do on a path that ends in From 99b7ed5835fb42baec33fc7912831c1571007b75 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 09:42:59 +0000 Subject: [PATCH 18/25] ROCMAI-872: keep the update check from preparing a managed Python Reading the index for a wheel runtime needs the interpreter's wheel tag, and a runtime that records no usable Python made the check go and get one: on a host with none it downloaded a managed uv, had uv install Python and saved that Python's path in the configuration. That ran for `rocm update`, for `rocm update --json` (the dashboard's check), for the check the CLI runs ahead of other commands, and for the plan behind `rocm update --apply --dry-run`, so a read-only look at the runtimes changed the host. These callers now go through `runtime_update_check`, which finds an interpreter with the search-only entry point the install preview already uses and, when there is none, takes the wheel tag from the interpreter the layout requires. The text report adds a `python_note:` line saying an update would use uv to install the managed Python, which the check did not do; the JSON keeps its shape. `runtime_update_plan`, which `rocm update --apply` works from, still prepares the Python, since the install that follows needs it. A unit test drives the report, the JSON, the startup check and the check plan on a host with no Python and a recording uv, with the apply plan as the control that shows the stand-in is reachable. Scenarios update-09 and update-10 drive the report and the dry-run preview through the built binary and check the note against the state it left. Signed-off-by: Jussi Elo --- apps/rocm/src/therock.rs | 2 +- apps/rocm/src/therock/python.rs | 155 ++++++++---- apps/rocm/src/therock/test_support.rs | 40 ++- apps/rocm/src/therock/update.rs | 231 +++++++++++++++++- apps/rocm/src/update_cmd.rs | 46 +++- docs/architecture.md | 2 +- docs/manual-testing.md | 7 + docs/testing.md | 34 +++ tests/e2e-cucumber/features/update.feature | 46 ++++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 94 +++++++ 10 files changed, 601 insertions(+), 56 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index e31b255aac..959a71cdb1 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -56,7 +56,7 @@ use self::source::{ }; pub(crate) use self::update::{ maybe_refresh_startup_update_check, render_update_json, render_update_report, - runtime_update_plan, + runtime_update_check, runtime_update_plan, }; pub(crate) use self::version::runtime_version_display; use self::version::{ diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 43b38f0261..3ca1ff1a55 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -525,8 +525,8 @@ pub(super) fn python_for_install( Ok(python) } -/// The interpreter a *preview* of the install reports, found without preparing -/// one. +/// The interpreter a *preview* of the install, or an update check, reports, +/// found without preparing one. /// /// [`resolve_python_launcher`] ends by downloading a managed `uv`, having it /// install Python, and saving that Python's path in the configuration when no @@ -538,7 +538,10 @@ pub(super) fn python_for_install( /// resolution raises before that step (an unusable `ROCM_CLI_PYTHON`, a /// disabled managed bootstrap) is raised here too, so a preview never succeeds /// on a host where the install would refuse. -fn plan_python_launcher(paths: &AppPaths, requirement: PythonRequirement) -> Result { +pub(super) fn plan_python_launcher( + paths: &AppPaths, + requirement: PythonRequirement, +) -> Result { let env = python_resolver_env_override().unwrap_or_else(PythonResolverEnv::from_process_env); plan_python_launcher_in(paths, &env, requirement) } @@ -655,6 +658,28 @@ impl PlannedPython { } } + /// The `python_note:` line of an update check, in the same terms as + /// [`Self::note`] but for the step an update would take. An update check + /// needs the interpreter's wheel tag to read the index, and a host with no + /// interpreter gets it from the one the layout requires, so this line is how + /// the check says it did not go and prepare one. Built from the decision, as + /// the preview's is. + pub(super) fn update_note(&self) -> Option { + match self { + Self::Ready(_) => None, + Self::WouldPrepareManaged { + version, + requirement, + tag_check, + } => { + let unchecked = unchecked_tag_caveat(*tag_check, *requirement); + Some(format!( + "no usable Python was found; updating would use uv to install managed Python {version}{unchecked} and save its path in the configuration, which this check did not do" + )) + } + } + } + /// The progress line that names the chosen interpreter: the one an install /// goes on with, or, for a preview on a host with no usable Python, what a /// real install would prepare. It is the only line that predicts the @@ -988,7 +1013,7 @@ fn python_venv_probe_temp_root() -> Result { mod tests { use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; - use crate::therock::test_support::test_paths; + use crate::therock::test_support::{RestoredEnv, test_paths}; #[cfg(unix)] fn write_fake_python_with_venv(dir: &Path, name: &str) -> Result { @@ -1410,43 +1435,6 @@ exit 1 // ---- a dry run prepares no Python ---------------------------------------- - /// Process environment variables set for one test and restored on drop. - /// Every caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds this. - struct RestoredEnv(Vec<(&'static str, Option)>); - - impl RestoredEnv { - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 - fn set(vars: &[(&'static str, Option<&Path>)]) -> Self { - let saved = vars - .iter() - .map(|(key, _)| (*key, std::env::var_os(key))) - .collect(); - for (key, value) in vars { - unsafe { - match value { - Some(value) => std::env::set_var(key, value), - None => std::env::remove_var(key), - } - } - } - Self(saved) - } - } - - impl Drop for RestoredEnv { - #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 - fn drop(&mut self) { - for (key, value) in self.0.drain(..) { - unsafe { - match value { - Some(value) => std::env::set_var(key, value), - None => std::env::remove_var(key), - } - } - } - } - } - /// A `uv` that records its arguments in `marker` and then fails. A host that /// reaches it has gone on to prepare a managed Python; failing keeps a test /// that does reach it from going on to the network. @@ -1541,6 +1529,16 @@ exit 1 ) } + /// What an update check goes on with, searching only this host's folder. + fn plan_for_update_check(&self) -> Result { + let _resolver = OverridePythonResolverEnv::new(PythonResolverEnv { + python_override: None, + search_dirs: vec![self.search_dir.clone()], + ..PythonResolverEnv::from_process_env() + }); + plan_python_launcher(&self.paths, python_requirement(SourceLayout::Canonical)) + } + fn uv_was_run(&self) -> bool { self.uv_marker.exists() } @@ -2300,6 +2298,81 @@ exit 1 Ok(()) } + /// An update check reads the index by the interpreter's wheel tag. On a host + /// with no interpreter that tag is the one the layout requires, which a real + /// update would prepare an interpreter to match, so the check needs nothing + /// prepared. The note it prints says so, and the folders agree; the same host + /// DOES reach `uv` for the install, so an unrun stand-in means the check + /// stayed out of it. The Gherkin scenario `update-09` drives the same case + /// through the built binary. + #[cfg(unix)] + #[test] + fn an_update_check_with_no_usable_python_reads_the_required_tag_and_prepares_nothing() + -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-update-check-none")?; + let requirement = python_requirement(SourceLayout::Canonical); + + let planned = host.plan_for_update_check()?; + + let compatibility = planned.wheel_compatibility()?; + assert_eq!(compatibility.python_tag, requirement.tag); + assert!(!compatibility.platform_tags.is_empty()); + assert_eq!( + planned.update_note().as_deref(), + Some( + "no usable Python was found; updating would use uv to install managed Python 3.12 and save its path in the configuration, which this check did not do" + ) + ); + assert!(!host.uv_was_run(), "the update check ran uv"); + assert_eq!( + snapshot(&host.paths), + Vec::::new(), + "the update check created files or folders under the config, data or cache folder" + ); + + // Control: the install on the same host does reach `uv`. + assert!(host.python_for_install(false).is_err()); + assert!( + host.uv_was_run(), + "the stand-in uv is not reachable, so the checks above prove nothing" + ); + Ok(()) + } + + /// A usable interpreter needs no note, and a managed Python whose tag cannot + /// be read off its version says so in the update note as in the preview's. + #[cfg(unix)] + #[test] + fn an_update_note_is_absent_for_a_usable_python_and_flags_an_unreadable_tag() -> Result<()> { + if current_platform_wheel_tags().is_err() { + return Ok(()); + } + let host = PythonHost::new("python-update-note")?; + { + let _unreadable = RestoredEnv::set(&[( + "ROCM_CLI_MANAGED_PYTHON_VERSION", + Some(Path::new("pypy@3.10")), + )]); + let planned = host.plan_for_update_check()?; + let note = planned.update_note().expect("nothing was prepared"); + assert!( + note.contains("managed Python pypy@3.10 (its wheel tag cannot be checked until it is installed; cp312 is required)") + && note.ends_with("which this check did not do"), + "{note}" + ); + } + + write_fake_python_with_venv(&host.search_dir, "python3")?; + let planned = host.plan_for_update_check()?; + assert!(matches!(planned, PlannedPython::Ready(_)), "{planned:?}"); + assert_eq!(planned.update_note(), None); + assert!(!host.uv_was_run()); + Ok(()) + } + /// The version-to-tag reading the preview's refusal rests on, and that it is /// the same rule `python_launcher_install_ready` applies (same message). #[test] diff --git a/apps/rocm/src/therock/test_support.rs b/apps/rocm/src/therock/test_support.rs index e0b41a46d0..f27c50dd8e 100644 --- a/apps/rocm/src/therock/test_support.rs +++ b/apps/rocm/src/therock/test_support.rs @@ -11,7 +11,45 @@ use crate::runtime_registry::{InstalledRuntimeManifest, runtime_manifest_path}; use anyhow::Result; use rocm_core::AppPaths; use std::fs; -use std::path::PathBuf; +use std::path::{Path, PathBuf}; + +/// Process environment variables set for one test and restored on drop. Every +/// caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds this. +pub(super) struct RestoredEnv(Vec<(&'static str, Option)>); + +impl RestoredEnv { + /// Sets (`Some`) or removes (`None`) each variable, remembering what it was. + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + pub(super) fn set(vars: &[(&'static str, Option<&Path>)]) -> Self { + let saved = vars + .iter() + .map(|(key, _)| (*key, std::env::var_os(key))) + .collect(); + for (key, value) in vars { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + Self(saved) + } +} + +impl Drop for RestoredEnv { + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + fn drop(&mut self) { + for (key, value) in self.0.drain(..) { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + } +} pub(super) fn family_for_test(family: &str, raw_arch: Option<&str>) -> FamilyResolution { FamilyResolution { diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index 3b203c3e2d..3a700d8134 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -25,8 +25,8 @@ use super::family::family_override_or_recovered_arch; use super::io::write_file_atomically; use super::process::SuppressProgressOutput; use super::python::{ - PythonLauncher, PythonSource, python_launcher_install_ready, python_requirement, - resolve_python_launcher, wheel_compatibility_for_python, + PythonLauncher, PythonSource, plan_python_launcher, python_launcher_install_ready, + python_requirement, resolve_python_launcher, wheel_compatibility_for_python, }; use super::resolve::{ AggregateDeviceTarget, resolve_pip_runtime_with_timeout, resolve_tarball_artifact_with_timeout, @@ -83,6 +83,22 @@ pub(crate) struct RuntimeUpdatePlan { pub source_layout_generation: Option, pub repair_required: bool, pub update_available: bool, + /// Set when the runtime records no usable Python and the check left one + /// unprepared: what an update would do about it. + pub python_note: Option, +} + +/// Whether resolving a wheel runtime's latest version may prepare a Python. +/// +/// Reading the index needs the interpreter's wheel tag. A runtime that records +/// a usable Python supplies it. For one that does not, an apply goes on to +/// prepare a managed Python (it needs one for the install that follows), but a +/// check changes nothing, so it works the tag out from the interpreter the +/// layout requires and says it left the preparation undone. +#[derive(Debug, Clone, Copy, Eq, PartialEq)] +enum PythonAccess { + MayPrepare, + SearchOnly, } #[derive(Debug, Clone, Copy, Eq, PartialEq)] @@ -116,6 +132,7 @@ struct ResolvedRuntimeUpdate { format: String, source_layout_generation: String, wheel_composition: Option, + python_note: Option, } pub(crate) fn render_update_report(paths: &AppPaths) -> Result { @@ -144,7 +161,7 @@ pub(crate) fn render_update_report(paths: &AppPaths) -> Result { } for manifest in &manifests { - let plan = match runtime_update_plan(paths, manifest, &manifests, None) { + let plan = match runtime_update_check(paths, manifest, &manifests, None) { Ok(plan) => Some(plan), Err(error) => { let _ = writeln!( @@ -181,6 +198,9 @@ pub(crate) fn render_update_report(paths: &AppPaths) -> Result { manifest.install_root.display() ); let _ = writeln!(output, " source: {}", plan.latest_source); + if let Some(note) = &plan.python_note { + let _ = writeln!(output, " python_note: {note}"); + } if plan.update_available { let next_step = if plan.repair_required { format!( @@ -247,7 +267,7 @@ pub(crate) fn render_update_json( let manifests = load_runtime_manifests(paths)?; let mut runtimes = Vec::with_capacity(manifests.len()); for manifest in &manifests { - match runtime_update_plan(paths, manifest, &manifests, download_timeout_secs) { + match runtime_update_check(paths, manifest, &manifests, download_timeout_secs) { Ok(plan) => runtimes.push(UpdateJsonRuntime { runtime_key: manifest.runtime_key.clone(), channel: manifest.channel.clone(), @@ -356,13 +376,49 @@ fn runtime_freshness_with_manifests( } } +/// The plan an apply works from. A wheel runtime that records no usable Python +/// has one prepared here, since the install that follows needs it. pub(crate) fn runtime_update_plan( paths: &AppPaths, manifest: &InstalledRuntimeManifest, manifests: &[InstalledRuntimeManifest], download_timeout_secs: Option, ) -> Result { - let latest = resolve_latest_for_manifest(paths, manifest, download_timeout_secs)?; + plan_runtime_update( + paths, + manifest, + manifests, + download_timeout_secs, + PythonAccess::MayPrepare, + ) +} + +/// The same plan for a caller that changes nothing: the update report, the JSON +/// the dashboard reads, and the preview of an apply. It never prepares a Python. +pub(crate) fn runtime_update_check( + paths: &AppPaths, + manifest: &InstalledRuntimeManifest, + manifests: &[InstalledRuntimeManifest], + download_timeout_secs: Option, +) -> Result { + plan_runtime_update( + paths, + manifest, + manifests, + download_timeout_secs, + PythonAccess::SearchOnly, + ) +} + +fn plan_runtime_update( + paths: &AppPaths, + manifest: &InstalledRuntimeManifest, + manifests: &[InstalledRuntimeManifest], + download_timeout_secs: Option, + python_access: PythonAccess, +) -> Result { + let latest = + resolve_latest_for_manifest(paths, manifest, download_timeout_secs, python_access)?; let freshness = runtime_freshness_with_manifests( manifests, manifest, @@ -385,6 +441,7 @@ pub(crate) fn runtime_update_plan( source_layout_generation: Some(latest.source_layout_generation), repair_required: freshness == RuntimeFreshness::RepairAvailable, update_available: freshness.update_available(), + python_note: latest.python_note, }) } @@ -416,6 +473,7 @@ fn resolve_latest_for_manifest( paths: &AppPaths, manifest: &InstalledRuntimeManifest, download_timeout_secs: Option, + python_access: PythonAccess, ) -> Result { let channel = TheRockChannel::parse(&manifest.channel)?; let layout = manifest_source_layout(manifest)?; @@ -436,12 +494,17 @@ fn resolve_latest_for_manifest( executable, source: PythonSource::Manifest, }); - let python_executable = match manifest_python { - Some(python) => python, - None => resolve_python_launcher(paths, requirement)?, + let (wheel_compatibility, python_note) = match (manifest_python, python_access) { + (Some(python), _) => (wheel_compatibility_for_python(&python.executable)?, None), + (None, PythonAccess::MayPrepare) => { + let python = resolve_python_launcher(paths, requirement)?; + (wheel_compatibility_for_python(&python.executable)?, None) + } + (None, PythonAccess::SearchOnly) => { + let planned = plan_python_launcher(paths, requirement)?; + (planned.wheel_compatibility()?, planned.update_note()) + } }; - let wheel_compatibility = - wheel_compatibility_for_python(&python_executable.executable)?; let family_override = manifest_wheel_family_override(manifest); let resolution = resolve_pip_runtime_with_timeout( paths, @@ -492,6 +555,7 @@ fn resolve_latest_for_manifest( format: "wheel".to_owned(), source_layout_generation: resolution.layout.generation().to_owned(), wheel_composition, + python_note, }) } "tarball" => { @@ -516,6 +580,7 @@ fn resolve_latest_for_manifest( format: "tarball".to_owned(), source_layout_generation: artifact.layout.generation().to_owned(), wheel_composition: None, + python_note: None, }) } other => bail!("unknown manifest format `{other}`"), @@ -589,7 +654,12 @@ fn build_startup_update_check_record( now_unix_ms: u128, download_timeout_secs: Option, ) -> StartupUpdateCheckRecord { - match resolve_latest_for_manifest(paths, manifest, download_timeout_secs) { + match resolve_latest_for_manifest( + paths, + manifest, + download_timeout_secs, + PythonAccess::SearchOnly, + ) { Ok(latest) => { let freshness = runtime_freshness_with_manifests( manifests, @@ -658,11 +728,15 @@ mod tests { use super::super::process::{PROGRESS_LINE_SINK, progress_output_suppressed}; use super::super::python::{OverridePythonResolverEnv, PythonResolverEnv}; use super::super::source::THEROCK_SOURCE_LAYOUT_GENERATION; + #[cfg(unix)] + use super::super::test_support::RestoredEnv; use super::super::test_support::{ test_paths, test_runtime_manifest, write_test_runtime_manifest, }; use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; + #[cfg(unix)] + use std::path::Path; /// Updating a next-layout manifest whose family is a group label (as /// `gfx125X-dcgpu` always is) must recover the exact arch this runtime was @@ -1197,4 +1271,139 @@ mod tests { let _ = fs::remove_dir_all(root); Ok(()) } + + /// The bug: a read-only look at a wheel runtime that records no usable Python, + /// on a host with none, went on to prepare one (download a managed `uv`, have + /// it install Python, save the path in the configuration). Driven here, each + /// against the same host: the update report, the JSON the dashboard reads, + /// the startup check, `runtime_update_check` itself, and + /// `apply_runtime_update` with `dry_run` (the preview of an apply, which takes + /// the check). Each must leave `uv` unrun and the configuration and managed + /// tools absent, and each must still reach the index (the connection to the + /// unreachable index is what each error names), so the absences are not a + /// check that stopped early. `runtime_update_plan` and a real + /// `apply_runtime_update` do prepare one on the same host, which is also what + /// shows the stand-in `uv` is reachable. The choice between the two is pinned + /// on every platform by `a_dry_run_takes_the_check_and_an_apply_takes_the_plan` + /// in `update_cmd.rs`; the Gherkin scenarios `update-09` and `update-10` drive + /// the report and the preview through the built binary. + #[cfg(unix)] + #[test] + fn the_update_checks_prepare_no_python_and_the_apply_plan_does() -> Result<()> { + use rocm_core::fake_executable::write_fake_executable; + + let _env_lock = PROCESS_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = test_paths("update-checks-prepare-no-python"); + + let marker = root.join("uv-was-run"); + let tools = root.join("tools"); + fs::create_dir_all(&tools)?; + let uv = tools.join("uv"); + write_fake_executable( + &uv, + format!("#!/bin/sh\necho \"$@\" >> '{}'\nexit 1\n", marker.display()), + )?; + let search = root.join("search"); + fs::create_dir_all(&search)?; + // Port 9 refuses the connection at once, so a check that gets past + // Python fails at the index without touching the network. + let unreachable_index = "http://127.0.0.1:9/"; + let _env = RestoredEnv::set(&[ + ("ROCM_CLI_UV_BINARY", Some(uv.as_path())), + ("ROCM_CLI_PYTHON", None), + ("ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP", None), + ("ROCM_CLI_MANAGED_PYTHON_VERSION", None), + ("ROCM_CLI_DISABLE_STARTUP_UPDATE_CHECK", None), + ("ROCM_CLI_THEROCK_ALLOW_BASE_OVERRIDE", Some(Path::new("1"))), + ( + "ROCM_CLI_THEROCK_RELEASE_PIP_BASE", + Some(Path::new(unreachable_index)), + ), + ]); + let _resolver = OverridePythonResolverEnv::new(PythonResolverEnv { + python_override: None, + search_dirs: vec![search], + ..PythonResolverEnv::from_process_env() + }); + + // The fixture's recorded interpreter does not exist, so the runtime + // records no usable Python. + let manifest = test_runtime_manifest("wheel-no-python", "therock-release:gfx120X-all", 1); + write_test_runtime_manifest(&paths, &manifest)?; + let manifests = load_runtime_manifests(&paths)?; + + let prepared_nothing = |what: &str| { + assert!(!marker.exists(), "{what} ran uv"); + assert!( + !paths.config_path().exists(), + "{what} saved a Python path in the configuration" + ); + assert!( + !rocm_core::managed_tools_dir(&paths.data_dir).exists(), + "{what} created the managed tools folder" + ); + }; + + let report = render_update_report(&paths)?; + assert!(report.contains("127.0.0.1:9"), "{report}"); + prepared_nothing("the update report"); + + let document = render_update_json(&paths, Some(1))?; + assert_eq!(document.runtimes[0].status, "error"); + assert!( + document.runtimes[0] + .message + .as_deref() + .is_some_and(|message| message.contains("127.0.0.1:9")), + "{document:?}" + ); + prepared_nothing("the update JSON"); + + let record = maybe_refresh_startup_update_check_at(&paths, None, 0)? + .expect("a registered runtime is checked at startup"); + assert!( + record + .message + .as_deref() + .is_some_and(|message| message.contains("127.0.0.1:9")), + "{record:?}" + ); + prepared_nothing("the startup check"); + + let error = runtime_update_check(&paths, &manifest, &manifests, Some(1)) + .expect_err("the index is unreachable") + .to_string(); + assert!(error.contains("127.0.0.1:9"), "{error}"); + prepared_nothing("the update check"); + + let mut config = rocm_core::RocmCliConfig::default(); + let preview = + crate::update_cmd::apply_runtime_update(&paths, &mut config, None, false, true) + .expect_err("the index is unreachable") + .to_string(); + assert!(preview.contains("127.0.0.1:9"), "{preview}"); + prepared_nothing("the --dry-run preview"); + + // Control: the plan an apply works from does reach `uv` on this host, and + // so does a real apply, which takes that plan. + assert!(runtime_update_plan(&paths, &manifest, &manifests, Some(1)).is_err()); + assert!( + marker.exists(), + "the stand-in uv is not reachable, so the checks above prove nothing" + ); + fs::remove_file(&marker)?; + assert!( + crate::update_cmd::apply_runtime_update(&paths, &mut config, None, false, false) + .is_err() + ); + assert!( + marker.exists(), + "a real apply did not take the plan that prepares a Python" + ); + + fs::remove_dir_all(&root).ok(); + Ok(()) + } } diff --git a/apps/rocm/src/update_cmd.rs b/apps/rocm/src/update_cmd.rs index 49cf65942c..e6a7c751de 100644 --- a/apps/rocm/src/update_cmd.rs +++ b/apps/rocm/src/update_cmd.rs @@ -254,6 +254,18 @@ pub(crate) const fn update_should_preview_or_apply(apply: bool, dry_run: bool) - apply || dry_run } +/// The plan an update works from. A `--dry-run` only previews, so it takes the +/// check, which prepares nothing; a real apply takes the plan, which prepares the +/// Python the install that follows needs. A function of the two so a test runs it +/// on every platform without a host that has no Python. +fn plan_for_update( + dry_run: bool, + check: impl FnOnce() -> T, + apply_plan: impl FnOnce() -> T, +) -> T { + if dry_run { check() } else { apply_plan() } +} + pub(crate) fn apply_runtime_update( paths: &AppPaths, config: &mut RocmCliConfig, @@ -263,7 +275,11 @@ pub(crate) fn apply_runtime_update( ) -> Result { let manifests = therock::load_runtime_manifests(paths)?; let source = select_runtime_update_source(&manifests, config, runtime_selector)?; - let plan = therock::runtime_update_plan(paths, source, &manifests, None)?; + let plan = plan_for_update( + dry_run, + || therock::runtime_update_check(paths, source, &manifests, None), + || therock::runtime_update_plan(paths, source, &manifests, None), + )?; let mut output = String::new(); let _ = writeln!(output, "runtime update"); let _ = writeln!(output, " source_runtime_key: {}", source.runtime_key); @@ -440,6 +456,34 @@ mod tests { use crate::test_support::write_test_pip_runtime; use crate::tests::{test_paths, test_runtime_manifest_for_update}; + /// A `--dry-run` takes its plan from the check and an apply from the plan, + /// and calls only that one: the check must never be the one that prepares a + /// Python, and an apply must still get the plan that does. This pins the + /// choice on every platform; `the_update_checks_prepare_no_python_and_the_apply_plan_does` + /// in `therock/update.rs` drives the real `apply_runtime_update` on a host + /// with no Python, and scenario `update-10` drives the built binary. + #[test] + fn a_dry_run_takes_the_check_and_an_apply_takes_the_plan() { + let calls = std::cell::RefCell::new(Vec::new()); + let take = |dry_run: bool| { + calls.borrow_mut().clear(); + let taken = plan_for_update( + dry_run, + || { + calls.borrow_mut().push("check"); + "check" + }, + || { + calls.borrow_mut().push("plan"); + "plan" + }, + ); + (taken, calls.borrow().clone()) + }; + assert_eq!(take(true), ("check", vec!["check"])); + assert_eq!(take(false), ("plan", vec!["plan"])); + } + #[test] fn render_update_text_reports_all_update_surfaces() -> Result<()> { let (root, paths) = test_paths("update-surfaces"); diff --git a/docs/architecture.md b/docs/architecture.md index 3a00d4d0c3..0a575f67a1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -97,7 +97,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. - [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`); `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, and `TorchaudioPin` with its `describe`, so they can use what `resolve_pip_runtime` returns without naming the types; the rest is private. - [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private. -- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/io.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents`, which name and inspect the install a plan targets, stay in `therock.rs`. `render_update_report`, `render_update_json`, `runtime_update_plan` and `maybe_refresh_startup_update_check` are `pub(crate)` and re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. +- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/io.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key`, `wheel_runtime_key` and `has_nontrivial_directory_contents`, which name and inspect the install a plan targets, stay in `therock.rs`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. - [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK`. - [`uninstall.rs`](../apps/rocm/src/uninstall.rs) — mechanical relocation, owns types: `uninstall()`, plus the installer `PATH` undo and running-executable deletion. The shared plan type and its file-removal helpers live in [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) below instead, because [`storage.rs`](../apps/rocm/src/storage.rs) reuses them too. The two modules depend on each other: `uninstall_plan.rs` reads this module's `pub(crate)` `PathEdit`, `PATH_EDIT_RECORD`, `plan_path_edits`, `plan_is_empty`, `removal_count` and `render_extra_plan`. - [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) — mechanical relocation, shares crate-visible types (Phase 6f, ROCMAI-212): the uninstall-plan types (`UninstallOptions`, `UninstallPlan`, `UninstallPlanEntry`), building the plan (`build_uninstall_plan`, `plan_installed_binaries`, and the installed-binary/shared-cache discovery helpers behind them), rendering it (`render_uninstall_dry_run`, `render_uninstall_plan`), the `[y/N]` confirmation prompt (`confirm_uninstall`), and the filesystem removal primitive both [`uninstall.rs`](../apps/rocm/src/uninstall.rs) and [`storage.rs`](../apps/rocm/src/storage.rs) call to carry a plan out (`remove_path`, and the entry-resolution helpers behind it). Kept separate from `uninstall.rs` rather than folded into it, since `uninstall.rs`'s own doc comment and name both describe `uninstall()`'s exclusive logic (the installer `PATH` undo and running-executable deletion), while this module's plan/render/removal helpers are shared with `storage.rs`. `main.rs` (`UninstallOptions`), `uninstall.rs`, `storage.rs`, `runtimes_cmd.rs`, `chat.rs`, and [`deletion_properties.rs`](../apps/rocm/src/deletion_properties.rs) (Unix-only property tests) each import the subset of these `pub(crate)` types and helpers they need; see this module's own doc comment for which symbol each one uses. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 5941e47310..6d058397bf 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -174,6 +174,13 @@ Expected result: `uv` to resolve the package versions, so on a clean host it can download the managed `uv` and create the `tools` folder, although it prepares no Python and saves no Python path. +- On the same host, with a wheel runtime registered whose manifest records no + usable Python, `rocm update` (also `--json`, `--dry-run`, and the check the + CLI runs at startup) still reports. The text report gives the runtime's + verdict and a `python_note:` line saying an update would use `uv` to install + the managed Python, which the check did not do. Afterwards the data folder has + no `tools` folder and the config folder has no `config.json`. `rocm update + --apply` on the same host does prepare the Python, since the install needs it. - With `ROCM_CLI_DISABLE_MANAGED_PYTHON_BOOTSTRAP=1`, or a `ROCM_CLI_MANAGED_PYTHON_VERSION` whose Python the layout does not accept (such as `3.13` for the canonical layout), on the same host the preview fails diff --git a/docs/testing.md b/docs/testing.md index 01b6a93fd4..c5abfcd702 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1858,6 +1858,33 @@ cargo test -p rocm --bin rocm render_update_text_reports_all_update_surfaces surfaces honestly. `rocm update --apply` remains runtime-only until production metadata feeds exist for the other surfaces. +A check changes nothing, and that includes Python. Reading the index for a wheel +runtime needs the interpreter's wheel tag. A runtime that records a usable Python +supplies it. For one that does not, on a host with no usable Python, the check +used to download a managed `uv`, have it install Python and save that Python's +path in the config, only to ask it for the tag. The text report, `--json`, the +startup check that runs ahead of other commands, and the plan behind +`rocm update --apply --dry-run` now take the tag from the interpreter the layout +requires instead and prepare nothing; the text report adds a `python_note:` line +saying an update would use `uv` to install the managed Python, which the check did +not do. `--json` carries no such line, since its shape is the dashboard's +contract. `rocm update --apply` still prepares the Python, because the install +that follows needs it. Scenarios `update-09` (the report) and `update-10` +(`--dry-run`) check the note against the state it left, as `runtime-23` does for +the install preview: the recording `uv` was never run, and there is no +managed-tools folder and no saved config. They run on Linux; the entry points the +scenarios do not drive are covered by +`the_update_checks_prepare_no_python_and_the_apply_plan_does` in +[update.rs](../apps/rocm/src/therock/update.rs), which drives the report, the +JSON, the startup check, the check plan and `apply_runtime_update` with +`--dry-run`, with the plan an apply works from, and a real apply, as the controls +that show the stand-in `uv` is reachable. Which of the two plans a `--dry-run` and +an apply take is also pinned on every platform, Windows included, by +`a_dry_run_takes_the_check_and_an_apply_takes_the_plan` in +[update_cmd.rs](../apps/rocm/src/update_cmd.rs). As for the install preview, resolving a +ROCm 10 or newer runtime uses `uv pip compile` and can fetch the managed `uv`, +though never a Python. + Runtime version-ordering tests: ```bash @@ -1865,6 +1892,13 @@ cargo test -p rocm --bin rocm version_proptests cargo xtask e2e -- -n 'update-0[78]' ``` +Update checks that must not prepare Python: + +```bash +cargo test -p rocm --bin rocm the_update_checks_prepare_no_python +cargo xtask e2e -- -n 'update-(09|10)' +``` + Where `rocm install sdk` and `rocm update` compare runtime versions, they 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 diff --git a/tests/e2e-cucumber/features/update.feature b/tests/e2e-cucumber/features/update.feature index 21ad0c1a35..078a27cfa2 100644 --- a/tests/e2e-cucumber/features/update.feature +++ b/tests/e2e-cucumber/features/update.feature @@ -92,3 +92,49 @@ Feature: Update report When the user checks for updates against that catalog Then the report calls the runtime the catalog spells differently up to date And the report offers no update for the four-component runtime that is ahead of the catalog + + # `rocm update` is a check: it reads the installed runtimes and the index and + # changes nothing. To tell which wheels fit a wheel runtime it needs the + # interpreter's tag, and on a host with no usable Python it used to go and get + # one: it downloaded a managed `uv`, had `uv` install Python and saved that + # Python's path in the configuration, all before printing the report. The same + # resolution runs for `rocm update --json` (the dashboard's check) and for the + # startup check that runs ahead of other commands, so a read-only look at the + # runtimes could prepare a Python. Now the check works the tag out from the + # interpreter the install would prepare, says it would prepare one, and + # prepares nothing. + # + # The report's note says the check prepared nothing, so the Then checks that + # note and the state together, as runtime-23 does for the install preview: the + # recording `uv` is reached only by going on to prepare a Python, so its log not + # existing means no preparation was attempted, and the managed tools folder and + # the configuration must be absent too. The first Then shows the check still got + # as far as a verdict, so the absences are not just a command that stopped + # early. `--json` and the startup check are pinned by the unit tests in + # `apps/rocm/src/therock/update.rs`. + # + # Linux only, for the same empty-`PATH` host as runtime-23. The canonical + # release index is served from a loopback fixture, so no network is needed. + @id:update-check-prepares-no-python @requires-os:linux + Scenario: update-09 - Checking for updates on a host with no usable Python prepares no Python + Given a canonical release pip index fixture + And a host with no usable Python and a recording uv + And a registered wheel runtime older than the index with no recorded Python + When the user checks for updates against the pip index + Then the report offers the newer runtime and says it would prepare a managed Python + And the update check prepared no Python, as it says + + # The sibling for `--dry-run`, which promises to show what `--apply` would do + # and change nothing. Its plan step resolved the same way and prepared the + # Python before the preview was printed; the apply itself still prepares what it + # needs, which the unit tests keep apart from the check. + # + # Linux only, for the same empty-`PATH` host as update-09. + @id:update-dry-run-prepares-no-python @requires-os:linux + Scenario: update-10 - Previewing an update on a host with no usable Python prepares no Python + Given a canonical release pip index fixture + And a host with no usable Python and a recording uv + And a registered wheel runtime older than the index with no recorded Python + When the user previews applying the update to that wheel runtime + Then the preview says a real install would prepare a managed Python + And the preview prepared no Python, as it says diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index d07a243d34..0f7e681df8 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -478,6 +478,100 @@ async fn registered_next_wheel_runtime_with_grouped_family(world: &mut E2eWorld) .expect("failed to write runtime manifest"); } +/// Registry key for the planted canonical wheel runtime below. +const OLDER_WHEEL_RUNTIME_KEY: &str = "release-wheel-gfx1200-7-9-0"; + +/// Plants a canonical-layout wheel runtime older than the release index the +/// fixture serves, whose manifest records no Python (a runtime registered before +/// the field was written, or whose recorded interpreter is gone). The update +/// check then has to find an interpreter for itself, which on the host the +/// recording-uv Given builds means preparing one. No `source_layout_generation` +/// is recorded, so the manifest reads as the canonical stream, as an old one does. +#[given("a registered wheel runtime older than the index with no recorded Python")] +async fn registered_older_wheel_runtime_without_python(world: &mut E2eWorld) { + let install_root = root(world).join("runtime-older-wheel"); + std::fs::create_dir_all(&install_root).expect("failed to create install root"); + let registry = root(world).join("data").join("runtimes").join("registry"); + std::fs::create_dir_all(®istry).expect("failed to create registry dir"); + let manifest = serde_json::to_string_pretty(&serde_json::json!({ + "runtime_key": OLDER_WHEEL_RUNTIME_KEY, + "runtime_id": format!("therock-release:{RAW_ARCH}"), + "channel": "release", + "format": "wheel", + "family": RAW_ARCH, + "family_source": "manual", + "version": "7.9.0", + "install_root": install_root, + "selected_artifact_url": "https://example.invalid/rocm", + "read_only": false, + "installed_at_unix_ms": 1_700_000_000_000u64, + })) + .expect("failed to serialize runtime manifest"); + std::fs::write( + registry.join(format!("{OLDER_WHEEL_RUNTIME_KEY}.json")), + manifest, + ) + .expect("failed to write runtime manifest"); +} + +#[when("the user checks for updates against the pip index")] +async fn check_updates_against_pip_index(world: &mut E2eWorld) { + preview_ok(world, &["update"]); +} + +#[when("the user previews applying the update to that wheel runtime")] +async fn preview_apply_update_to_older_wheel_runtime(world: &mut E2eWorld) { + preview_ok( + world, + &[ + "update", + "--apply", + "--dry-run", + "--runtime", + OLDER_WHEEL_RUNTIME_KEY, + ], + ); +} + +/// The report reached a verdict (the runtime is behind the index) and says what +/// the update would do about Python, without a path that would be a guess. +#[then("the report offers the newer runtime and says it would prepare a managed Python")] +async fn report_offers_update_and_names_the_python_it_would_prepare(world: &mut E2eWorld) { + assert_contains( + world, + &format!("runtime {OLDER_WHEEL_RUNTIME_KEY} format=wheel"), + "the runtime line", + ); + assert_contains(world, "status=update_available", "the runtime's verdict"); + assert_contains( + world, + &format!("latest={CURRENT_ROCM_VERSION}"), + "the version the index publishes", + ); + assert_contains( + world, + &format!( + "python_note: no usable Python was found; updating would use uv to install managed \ + Python {CANONICAL_MANAGED_PYTHON}" + ), + "the note about the Python an update would prepare", + ); +} + +/// The check says it prepared no Python, and the state it left agrees. Claim and +/// filesystem are checked together: the note alone would pass with the bug +/// present, and so would empty folders alone if the check had stopped before it +/// got to Python. +#[then("the update check prepared no Python, as it says")] +async fn update_check_prepared_no_python(world: &mut E2eWorld) { + assert_contains( + world, + "which this check did not do", + "the note about what the check skipped", + ); + assert_no_python_prepared(world); +} + /// Makes the planted ROCm 10 runtime the active default, so a real install /// without consent reaches the non-interactive refusal: past every point where /// the plan is chosen and announced, but before `uv`, any download or any From 96f121add999200c21a7b19626cd119867943c74 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Fri, 6 Nov 2026 15:53:20 +0000 Subject: [PATCH 19/25] ROCMAI-872: state what the update and SDK preview tools do and do not prepare The side-effects note on the read-only ROCm tools still said that `update_check` can download a managed `uv` and Python and record that Python in the saved config, which is the behaviour the update check no longer has: it runs `rocm update`, which now only reports the Python a real update would prepare, in a `python_note:` line of its text report. The note now says that neither `update_check` nor `install_sdk_dry_run` prepares a Python or saves a Python path, that only a real apply or install does, and keeps the caveat that a ROCm 10 or newer check or preview can still fetch the managed `uv`. No other file repeated the old claim. Signed-off-by: Jussi Elo --- crates/rocm-dash-tui/src/agent/tools.rs | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/crates/rocm-dash-tui/src/agent/tools.rs b/crates/rocm-dash-tui/src/agent/tools.rs index 28495952a7..01255543a1 100644 --- a/crates/rocm-dash-tui/src/agent/tools.rs +++ b/crates/rocm-dash-tui/src/agent/tools.rs @@ -208,12 +208,13 @@ pub const TELEMETRY_TOOL_NAMES: [&str; 4] = [ // stop has finished). `doctor`/`examine` can re-register the configured setup // runtime in the runtime registry when its entry is missing. `update_check` and // `install_sdk_dry_run` cache package-index metadata under the cache folder. -// `update_check` can also, on a host with no usable Python on PATH, download a -// managed `uv` and Python into the data folder and record that Python in the -// saved config; `install_sdk_dry_run` prepares no Python and saves no Python -// path: on such a host it reports the Python a real install would prepare. (A -// ROCm 10 preview still resolves package versions with `uv` and can fetch the -// managed `uv` into the data folder.) The boundary type +// Neither prepares a Python or saves a Python path: on a host with no usable +// Python on PATH they report the Python a real update or install would prepare +// (`update_check` runs `rocm update`, whose text report then carries a +// `python_note:` line saying so), and only a real apply or install, which these +// tools never run, prepares it. (A ROCm 10 or newer check or preview still +// resolves package versions with `uv` and can fetch the managed `uv` into the +// data folder, though never a Python.) The boundary type // (`SharedRocmToolExecutor`) is plain data — importing it does NOT pull // `rocm-core` into this crate; the `agent` module stays the sole `rig` namer. // --------------------------------------------------------------------------- From b5c49b2fdd8357648ddf69445ea6859b6e14611e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 9 Nov 2026 10:31:04 +0000 Subject: [PATCH 20/25] ROCMAI-872: pin on every platform that a --dry-run takes the check and an apply the plan apply_runtime_update chose between the two planners through a pass-through helper whose unit test proved only the `if`, so the dry_run argument at the call site was caught only by a test that runs on Unix and by update-10 on Linux. The flow now takes the two planners as arguments (apply_runtime_update_with), and the unit test drives it with planners that report nothing newer, so it needs no host without a Python and runs on Windows too: a --dry-run must call only the check and an apply only the plan. Which therock function is the check stays pinned only on Unix and by update-10, and the comments now say so. Signed-off-by: Jussi Elo --- apps/rocm/src/therock.rs | 4 +- apps/rocm/src/therock/update.rs | 10 ++- apps/rocm/src/update_cmd.rs | 136 ++++++++++++++++++++++++-------- docs/architecture.md | 4 +- 4 files changed, 112 insertions(+), 42 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 99512e72d6..7aab3d89b6 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -55,8 +55,8 @@ use self::source::{ requested_source_layout, select_source_layout, }; pub(crate) use self::update::{ - maybe_refresh_startup_update_check, render_update_json, render_update_report, - runtime_update_check, runtime_update_plan, + RuntimeUpdatePlan, maybe_refresh_startup_update_check, render_update_json, + render_update_report, runtime_update_check, runtime_update_plan, }; pub(crate) use self::version::runtime_version_display; use self::version::{ diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index 4f32db0a0a..835526b21d 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -1333,10 +1333,12 @@ mod tests { /// unreachable index is what each error names), so the absences are not a /// check that stopped early. `runtime_update_plan` and a real /// `apply_runtime_update` do prepare one on the same host, which is also what - /// shows the stand-in `uv` is reachable. The choice between the two is pinned - /// on every platform by `a_dry_run_takes_the_check_and_an_apply_takes_the_plan` - /// in `update_cmd.rs`; the Gherkin scenarios `update-09` and `update-10` drive - /// the report and the preview through the built binary. + /// shows the stand-in `uv` is reachable. That a `--dry-run` takes the check and + /// an apply the plan is pinned on every platform by + /// `a_dry_run_takes_the_check_and_an_apply_takes_the_plan` in `update_cmd.rs`; + /// which function is the check is pinned only here and by scenario `update-10` + /// on Linux, and no test on Windows pins it. The Gherkin scenarios `update-09` + /// and `update-10` drive the report and the preview through the built binary. #[cfg(unix)] #[test] fn the_update_checks_prepare_no_python_and_the_apply_plan_does() -> Result<()> { diff --git a/apps/rocm/src/update_cmd.rs b/apps/rocm/src/update_cmd.rs index 4960703d38..eb45fb75b9 100644 --- a/apps/rocm/src/update_cmd.rs +++ b/apps/rocm/src/update_cmd.rs @@ -254,32 +254,61 @@ pub(crate) const fn update_should_preview_or_apply(apply: bool, dry_run: bool) - apply || dry_run } -/// The plan an update works from. A `--dry-run` only previews, so it takes the -/// check, which prepares nothing; a real apply takes the plan, which prepares the -/// Python the install that follows needs. A function of the two so a test runs it -/// on every platform without a host that has no Python. -fn plan_for_update( +/// Which planner each path takes is pinned in two places. The `--dry-run` choice, +/// the check and not the plan, is pinned on every platform by +/// `a_dry_run_takes_the_check_and_an_apply_takes_the_plan` below, which runs +/// `apply_runtime_update_with`. That `runtime_update_check` is the check and +/// `runtime_update_plan` the plan, which the two arguments below cannot tell +/// apart by type, is pinned only on Unix: by +/// `the_update_checks_prepare_no_python_and_the_apply_plan_does` in +/// `therock/update.rs` and by scenario `update-10` on Linux. No test on Windows +/// pins that pairing. +pub(crate) fn apply_runtime_update( + paths: &AppPaths, + config: &mut RocmCliConfig, + runtime_selector: Option<&str>, + activate: bool, dry_run: bool, - check: impl FnOnce() -> T, - apply_plan: impl FnOnce() -> T, -) -> T { - if dry_run { check() } else { apply_plan() } +) -> Result { + apply_runtime_update_with( + paths, + config, + runtime_selector, + activate, + dry_run, + |source, manifests| therock::runtime_update_check(paths, source, manifests, None), + |source, manifests| therock::runtime_update_plan(paths, source, manifests, None), + ) } -pub(crate) fn apply_runtime_update( +/// The update flow with its two planners passed in. A `--dry-run` only previews, +/// so it takes `check`, which prepares nothing; a real apply takes `apply_plan`, +/// which prepares the Python the install that follows needs. Taking them as +/// arguments lets a test run the choice on every platform without a host that +/// has no Python. +fn apply_runtime_update_with( paths: &AppPaths, config: &mut RocmCliConfig, runtime_selector: Option<&str>, activate: bool, dry_run: bool, + check: impl FnOnce( + &therock::InstalledRuntimeManifest, + &[therock::InstalledRuntimeManifest], + ) -> Result, + apply_plan: impl FnOnce( + &therock::InstalledRuntimeManifest, + &[therock::InstalledRuntimeManifest], + ) -> Result, ) -> Result { let manifests = therock::load_runtime_manifests(paths)?; let source = select_runtime_update_source(&manifests, config, runtime_selector)?; - let plan = plan_for_update( - dry_run, - || therock::runtime_update_check(paths, source, &manifests, None), - || therock::runtime_update_plan(paths, source, &manifests, None), - )?; + let planned = if dry_run { + check(source, &manifests) + } else { + apply_plan(source, &manifests) + }; + let plan = planned?; let mut output = String::new(); let _ = writeln!(output, "runtime update"); let _ = writeln!(output, " source_runtime_key: {}", source.runtime_key); @@ -458,30 +487,69 @@ mod tests { /// A `--dry-run` takes its plan from the check and an apply from the plan, /// and calls only that one: the check must never be the one that prepares a - /// Python, and an apply must still get the plan that does. This pins the - /// choice on every platform; `the_update_checks_prepare_no_python_and_the_apply_plan_does` - /// in `therock/update.rs` drives the real `apply_runtime_update` on a host - /// with no Python, and scenario `update-10` drives the built binary. + /// Python, and an apply must still get the plan that does. Both planners + /// report nothing newer, so the flow returns before it installs or previews + /// anything and the test needs no host without a Python, which runs it on + /// every platform. Which `therock` function is the check is pinned only on + /// Unix, by `the_update_checks_prepare_no_python_and_the_apply_plan_does` in + /// `therock/update.rs`, and by scenario `update-10`. #[test] - fn a_dry_run_takes_the_check_and_an_apply_takes_the_plan() { + fn a_dry_run_takes_the_check_and_an_apply_takes_the_plan() -> Result<()> { + let (root, paths) = test_paths("update-takes-check-or-plan"); + write_test_pip_runtime( + &paths, + "release-pip-gfx120x-all", + "therock-release:gfx120X-all", + "7.13.0a20260416", + 1, + )?; let calls = std::cell::RefCell::new(Vec::new()); - let take = |dry_run: bool| { + let planner = |name: &'static str| { + let calls = &calls; + move |source: &therock::InstalledRuntimeManifest, + _: &[therock::InstalledRuntimeManifest]| { + calls.borrow_mut().push(name); + Ok(therock::RuntimeUpdatePlan { + latest_version: source.version.clone(), + latest_source: String::new(), + format: source.format.clone(), + status: "up_to_date".to_owned(), + target_runtime_key: source.runtime_key.clone(), + device_target: None, + source_layout_generation: None, + repair_required: false, + update_available: false, + python_note: None, + }) + } + }; + let take = |dry_run: bool| -> Result<(String, Vec<&'static str>)> { calls.borrow_mut().clear(); - let taken = plan_for_update( + let output = apply_runtime_update_with( + &paths, + &mut RocmCliConfig::default(), + None, + false, dry_run, - || { - calls.borrow_mut().push("check"); - "check" - }, - || { - calls.borrow_mut().push("plan"); - "plan" - }, - ); - (taken, calls.borrow().clone()) + planner("check"), + planner("plan"), + )?; + Ok((output, calls.borrow().clone())) }; - assert_eq!(take(true), ("check", vec!["check"])); - assert_eq!(take(false), ("plan", vec!["plan"])); + let (output, taken) = take(true)?; + assert_eq!(taken, ["check"], "a --dry-run took the plan: {output}"); + assert!( + output.contains("result: no newer runtime found"), + "{output}" + ); + let (output, taken) = take(false)?; + assert_eq!(taken, ["plan"], "an apply took the check: {output}"); + assert!( + output.contains("result: no newer runtime found"), + "{output}" + ); + fs::remove_dir_all(root).ok(); + Ok(()) } #[test] diff --git a/docs/architecture.md b/docs/architecture.md index 615515aaf2..533392b45a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -111,12 +111,12 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. - [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`); `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, and `TorchaudioPin` with its `describe`, so they can use what `resolve_pip_runtime` returns without naming the types; the rest is private. - [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private. -- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/io.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. +- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/io.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and, with `RuntimeUpdatePlan`, which [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) reads its verdict from, re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. - [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`. - [`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 immediately and which need the user's approval first. It owns `ChatRocmCommandAction` (read-only, or approval with the titles the approval prompt shows) and `ChatToolApprovalRequest`, the validators (`validate_chat_tool_call`, the `validate_chat_*_tool_call` family, `validate_required_chat_string`, `validate_optional_chat_integer`, `reject_control_characters_in_tool_arguments` (which refuses a model-supplied tool name or argument carrying a terminal control character, for every tool except `rocm_command`, whose argv `normalized_chat_rocm_command_args` screens entry by entry), `validate_serve_command_safety`, the four rules a model-proposed `serve` must satisfy (no public bind, no CPU device, a loopback host, `--managed` without `--foreground`), and `validate_chat_rocm_command_safety`, which applies them to a `serve` argv and also refuses a system install folder (`chat_install_prefix_is_system`)), the classifiers (`chat_rocm_command_action`, `chat_rocm_command_action_from_args`, `chat_install_driver_action`, `canonicalize_chat_rocm_command`, `normalized_chat_rocm_command_args`, `chat_tool_call_is_read_only`), `chat_tool_approval_request`, and the readers that turn a tool call into its argv and one-line command (`rocm_chat_tool_requested_args`, `rocm_chat_tool_requested_command`, with `push_optional_json_cli_arg` and `json_string`). It moved verbatim from `chat.rs` with the tests that exercise only these items. It depends on [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs), `providers::ChatToolCall`, `service_launch::is_loopback_host`, `services_text::validate_service_id`, `shell_quote::has_terminal_control_character`, `therock::RuntimeVersionSelector` and `driver_install::host_install_driver_only_reports`, none of which imports `chat`, so `freeform_planner.rs` calls `validate_serve_command_safety` and `validate_chat_rocm_command_safety` here instead of through `chat`, and keeps no copy of the serve rules. `chat.rs`'s child modules call into it and `chat.rs` re-exports `validate_chat_tool_call`, `chat_tool_call_is_read_only` and `chat_tool_approval_request` (read by `dash_seam.rs`), and `ChatRocmCommandAction`, `chat_install_driver_action`, `chat_rocm_command_action_from_args` and `rocm_chat_tool_requested_args`, which only other modules' tests read as `crate::chat::` (`driver_plan.rs`, `system_packages.rs`). - [`uninstall.rs`](../apps/rocm/src/uninstall.rs) — mechanical relocation, owns types: `uninstall()`, plus the installer `PATH` undo and running-executable deletion. The shared plan type and its file-removal helpers live in [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) below instead, because [`storage.rs`](../apps/rocm/src/storage.rs) reuses them too. The two modules depend on each other: `uninstall_plan.rs` reads this module's `pub(crate)` `PathEdit`, `PATH_EDIT_RECORD`, `plan_path_edits`, `plan_is_empty`, `removal_count` and `render_extra_plan`. - [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) — mechanical relocation, shares crate-visible types (Phase 6f, ROCMAI-212): the uninstall-plan types (`UninstallOptions`, `UninstallPlan`, `UninstallPlanEntry`), building the plan (`build_uninstall_plan`, `plan_installed_binaries`, and the installed-binary/shared-cache discovery helpers behind them), rendering it (`render_uninstall_dry_run`, `render_uninstall_plan`), the `[y/N]` confirmation prompt (`confirm_uninstall`), and the filesystem removal primitive both [`uninstall.rs`](../apps/rocm/src/uninstall.rs) and [`storage.rs`](../apps/rocm/src/storage.rs) call to carry a plan out (`remove_path`, and the entry-resolution helpers behind it). Kept separate from `uninstall.rs` rather than folded into it, since `uninstall.rs`'s own doc comment and name both describe `uninstall()`'s exclusive logic (the installer `PATH` undo and running-executable deletion), while this module's plan/render/removal helpers are shared with `storage.rs`. `main.rs` (`UninstallOptions`), `uninstall.rs`, `storage.rs`, `runtimes_cmd.rs`, `chat/mcp_bridge.rs`, and [`deletion_properties.rs`](../apps/rocm/src/deletion_properties.rs) (Unix-only property tests) each import the subset of these `pub(crate)` types and helpers they need; see this module's own doc comment for which symbol each one uses. -- [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types (Phase 6f, ROCMAI-210): `rocm update`'s command handler (`update()`, the body of the `update` arm of `dispatch()`) and its rendering/activation logic — the read-only status report (`render_update_text`, `append_update_surfaces`), the predicate deciding whether `update` should route into the mutating path instead of that report (`update_should_preview_or_apply`), applying a runtime update (`apply_runtime_update`, `append_update_activate_summary`), and the update-source/installed-runtime pickers behind it (`select_runtime_update_source`, `select_installed_update_runtime`). `const ROLLBACK_RECOVERY_HINT` stays in `main.rs` as a shared crate-root constant, because callers outside this module also use it ([`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s `RuntimesCommand::Activate` handler and [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)'s `render_sdk_install_success`); this module reaches it via its `use crate::{...};` import, the same way `gpu_policy.rs`'s `device_policy_name` stays in `main.rs`. `update()` is `pub(crate)` and called from [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` through a re-import (`use crate::update_cmd::update;`), and calls `update_should_preview_or_apply`, `apply_runtime_update` and `render_update_text` itself; `render_update_text` is also `pub(crate)` and read from [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) (the read-only `rocm update` handling), while `apply_runtime_update` and `update_should_preview_or_apply` keep the `pub(crate)` they had when `dispatch()` called them directly, though only `update()` calls them now; `select_runtime_update_source` is also `pub(crate)`, read from [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs)'s property tests via `crate::update_cmd::select_runtime_update_source`. `append_update_surfaces`, `append_update_activate_summary`, and `select_installed_update_runtime` have no callers outside this module and stay private. The cluster's regression tests live in `update_cmd.rs`'s own `mod tests`, reaching shared fixtures (`test_paths`, `test_runtime_manifest_for_update`, `write_test_pip_runtime`) through `crate::tests::`/`crate::test_support::` the same way other mechanically relocated modules do. +- [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) — mechanical relocation, dispatch-adjacent, no owned types (Phase 6f, ROCMAI-210): `rocm update`'s command handler (`update()`, the body of the `update` arm of `dispatch()`) and its rendering/activation logic — the read-only status report (`render_update_text`, `append_update_surfaces`), the predicate deciding whether `update` should route into the mutating path instead of that report (`update_should_preview_or_apply`), applying a runtime update (`apply_runtime_update`, a thin wrapper that hands `apply_runtime_update_with` the check and the plan from `therock/update.rs`, so a unit test can run the choice between them on any platform; `append_update_activate_summary`), and the update-source/installed-runtime pickers behind it (`select_runtime_update_source`, `select_installed_update_runtime`). `const ROLLBACK_RECOVERY_HINT` stays in `main.rs` as a shared crate-root constant, because callers outside this module also use it ([`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs)'s `RuntimesCommand::Activate` handler and [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)'s `render_sdk_install_success`); this module reaches it via its `use crate::{...};` import, the same way `gpu_policy.rs`'s `device_policy_name` stays in `main.rs`. `update()` is `pub(crate)` and called from [`main.rs`](../apps/rocm/src/main.rs)'s `dispatch()` through a re-import (`use crate::update_cmd::update;`), and calls `update_should_preview_or_apply`, `apply_runtime_update` and `render_update_text` itself; `render_update_text` is also `pub(crate)` and read from [`chat/mcp_bridge.rs`](../apps/rocm/src/chat/mcp_bridge.rs) (the read-only `rocm update` handling), while `apply_runtime_update` and `update_should_preview_or_apply` keep the `pub(crate)` they had when `dispatch()` called them directly, though only `update()` calls them now; `select_runtime_update_source` is also `pub(crate)`, read from [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs)'s property tests via `crate::update_cmd::select_runtime_update_source`. `append_update_surfaces`, `append_update_activate_summary`, and `select_installed_update_runtime` have no callers outside this module and stay private. The cluster's regression tests live in `update_cmd.rs`'s own `mod tests`, reaching shared fixtures (`test_paths`, `test_runtime_manifest_for_update`, `write_test_pip_runtime`) through `crate::tests::`/`crate::test_support::` the same way other mechanically relocated modules do. Further `apps/rocm` modules, not part of the `main.rs` split: From 9000afacb11484e9413f3ed37a507f095014ee30 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 9 Nov 2026 10:32:34 +0000 Subject: [PATCH 21/25] ROCMAI-872: say why a --apply --dry-run does not print the plan's python_note The plan an apply --dry-run works from carries a python_note, and apply_runtime_update never printed it. The preview that follows prints its own python_note from the decision a real install takes, which scenario update-10 asserts, so printing the plan's as well would say the same thing twice. A comment now records that, and that a dry run which finds nothing newer returns before the preview and prints neither note. Signed-off-by: Jussi Elo --- apps/rocm/src/update_cmd.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/apps/rocm/src/update_cmd.rs b/apps/rocm/src/update_cmd.rs index eb45fb75b9..c329c90d9f 100644 --- a/apps/rocm/src/update_cmd.rs +++ b/apps/rocm/src/update_cmd.rs @@ -334,6 +334,11 @@ fn apply_runtime_update_with( return Ok(output); } + // The plan's `python_note` is not printed here: the preview below prints its + // own `python_note:` from the decision a real install takes (scenario + // `update-10` asserts it), so a second line would say the same thing twice. + // A dry run that finds nothing newer returned above and prints neither; the + // plain `rocm update` report is where the check's note shows. if dry_run { let _ = writeln!(output, " mode: dry-run"); let install_plan = therock::install_sdk_for_update( From 121657398bbfd1e01cc365161a446a49a0445d1e Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 9 Nov 2026 10:36:15 +0000 Subject: [PATCH 22/25] ROCMAI-872: describe plan_python_launcher and the update note in the python.rs entry The architecture entry for therock/python.rs named neither the planned-Python lookup that previews and update checks use nor the python_note lines it writes, and did not list what therock/update.rs reads from it. It now says what plan_python_launcher, python_for_install and PlannedPython are and which items are pub(super) for the update module. Signed-off-by: Jussi Elo --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 533392b45a..83892f54ae 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -105,7 +105,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) — full domain extraction, a child of `therock.rs` that depends on `therock/io.rs` for atomic writes and on `slugify` in the parent for cache file names (split out of `therock.rs`): HTTP fetching for installs. `download_text_cached` is the metadata GET with its on-disk etag cache (`CachedHttp*`) and detached-signature verification (`MetadataSignaturePolicy`, `PINNED_METADATA_PUBLIC_KEY_PEM`, the unset trust root that `cargo xtask verify-pinned-keys` checks against the canonical published key, so its path is pinned in `xtask`); `download_file` is the streaming artifact download; `head_content_length` and `preflight_tarball_space` size the download and check free space first; `http_get` is the shared request. `truthy_env` is `pub(crate)` and re-exported by `therock.rs` for [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs); `download_text_cached`, `download_file`, `preflight_tarball_space` and the `CachedHttpText` struct (with its `text` field) that `download_text_cached` returns are `pub(super)` for the install and resolution code that stays in `therock.rs`; everything else is private. - [`therock/source.rs`](../apps/rocm/src/therock/source.rs) — full domain extraction, a child of `therock.rs` that depends only on `therock/version.rs` (split out of `therock.rs`): where an install reads from. `TheRockChannel` (release or nightly) and `SourceLayout` (the canonical stream, or ROCm 10's separately hosted next layout) are the two axes; `resolve_source` maps a pair to the `ResolvedSource` wheel-index and tarball-catalog bases, honouring a `ROCM_CLI_THEROCK_*_BASE` override only behind the explicit opt-in (`therock_base_override_allowed`, `select_base_override`, `env_override_base`); `select_source_layout`, `requested_source_layout` and `next_layout_requested` decide the layout from a pin; `RuntimeVersionSelector` is the version or build date a user pins (`pub(crate)`, re-exported by `therock.rs`). `FamilyResolution` lives here rather than in `therock/family.rs` because choosing the layout reads it; that keeps the dependency one-way, with `family.rs` building on this file. `TheRockChannel`, `SourceLayout`, `ResolvedSource` and `FamilyResolution` (with their methods and fields), `RuntimeVersionSelector`'s `describe` and `matches_version`, `resolve_source`, the three layout functions, and the `THEROCK_SOURCE_LAYOUT_GENERATION` and `THEROCK_NEXT_MIN_MAJOR` constants are `pub(super)` for `therock.rs` and its siblings; the base-override helpers and the other constants (the per-channel and next-layout base URLs, and the next layout's generation tag) are private to this file. - [`therock/family.rs`](../apps/rocm/src/therock/family.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` for `TheRockChannel` and `FamilyResolution` (split out of `therock.rs`): which package family a request targets. `resolve_family` picks it from `--family`, `ROCM_CLI_THEROCK_FAMILY`, a managed runtime or the host GPU, in that order, and refuses a GPU with no ROCm build (`unsupported_host_gpu_message`, `unsupported_requested_target_message`) instead of substituting another family; `family_override_or_recovered_arch` and `raw_arch_agreeing_with_family` recover the exact arch behind a grouped family; `family_resolution_hint` is the recovery text appended when no runtime is found. `resolve_family`, `family_override_or_recovered_arch` and `family_resolution_hint` are `pub(super)`; the rest is private. -- [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. +- [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `plan_python_launcher` is the same lookup for a caller that must change nothing, an install preview or an update check: it returns a `PlannedPython`, either `Ready` with the interpreter a real install would pick or `WouldPrepareManaged` with the managed Python a real install would prepare and this caller did not, and it raises the refusals the real resolution raises before that step. `python_for_install` is the install's one choice between that and `resolve_python_launcher`, and prints the progress line that names the interpreter; `PlannedPython` also writes the `python_note:` line from the decision itself, `note` for an install preview and `update_note` for an update check, so a note cannot name a version the install will not prepare. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, `plan_python_launcher` with `PlannedPython`'s `wheel_compatibility` and `update_note`, which `therock/update.rs` reads, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. - [`therock/probe.rs`](../apps/rocm/src/therock/probe.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/process.rs` and `therock/python.rs` (split out of `therock.rs`): asking an installed runtime about itself through its own interpreter. `probe_rocm_sdk_runtime` runs `ROCM_SDK_PROBE_SCRIPT` and parses what `rocm_sdk` reports into the `RocmSdkPythonProbe` that [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) owns and validates; `probe_runtime_devices` runs `RUNTIME_DEVICE_PROBE_SCRIPT` to count the devices the runtime's torch can open and whether one can run a kernel (`RuntimeDeviceProbe`); `probe_torch_alignment` reads the installed torch and the one an engine pins from distribution metadata without importing torch (`TorchAlignmentProbe`); and `split_local_version`, `requirement_pinned_version` and `install_pinned_package` are the torch-pin helpers [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) uses to put the SDK's torch back after an engine install. The `pub(crate)` items are re-exported by `therock.rs` for [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs); `probe_rocm_sdk_runtime_for_target`, which `install_wheel_runtime` calls with the device payload it just chose, is `pub(super)`. - [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) — a child of `therock.rs` that holds no logic (split out of `therock.rs`): only the `mod` declarations for the artifact-resolution modules under `therock/resolve/` and the `pub(super) use` lines through which `therock.rs` reads them. It is the parent the `resolve/` files hang from, so a module there is `pub(in crate::therock)` for the items `therock.rs` reaches and private otherwise. - [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. From 5e630fc9420ee5ae978ff16f28cfc19c99e9325b Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 9 Nov 2026 12:21:53 +0000 Subject: [PATCH 23/25] ROCMAI-872: list RestoredEnv in the therock/test_support.rs architecture entry Signed-off-by: Jussi Elo --- docs/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture.md b/docs/architecture.md index 83892f54ae..f098ca9753 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -112,7 +112,7 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`); `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, and `TorchaudioPin` with its `describe`, so they can use what `resolve_pip_runtime` returns without naming the types; the rest is private. - [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private. - [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/io.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and, with `RuntimeUpdatePlan`, which [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) reads its verdict from, re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. -- [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`. +- [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`, and `RestoredEnv`, which sets or removes process environment variables for one test and puts them back on drop, so a caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds one). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`. - [`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 immediately and which need the user's approval first. It owns `ChatRocmCommandAction` (read-only, or approval with the titles the approval prompt shows) and `ChatToolApprovalRequest`, the validators (`validate_chat_tool_call`, the `validate_chat_*_tool_call` family, `validate_required_chat_string`, `validate_optional_chat_integer`, `reject_control_characters_in_tool_arguments` (which refuses a model-supplied tool name or argument carrying a terminal control character, for every tool except `rocm_command`, whose argv `normalized_chat_rocm_command_args` screens entry by entry), `validate_serve_command_safety`, the four rules a model-proposed `serve` must satisfy (no public bind, no CPU device, a loopback host, `--managed` without `--foreground`), and `validate_chat_rocm_command_safety`, which applies them to a `serve` argv and also refuses a system install folder (`chat_install_prefix_is_system`)), the classifiers (`chat_rocm_command_action`, `chat_rocm_command_action_from_args`, `chat_install_driver_action`, `canonicalize_chat_rocm_command`, `normalized_chat_rocm_command_args`, `chat_tool_call_is_read_only`), `chat_tool_approval_request`, and the readers that turn a tool call into its argv and one-line command (`rocm_chat_tool_requested_args`, `rocm_chat_tool_requested_command`, with `push_optional_json_cli_arg` and `json_string`). It moved verbatim from `chat.rs` with the tests that exercise only these items. It depends on [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs), `providers::ChatToolCall`, `service_launch::is_loopback_host`, `services_text::validate_service_id`, `shell_quote::has_terminal_control_character`, `therock::RuntimeVersionSelector` and `driver_install::host_install_driver_only_reports`, none of which imports `chat`, so `freeform_planner.rs` calls `validate_serve_command_safety` and `validate_chat_rocm_command_safety` here instead of through `chat`, and keeps no copy of the serve rules. `chat.rs`'s child modules call into it and `chat.rs` re-exports `validate_chat_tool_call`, `chat_tool_call_is_read_only` and `chat_tool_approval_request` (read by `dash_seam.rs`), and `ChatRocmCommandAction`, `chat_install_driver_action`, `chat_rocm_command_action_from_args` and `rocm_chat_tool_requested_args`, which only other modules' tests read as `crate::chat::` (`driver_plan.rs`, `system_packages.rs`). - [`uninstall.rs`](../apps/rocm/src/uninstall.rs) — mechanical relocation, owns types: `uninstall()`, plus the installer `PATH` undo and running-executable deletion. The shared plan type and its file-removal helpers live in [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) below instead, because [`storage.rs`](../apps/rocm/src/storage.rs) reuses them too. The two modules depend on each other: `uninstall_plan.rs` reads this module's `pub(crate)` `PathEdit`, `PATH_EDIT_RECORD`, `plan_path_edits`, `plan_is_empty`, `removal_count` and `render_extra_plan`. - [`uninstall_plan.rs`](../apps/rocm/src/uninstall_plan.rs) — mechanical relocation, shares crate-visible types (Phase 6f, ROCMAI-212): the uninstall-plan types (`UninstallOptions`, `UninstallPlan`, `UninstallPlanEntry`), building the plan (`build_uninstall_plan`, `plan_installed_binaries`, and the installed-binary/shared-cache discovery helpers behind them), rendering it (`render_uninstall_dry_run`, `render_uninstall_plan`), the `[y/N]` confirmation prompt (`confirm_uninstall`), and the filesystem removal primitive both [`uninstall.rs`](../apps/rocm/src/uninstall.rs) and [`storage.rs`](../apps/rocm/src/storage.rs) call to carry a plan out (`remove_path`, and the entry-resolution helpers behind it). Kept separate from `uninstall.rs` rather than folded into it, since `uninstall.rs`'s own doc comment and name both describe `uninstall()`'s exclusive logic (the installer `PATH` undo and running-executable deletion), while this module's plan/render/removal helpers are shared with `storage.rs`. `main.rs` (`UninstallOptions`), `uninstall.rs`, `storage.rs`, `runtimes_cmd.rs`, `chat/mcp_bridge.rs`, and [`deletion_properties.rs`](../apps/rocm/src/deletion_properties.rs) (Unix-only property tests) each import the subset of these `pub(crate)` types and helpers they need; see this module's own doc comment for which symbol each one uses. From a623dc5bf3ad851967929f3094b243fce68d4a85 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 9 Nov 2026 12:22:14 +0000 Subject: [PATCH 24/25] ROCMAI-872: describe the update check and its python_note in the update.rs module doc Signed-off-by: Jussi Elo --- apps/rocm/src/therock/update.rs | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index 835526b21d..69888255b6 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -4,14 +4,20 @@ //! Whether an installed runtime has something newer to offer, and the bounded //! startup check that asks. `runtime_update_plan` resolves the latest source for -//! one runtime (`resolve_latest_for_manifest`, which re-resolves a wheel -//! runtime through `resolve_pip_runtime_with_timeout` and a tarball one through +//! one runtime, and `runtime_update_check` does the same for a caller that +//! changes nothing (the report, the JSON, the startup check and an apply's +//! preview). They differ in `PythonAccess`: given a wheel runtime that records +//! no usable Python, the plan prepares a managed Python (an apply needs one), +//! while the check works the wheel tag out from the interpreter the layout +//! requires and carries a `python_note` saying the preparation was left undone +//! (`resolve_latest_for_manifest` re-resolves a wheel runtime through +//! `resolve_pip_runtime_with_timeout` and a tarball one through //! `resolve_tarball_artifact_with_timeout`, on the layout the runtime was //! installed from) and `runtime_freshness` classifies it (`RuntimeFreshness`: //! up to date, update available, repair available, or ahead of the index) into //! a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` show //! the plans for `rocm update` (the JSON form is what the dashboard's update -//! check parses), and `maybe_refresh_startup_update_check` keeps one +//! check parses and carries no `python_note`), and `maybe_refresh_startup_update_check` keeps one //! `StartupUpdateCheckRecord` in the cache so the check runs at most once an //! interval and is bounded by a short download timeout. //! From cf785f1fb6c4926b785a213b8d56329165cc944d Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Mon, 9 Nov 2026 14:46:59 +0000 Subject: [PATCH 25/25] ROCMAI-872: say what the update check does with uv and Python now that the install preview fetches no uv The merged notes still said the update check prepares a managed Python, which this change made false, and that the install preview can fetch the managed uv, which the preview change made false. The check on a ROCm 10 or newer runtime still resolves the package versions with uv and can fetch it; it prepares no Python, and the install preview fetches no uv. Signed-off-by: Jussi Elo --- docs/testing.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/testing.md b/docs/testing.md index df6c84d63d..cb98f6dc76 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -839,8 +839,8 @@ progress output and that `uv` was not run and no file was written. Beside it are `a_dry_run_reads_every_spelling_of_a_managed_python_version_the_same_way`. The preview does still write its package-index cache under the cache folder. The `update_check` tool and the plain `rocm update` check (no `--apply`) are not -previews in this sense: they resolve with `uv` and can fetch it, and prepare a -managed Python too. +previews in this sense: on a ROCm 10 or newer runtime they resolve with `uv` and +can fetch it. They prepare no Python, though (see `update-09` and `update-10`). Then it verifies: @@ -2380,9 +2380,10 @@ JSON, the startup check, the check plan and `apply_runtime_update` with that show the stand-in `uv` is reachable. Which of the two plans a `--dry-run` and an apply take is also pinned on every platform, Windows included, by `a_dry_run_takes_the_check_and_an_apply_takes_the_plan` in -[update_cmd.rs](../apps/rocm/src/update_cmd.rs). As for the install preview, resolving a -ROCm 10 or newer runtime uses `uv pip compile` and can fetch the managed `uv`, -though never a Python. +[update_cmd.rs](../apps/rocm/src/update_cmd.rs). Unlike the install preview, which fetches no +`uv`, the check on a ROCm 10 or newer runtime still resolves the package versions +with `uv pip compile` and can fetch the managed `uv`, though never a Python; the +scenarios above use the canonical layout, which needs no `uv`. Runtime version-ordering tests: