diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 8efc17ebbe..e31b255aac 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, + 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,30 +362,24 @@ fn install_wheel_runtime( } } }; - progress_line(format!( - "Checking Python for the ROCm install; if needed, ROCm CLI will prepare Python {}.", - 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 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) + ) }); - let wheel_compatibility = wheel_compatibility_for_python(&python_launcher.executable)?; + // 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. + // It also prints the line naming the interpreter, once the decision is made. + let python = python_for_install(paths, python_requirement, dry_run)?; + let wheel_compatibility = python.wheel_compatibility()?; progress_line(format!( "Checking TheRock {} packages for this AMD GPU...", channel.as_str() @@ -478,12 +471,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().as_str()); + if let Some(note) = python.note() { + let _ = writeln!(output, " python_note: {note}"); + } let _ = writeln!( output, " python_wheel_tag: {}", @@ -538,7 +530,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); // This line is offered as the command to run, so it has to be one a // shell reads back as the argv it previews. The install root in it // comes from a `--prefix` the local assistant can choose @@ -568,6 +560,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..43b38f0261 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)] @@ -249,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)?; @@ -283,7 +312,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 +386,7 @@ fn ensure_managed_python( )); Ok(PythonLauncher { executable, - source: "managed", + source: PythonSource::Managed, }) } @@ -377,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` @@ -455,38 +500,332 @@ 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. +/// +/// 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 { + let python = if dry_run { + plan_python_launcher(paths, requirement)? + } else { + 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 +/// 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 => { + 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 + // 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 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" + ) + })?; + } + PlannedPython::WouldPrepareManaged { + version, + requirement, + tag_check: if tag.is_some() { + TagCheck::Checked + } else { + TagCheck::Unchecked + }, + } + } + }) +} + +/// 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. `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_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 + /// 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) -> PythonSource { + match self { + Self::Ready(launcher) => launcher.source, + Self::WouldPrepareManaged { .. } => PythonSource::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, + requirement, + 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_check, *requirement) + )), + } + } + + /// 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(launcher) => match launcher.source { + PythonSource::Path => { + format!("Using Python from PATH: {}.", launcher.executable.display()) + } + PythonSource::Env => format!( + "Using Python from ROCM_CLI_PYTHON: {}.", + launcher.executable.display() + ), + PythonSource::Managed => format!( + "Using ROCm CLI's portable Python: {}.", + launcher.executable.display() + ), + PythonSource::Manifest => { + format!("Using Python from {}.", launcher.executable.display()) + } + }, + Self::WouldPrepareManaged { + version, + requirement, + tag_check, + } => format!( + "No usable Python found; a real install would prepare Python {version}{}. This preview does not.", + unchecked_tag_caveat(*tag_check, *requirement) + ), + } + } + + /// 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" + ), + } + } +} + +/// 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_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 + ), + } +} + +/// 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 +/// the finding and leaves the prediction to the decision's own line. +#[derive(Clone, Copy, Debug)] +enum LookupPurpose { + Install, + 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. + 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, env.managed_python_version(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", - }); + source: PythonSource::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", - }); + source: PythonSource::Path, + })); } Err(_) => { skipped_path_python = true; } } } + // 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); using ROCm CLI's managed Python.", - requirement.tag + progress_line(purpose.unusable_python_line( + "Python from PATH", + requirement, + "using ROCm CLI's managed Python", )); } @@ -494,23 +833,24 @@ 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", - }); + source: PythonSource::Managed, + })); } - progress_line(format!( - "Saved managed Python is not usable for this ROCm install ({} is required); preparing Python again.", - requirement.tag + progress_line(purpose.unusable_python_line( + "Saved managed Python", + requirement, + "preparing Python again", )); } - 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" ); } - ensure_managed_python(paths, requirement) + Ok(PythonLookup::NeedsManagedBootstrap) } fn python_path_candidates(search_dirs: &[PathBuf]) -> Vec { @@ -564,14 +904,60 @@ 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, 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.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@"] + .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()?; + // 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}")) } fn verify_python_can_create_venv(program: &Path) -> Result<()> { @@ -786,10 +1172,11 @@ exit 1 &PythonResolverEnv { python_override: None, search_dirs: vec![bin_dir], + ..PythonResolverEnv::from_process_env() }, 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: {}", @@ -888,11 +1275,12 @@ exit 1 &PythonResolverEnv { python_override: None, search_dirs: vec![bin_dir], + ..PythonResolverEnv::from_process_env() }, 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(()) @@ -954,12 +1342,14 @@ 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))? }; 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)); @@ -980,6 +1370,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() @@ -992,6 +1383,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() @@ -1016,6 +1408,1006 @@ exit 1 ); } + // ---- a dry run prepares no Python ---------------------------------------- + + /// Process environment variables set for one test and restored on drop. + /// Every caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds this. + struct RestoredEnv(Vec<(&'static str, Option)>); + + impl RestoredEnv { + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + fn set(vars: &[(&'static str, Option<&Path>)]) -> Self { + let saved = vars + .iter() + .map(|(key, _)| (*key, std::env::var_os(key))) + .collect(); + for (key, value) in vars { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + Self(saved) + } + } + + impl Drop for RestoredEnv { + #[allow(unsafe_code)] // std::env::set_var is unsafe in edition 2024 + fn drop(&mut self) { + for (key, value) in self.0.drain(..) { + unsafe { + match value { + Some(value) => std::env::set_var(key, value), + None => std::env::remove_var(key), + } + } + } + } + } + + /// A `uv` that records its arguments in `marker` and then fails. A host that + /// reaches it has gone on to prepare a managed Python; failing keeps a test + /// that does reach it from going on to the network. + #[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. + 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()], + ..PythonResolverEnv::from_process_env() + }); + 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-23` 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, + 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_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"); + 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(()) + } + + /// 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, 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_check: planned_check, + .. + } = &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!(*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!( + 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(()) + } + + /// 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)] + #[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, PythonSource::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, PythonSource::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(()) + } + + /// `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 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} (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.") + }); + } + } + } + + 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 + /// 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_check: TagCheck::Checked, + .. + } + ), + "{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_check: TagCheck::Unchecked, + .. + } + ), + "{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}" + ); + assert_eq!( + planned.progress_text(), + "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()); + 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")); + // 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", + "3.*", + "*", + "latest", + "pypy@3.10", + "3.13rc1", + ">=3.12", + "cpython-", + ] { + 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. + #[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, + tag_check: TagCheck::Checked, + }; + + let compatibility = planned.wheel_compatibility()?; + assert_eq!(compatibility.python_tag, tag); + assert!(compatibility.platform_tags.contains(&"any".to_owned())); + 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!( + 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: PythonSource::Path, + }); + assert_eq!(planned.launcher_display(), "/usr/bin/python3"); + 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!( + 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/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index 22b4e3c96a..3b203c3e2d 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, @@ -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()); diff --git a/crates/rocm-dash-tui/src/agent/tools.rs b/crates/rocm-dash-tui/src/agent/tools.rs index 1b3b19d4c7..3b4a0a6512 100644 --- a/crates/rocm-dash-tui/src/agent/tools.rs +++ b/crates/rocm-dash-tui/src/agent/tools.rs @@ -207,11 +207,15 @@ 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` 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. // --------------------------------------------------------------------------- /// 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..5941e47310 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -158,6 +158,28 @@ 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. 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. +- 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 5497fac09f..01b6a93fd4 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -508,6 +508,59 @@ 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 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. 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 +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 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, +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`. 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 2879432000..d3b93cf112 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -473,3 +473,89 @@ Feature: Runtime configuration When the user approves a natural-language SDK install into a folder whose name has a quote Then the request plan names that folder as a single argument And the executed command names that folder as a single argument + + # 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. 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. + # + # 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 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 + # 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 cannot trip the backstop check. + @id:runtime-install-preview-prepares-no-python @requires-os:linux + Scenario: runtime-23 - 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 + + # 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-23 does. + # + # Linux only, for the same empty-`PATH` host as runtime-23. 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-24 - 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 + + # 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/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 7074902508..d07a243d34 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -233,6 +233,80 @@ 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"; + +/// 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 +/// 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())); + // 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 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 + .command_env + .push(("ROCM_CLI_CACHE_DIR", scratch_cache.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"); @@ -1040,6 +1114,192 @@ 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", + ); + assert_no_python_prepared(world); +} + +/// 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. 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(); + 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() + ); + // 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(), + "the preview downloaded a tool archive into {}", + cache_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() + ); +} + +/// 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 + .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}" + ); + } + // 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); +} + #[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);