From 9119af7f9caf9e47d19cf1bdbc8b8fbebdaa3f63 Mon Sep 17 00:00:00 2001 From: Jussi Elo Date: Thu, 5 Nov 2026 10:26:41 +0000 Subject: [PATCH 01/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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/17] 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