From f63710af4c58196b87bab55638779ffe97e77386 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 6 Oct 2026 10:49:29 +0000 Subject: [PATCH 01/15] fix(therock): never delete an install folder to rebuild its venv When the Python in an install folder failed `--version` or no longer matched the required interpreter, `ensure_uv_venv` ran `remove_dir_all` on the whole folder. With `install sdk --prefix` that folder is whatever the user named, so a home directory with a failing `~/bin/python` was deleted, and only then did the rebuild fail. Even a runtime ROCm CLI created holds data that is not the venv: ComfyUI keeps the user's models, workflows and outputs under `/apps/comfyui`. The rebuild now: - refuses a protected system location, by the path as given and by where it resolves; - refuses any folder ROCm CLI cannot show it created: it needs `pyvenv.cfg` and either the in-tree `.rocm-cli-runtime.json` naming this folder or a place inside the managed runtimes folder. The refusal names the folder and what was found, changes nothing, and says to choose an empty folder or one ROCm CLI created; - removes only the venv's own entries (`bin`/`Scripts`, `lib`/`Lib`, `lib64`, `include`, `pyvenv.cfg`, `CACHEDIR.TAG`), unlinking rather than following links, then runs `uv venv --allow-existing`, and prints what it kept, computed from the folder after clearing; - pins `UV_VENV_CLEAR=0` for `uv venv`, so a value exported in the user's shell cannot make uv clear the folder instead. Fixes #533 Signed-off-by: Roman Inflianskas --- README.md | 14 +- apps/rocm/src/cli.rs | 5 + apps/rocm/src/therock/consent.rs | 10 +- apps/rocm/src/therock/python.rs | 742 +++++++++++++++++- docs/manual-testing.md | 6 + .../features/runtime_setup.feature | 34 + tests/e2e-cucumber/tests/e2e/therock_steps.rs | 282 +++++++ 7 files changed, 1075 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 313a7f4ee1..43d10809da 100644 --- a/README.md +++ b/README.md @@ -529,9 +529,17 @@ same-version reinstall reuses the same root. `--prefix` changes this. The folder you name is used as-is for every version, so successive installs into one prefix replace each other in place. If the venv -already there no longer runs its own Python, it is removed outright and rebuilt. -The approval prompt doesn't cover this, because it asks only about changing the -active default runtime, not about what a named prefix loses. +already there no longer runs its own Python, ROCm CLI rebuilds it only when it +can show it created that venv: the folder has `pyvenv.cfg` and either the +`.rocm-cli-runtime.json` a ROCm CLI install writes, naming that folder, or a +place inside ROCm CLI's own managed runtimes folder. The rebuild removes only +the venv's own files (`bin`/`Scripts`, `lib`/`Lib`, `lib64`, `include`, +`pyvenv.cfg`) and keeps everything else in the folder, such as ComfyUI's models, +workflows, and outputs under `apps/comfyui`; the install prints what it kept. +Any other folder, or one in a protected system location, is refused with +nothing changed; choose an empty folder, or one ROCm CLI created, instead. +A `UV_VENV_CLEAR` exported in your shell is ignored when ROCm CLI creates the +venv, so it cannot make uv clear the folder either. #### ROCm 10 and newer diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index ff922a0664..7cd50d4262 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -788,6 +788,11 @@ rocm install sdk --devel")] #[arg(long, default_value = "wheel")] format: InstallFormat, /// Full folder path where the ROCm Python environment should be created. + /// + /// Use an empty folder or one ROCm CLI created. If the environment + /// already there no longer runs, ROCm CLI rebuilds only its venv files, + /// and only in a folder it can show it created; any other folder is + /// refused with nothing changed. #[arg(long)] prefix: Option, /// Exact TheRock package version to install. diff --git a/apps/rocm/src/therock/consent.rs b/apps/rocm/src/therock/consent.rs index 165bddca9b..f01411adb7 100644 --- a/apps/rocm/src/therock/consent.rs +++ b/apps/rocm/src/therock/consent.rs @@ -411,10 +411,12 @@ pub(super) fn refuse_non_interactive_message(relation: &str) -> String { /// /// `--prefix` is the exception and the prompt does not claim otherwise: /// `resolved_install_root` uses the given folder verbatim for every version, so -/// a second install into one prefix does replace the first in place (and -/// `ensure_uv_venv` will `remove_dir_all` it outright if the existing venv's -/// python no longer answers `--version`). The gate is unchanged either way — -/// what is being consented to is the change of active default, not a deletion. +/// a second install into one prefix does replace the first in place (and if +/// the existing venv's python no longer answers `--version`, `ensure_uv_venv` +/// rebuilds the venv's own files, and only when ROCm CLI can show it created +/// that venv; see `clear_owned_venv_for_rebuild`). The gate is unchanged either +/// way — what is being consented to is the change of active default, not a +/// deletion. pub(super) fn confirm_overwrite_existing_sdk( channel: TheRockChannel, family: &str, diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 3ca1ff1a55..b35b607bfa 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -122,6 +122,7 @@ pub(super) fn ensure_uv_venv( install_root: &Path, ) -> Result<()> { let env_python = venv_python_path(install_root); + let mut rebuilding = false; if env_python.is_file() { let reusable = run_command( &env_python, @@ -140,24 +141,30 @@ pub(super) fn ensure_uv_venv( // resolved version/build date, not on the interpreter), so an existing // venv left over from a lower-tag requirement must not be mistaken for // a compatible one just because it still runs. - progress_line( - "Existing Python environment does not match the required interpreter; recreating it.", - ); - fs::remove_dir_all(install_root).with_context(|| { - format!( - "failed to remove incompatible Python environment at {}", - install_root.display() - ) - })?; + // + // The folder itself is never deleted: with `--prefix` it is whatever + // the user named, and even a runtime ROCm CLI created holds data that + // is not the venv's (ComfyUI keeps its models, workflows and outputs + // under `/apps/comfyui`). Only the venv's own parts go. + let kept = clear_owned_venv_for_rebuild(paths, install_root)?; + progress_line(venv_rebuild_line(install_root, &kept)); + rebuilding = true; + } + let mut args = uv_venv_args(python_launcher, install_root); + if rebuilding { + // What is left after clearing is not a venv any more, so uv would + // refuse it as "a directory already exists". `--allow-existing` + // writes the new venv beside it; `--clear` would instead delete the + // whole folder, which is exactly what the clearing step avoids. + args.push("--allow-existing".to_owned()); } - let args = uv_venv_args(python_launcher, install_root); run_command_with_env( uv, args.iter() .map(String::as_str) .collect::>() .as_slice(), - &uv_command_env(paths), + &uv_venv_command_env(paths), "create managed TheRock runtime virtual environment", )?; if !env_python.is_file() { @@ -169,6 +176,224 @@ pub(super) fn ensure_uv_venv( Ok(()) } +/// The environment for `uv venv` into an install root. +/// +/// `UV_VENV_CLEAR=1` inherited from the user's shell makes uv delete an +/// existing folder before creating the venv, which is the `--clear` this +/// function's caller deliberately does not pass: the folder may be a `--prefix` +/// the user named, holding their own files. Pinning it off keeps that decision +/// here instead of in whatever the shell happened to export. +fn uv_venv_command_env(paths: &AppPaths) -> Vec<(String, String)> { + let mut env = uv_command_env(paths); + env.push(("UV_VENV_CLEAR".to_owned(), "0".to_owned())); + env +} + +/// The entries a Python virtual environment is made of, as `uv venv` and +/// `python -m venv` lay one out on Linux (`bin`, `lib`, `lib64`, `include`) and +/// Windows (`Scripts`, `Lib`, `Include`). Clearing these and nothing else is +/// what lets a broken venv be rebuilt without taking the rest of its folder. +/// +/// `share` is deliberately absent: packages install data there, but so can a +/// person, and nothing distinguishes the two. A stale `share` costs nothing, +/// because the reinstall that follows overwrites what it needs. +const VENV_OWNED_ENTRIES: &[&str] = &[ + "bin", + "Scripts", + "lib", + "lib64", + "Lib", + "include", + "Include", + "pyvenv.cfg", + "CACHEDIR.TAG", +]; + +/// The in-tree runtime manifest `save_runtime_manifest` writes beside every +/// install. Only the fields ownership needs: an older manifest that no longer +/// deserializes as a full [`InstalledRuntimeManifest`] still proves who made +/// the folder. +#[derive(Debug, Deserialize)] +struct RuntimeOwnershipMarker { + runtime_key: String, + install_root: PathBuf, +} + +/// What a folder's own contents say about whether ROCm CLI made it. +#[derive(Debug, Clone, PartialEq, Eq)] +enum MarkerFinding { + Missing, + Unreadable, + NamesOtherFolder(PathBuf), + Matches, +} + +/// Clear a venv ROCm CLI owns so `uv venv` can rebuild it, keeping everything +/// in its folder that is not part of the venv. Returns the names that were kept. +/// +/// Refuses, changing nothing, unless the folder is somewhere ROCm CLI may +/// delete from AND it can show the venv is its own: +/// +/// 1. not a protected system location, by its given spelling or by where it +/// really resolves (`rocm_core::runtime_install_root_is_protected`); and +/// 2. it has `pyvenv.cfg`, so it is a venv at all, and either ROCm CLI's +/// in-tree runtime manifest naming this very folder, or it sits inside +/// ROCm CLI's own managed runtimes folder. The second case covers an +/// install that failed after creating the venv but before writing its +/// manifest: nobody else puts a venv there. +/// +/// A `--prefix` folder is used verbatim, so without these checks a home +/// directory whose `~/bin/python` fails `--version` was deleted whole. +fn clear_owned_venv_for_rebuild(paths: &AppPaths, install_root: &Path) -> Result> { + refuse_protected_venv_rebuild(install_root)?; + + let has_pyvenv_cfg = install_root.join("pyvenv.cfg").is_file(); + let marker = runtime_ownership_marker_finding(install_root); + let in_managed_root = install_root_is_in_managed_wheel_root(paths, install_root); + let owned = has_pyvenv_cfg && (marker == MarkerFinding::Matches || in_managed_root); + if !owned { + bail!(unowned_venv_rebuild_refusal( + install_root, + has_pyvenv_cfg, + &marker, + in_managed_root + )); + } + + for name in VENV_OWNED_ENTRIES { + remove_venv_entry(&install_root.join(name))?; + } + let mut kept = fs::read_dir(install_root) + .with_context(|| format!("failed to read {}", install_root.display()))? + .map(|entry| entry.map(|entry| entry.file_name().to_string_lossy().into_owned())) + .collect::>>() + .with_context(|| format!("failed to read {}", install_root.display()))?; + kept.sort(); + Ok(kept) +} + +/// The protected-location half of [`clear_owned_venv_for_rebuild`], checked on +/// the path as given and again on where it really resolves: a link inside the +/// home folder can point into `/usr`, and the lexical check alone answers for +/// the link, not for what a delete would reach. +fn refuse_protected_venv_rebuild(install_root: &Path) -> Result<()> { + let resolved = install_root.canonicalize().ok(); + let protected = std::iter::once(install_root) + .chain(resolved.as_deref()) + .find(|candidate| rocm_core::runtime_install_root_is_protected(candidate)); + if let Some(protected) = protected { + bail!( + "refusing to rebuild the Python environment at {}: {} is a protected system location. Nothing was changed. Choose an empty folder with --prefix instead, for example `rocm install sdk --prefix `", + install_root.display(), + protected.display() + ); + } + Ok(()) +} + +fn runtime_ownership_marker_finding(install_root: &Path) -> MarkerFinding { + let path = install_root.join(".rocm-cli-runtime.json"); + if !path.is_file() { + return MarkerFinding::Missing; + } + let Some(marker) = fs::read(&path) + .ok() + .and_then(|bytes| serde_json::from_slice::(&bytes).ok()) + .filter(|marker| !marker.runtime_key.trim().is_empty()) + else { + return MarkerFinding::Unreadable; + }; + let recorded = normalize_runtime_path_for_host(&marker.install_root); + if paths_name_same_folder(&recorded, install_root) { + MarkerFinding::Matches + } else { + MarkerFinding::NamesOtherFolder(recorded) + } +} + +fn paths_name_same_folder(left: &Path, right: &Path) -> bool { + if rocm_core::runtime_paths_equivalent(left, right) { + return true; + } + match (left.canonicalize(), right.canonicalize()) { + (Ok(left), Ok(right)) => rocm_core::runtime_paths_equivalent(&left, &right), + _ => false, + } +} + +/// Strictly inside `/runtimes/wheel`, where every folder is one +/// `install sdk` made for itself. +fn install_root_is_in_managed_wheel_root(paths: &AppPaths, install_root: &Path) -> bool { + let managed = + rocm_core::resolve_path_through_symlinks(&paths.data_dir.join("runtimes").join("wheel")); + let root = rocm_core::resolve_path_through_symlinks(install_root); + rocm_core::runtime_path_is_same_or_inside(&root, &managed) + && !rocm_core::runtime_paths_equivalent(&root, &managed) +} + +fn unowned_venv_rebuild_refusal( + install_root: &Path, + has_pyvenv_cfg: bool, + marker: &MarkerFinding, + in_managed_root: bool, +) -> String { + let mut found = vec![format!( + "a Python at {} that does not run or does not match", + venv_python_path(install_root).display() + )]; + if !has_pyvenv_cfg { + found.push("no pyvenv.cfg, so it is not a Python virtual environment".to_owned()); + } + match marker { + MarkerFinding::Missing if !in_managed_root => { + found.push("no .rocm-cli-runtime.json from a ROCm CLI install".to_owned()); + } + MarkerFinding::Unreadable if !in_managed_root => { + found.push("a .rocm-cli-runtime.json ROCm CLI cannot read".to_owned()); + } + MarkerFinding::NamesOtherFolder(other) if !in_managed_root => found.push(format!( + "a .rocm-cli-runtime.json that belongs to {}", + other.display() + )), + _ => {} + } + format!( + "refusing to rebuild the Python environment at {}: ROCm CLI cannot show it created this folder (found {}), and rebuilding would delete what is in it. Nothing was changed. Choose an empty folder, or one ROCm CLI created, with --prefix, for example `rocm install sdk --prefix `", + install_root.display(), + found.join("; ") + ) +} + +/// Remove one venv entry without following a link out of the folder: `lib64` +/// is a symlink to `lib` in a uv venv, and a link must go, not its target. +fn remove_venv_entry(path: &Path) -> Result<()> { + let Ok(metadata) = fs::symlink_metadata(path) else { + return Ok(()); + }; + let result = if metadata.file_type().is_symlink() { + fs::remove_file(path).or_else(|_| fs::remove_dir(path)) + } else if metadata.is_dir() { + fs::remove_dir_all(path) + } else { + fs::remove_file(path) + }; + result.with_context(|| format!("failed to remove {}", path.display())) +} + +/// The progress line for a rebuild, from the same list the rebuild returned, +/// so what it says was kept is what is still on disk. +fn venv_rebuild_line(install_root: &Path, kept: &[String]) -> String { + let kept = if kept.is_empty() { + "nothing else was in the folder".to_owned() + } else { + format!("kept: {}", kept.join(", ")) + }; + format!( + "Existing Python environment at {} no longer runs or does not match the required interpreter; rebuilding only its venv files ({kept}).", + install_root.display() + ) +} + fn python_venv_args(install_root: &Path) -> Vec { vec![ "-m".to_owned(), @@ -1011,6 +1236,8 @@ fn python_venv_probe_temp_root() -> Result { #[cfg(test)] mod tests { + use super::super::managed_runtime_root; + use super::super::process::PROGRESS_LINE_SINK; use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; use crate::therock::test_support::{RestoredEnv, test_paths}; @@ -2505,6 +2732,9 @@ exit 1 let stale_bin = install_root.join("bin"); fs::create_dir_all(&stale_bin).unwrap(); write_fake_python_reporting(&stale_bin, "python", "cp312", "Python 3.12.10").unwrap(); + // A venv a previous `install sdk` made: rebuilding is only allowed on + // one ROCm CLI can show it created. + plant_rocm_owned_venv_markers(&install_root); let python_launcher = write_fake_python_reporting(&root, "python3.14", "cp314", "Python 3.14.5").unwrap(); @@ -2521,4 +2751,494 @@ exit 1 fs::remove_dir_all(root).ok(); } + + // ── ensure_uv_venv: rebuilding a broken venv (#533) ───────────── + // + // Every case plants a `bin/python` that fails `--version`, the trigger for + // the rebuild, and a sentinel file beside the install root. The oracle is + // the filesystem: a refusal must leave the tree byte-for-byte as it was, + // and a rebuild must leave everything that is not part of the venv. + + /// A canonical sandbox with `AppPaths` inside it and a sentinel file + /// outside every install root the test will use. + #[cfg(unix)] + fn venv_rebuild_sandbox(label: &str) -> (PathBuf, AppPaths) { + static SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + let root = std::env::temp_dir().join(format!( + "rocm-cli-venv-rebuild-{label}-{}-{}-{}", + std::process::id(), + unix_time_millis(), + SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + )); + fs::create_dir_all(root.join("data")).unwrap(); + fs::create_dir_all(root.join("cache")).unwrap(); + let root = root.canonicalize().unwrap(); + fs::write(root.join("sentinel"), b"outside every install root").unwrap(); + let paths = AppPaths { + config_dir: root.join("config"), + data_dir: root.join("data"), + cache_dir: root.join("cache"), + }; + (root, paths) + } + + #[cfg(unix)] + fn plant_failing_venv_python(install_root: &Path) { + use std::os::unix::fs::PermissionsExt; + let python = venv_python_path(install_root); + fs::create_dir_all(python.parent().unwrap()).unwrap(); + fs::write(&python, "#!/bin/sh\nexit 1\n").unwrap(); + fs::set_permissions(&python, fs::Permissions::from_mode(0o755)).unwrap(); + } + + /// What `uv venv` and `save_runtime_manifest` leave in a runtime ROCm CLI + /// installed: `pyvenv.cfg` plus the in-tree runtime manifest naming the + /// folder it sits in. + #[cfg(unix)] + fn plant_rocm_owned_venv_markers(install_root: &Path) { + fs::create_dir_all(install_root).unwrap(); + fs::write(install_root.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); + write_runtime_marker(install_root, install_root); + } + + #[cfg(unix)] + fn write_runtime_marker(install_root: &Path, recorded_root: &Path) { + let marker = serde_json::json!({ + "runtime_key": "release-wheel-gfx120x-7-10-0", + "runtime_id": "therock-release:gfx120X-all", + "install_root": recorded_root, + }); + fs::write( + install_root.join(".rocm-cli-runtime.json"), + serde_json::to_vec_pretty(&marker).unwrap(), + ) + .unwrap(); + } + + /// A fake `uv` that records every invocation and, for `venv`, creates a + /// working interpreter at `$4` (the env root `uv_venv_args` passes). + #[cfg(unix)] + fn write_logging_fake_uv(dir: &Path) -> (PathBuf, PathBuf) { + use std::os::unix::fs::PermissionsExt; + let log = dir.join("uv-calls.log"); + let path = dir.join("uv"); + let script = format!( + r#"#!/bin/sh +echo "$@" >> "{log}" +echo "UV_VENV_CLEAR=${{UV_VENV_CLEAR-unset}}" >> "{log}" +if [ "$1" = "venv" ] && [ "$2" = "--python" ]; then + /bin/mkdir -p "$4/bin" + printf '#!/bin/sh\nif [ "$1" = "-c" ]; then echo cp312; exit 0; fi\necho Python 3.12.10\n' > "$4/bin/python" + /bin/chmod +x "$4/bin/python" + echo "home = /usr/bin" > "$4/pyvenv.cfg" + exit 0 +fi +exit 1 +"#, + log = log.display() + ); + fs::write(&path, script).unwrap(); + fs::set_permissions(&path, fs::Permissions::from_mode(0o755)).unwrap(); + (path, log) + } + + /// Every entry under `root`, with file contents and link targets, without + /// following links: equality before and after is "nothing was changed". + #[cfg(unix)] + fn tree_snapshot(root: &Path) -> Vec<(PathBuf, String)> { + let mut out = Vec::new(); + let mut stack = vec![root.to_path_buf()]; + while let Some(path) = stack.pop() { + let Ok(meta) = fs::symlink_metadata(&path) else { + continue; + }; + let what = if meta.file_type().is_symlink() { + format!("link -> {}", fs::read_link(&path).unwrap().display()) + } else if meta.is_dir() { + for entry in fs::read_dir(&path).unwrap() { + stack.push(entry.unwrap().path()); + } + "dir".to_owned() + } else { + format!("file {:?}", fs::read(&path).unwrap()) + }; + out.push((path, what)); + } + out.sort(); + out + } + + #[cfg(unix)] + fn cp312_launcher(root: &Path) -> PathBuf { + write_fake_python_reporting(root, "python3.12", "cp312", "Python 3.12.10").unwrap() + } + + /// The reported case: a home-like folder whose `~/bin/python` fails + /// `--version` was deleted whole, then the rebuild failed anyway. + #[test] + #[cfg(unix)] + fn ensure_uv_venv_refuses_to_rebuild_a_folder_rocm_cli_did_not_create() { + let (root, paths) = venv_rebuild_sandbox("unowned"); + let home = root.join("home"); + plant_failing_venv_python(&home); + fs::create_dir_all(home.join("Documents")).unwrap(); + fs::write(home.join("Documents").join("thesis.txt"), b"years of work").unwrap(); + fs::write(home.join(".bashrc"), b"export PATH=$HOME/bin:$PATH\n").unwrap(); + let (uv, uv_log) = write_logging_fake_uv(&root); + let launcher = cp312_launcher(&root); + let before = tree_snapshot(&root); + + let error = ensure_uv_venv(&paths, &uv, &launcher, &home) + .expect_err("a folder ROCm CLI did not create must not be rebuilt") + .to_string(); + + assert_eq!( + tree_snapshot(&root), + before, + "a refusal must change nothing" + ); + assert!(!uv_log.exists(), "uv must not run after a refusal"); + assert!(error.contains(&home.display().to_string()), "{error}"); + assert!(error.contains("no pyvenv.cfg"), "{error}"); + assert!(error.contains("no .rocm-cli-runtime.json"), "{error}"); + assert!(error.contains("Nothing was changed"), "{error}"); + assert!( + error.contains("rocm install sdk --prefix "), + "{error}" + ); + + fs::remove_dir_all(root).ok(); + } + + /// The refusal tells the user to choose an empty folder, or one ROCm CLI + /// created. Both must then actually get past it, or the advice is a dead + /// end; and taking it must not touch the folder that was refused. + #[test] + #[cfg(unix)] + fn following_the_refusal_advice_gets_past_it() { + let (root, paths) = venv_rebuild_sandbox("advice"); + let refused = root.join("home"); + plant_failing_venv_python(&refused); + fs::write(refused.join("notes.txt"), b"mine").unwrap(); + let (uv, uv_log) = write_logging_fake_uv(&root); + let launcher = cp312_launcher(&root); + let error = ensure_uv_venv(&paths, &uv, &launcher, &refused) + .unwrap_err() + .to_string(); + assert!(error.contains("Choose an empty folder, or one ROCm CLI created")); + let refused_before = tree_snapshot(&refused); + + let empty = root.join("empty-folder"); + fs::create_dir_all(&empty).unwrap(); + ensure_uv_venv(&paths, &uv, &launcher, &empty) + .expect("an empty folder is what the refusal recommends"); + assert!(venv_python_path(&empty).is_file()); + // A fresh venv into a folder that exists is where an inherited + // UV_VENV_CLEAR=1 would make uv delete the folder first. + assert!( + fs::read_to_string(&uv_log) + .unwrap() + .lines() + .any(|line| line == "UV_VENV_CLEAR=0"), + "uv venv must run with UV_VENV_CLEAR pinned off" + ); + + let created = root.join("created-by-rocm-cli"); + plant_failing_venv_python(&created); + plant_rocm_owned_venv_markers(&created); + ensure_uv_venv(&paths, &uv, &launcher, &created) + .expect("a folder ROCm CLI created is what the refusal recommends"); + assert!(venv_python_path(&created).is_file()); + + assert_eq!(tree_snapshot(&refused), refused_before); + assert!(root.join("sentinel").is_file()); + fs::remove_dir_all(root).ok(); + } + + /// ComfyUI keeps the user's models, workflows and outputs under + /// `/apps/comfyui`, so even a runtime ROCm CLI made carries + /// user data. A rebuild replaces the venv's files and nothing else, and + /// the line it prints names what it kept — checked against the disk. + #[test] + #[cfg(unix)] + fn ensure_uv_venv_rebuilds_an_owned_venv_in_place_and_keeps_comfyui_data() { + let (root, paths) = venv_rebuild_sandbox("owned"); + let install_root = root.join("prefix"); + plant_failing_venv_python(&install_root); + plant_rocm_owned_venv_markers(&install_root); + let site = install_root + .join("lib") + .join("python3.12") + .join("site-packages"); + fs::create_dir_all(&site).unwrap(); + fs::write(site.join("stale.py"), b"old").unwrap(); + std::os::unix::fs::symlink("lib", install_root.join("lib64")).unwrap(); + fs::create_dir_all(install_root.join("include")).unwrap(); + fs::write(install_root.join("CACHEDIR.TAG"), b"Signature").unwrap(); + let models = install_root + .join("apps") + .join("comfyui") + .join("source") + .join("models"); + fs::create_dir_all(&models).unwrap(); + fs::write(models.join("x.safetensors"), b"weights").unwrap(); + let marker_before = fs::read(install_root.join(".rocm-cli-runtime.json")).unwrap(); + let (uv, uv_log) = write_logging_fake_uv(&root); + + PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().clear()); + ensure_uv_venv(&paths, &uv, &cp312_launcher(&root), &install_root) + .expect("a venv ROCm CLI created is rebuilt"); + let printed = PROGRESS_LINE_SINK.with(|sink| sink.borrow().clone()); + + assert_eq!( + fs::read(models.join("x.safetensors")).unwrap(), + b"weights", + "ComfyUI data must survive a venv rebuild" + ); + assert_eq!( + fs::read(install_root.join(".rocm-cli-runtime.json")).unwrap(), + marker_before + ); + assert!(!site.join("stale.py").exists(), "the old venv's files go"); + assert!(fs::symlink_metadata(install_root.join("lib64")).is_err()); + assert!(!install_root.join("include").exists()); + assert!(!install_root.join("CACHEDIR.TAG").exists()); + assert!( + venv_python_path(&install_root).is_file(), + "and a new venv is built" + ); + assert!(root.join("sentinel").is_file()); + + let calls = fs::read_to_string(&uv_log).unwrap(); + assert!( + calls.lines().any(|line| line.starts_with("venv ") + && line.ends_with(" --allow-existing") + && !line.contains("--clear")), + "the rebuild must not let uv clear the folder: {calls}" + ); + assert!( + calls + .lines() + .all(|line| !line.starts_with("UV_VENV_CLEAR=") || line == "UV_VENV_CLEAR=0"), + "uv venv must run with UV_VENV_CLEAR pinned off: {calls}" + ); + + // The printed line and the disk agree on what was kept. + let line = printed + .iter() + .find(|line| line.contains("rebuilding only its venv files")) + .unwrap_or_else(|| panic!("no rebuild line in {printed:?}")); + assert!( + line.contains("kept: .rocm-cli-runtime.json, apps"), + "{line}" + ); + for kept in [".rocm-cli-runtime.json", "apps"] { + assert!(install_root.join(kept).exists(), "{kept} was reported kept"); + } + + fs::remove_dir_all(root).ok(); + } + + /// A venv entry that is a link is unlinked, never followed: `lib64` here + /// points out of the folder, and what it points at is not the venv's. + #[test] + #[cfg(unix)] + fn venv_rebuild_unlinks_a_linked_venv_entry_without_following_it() { + let (root, paths) = venv_rebuild_sandbox("link"); + let install_root = root.join("prefix"); + plant_failing_venv_python(&install_root); + plant_rocm_owned_venv_markers(&install_root); + let outside = root.join("outside-the-prefix"); + fs::create_dir_all(&outside).unwrap(); + fs::write(outside.join("keep.txt"), b"not the venv's").unwrap(); + std::os::unix::fs::symlink(&outside, install_root.join("lib64")).unwrap(); + let (uv, _) = write_logging_fake_uv(&root); + + ensure_uv_venv(&paths, &uv, &cp312_launcher(&root), &install_root).unwrap(); + + assert!(fs::symlink_metadata(install_root.join("lib64")).is_err()); + assert_eq!( + fs::read(outside.join("keep.txt")).unwrap(), + b"not the venv's" + ); + fs::remove_dir_all(root).ok(); + } + + /// A marker copied from another runtime does not make this folder ROCm + /// CLI's: it must name the folder it sits in. + #[test] + #[cfg(unix)] + fn ensure_uv_venv_refuses_a_runtime_marker_that_names_another_folder() { + let (root, paths) = venv_rebuild_sandbox("other-marker"); + let install_root = root.join("prefix"); + plant_failing_venv_python(&install_root); + fs::write(install_root.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); + write_runtime_marker(&install_root, &root.join("elsewhere")); + fs::write(install_root.join("work.txt"), b"mine").unwrap(); + let (uv, uv_log) = write_logging_fake_uv(&root); + let before = tree_snapshot(&install_root); + + let error = ensure_uv_venv(&paths, &uv, &cp312_launcher(&root), &install_root) + .unwrap_err() + .to_string(); + + assert_eq!(tree_snapshot(&install_root), before); + assert!(!uv_log.exists()); + assert!(error.contains("belongs to"), "{error}"); + assert!( + error.contains(&root.join("elsewhere").display().to_string()), + "{error}" + ); + fs::remove_dir_all(root).ok(); + } + + /// The managed runtimes folder is ROCm CLI's own, so a venv there without + /// a manifest yet (an install that failed after `uv venv`) is still + /// rebuilt rather than stranded. + #[test] + #[cfg(unix)] + fn ensure_uv_venv_rebuilds_a_manifestless_venv_in_the_managed_runtimes_folder() { + let (root, paths) = venv_rebuild_sandbox("managed"); + let install_root = managed_runtime_root(&paths, "wheel", "release-wheel-x"); + plant_failing_venv_python(&install_root); + fs::write(install_root.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); + let (uv, _) = write_logging_fake_uv(&root); + + ensure_uv_venv(&paths, &uv, &cp312_launcher(&root), &install_root) + .expect("a venv in the managed runtimes folder is ROCm CLI's"); + assert!(venv_python_path(&install_root).is_file()); + + // The managed folder itself is not a runtime and is never rebuilt. + let wheel_root = paths.data_dir.join("runtimes").join("wheel"); + assert!(!install_root_is_in_managed_wheel_root(&paths, &wheel_root)); + fs::remove_dir_all(root).ok(); + } + + /// The protected-location check runs before ownership is even looked at, + /// on the path as given (it need not exist) and on where it resolves (a + /// link in a user folder that points into a system one). + #[test] + #[cfg(unix)] + fn venv_rebuild_refuses_a_protected_location_by_spelling_and_by_resolution() { + let (root, paths) = venv_rebuild_sandbox("protected"); + + let spelled = Path::new("/usr/share/rocm-cli-venv-rebuild-does-not-exist"); + let error = clear_owned_venv_for_rebuild(&paths, spelled) + .unwrap_err() + .to_string(); + assert!( + error.contains( + "/usr/share/rocm-cli-venv-rebuild-does-not-exist is a protected system location" + ), + "{error}" + ); + + let link = root.join("looks-like-mine"); + std::os::unix::fs::symlink("/usr/share", &link).unwrap(); + let error = clear_owned_venv_for_rebuild(&paths, &link) + .unwrap_err() + .to_string(); + assert!( + error.contains(": /usr/share is a protected system location"), + "{error}" + ); + assert!(error.contains("Nothing was changed"), "{error}"); + assert!(Path::new("/usr/share").is_dir()); + + fs::remove_dir_all(root).ok(); + } + + /// Exhaustive over the shapes a folder can have when the rebuild is + /// triggered: whether it is a venv, what its runtime marker says, whether + /// it sits in the managed runtimes folder, and what non-venv data is in it. + /// The properties: the rebuild happens exactly when the folder is a venv + /// ROCm CLI can show is its own; a refusal changes nothing at all; and a + /// rebuild keeps every planted entry that is not part of the venv. + #[test] + #[cfg(unix)] + fn venv_rebuild_deletes_only_venv_files_and_only_from_an_owned_venv() { + #[derive(Debug, Clone, Copy)] + enum Marker { + Missing, + Garbage, + OtherFolder, + Matching, + } + let mut cases = 0; + for is_venv in [false, true] { + for marker in [ + Marker::Missing, + Marker::Garbage, + Marker::OtherFolder, + Marker::Matching, + ] { + for managed in [false, true] { + for data in ["Documents/thesis.txt", "apps/comfyui/source/models/x"] { + cases += 1; + let (root, paths) = venv_rebuild_sandbox("shapes"); + let install_root = if managed { + managed_runtime_root(&paths, "wheel", "release-wheel-k") + } else { + root.join("prefix") + }; + plant_failing_venv_python(&install_root); + if is_venv { + fs::write(install_root.join("pyvenv.cfg"), "home = /x\n").unwrap(); + fs::create_dir_all(install_root.join("lib")).unwrap(); + } + match marker { + Marker::Missing => {} + Marker::Garbage => { + fs::write(install_root.join(".rocm-cli-runtime.json"), "{}") + .unwrap(); + } + Marker::OtherFolder => { + write_runtime_marker(&install_root, &root.join("other")); + } + Marker::Matching => write_runtime_marker(&install_root, &install_root), + } + let data_path = install_root.join(data); + fs::create_dir_all(data_path.parent().unwrap()).unwrap(); + fs::write(&data_path, b"user data").unwrap(); + let (uv, uv_log) = write_logging_fake_uv(&root); + let launcher = cp312_launcher(&root); + let before = tree_snapshot(&install_root); + let non_venv_before: Vec<_> = before + .iter() + .filter(|(path, _)| { + let rel = path.strip_prefix(&install_root).unwrap(); + rel.components().next().is_some_and(|first| { + !VENV_OWNED_ENTRIES + .contains(&first.as_os_str().to_str().unwrap()) + }) + }) + .cloned() + .collect(); + + let result = ensure_uv_venv(&paths, &uv, &launcher, &install_root); + let shape = format!( + "is_venv={is_venv} marker={marker:?} managed={managed} data={data}" + ); + let owned = is_venv && (matches!(marker, Marker::Matching) || managed); + let after = tree_snapshot(&install_root); + assert!(root.join("sentinel").is_file(), "{shape}"); + if owned { + assert!(result.is_ok(), "{shape}: {result:?}"); + let missing: Vec<_> = non_venv_before + .iter() + .filter(|entry| !after.contains(entry)) + .collect(); + assert!(missing.is_empty(), "{shape}: lost {missing:?}"); + } else { + assert!(result.is_err(), "{shape}: rebuilt a folder it does not own"); + assert_eq!(after, before, "{shape}: a refusal changed the folder"); + assert!(!uv_log.exists(), "{shape}"); + } + fs::remove_dir_all(root).ok(); + } + } + } + } + assert_eq!(cases, 32); + } } diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 0a4aaacc9b..8393fe924b 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -195,6 +195,12 @@ Expected result: 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. +- If the `--prefix` folder already holds a venv whose Python no longer runs, + rocm-cli rebuilds only that venv's own files, and only when it created the + venv (the folder has `pyvenv.cfg` and its `.rocm-cli-runtime.json`). It prints + what it kept, and anything else in the folder, such as `apps/comfyui`, is + still there afterwards. A folder it did not create, such as your home folder + with a broken `~/bin/python`, is refused with nothing changed. - pip installs pinned `rocm`, `torch`, and `torchvision` requirements with exactly one `device-` extra (`rocm` also requests `libraries`, and `devel` only when `--devel` is passed), alongside pinned diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 35be0b0678..5f6c944583 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -634,3 +634,37 @@ Feature: Runtime configuration And a host with no uv and no usable Python When the user previews a wheel SDK install for arch gfx1200 pinned to ROCm 10.0.0 Then the preview says it did not resolve the ROCm 10 package versions, as it says + + # `install sdk --prefix` uses the folder it is given as-is, and rebuilds the + # Python environment in it when the one already there no longer runs. That + # rebuild used to delete the whole folder, whoever made it — reported for a + # home folder whose `~/bin/python` fails `--version`. The install now refuses + # a folder ROCm CLI cannot show it created, and the second half takes the + # refusal's own advice to prove it is a way forward, not a dead end. + # + # No GPU or network: the index is a loopback fixture, and the install pins + # ROCm 10 with an exact arch, the one path whose device payload comes from the + # arch given rather than a probe of the host GPU. A fake uv and Python stand + # in for the real ones, so the install stops at the package step, after the + # decision under test. Linux-only because those fakes and the broken Python + # are shell scripts. + @id:runtime-install-sdk-refuses-unowned-prefix @requires-os:linux + Scenario: runtime-29 - Installing into a home folder with a broken Python refuses rather than deleting it + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + And the user's home folder holds their files and a Python that no longer runs + When the user installs the SDK into their home folder + Then the install refuses to rebuild the home folder and changes nothing in it + When the user installs the SDK into an empty folder instead + Then the install gets past the refusal and creates a Python environment in the empty folder + + # Even a folder ROCm CLI did create holds more than the environment: ComfyUI + # keeps the user's models, workflows and outputs under `apps/comfyui`. A + # rebuild replaces the environment's own files and nothing else, and the line + # it prints names what it kept — asserted together with the disk. Same + # hermetic setup and Linux-only reason as runtime-29. + @id:runtime-install-sdk-rebuild-keeps-comfyui-data @requires-os:linux + Scenario: runtime-30 - Rebuilding a broken environment ROCm CLI created keeps the ComfyUI data in its folder + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + And a folder ROCm CLI installed into holds ComfyUI models and a Python that no longer runs + When the user installs the SDK into the folder ROCm CLI installed into + Then the install rebuilds only the environment's own files and reports keeping the ComfyUI data diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index ed2d54a65d..21b0ee4e7b 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -2141,3 +2141,285 @@ async fn preview_does_not_claim_host_newer(world: &mut E2eWorld) { "the preview claimed an unreadable host ROCm version is newer:\n{preview}" ); } + +// ── Rebuilding a broken environment in an install folder (#533) ───────── +// +// `install sdk --format wheel --prefix ` reuses the folder it is given. +// When the Python already there no longer runs, the install used to delete the +// whole folder and start again, whoever made it. These steps drive that path +// for real, up to and including the rebuild decision, against the loopback +// canonical index (so no network) and an exact `--family` (so no GPU). +// +// A fake `uv` stands in for the real one: it creates a venv on `uv venv` and +// fails everything else, so the install stops at the package step right after +// the decision under test. The fake is a shell script, hence these scenarios +// are Linux-only. + +/// The user's home folder in the reported case: their files beside a +/// `bin/python` that fails `--version`. +const USER_HOME_FOLDER: &str = "user-home"; +/// The folder the refusal tells the user to choose instead. +const EMPTY_INSTALL_FOLDER: &str = "empty-install-folder"; +/// A runtime folder an earlier `install sdk --prefix` created, now holding +/// ComfyUI's models as well as the venv. +const ROCM_CLI_MADE_FOLDER: &str = "rocm-cli-made-prefix"; + +fn install_folder(world: &E2eWorld, name: &str) -> std::path::PathBuf { + let folder = root(world).join(name); + std::fs::create_dir_all(&folder).expect("failed to create install folder"); + // Canonical, because that is the spelling the install resolves `--prefix` + // to and records in its runtime manifest. + folder + .canonicalize() + .expect("failed to canonicalize install folder") +} + +fn write_executable(path: &Path, body: &str) { + write_fixture(path, body); + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)) + .unwrap_or_else(|e| panic!("failed to chmod {}: {e}", path.display())); + } +} + +fn plant_python_that_no_longer_runs(folder: &Path) { + write_executable(&folder.join("bin").join("python"), "#!/bin/sh\nexit 1\n"); +} + +/// Run a real (not `--dry-run`) wheel install into `folder`. +/// +/// Pinned to the ROCm 10 layout with an exact arch because that layout takes +/// its device payload from the arch it is given rather than probing the host +/// GPU, so it reaches the install step on a machine with no GPU. The fake `uv` +/// answers the three calls this path makes: `pip compile` (pins the fixture's +/// versions), `venv` (creates a working interpreter at `$4`), and the package +/// install, which it fails. The fake launcher reports the `cp314` tag that +/// layout requires, so the host's Python version does not matter and no managed +/// Python is bootstrapped over the network. +/// +/// `HOME` is the user's home folder from runtime-29 throughout, so the CLI sees +/// the same home the user would. +fn install_sdk_into(world: &mut E2eWorld, folder: &Path) { + let uv = root(world).join("fake-uv").join("uv"); + write_executable( + &uv, + &format!( + r#"#!/bin/sh +if [ "$1" = pip ] && [ "$2" = compile ]; then + cat > /dev/null + echo rocm=={NEXT_ROCM_VERSION} + echo torch=={NEXT_TORCH_VERSION} + echo torchvision=={NEXT_TORCHVISION_VERSION} + echo torchaudio=={NEXT_TORCHAUDIO_VERSION} + exit 0 +fi +if [ "$1" = venv ] && [ "$2" = --python ]; then + mkdir -p "$4/bin" + printf '#!/bin/sh\necho Python 3.14.0\n' > "$4/bin/python" + chmod +x "$4/bin/python" + echo 'home = /usr/bin' > "$4/pyvenv.cfg" + exit 0 +fi +echo "fake uv: $*" >&2 +exit 1 +"# + ), + ); + let launcher = root(world).join("fake-python").join("python3.14"); + write_executable( + &launcher, + "#!/bin/sh\nif [ \"$1\" = -c ]; then echo cp314; fi\nexit 0\n", + ); + let home = install_folder(world, USER_HOME_FOLDER); + world + .command_env + .push(("ROCM_CLI_UV_BINARY", uv.into_os_string())); + world + .command_env + .push(("ROCM_CLI_PYTHON", launcher.into_os_string())); + world.command_env.push(("HOME", home.into_os_string())); + let prefix = folder.display().to_string(); + preview( + world, + &[ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + NEXT_ROCM_VERSION, + "--prefix", + &prefix, + ], + ); +} + +fn reported(world: &E2eWorld) -> String { + format!( + "{}\n{}", + stdout(world), + world.cli_stderr.as_deref().unwrap_or_default() + ) +} + +#[given("the user's home folder holds their files and a Python that no longer runs")] +async fn home_folder_with_failing_python(world: &mut E2eWorld) { + let home = install_folder(world, USER_HOME_FOLDER); + plant_python_that_no_longer_runs(&home); + write_fixture(&home.join("Documents").join("thesis.txt"), "years of work"); +} + +#[given("a folder ROCm CLI installed into holds ComfyUI models and a Python that no longer runs")] +async fn rocm_cli_folder_with_comfyui_models(world: &mut E2eWorld) { + let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); + plant_python_that_no_longer_runs(&folder); + write_fixture(&folder.join("pyvenv.cfg"), "home = /usr/bin\n"); + write_fixture( + &folder + .join("lib") + .join("python3.12") + .join("site-packages") + .join("stale.py"), + "old", + ); + // What `save_runtime_manifest` writes beside every install it completes. + let marker = serde_json::to_string_pretty(&serde_json::json!({ + "runtime_key": "release-wheel-gfx1200-7-10-0", + "runtime_id": format!("therock-release:{GROUP_FAMILY}"), + "install_root": folder, + })) + .expect("failed to serialize runtime marker"); + write_fixture(&folder.join(".rocm-cli-runtime.json"), &marker); + write_fixture( + &folder + .join("apps") + .join("comfyui") + .join("source") + .join("models") + .join("checkpoint.safetensors"), + "the user's model", + ); +} + +#[when("the user installs the SDK into their home folder")] +async fn install_sdk_into_home(world: &mut E2eWorld) { + let home = install_folder(world, USER_HOME_FOLDER); + install_sdk_into(world, &home); +} + +#[when("the user installs the SDK into an empty folder instead")] +async fn install_sdk_into_empty_folder(world: &mut E2eWorld) { + let empty = install_folder(world, EMPTY_INSTALL_FOLDER); + install_sdk_into(world, &empty); +} + +#[when("the user installs the SDK into the folder ROCm CLI installed into")] +async fn install_sdk_into_rocm_cli_folder(world: &mut E2eWorld) { + let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); + install_sdk_into(world, &folder); +} + +#[then("the install refuses to rebuild the home folder and changes nothing in it")] +async fn install_refuses_home_folder(world: &mut E2eWorld) { + let home = install_folder(world, USER_HOME_FOLDER); + let reported = reported(world); + assert_ne!(world.cli_rc, Some(0), "the install succeeded:\n{reported}"); + assert!( + reported.contains(&format!( + "refusing to rebuild the Python environment at {}", + home.display() + )), + "the refusal did not name the home folder:\n{reported}" + ); + assert!( + reported.contains("Nothing was changed"), + "the refusal did not say nothing was changed:\n{reported}" + ); + // The claim and the disk, together. + assert_eq!( + std::fs::read_to_string(home.join("Documents").join("thesis.txt")).ok(), + Some("years of work".to_owned()), + "the user's file is gone or changed although the install said nothing was changed" + ); + assert_eq!( + std::fs::read_to_string(home.join("bin").join("python")).ok(), + Some("#!/bin/sh\nexit 1\n".to_owned()), + "the user's bin/python is gone or changed" + ); + assert!( + reported.contains("rocm install sdk --prefix "), + "the refusal did not say what to do instead:\n{reported}" + ); +} + +#[then("the install gets past the refusal and creates a Python environment in the empty folder")] +async fn install_proceeds_in_empty_folder(world: &mut E2eWorld) { + let empty = install_folder(world, EMPTY_INSTALL_FOLDER); + let reported = reported(world); + assert!( + !reported.contains("refusing to rebuild"), + "following the refusal's advice was refused again:\n{reported}" + ); + assert!( + empty.join("bin").join("python").is_file(), + "no Python environment was created in the empty folder:\n{reported}" + ); + let home = install_folder(world, USER_HOME_FOLDER); + assert!( + home.join("Documents").join("thesis.txt").is_file(), + "installing elsewhere touched the home folder" + ); +} + +#[then( + "the install rebuilds only the environment's own files and reports keeping the ComfyUI data" +)] +async fn install_rebuilds_and_keeps_comfyui(world: &mut E2eWorld) { + let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); + let reported = reported(world); + let line = format!( + "Existing Python environment at {} no longer runs or does not match the required interpreter; rebuilding only its venv files (kept: .rocm-cli-runtime.json, apps).", + folder.display() + ); + assert!( + reported.contains(&line), + "the install did not report a rebuild that kept the ComfyUI data:\n{reported}" + ); + // The line says `apps` was kept; the disk has to agree. + assert_eq!( + std::fs::read_to_string( + folder + .join("apps") + .join("comfyui") + .join("source") + .join("models") + .join("checkpoint.safetensors") + ) + .ok(), + Some("the user's model".to_owned()), + "the ComfyUI model is gone although the install reported keeping it:\n{reported}" + ); + assert!( + folder.join(".rocm-cli-runtime.json").is_file(), + "the runtime manifest is gone although the install reported keeping it" + ); + assert!( + !folder + .join("lib") + .join("python3.12") + .join("site-packages") + .join("stale.py") + .exists(), + "the old environment's files were not cleared" + ); + assert!( + folder.join("bin").join("python").is_file(), + "no new Python environment was created:\n{reported}" + ); +} From e4bf0adeea3795c6953a31237964a10096e6e2f4 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 6 Oct 2026 13:00:06 +0000 Subject: [PATCH 02/15] fix(therock): route every non-empty install folder through the ownership check Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/python.rs | 735 ++++++++++++++++++++++++-------- 1 file changed, 547 insertions(+), 188 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index b35b607bfa..674efe4e39 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -122,7 +122,6 @@ pub(super) fn ensure_uv_venv( install_root: &Path, ) -> Result<()> { let env_python = venv_python_path(install_root); - let mut rebuilding = false; if env_python.is_file() { let reusable = run_command( &env_python, @@ -141,23 +140,26 @@ pub(super) fn ensure_uv_venv( // resolved version/build date, not on the interpreter), so an existing // venv left over from a lower-tag requirement must not be mistaken for // a compatible one just because it still runs. - // - // The folder itself is never deleted: with `--prefix` it is whatever - // the user named, and even a runtime ROCm CLI created holds data that - // is not the venv's (ComfyUI keeps its models, workflows and outputs - // under `/apps/comfyui`). Only the venv's own parts go. - let kept = clear_owned_venv_for_rebuild(paths, install_root)?; - progress_line(venv_rebuild_line(install_root, &kept)); - rebuilding = true; - } - let mut args = uv_venv_args(python_launcher, install_root); - if rebuilding { - // What is left after clearing is not a venv any more, so uv would - // refuse it as "a directory already exists". `--allow-existing` - // writes the new venv beside it; `--clear` would instead delete the - // whole folder, which is exactly what the clearing step avoids. - args.push("--allow-existing".to_owned()); } + // Anything already in the folder goes through the ownership-checked + // rebuild, not only a folder whose Python is present: a venv with no + // Python (an earlier rebuild that failed part-way, a deleted interpreter) + // handed to a plain `uv venv` is deleted whole by uv 0.7, built over with + // its stale packages by 0.9, and refused for good by 0.10. + // + // The folder itself is never deleted: with `--prefix` it is whatever + // the user named, and even a runtime ROCm CLI created holds data that + // is not the venv's (ComfyUI keeps its models, workflows and outputs + // under `/apps/comfyui`). Only the venv's own parts go. + let rebuilding = match venv_folder_state(paths, install_root)? { + VenvFolder::Empty => false, + VenvFolder::Owned => { + let kept = clear_owned_venv_for_rebuild(paths, install_root)?; + progress_line(venv_rebuild_line(install_root, env_python.is_file(), &kept)); + true + } + }; + let args = uv_venv_command_args(python_launcher, install_root, rebuilding); run_command_with_env( uv, args.iter() @@ -176,6 +178,25 @@ pub(super) fn ensure_uv_venv( Ok(()) } +/// The `uv venv` arguments for an install root, shared by the install and its +/// `--dry-run` preview so the preview shows the command that will run. +/// +/// Over a folder that already has entries, `--allow-existing` is the only +/// form that is safe on every uv: without it uv 0.7 deletes an existing venv +/// whole and uv 0.10 refuses the folder; `--clear` deletes the whole folder. +/// Only a missing or empty folder gets the plain form. +pub(super) fn uv_venv_command_args( + python_launcher: &Path, + install_root: &Path, + folder_has_entries: bool, +) -> Vec { + let mut args = uv_venv_args(python_launcher, install_root); + if folder_has_entries { + args.push("--allow-existing".to_owned()); + } + args +} + /// The environment for `uv venv` into an install root. /// /// `UV_VENV_CLEAR=1` inherited from the user's shell makes uv delete an @@ -194,10 +215,17 @@ fn uv_venv_command_env(paths: &AppPaths) -> Vec<(String, String)> { /// Windows (`Scripts`, `Lib`, `Include`). Clearing these and nothing else is /// what lets a broken venv be rebuilt without taking the rest of its folder. /// +/// `pyvenv.cfg` is first, so a clear that fails part-way (a file it may not +/// delete, a busy one on Windows) never leaves a folder that still looks like +/// a venv with nothing behind it. Whatever it does leave, the next run sends +/// back through [`venv_folder_state`]. +/// /// `share` is deliberately absent: packages install data there, but so can a /// person, and nothing distinguishes the two. A stale `share` costs nothing, /// because the reinstall that follows overwrites what it needs. const VENV_OWNED_ENTRIES: &[&str] = &[ + "pyvenv.cfg", + "CACHEDIR.TAG", "bin", "Scripts", "lib", @@ -205,8 +233,6 @@ const VENV_OWNED_ENTRIES: &[&str] = &[ "Lib", "include", "Include", - "pyvenv.cfg", - "CACHEDIR.TAG", ]; /// The in-tree runtime manifest `save_runtime_manifest` writes beside every @@ -216,6 +242,8 @@ const VENV_OWNED_ENTRIES: &[&str] = &[ #[derive(Debug, Deserialize)] struct RuntimeOwnershipMarker { runtime_key: String, + #[serde(default)] + format: Option, install_root: PathBuf, } @@ -225,41 +253,69 @@ enum MarkerFinding { Missing, Unreadable, NamesOtherFolder(PathBuf), - Matches, + /// A manifest for this folder from a non-wheel install: a tarball + /// extracts its own `bin`, `lib` and `include` here, which are the SDK, + /// not a venv, so they are not the venv's to clear. + OtherFormat(String), + WheelHere, } -/// Clear a venv ROCm CLI owns so `uv venv` can rebuild it, keeping everything -/// in its folder that is not part of the venv. Returns the names that were kept. -/// -/// Refuses, changing nothing, unless the folder is somewhere ROCm CLI may -/// delete from AND it can show the venv is its own: +/// What [`ensure_uv_venv`] may do with an install root. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum VenvFolder { + /// Missing or without a single entry: a plain `uv venv` is safe. + Empty, + /// Has entries, and ROCm CLI can show it made the folder for a wheel + /// runtime: its venv files may be cleared and rebuilt in place. + Owned, +} + +/// Decide, without changing anything, whether a venv may be (re)built in +/// `install_root`. Refuses a folder that has entries unless it is somewhere +/// ROCm CLI may delete from AND it can show it made the folder: /// /// 1. not a protected system location, by its given spelling or by where it /// really resolves (`rocm_core::runtime_install_root_is_protected`); and -/// 2. it has `pyvenv.cfg`, so it is a venv at all, and either ROCm CLI's -/// in-tree runtime manifest naming this very folder, or it sits inside -/// ROCm CLI's own managed runtimes folder. The second case covers an -/// install that failed after creating the venv but before writing its -/// manifest: nobody else puts a venv there. +/// 2. either ROCm CLI's in-tree runtime manifest from a wheel install, +/// naming this very folder, or a place inside ROCm CLI's own managed +/// runtimes folder. The second covers an install that failed after +/// creating the venv but before writing its manifest: nobody else puts a +/// venv there. +/// +/// `pyvenv.cfg` is not a condition. Anyone's venv has one, so it proves +/// nothing about who made it; and a clear that removed it before failing must +/// still be retried. /// /// A `--prefix` folder is used verbatim, so without these checks a home /// directory whose `~/bin/python` fails `--version` was deleted whole. -fn clear_owned_venv_for_rebuild(paths: &AppPaths, install_root: &Path) -> Result> { +fn venv_folder_state(paths: &AppPaths, install_root: &Path) -> Result { + if !folder_has_entries(install_root)? { + return Ok(VenvFolder::Empty); + } refuse_protected_venv_rebuild(install_root)?; - - let has_pyvenv_cfg = install_root.join("pyvenv.cfg").is_file(); let marker = runtime_ownership_marker_finding(install_root); let in_managed_root = install_root_is_in_managed_wheel_root(paths, install_root); - let owned = has_pyvenv_cfg && (marker == MarkerFinding::Matches || in_managed_root); - if !owned { - bail!(unowned_venv_rebuild_refusal( - install_root, - has_pyvenv_cfg, - &marker, - in_managed_root - )); + if marker == MarkerFinding::WheelHere || in_managed_root { + return Ok(VenvFolder::Owned); + } + bail!(unowned_venv_rebuild_refusal(install_root, &marker)) +} + +pub(super) fn folder_has_entries(path: &Path) -> Result { + match fs::read_dir(path) { + Ok(mut entries) => Ok(entries.next().is_some()), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false), + Err(error) => Err(error).with_context(|| format!("failed to read {}", path.display())), } +} +/// Clear the venv files of a folder [`venv_folder_state`] reports as +/// [`VenvFolder::Owned`], keeping everything else. Returns the names kept. +/// Re-checks ownership itself, so no caller can reach the deletes without it. +fn clear_owned_venv_for_rebuild(paths: &AppPaths, install_root: &Path) -> Result> { + if venv_folder_state(paths, install_root)? != VenvFolder::Owned { + return Ok(Vec::new()); + } for name in VENV_OWNED_ENTRIES { remove_venv_entry(&install_root.join(name))?; } @@ -272,10 +328,10 @@ fn clear_owned_venv_for_rebuild(paths: &AppPaths, install_root: &Path) -> Result Ok(kept) } -/// The protected-location half of [`clear_owned_venv_for_rebuild`], checked on -/// the path as given and again on where it really resolves: a link inside the -/// home folder can point into `/usr`, and the lexical check alone answers for -/// the link, not for what a delete would reach. +/// The protected-location half of [`venv_folder_state`], checked on the path +/// as given and again on where it really resolves: a link inside the home +/// folder can point into `/usr`, and the lexical check alone answers for the +/// link, not for what a delete would reach. fn refuse_protected_venv_rebuild(install_root: &Path) -> Result<()> { let resolved = install_root.canonicalize().ok(); let protected = std::iter::once(install_root) @@ -304,10 +360,12 @@ fn runtime_ownership_marker_finding(install_root: &Path) -> MarkerFinding { return MarkerFinding::Unreadable; }; let recorded = normalize_runtime_path_for_host(&marker.install_root); - if paths_name_same_folder(&recorded, install_root) { - MarkerFinding::Matches - } else { - MarkerFinding::NamesOtherFolder(recorded) + if !paths_name_same_folder(&recorded, install_root) { + return MarkerFinding::NamesOtherFolder(recorded); + } + match marker.format.as_deref() { + Some("wheel") => MarkerFinding::WheelHere, + other => MarkerFinding::OtherFormat(other.unwrap_or("unknown").to_owned()), } } @@ -331,34 +389,33 @@ fn install_root_is_in_managed_wheel_root(paths: &AppPaths, install_root: &Path) && !rocm_core::runtime_paths_equivalent(&root, &managed) } -fn unowned_venv_rebuild_refusal( - install_root: &Path, - has_pyvenv_cfg: bool, - marker: &MarkerFinding, - in_managed_root: bool, -) -> String { - let mut found = vec![format!( - "a Python at {} that does not run or does not match", - venv_python_path(install_root).display() - )]; - if !has_pyvenv_cfg { - found.push("no pyvenv.cfg, so it is not a Python virtual environment".to_owned()); - } - match marker { - MarkerFinding::Missing if !in_managed_root => { - found.push("no .rocm-cli-runtime.json from a ROCm CLI install".to_owned()); - } - MarkerFinding::Unreadable if !in_managed_root => { - found.push("a .rocm-cli-runtime.json ROCm CLI cannot read".to_owned()); - } - MarkerFinding::NamesOtherFolder(other) if !in_managed_root => found.push(format!( +fn unowned_venv_rebuild_refusal(install_root: &Path, marker: &MarkerFinding) -> String { + let python = venv_python_path(install_root); + let mut found = vec![if python.is_file() { + format!( + "a Python at {} that does not run or does not match", + python.display() + ) + } else if install_root.join("pyvenv.cfg").is_file() { + format!("pyvenv.cfg but no Python at {}", python.display()) + } else { + "files that are not a Python environment".to_owned() + }]; + found.push(match marker { + MarkerFinding::Missing => "no .rocm-cli-runtime.json from a ROCm CLI install".to_owned(), + MarkerFinding::Unreadable => "a .rocm-cli-runtime.json ROCm CLI cannot read".to_owned(), + MarkerFinding::NamesOtherFolder(other) => format!( "a .rocm-cli-runtime.json that belongs to {}", other.display() - )), - _ => {} - } + ), + MarkerFinding::OtherFormat(format) => { + format!("a .rocm-cli-runtime.json from a {format} install, not a Python environment") + } + // Unreachable for a refusal, but stated rather than hidden. + MarkerFinding::WheelHere => "a .rocm-cli-runtime.json for this folder".to_owned(), + }); format!( - "refusing to rebuild the Python environment at {}: ROCm CLI cannot show it created this folder (found {}), and rebuilding would delete what is in it. Nothing was changed. Choose an empty folder, or one ROCm CLI created, with --prefix, for example `rocm install sdk --prefix `", + "refusing to create the Python environment at {}: the folder is not empty and ROCm CLI cannot show it created it (found {}), so it will not delete or overwrite what is in it. Nothing was changed. Choose an empty folder, or one ROCm CLI created, with --prefix, for example `rocm install sdk --prefix `", install_root.display(), found.join("; ") ) @@ -382,18 +439,34 @@ fn remove_venv_entry(path: &Path) -> Result<()> { /// The progress line for a rebuild, from the same list the rebuild returned, /// so what it says was kept is what is still on disk. -fn venv_rebuild_line(install_root: &Path, kept: &[String]) -> String { +fn venv_rebuild_line(install_root: &Path, had_python: bool, kept: &[String]) -> String { let kept = if kept.is_empty() { "nothing else was in the folder".to_owned() } else { format!("kept: {}", kept.join(", ")) }; + let state = if had_python { + "no longer runs or does not match the required interpreter" + } else { + "is incomplete" + }; format!( - "Existing Python environment at {} no longer runs or does not match the required interpreter; rebuilding only its venv files ({kept}).", + "Existing Python environment at {} {state}; rebuilding only its venv files ({kept}).", install_root.display() ) } +/// The `--dry-run` line for the venv step, from the same decision the +/// install takes, so the preview predicts a refusal instead of showing a +/// command that will not run. +pub(super) fn venv_step_preview(paths: &AppPaths, install_root: &Path) -> String { + match venv_folder_state(paths, install_root) { + Ok(VenvFolder::Empty) => "create a new Python environment in an empty folder".to_owned(), + Ok(VenvFolder::Owned) => "reuse the Python environment ROCm CLI created here if it runs and matches; otherwise rebuild only its venv files and keep everything else in the folder".to_owned(), + Err(error) => format!("the install will refuse this folder: {error}"), + } +} + fn python_venv_args(install_root: &Path) -> Vec { vec![ "-m".to_owned(), @@ -2754,10 +2827,11 @@ exit 1 // ── ensure_uv_venv: rebuilding a broken venv (#533) ───────────── // - // Every case plants a `bin/python` that fails `--version`, the trigger for - // the rebuild, and a sentinel file beside the install root. The oracle is - // the filesystem: a refusal must leave the tree byte-for-byte as it was, - // and a rebuild must leave everything that is not part of the venv. + // The oracle is the filesystem: a refusal must leave the tree + // byte-for-byte as it was, and a rebuild must leave every planted entry + // that is not part of the venv. Expected outcomes and the paths that must + // survive are written out literally rather than derived from the code + // under test, so a change to that code cannot quietly move the goalposts. /// A canonical sandbox with `AppPaths` inside it and a sentinel file /// outside every install root the test will use. @@ -2787,25 +2861,27 @@ exit 1 use std::os::unix::fs::PermissionsExt; let python = venv_python_path(install_root); fs::create_dir_all(python.parent().unwrap()).unwrap(); + let _ = fs::remove_file(&python); fs::write(&python, "#!/bin/sh\nexit 1\n").unwrap(); fs::set_permissions(&python, fs::Permissions::from_mode(0o755)).unwrap(); } /// What `uv venv` and `save_runtime_manifest` leave in a runtime ROCm CLI - /// installed: `pyvenv.cfg` plus the in-tree runtime manifest naming the - /// folder it sits in. + /// installed: `pyvenv.cfg` plus the in-tree runtime manifest of a wheel + /// install naming the folder it sits in. #[cfg(unix)] fn plant_rocm_owned_venv_markers(install_root: &Path) { fs::create_dir_all(install_root).unwrap(); fs::write(install_root.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); - write_runtime_marker(install_root, install_root); + write_runtime_marker(install_root, install_root, "wheel"); } #[cfg(unix)] - fn write_runtime_marker(install_root: &Path, recorded_root: &Path) { + fn write_runtime_marker(install_root: &Path, recorded_root: &Path, format: &str) { let marker = serde_json::json!({ "runtime_key": "release-wheel-gfx120x-7-10-0", "runtime_id": "therock-release:gfx120X-all", + "format": format, "install_root": recorded_root, }); fs::write( @@ -2815,8 +2891,13 @@ exit 1 .unwrap(); } - /// A fake `uv` that records every invocation and, for `venv`, creates a - /// working interpreter at `$4` (the env root `uv_venv_args` passes). + /// A fake `uv` that records every invocation and, for `venv`, behaves the + /// way uv 0.10 does about an existing folder at `$4` (the env root + /// `uv_venv_args` passes): it refuses one with entries unless + /// `--allow-existing` is given, and wipes it on `--clear` or an inherited + /// `UV_VENV_CLEAR=1`. Then it creates a working interpreter there. So a + /// code path that leans on uv to cope with an existing folder fails here + /// the way it would against a real uv. #[cfg(unix)] fn write_logging_fake_uv(dir: &Path) -> (PathBuf, PathBuf) { use std::os::unix::fs::PermissionsExt; @@ -2827,10 +2908,25 @@ exit 1 echo "$@" >> "{log}" echo "UV_VENV_CLEAR=${{UV_VENV_CLEAR-unset}}" >> "{log}" if [ "$1" = "venv" ] && [ "$2" = "--python" ]; then - /bin/mkdir -p "$4/bin" - printf '#!/bin/sh\nif [ "$1" = "-c" ]; then echo cp312; exit 0; fi\necho Python 3.12.10\n' > "$4/bin/python" - /bin/chmod +x "$4/bin/python" - echo "home = /usr/bin" > "$4/pyvenv.cfg" + target="$4" + allow=0; clear=0 + for arg in "$@"; do + [ "$arg" = "--allow-existing" ] && allow=1 + [ "$arg" = "--clear" ] && clear=1 + done + [ "$allow" = 0 ] && [ "${{UV_VENV_CLEAR-}}" = 1 ] && clear=1 + if [ -d "$target" ] && [ -n "$(/bin/ls -A "$target")" ]; then + if [ "$clear" = 1 ]; then + /bin/rm -rf "$target" + elif [ "$allow" = 0 ]; then + echo "error: A directory already exists at: $target" >&2 + exit 2 + fi + fi + /bin/mkdir -p "$target/bin" + printf '#!/bin/sh\nif [ "$1" = "-c" ]; then echo cp312; exit 0; fi\necho Python 3.12.10\n' > "$target/bin/python" + /bin/chmod +x "$target/bin/python" + echo "home = /usr/bin" > "$target/pyvenv.cfg" exit 0 fi exit 1 @@ -2898,8 +2994,17 @@ exit 1 "a refusal must change nothing" ); assert!(!uv_log.exists(), "uv must not run after a refusal"); - assert!(error.contains(&home.display().to_string()), "{error}"); - assert!(error.contains("no pyvenv.cfg"), "{error}"); + assert!( + error.contains(&format!( + "refusing to create the Python environment at {}", + home.display() + )), + "{error}" + ); + assert!( + error.contains("that does not run or does not match"), + "{error}" + ); assert!(error.contains("no .rocm-cli-runtime.json"), "{error}"); assert!(error.contains("Nothing was changed"), "{error}"); assert!( @@ -3039,6 +3144,162 @@ exit 1 fs::remove_dir_all(root).ok(); } + /// A rebuild that fails part-way must not leave a folder the next run + /// treats as fresh. Here a read-only directory inside `lib` stops the + /// clear after `pyvenv.cfg` and `bin` are gone; the next run, with the + /// directory deletable again, has no Python to test, and must still go + /// through the ownership-checked rebuild and `--allow-existing` rather + /// than a plain `uv venv`, which uv 0.7 answers by deleting the folder. + #[test] + #[cfg(unix)] + fn a_rebuild_that_fails_part_way_is_finished_by_the_next_run_keeping_comfyui_data() { + let (root, paths) = venv_rebuild_sandbox("partial"); + let install_root = root.join("prefix"); + let (uv, uv_log) = write_logging_fake_uv(&root); + let launcher = cp312_launcher(&root); + let models = partial_clear_fixture(&install_root); + + let first = ensure_uv_venv(&paths, &uv, &launcher, &install_root); + let locked = install_root.join("lib").join("locked"); + restore_partial_clear_fixture(&install_root, first.is_ok()); + assert_eq!( + fs::read(models.join("x.safetensors")).unwrap(), + b"weights", + "the failed first run must not touch ComfyUI data" + ); + assert!(!install_root.join("pyvenv.cfg").exists()); + assert!(!venv_python_path(&install_root).exists()); + fs::remove_file(&uv_log).ok(); + + PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().clear()); + ensure_uv_venv(&paths, &uv, &launcher, &install_root) + .expect("the next run finishes the rebuild"); + let printed = PROGRESS_LINE_SINK.with(|sink| sink.borrow().clone()); + + assert_eq!(fs::read(models.join("x.safetensors")).unwrap(), b"weights"); + assert!(!locked.exists(), "the rest of the old venv is cleared"); + assert!(venv_python_path(&install_root).is_file()); + let calls = fs::read_to_string(&uv_log).unwrap(); + assert!( + calls + .lines() + .any(|line| line.starts_with("venv ") && line.ends_with(" --allow-existing")), + "the second run must not hand uv a plain `uv venv`: {calls}" + ); + assert!( + printed + .iter() + .any(|line| line.contains("is incomplete; rebuilding only its venv files")), + "{printed:?}" + ); + fs::remove_dir_all(root).ok(); + } + + /// An owned venv with a broken Python, ComfyUI data, and a read-only + /// directory inside `lib` that stops a clear part-way. + #[cfg(unix)] + fn partial_clear_fixture(install_root: &Path) -> PathBuf { + use std::os::unix::fs::PermissionsExt; + plant_failing_venv_python(install_root); + plant_rocm_owned_venv_markers(install_root); + let models = install_root + .join("apps") + .join("comfyui") + .join("source") + .join("models"); + fs::create_dir_all(&models).unwrap(); + fs::write(models.join("x.safetensors"), b"weights").unwrap(); + let locked = install_root.join("lib").join("locked"); + fs::create_dir_all(&locked).unwrap(); + fs::write(locked.join("held.py"), b"held").unwrap(); + fs::set_permissions(&locked, fs::Permissions::from_mode(0o555)).unwrap(); + models + } + + /// Make the read-only directory deletable again. A process that may + /// delete it anyway (root) cleared everything on the first run, so the + /// state a failed clear leaves is built by hand instead. + #[cfg(unix)] + fn restore_partial_clear_fixture(install_root: &Path, first_run_succeeded: bool) { + use std::os::unix::fs::PermissionsExt; + let locked = install_root.join("lib").join("locked"); + if first_run_succeeded { + for name in ["bin", "pyvenv.cfg"] { + let _ = remove_venv_entry(&install_root.join(name)); + } + fs::create_dir_all(&locked).unwrap(); + fs::write(locked.join("held.py"), b"held").unwrap(); + } else { + fs::set_permissions(&locked, fs::Permissions::from_mode(0o755)).unwrap(); + } + } + + /// The same partial-clear sequence against real uv releases, which differ + /// in exactly the way that matters here: given a plain `uv venv` over a + /// leftover venv, 0.7 deletes the folder, 0.9 builds over it, and 0.10 + /// refuses. Opt-in, since CI has no pinned uv set: + /// `ROCM_CLI_TEST_UV_BINARIES=/path/uv-0.7:/path/uv-0.10` plus + /// `ROCM_CLI_TEST_PYTHON=/usr/bin/python3`. + #[test] + #[cfg(unix)] + fn a_partial_clear_is_finished_safely_by_every_listed_real_uv() { + let (Some(binaries), Some(python)) = ( + std::env::var_os("ROCM_CLI_TEST_UV_BINARIES"), + std::env::var_os("ROCM_CLI_TEST_PYTHON"), + ) else { + eprintln!("skipped: set ROCM_CLI_TEST_UV_BINARIES and ROCM_CLI_TEST_PYTHON"); + return; + }; + let python = PathBuf::from(python); + for real_uv in std::env::split_paths(&binaries) { + let (root, paths) = venv_rebuild_sandbox("real-uv"); + let log = root.join("uv-calls.log"); + let uv = root.join("uv"); + fs::write( + &uv, + format!( + "#!/bin/sh\necho \"$@\" >> \"{}\"\nexec \"{}\" \"$@\"\n", + log.display(), + real_uv.display() + ), + ) + .unwrap(); + { + use std::os::unix::fs::PermissionsExt; + fs::set_permissions(&uv, fs::Permissions::from_mode(0o755)).unwrap(); + } + let install_root = root.join("prefix"); + ensure_uv_venv(&paths, &uv, &python, &install_root) + .unwrap_or_else(|e| panic!("{}: initial venv: {e:#}", real_uv.display())); + let models = partial_clear_fixture(&install_root); + + let first = ensure_uv_venv(&paths, &uv, &python, &install_root); + restore_partial_clear_fixture(&install_root, first.is_ok()); + fs::remove_file(&log).ok(); + let second = ensure_uv_venv(&paths, &uv, &python, &install_root); + + let label = real_uv.display(); + assert!(second.is_ok(), "{label}: {second:?}"); + assert_eq!( + fs::read(models.join("x.safetensors")).ok().as_deref(), + Some(&b"weights"[..]), + "{label}: ComfyUI data lost" + ); + assert!( + run_command(&venv_python_path(&install_root), &["--version"], "probe").is_ok(), + "{label}: the rebuilt venv does not run" + ); + let calls = fs::read_to_string(&log).unwrap(); + assert!( + calls + .lines() + .any(|line| line.starts_with("venv ") && line.ends_with(" --allow-existing")), + "{label}: {calls}" + ); + fs::remove_dir_all(root).ok(); + } + } + /// A venv entry that is a link is unlinked, never followed: `lib64` here /// points out of the folder, and what it points at is not the venv's. #[test] @@ -3073,7 +3334,7 @@ exit 1 let install_root = root.join("prefix"); plant_failing_venv_python(&install_root); fs::write(install_root.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); - write_runtime_marker(&install_root, &root.join("elsewhere")); + write_runtime_marker(&install_root, &root.join("elsewhere"), "wheel"); fs::write(install_root.join("work.txt"), b"mine").unwrap(); let (uv, uv_log) = write_logging_fake_uv(&root); let before = tree_snapshot(&install_root); @@ -3114,131 +3375,229 @@ exit 1 fs::remove_dir_all(root).ok(); } - /// The protected-location check runs before ownership is even looked at, - /// on the path as given (it need not exist) and on where it resolves (a - /// link in a user folder that points into a system one). + /// The protected-location check runs before ownership is looked at, on + /// the path as given and on where it resolves. `/proc/self/cwd` is + /// protected only by its spelling (it resolves to this test's working + /// directory); a link to `/usr/share` only by where it resolves. Only + /// `venv_folder_state` is called, which never deletes. #[test] - #[cfg(unix)] + #[cfg(target_os = "linux")] fn venv_rebuild_refuses_a_protected_location_by_spelling_and_by_resolution() { let (root, paths) = venv_rebuild_sandbox("protected"); - let spelled = Path::new("/usr/share/rocm-cli-venv-rebuild-does-not-exist"); - let error = clear_owned_venv_for_rebuild(&paths, spelled) - .unwrap_err() - .to_string(); + let spelled = Path::new("/proc/self/cwd"); + let error = venv_folder_state(&paths, spelled).unwrap_err().to_string(); assert!( - error.contains( - "/usr/share/rocm-cli-venv-rebuild-does-not-exist is a protected system location" - ), + error.contains(": /proc/self/cwd is a protected system location"), "{error}" ); let link = root.join("looks-like-mine"); std::os::unix::fs::symlink("/usr/share", &link).unwrap(); - let error = clear_owned_venv_for_rebuild(&paths, &link) - .unwrap_err() - .to_string(); + let error = venv_folder_state(&paths, &link).unwrap_err().to_string(); assert!( error.contains(": /usr/share is a protected system location"), "{error}" ); assert!(error.contains("Nothing was changed"), "{error}"); - assert!(Path::new("/usr/share").is_dir()); fs::remove_dir_all(root).ok(); } - /// Exhaustive over the shapes a folder can have when the rebuild is - /// triggered: whether it is a venv, what its runtime marker says, whether - /// it sits in the managed runtimes folder, and what non-venv data is in it. - /// The properties: the rebuild happens exactly when the folder is a venv - /// ROCm CLI can show is its own; a refusal changes nothing at all; and a - /// rebuild keeps every planted entry that is not part of the venv. + /// The `--dry-run` preview takes the install's own decision: it names the + /// refusal for a folder the install would refuse, and shows + /// `--allow-existing` for one it would rebuild. + #[test] + #[cfg(unix)] + fn the_dry_run_preview_predicts_what_the_venv_step_will_do() { + let (root, paths) = venv_rebuild_sandbox("preview"); + let launcher = root.join("python3"); + let empty = root.join("missing"); + assert_eq!( + venv_step_preview(&paths, &empty), + "create a new Python environment in an empty folder" + ); + assert!( + !uv_venv_command_args(&launcher, &empty, false) + .contains(&"--allow-existing".to_owned()) + ); + + let home = root.join("home"); + plant_failing_venv_python(&home); + let preview = venv_step_preview(&paths, &home); + assert!( + preview.starts_with("the install will refuse this folder: refusing to create"), + "{preview}" + ); + assert!(home.join("bin").exists(), "a preview changes nothing"); + + let owned = root.join("owned"); + plant_failing_venv_python(&owned); + plant_rocm_owned_venv_markers(&owned); + assert!( + venv_step_preview(&paths, &owned).starts_with("reuse the Python environment"), + "{}", + venv_step_preview(&paths, &owned) + ); + assert!( + venv_python_path(&owned).is_file(), + "a preview changes nothing" + ); + assert!( + uv_venv_command_args(&launcher, &owned, true) + .ends_with(&["--allow-existing".to_owned()]) + ); + fs::remove_dir_all(root).ok(); + } + + /// Every shape a folder can have when `ensure_uv_venv` meets it with + /// entries in it: what is left of a venv, what its runtime marker says, + /// and whether it sits in the managed runtimes folder. The expected + /// outcome of each is written out, not computed, and every case also holds + /// user data at paths listed literally here; a rebuild must keep all of + /// them and a refusal must change nothing. #[test] #[cfg(unix)] - fn venv_rebuild_deletes_only_venv_files_and_only_from_an_owned_venv() { + fn venv_rebuild_deletes_only_venv_files_and_only_from_an_owned_folder() { + #[derive(Debug, Clone, Copy)] + enum Venv { + /// `pyvenv.cfg`, `lib`, and a Python that fails `--version`. + BrokenPython, + /// `pyvenv.cfg` and `lib`, no Python. + NoPython, + /// Only `lib`: a clear that removed `pyvenv.cfg` and `bin` and + /// then failed. + Leftover, + } #[derive(Debug, Clone, Copy)] enum Marker { Missing, Garbage, OtherFolder, - Matching, - } - let mut cases = 0; - for is_venv in [false, true] { - for marker in [ - Marker::Missing, - Marker::Garbage, - Marker::OtherFolder, - Marker::Matching, - ] { - for managed in [false, true] { - for data in ["Documents/thesis.txt", "apps/comfyui/source/models/x"] { - cases += 1; - let (root, paths) = venv_rebuild_sandbox("shapes"); - let install_root = if managed { - managed_runtime_root(&paths, "wheel", "release-wheel-k") - } else { - root.join("prefix") - }; - plant_failing_venv_python(&install_root); - if is_venv { - fs::write(install_root.join("pyvenv.cfg"), "home = /x\n").unwrap(); - fs::create_dir_all(install_root.join("lib")).unwrap(); - } - match marker { - Marker::Missing => {} - Marker::Garbage => { - fs::write(install_root.join(".rocm-cli-runtime.json"), "{}") - .unwrap(); - } - Marker::OtherFolder => { - write_runtime_marker(&install_root, &root.join("other")); - } - Marker::Matching => write_runtime_marker(&install_root, &install_root), - } - let data_path = install_root.join(data); - fs::create_dir_all(data_path.parent().unwrap()).unwrap(); - fs::write(&data_path, b"user data").unwrap(); - let (uv, uv_log) = write_logging_fake_uv(&root); - let launcher = cp312_launcher(&root); - let before = tree_snapshot(&install_root); - let non_venv_before: Vec<_> = before - .iter() - .filter(|(path, _)| { - let rel = path.strip_prefix(&install_root).unwrap(); - rel.components().next().is_some_and(|first| { - !VENV_OWNED_ENTRIES - .contains(&first.as_os_str().to_str().unwrap()) - }) - }) - .cloned() - .collect(); - - let result = ensure_uv_venv(&paths, &uv, &launcher, &install_root); - let shape = format!( - "is_venv={is_venv} marker={marker:?} managed={managed} data={data}" + TarballHere, + WheelHere, + } + #[derive(Debug, Clone, Copy, PartialEq)] + enum Expect { + Rebuilt, + Refused, + } + use Expect::{Rebuilt, Refused}; + use Marker::{Garbage, Missing, OtherFolder, TarballHere, WheelHere}; + use Venv::{BrokenPython, Leftover, NoPython}; + #[rustfmt::skip] + let table = [ + // venv shape marker managed expected + (BrokenPython, Missing, false, Refused), + (BrokenPython, Garbage, false, Refused), + (BrokenPython, OtherFolder, false, Refused), + (BrokenPython, TarballHere, false, Refused), + (BrokenPython, WheelHere, false, Rebuilt), + (BrokenPython, Missing, true, Rebuilt), + (BrokenPython, Garbage, true, Rebuilt), + (BrokenPython, OtherFolder, true, Rebuilt), + (BrokenPython, TarballHere, true, Rebuilt), + (BrokenPython, WheelHere, true, Rebuilt), + (NoPython, Missing, false, Refused), + (NoPython, Garbage, false, Refused), + (NoPython, OtherFolder, false, Refused), + (NoPython, TarballHere, false, Refused), + (NoPython, WheelHere, false, Rebuilt), + (NoPython, Missing, true, Rebuilt), + (NoPython, Garbage, true, Rebuilt), + (NoPython, OtherFolder, true, Rebuilt), + (NoPython, TarballHere, true, Rebuilt), + (NoPython, WheelHere, true, Rebuilt), + (Leftover, Missing, false, Refused), + (Leftover, Garbage, false, Refused), + (Leftover, OtherFolder, false, Refused), + (Leftover, TarballHere, false, Refused), + (Leftover, WheelHere, false, Rebuilt), + (Leftover, Missing, true, Rebuilt), + (Leftover, Garbage, true, Rebuilt), + (Leftover, OtherFolder, true, Rebuilt), + (Leftover, TarballHere, true, Rebuilt), + (Leftover, WheelHere, true, Rebuilt), + ]; + // Never part of a venv, so a rebuild must leave each exactly as it was. + const USER_PATHS: [&str; 4] = [ + "Documents/thesis.txt", + "apps/comfyui/source/models/x", + "share/notes/todo.txt", + "work.py", + ]; + for (venv, marker, managed, expected) in table { + let shape = format!("{venv:?} {marker:?} managed={managed}"); + let (root, paths) = venv_rebuild_sandbox("shapes"); + let install_root = if managed { + managed_runtime_root(&paths, "wheel", "release-wheel-k") + } else { + root.join("prefix") + }; + fs::create_dir_all(install_root.join("lib").join("python3.12")).unwrap(); + fs::write( + install_root.join("lib").join("python3.12").join("stale.py"), + b"old", + ) + .unwrap(); + match venv { + BrokenPython => { + plant_failing_venv_python(&install_root); + fs::write(install_root.join("pyvenv.cfg"), "home = /x\n").unwrap(); + } + NoPython => fs::write(install_root.join("pyvenv.cfg"), "home = /x\n").unwrap(), + Leftover => {} + } + match marker { + Missing => {} + Garbage => fs::write(install_root.join(".rocm-cli-runtime.json"), "{}").unwrap(), + OtherFolder => write_runtime_marker(&install_root, &root.join("other"), "wheel"), + TarballHere => write_runtime_marker(&install_root, &install_root, "tarball"), + WheelHere => write_runtime_marker(&install_root, &install_root, "wheel"), + } + for user_path in USER_PATHS { + let path = install_root.join(user_path); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(&path, format!("user data: {user_path}")).unwrap(); + } + let (uv, uv_log) = write_logging_fake_uv(&root); + let launcher = cp312_launcher(&root); + let before = tree_snapshot(&install_root); + + let result = ensure_uv_venv(&paths, &uv, &launcher, &install_root); + + assert!(root.join("sentinel").is_file(), "{shape}"); + match expected { + Rebuilt => { + assert!(result.is_ok(), "{shape}: {result:?}"); + for user_path in USER_PATHS { + assert_eq!( + fs::read_to_string(install_root.join(user_path)).ok(), + Some(format!("user data: {user_path}")), + "{shape}: lost {user_path}" ); - let owned = is_venv && (matches!(marker, Marker::Matching) || managed); - let after = tree_snapshot(&install_root); - assert!(root.join("sentinel").is_file(), "{shape}"); - if owned { - assert!(result.is_ok(), "{shape}: {result:?}"); - let missing: Vec<_> = non_venv_before - .iter() - .filter(|entry| !after.contains(entry)) - .collect(); - assert!(missing.is_empty(), "{shape}: lost {missing:?}"); - } else { - assert!(result.is_err(), "{shape}: rebuilt a folder it does not own"); - assert_eq!(after, before, "{shape}: a refusal changed the folder"); - assert!(!uv_log.exists(), "{shape}"); - } - fs::remove_dir_all(root).ok(); } + assert!( + !install_root + .join("lib") + .join("python3.12") + .join("stale.py") + .exists(), + "{shape}: the old venv was not cleared" + ); + assert!(venv_python_path(&install_root).is_file(), "{shape}"); + } + Refused => { + assert!(result.is_err(), "{shape}: rebuilt a folder it does not own"); + assert_eq!( + tree_snapshot(&install_root), + before, + "{shape}: a refusal changed the folder" + ); + assert!(!uv_log.exists(), "{shape}"); } } + fs::remove_dir_all(root).ok(); } - assert_eq!(cases, 32); } } From 18cb6069c39d6f8cf73251700f82d8c5014ab77d Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 6 Oct 2026 13:18:15 +0000 Subject: [PATCH 03/15] test(e2e): make the fake uv refuse a non-empty folder and preview the venv step Signed-off-by: Roman Inflianskas --- README.md | 31 ++-- apps/rocm/src/cli.rs | 8 +- apps/rocm/src/therock/python.rs | 13 +- docs/manual-testing.md | 13 +- .../features/runtime_setup.feature | 14 +- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 136 ++++++++++++++---- 6 files changed, 161 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 43d10809da..886ca9d059 100644 --- a/README.md +++ b/README.md @@ -528,18 +528,25 @@ version. An upgrade or downgrade keeps the previous install on disk. Only a same-version reinstall reuses the same root. `--prefix` changes this. The folder you name is used as-is for every version, so -successive installs into one prefix replace each other in place. If the venv -already there no longer runs its own Python, ROCm CLI rebuilds it only when it -can show it created that venv: the folder has `pyvenv.cfg` and either the -`.rocm-cli-runtime.json` a ROCm CLI install writes, naming that folder, or a -place inside ROCm CLI's own managed runtimes folder. The rebuild removes only -the venv's own files (`bin`/`Scripts`, `lib`/`Lib`, `lib64`, `include`, -`pyvenv.cfg`) and keeps everything else in the folder, such as ComfyUI's models, -workflows, and outputs under `apps/comfyui`; the install prints what it kept. -Any other folder, or one in a protected system location, is refused with -nothing changed; choose an empty folder, or one ROCm CLI created, instead. -A `UV_VENV_CLEAR` exported in your shell is ignored when ROCm CLI creates the -venv, so it cannot make uv clear the folder either. +successive installs into one prefix replace each other in place. A venv that +runs and matches is reused. Otherwise, a folder that is missing or empty gets a +new venv, and a folder with anything in it is used only if ROCm CLI can show it +created it: the `.rocm-cli-runtime.json` a wheel install writes, naming that +folder, or a place inside ROCm CLI's own managed runtimes folder. ROCm CLI then +removes only the venv's own files (`pyvenv.cfg`, `CACHEDIR.TAG`, +`bin`/`Scripts`, `lib`/`Lib`, `lib64`, `include`/`Include`), keeps everything +else in the folder, such as ComfyUI's models, workflows, and outputs under +`apps/comfyui`, and prints what it kept. If that clearing stops part-way, the +next install finishes it the same way. Any other non-empty folder, or one in a +protected system location, is refused with nothing changed; choose an empty +folder, or one ROCm CLI created, instead. `--dry-run` reports which of these +will happen. + +ROCm CLI never runs `uv venv` over a folder that has anything in it without +`--allow-existing`, and sets `UV_VENV_CLEAR=0` for that command, so neither +uv's own handling of an existing folder (older uv deletes an existing venv, +newer uv refuses it) nor a `UV_VENV_CLEAR` exported in your shell can clear the +folder. #### ROCm 10 and newer diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 7cd50d4262..d41b1d8b4f 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -789,10 +789,10 @@ rocm install sdk --devel")] format: InstallFormat, /// Full folder path where the ROCm Python environment should be created. /// - /// Use an empty folder or one ROCm CLI created. If the environment - /// already there no longer runs, ROCm CLI rebuilds only its venv files, - /// and only in a folder it can show it created; any other folder is - /// refused with nothing changed. + /// Use an empty folder or one ROCm CLI created. In a folder that is + /// not empty, ROCm CLI reuses a working environment, or rebuilds only + /// its venv files if it can show it created the folder; any other + /// non-empty folder is refused with nothing changed. #[arg(long)] prefix: Option, /// Exact TheRock package version to install. diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 674efe4e39..7b432d68b2 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -154,8 +154,10 @@ pub(super) fn ensure_uv_venv( let rebuilding = match venv_folder_state(paths, install_root)? { VenvFolder::Empty => false, VenvFolder::Owned => { + // Read before the clear, which removes the Python it reports on. + let had_python = env_python.is_file(); let kept = clear_owned_venv_for_rebuild(paths, install_root)?; - progress_line(venv_rebuild_line(install_root, env_python.is_file(), &kept)); + progress_line(venv_rebuild_line(install_root, had_python, &kept)); true } }; @@ -3133,9 +3135,12 @@ exit 1 .iter() .find(|line| line.contains("rebuilding only its venv files")) .unwrap_or_else(|| panic!("no rebuild line in {printed:?}")); - assert!( - line.contains("kept: .rocm-cli-runtime.json, apps"), - "{line}" + assert_eq!( + line, + &format!( + "Existing Python environment at {} no longer runs or does not match the required interpreter; rebuilding only its venv files (kept: .rocm-cli-runtime.json, apps).", + install_root.display() + ) ); for kept in [".rocm-cli-runtime.json", "apps"] { assert!(install_root.join(kept).exists(), "{kept} was reported kept"); diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 8393fe924b..1c9b22d4d3 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -195,12 +195,13 @@ Expected result: 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. -- If the `--prefix` folder already holds a venv whose Python no longer runs, - rocm-cli rebuilds only that venv's own files, and only when it created the - venv (the folder has `pyvenv.cfg` and its `.rocm-cli-runtime.json`). It prints - what it kept, and anything else in the folder, such as `apps/comfyui`, is - still there afterwards. A folder it did not create, such as your home folder - with a broken `~/bin/python`, is refused with nothing changed. +- If the `--prefix` folder already has anything in it and its venv does not + run, rocm-cli rebuilds only that venv's own files, and only in a folder it + created (its `.rocm-cli-runtime.json` from a wheel install names the folder). + It prints what it kept, and anything else in the folder, such as + `apps/comfyui`, is still there afterwards. A folder it did not create, such + as your home folder with a broken `~/bin/python`, is refused with nothing + changed, and `--dry-run` predicts that refusal in its `python_env:` line. - pip installs pinned `rocm`, `torch`, and `torchvision` requirements with exactly one `device-` extra (`rocm` also requests `libraries`, and `devel` only when `--devel` is passed), alongside pinned diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 5f6c944583..d9d4e50c7d 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -640,7 +640,9 @@ Feature: Runtime configuration # rebuild used to delete the whole folder, whoever made it — reported for a # home folder whose `~/bin/python` fails `--version`. The install now refuses # a folder ROCm CLI cannot show it created, and the second half takes the - # refusal's own advice to prove it is a way forward, not a dead end. + # refusal's own advice to prove it is a way forward, not a dead end. The + # `--dry-run` preview comes first and has to predict that refusal, not show a + # command that will not run. # # No GPU or network: the index is a loopback fixture, and the install pins # ROCm 10 with an exact arch, the one path whose device payload comes from the @@ -652,6 +654,8 @@ Feature: Runtime configuration Scenario: runtime-29 - Installing into a home folder with a broken Python refuses rather than deleting it Given a canonical release pip index fixture and a ROCm 10 pip index fixture And the user's home folder holds their files and a Python that no longer runs + When the user previews installing the SDK into their home folder + Then the preview predicts the refusal of the home folder and changes nothing When the user installs the SDK into their home folder Then the install refuses to rebuild the home folder and changes nothing in it When the user installs the SDK into an empty folder instead @@ -660,11 +664,15 @@ Feature: Runtime configuration # Even a folder ROCm CLI did create holds more than the environment: ComfyUI # keeps the user's models, workflows and outputs under `apps/comfyui`. A # rebuild replaces the environment's own files and nothing else, and the line - # it prints names what it kept — asserted together with the disk. Same - # hermetic setup and Linux-only reason as runtime-29. + # it prints names what it kept — asserted together with the disk. The preview + # shows the `uv venv --allow-existing` a rebuild runs. Same hermetic setup and + # Linux-only reason as runtime-29; the fake uv refuses a non-empty folder + # without `--allow-existing` and wipes it on `--clear`, as uv 0.10 does. @id:runtime-install-sdk-rebuild-keeps-comfyui-data @requires-os:linux Scenario: runtime-30 - Rebuilding a broken environment ROCm CLI created keeps the ComfyUI data in its folder Given a canonical release pip index fixture and a ROCm 10 pip index fixture And a folder ROCm CLI installed into holds ComfyUI models and a Python that no longer runs + When the user previews installing the SDK into the folder ROCm CLI installed into + Then the preview shows a rebuild in place that keeps the folder When the user installs the SDK into the folder ROCm CLI installed into Then the install rebuilds only the environment's own files and reports keeping the ComfyUI data diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 21b0ee4e7b..9db121d8ba 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -2152,8 +2152,11 @@ async fn preview_does_not_claim_host_newer(world: &mut E2eWorld) { // // A fake `uv` stands in for the real one: it creates a venv on `uv venv` and // fails everything else, so the install stops at the package step right after -// the decision under test. The fake is a shell script, hence these scenarios -// are Linux-only. +// the decision under test. Like uv 0.10, it refuses a folder with entries +// unless `--allow-existing` is passed, and wipes it on `--clear` or +// `UV_VENV_CLEAR=1`, so an install that leaned on uv to cope with an existing +// folder fails here as it would for real. The fake is a shell script, hence +// these scenarios are Linux-only. /// The user's home folder in the reported case: their files beside a /// `bin/python` that fails `--version`. @@ -2202,6 +2205,10 @@ fn plant_python_that_no_longer_runs(folder: &Path) { /// `HOME` is the user's home folder from runtime-29 throughout, so the CLI sees /// the same home the user would. fn install_sdk_into(world: &mut E2eWorld, folder: &Path) { + run_sdk_install_into(world, folder, false); +} + +fn run_sdk_install_into(world: &mut E2eWorld, folder: &Path, dry_run: bool) { let uv = root(world).join("fake-uv").join("uv"); write_executable( &uv, @@ -2216,10 +2223,24 @@ if [ "$1" = pip ] && [ "$2" = compile ]; then exit 0 fi if [ "$1" = venv ] && [ "$2" = --python ]; then - mkdir -p "$4/bin" - printf '#!/bin/sh\necho Python 3.14.0\n' > "$4/bin/python" - chmod +x "$4/bin/python" - echo 'home = /usr/bin' > "$4/pyvenv.cfg" + target="$4"; allow=0; clear=0 + for arg in "$@"; do + [ "$arg" = --allow-existing ] && allow=1 + [ "$arg" = --clear ] && clear=1 + done + [ "$allow" = 0 ] && [ "${{UV_VENV_CLEAR-}}" = 1 ] && clear=1 + if [ -d "$target" ] && [ -n "$(ls -A "$target")" ]; then + if [ "$clear" = 1 ]; then + rm -rf "$target" + elif [ "$allow" = 0 ]; then + echo "error: A directory already exists at: $target" >&2 + exit 2 + fi + fi + mkdir -p "$target/bin" + printf '#!/bin/sh\necho Python 3.14.0\n' > "$target/bin/python" + chmod +x "$target/bin/python" + echo 'home = /usr/bin' > "$target/pyvenv.cfg" exit 0 fi echo "fake uv: $*" >&2 @@ -2240,24 +2261,37 @@ exit 1 .command_env .push(("ROCM_CLI_PYTHON", launcher.into_os_string())); world.command_env.push(("HOME", home.into_os_string())); + // `command_env` is consumed by each command, so the fixture index the + // `Given` pointed the CLI at has to be named again for every run here, or + // the second command of a scenario resolves the live index instead. + allow_base_overrides(world); + let current = current_pip_base(world); + let next = next_pip_base(world); + world + .command_env + .push(("ROCM_CLI_THEROCK_RELEASE_PIP_BASE", current.into())); + world + .command_env + .push(("ROCM_CLI_THEROCK_NEXT_PIP_BASE", next.into())); let prefix = folder.display().to_string(); - preview( - world, - &[ - "install", - "sdk", - "--channel", - "release", - "--format", - "wheel", - "--family", - RAW_ARCH, - "--version", - NEXT_ROCM_VERSION, - "--prefix", - &prefix, - ], - ); + let mut args = vec![ + "install", + "sdk", + "--channel", + "release", + "--format", + "wheel", + "--family", + RAW_ARCH, + "--version", + NEXT_ROCM_VERSION, + "--prefix", + &prefix, + ]; + if dry_run { + args.push("--dry-run"); + } + preview(world, &args); } fn reported(world: &E2eWorld) -> String { @@ -2292,6 +2326,7 @@ async fn rocm_cli_folder_with_comfyui_models(world: &mut E2eWorld) { let marker = serde_json::to_string_pretty(&serde_json::json!({ "runtime_key": "release-wheel-gfx1200-7-10-0", "runtime_id": format!("therock-release:{GROUP_FAMILY}"), + "format": "wheel", "install_root": folder, })) .expect("failed to serialize runtime marker"); @@ -2319,6 +2354,57 @@ async fn install_sdk_into_empty_folder(world: &mut E2eWorld) { install_sdk_into(world, &empty); } +#[when("the user previews installing the SDK into their home folder")] +async fn preview_sdk_install_into_home(world: &mut E2eWorld) { + let home = install_folder(world, USER_HOME_FOLDER); + run_sdk_install_into(world, &home, true); +} + +#[when("the user previews installing the SDK into the folder ROCm CLI installed into")] +async fn preview_sdk_install_into_rocm_cli_folder(world: &mut E2eWorld) { + let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); + run_sdk_install_into(world, &folder, true); +} + +#[then("the preview predicts the refusal of the home folder and changes nothing")] +async fn preview_predicts_home_refusal(world: &mut E2eWorld) { + let home = install_folder(world, USER_HOME_FOLDER); + let reported = reported(world); + assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); + assert!( + reported.contains(&format!( + "python_env: the install will refuse this folder: refusing to create the Python environment at {}", + home.display() + )), + "the preview did not predict the refusal:\n{reported}" + ); + assert_eq!( + std::fs::read_to_string(home.join("Documents").join("thesis.txt")).ok(), + Some("years of work".to_owned()), + "a preview changed the home folder" + ); + assert!(home.join("bin").join("python").is_file()); +} + +#[then("the preview shows a rebuild in place that keeps the folder")] +async fn preview_shows_rebuild_in_place(world: &mut E2eWorld) { + let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); + let reported = reported(world); + assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); + assert!( + reported.contains("python_env: reuse the Python environment ROCm CLI created here"), + "the preview did not describe the in-place rebuild:\n{reported}" + ); + assert!( + reported.contains(&format!("{} --allow-existing &&", folder.display())), + "the previewed uv venv command is not the one a rebuild runs:\n{reported}" + ); + assert!( + folder.join("lib").is_dir() && folder.join("pyvenv.cfg").is_file(), + "a preview changed the folder" + ); +} + #[when("the user installs the SDK into the folder ROCm CLI installed into")] async fn install_sdk_into_rocm_cli_folder(world: &mut E2eWorld) { let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); @@ -2332,7 +2418,7 @@ async fn install_refuses_home_folder(world: &mut E2eWorld) { assert_ne!(world.cli_rc, Some(0), "the install succeeded:\n{reported}"); assert!( reported.contains(&format!( - "refusing to rebuild the Python environment at {}", + "refusing to create the Python environment at {}", home.display() )), "the refusal did not name the home folder:\n{reported}" @@ -2363,7 +2449,7 @@ async fn install_proceeds_in_empty_folder(world: &mut E2eWorld) { let empty = install_folder(world, EMPTY_INSTALL_FOLDER); let reported = reported(world); assert!( - !reported.contains("refusing to rebuild"), + !reported.contains("refusing to create"), "following the refusal's advice was refused again:\n{reported}" ); assert!( From 3ff2dd719e8d62c2c3ef6b4c39cdbcc4e5d16631 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 6 Oct 2026 13:27:13 +0000 Subject: [PATCH 04/15] test(therock): satisfy items_after_statements in the shape table Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/python.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 7b432d68b2..343cf06a8b 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -3525,7 +3525,7 @@ exit 1 (Leftover, WheelHere, true, Rebuilt), ]; // Never part of a venv, so a rebuild must leave each exactly as it was. - const USER_PATHS: [&str; 4] = [ + let user_paths: [&str; 4] = [ "Documents/thesis.txt", "apps/comfyui/source/models/x", "share/notes/todo.txt", @@ -3560,7 +3560,7 @@ exit 1 TarballHere => write_runtime_marker(&install_root, &install_root, "tarball"), WheelHere => write_runtime_marker(&install_root, &install_root, "wheel"), } - for user_path in USER_PATHS { + for user_path in user_paths { let path = install_root.join(user_path); fs::create_dir_all(path.parent().unwrap()).unwrap(); fs::write(&path, format!("user data: {user_path}")).unwrap(); @@ -3575,7 +3575,7 @@ exit 1 match expected { Rebuilt => { assert!(result.is_ok(), "{shape}: {result:?}"); - for user_path in USER_PATHS { + for user_path in user_paths { assert_eq!( fs::read_to_string(install_root.join(user_path)).ok(), Some(format!("user data: {user_path}")), From 8d8321c69d6c58aa7d787b125c75ec6ea816fe35 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 6 Oct 2026 14:26:56 +0000 Subject: [PATCH 05/15] fix(therock): reuse only a real venv; preview no command for a refused folder A clear that stopped right after pyvenv.cfg left bin/python, a symlink to the base interpreter on Linux. It still ran and reported the right wheel tag, so the next run judged it reusable and installed ROCm and torch into the base Python. Reuse now also needs pyvenv.cfg and the interpreter's sys.prefix to be the install folder, and the clear removes bin first and pyvenv.cfg last again. The dry run printed a uv venv command even for a folder the install would refuse. It now takes the install's own decisions (reuse, fresh, rebuild, refuse) and prints command: none for a refusal. The refusal now says no finished ROCm CLI install was recorded, which is also true of a folder whose install failed before writing its manifest. Signed-off-by: Roman Inflianskas --- README.md | 28 +- apps/rocm/src/cli.rs | 8 +- apps/rocm/src/therock/python.rs | 545 ++++++++++++++---- docs/manual-testing.md | 7 +- .../features/runtime_setup.feature | 4 +- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 11 +- 6 files changed, 454 insertions(+), 149 deletions(-) diff --git a/README.md b/README.md index 886ca9d059..c539703b2f 100644 --- a/README.md +++ b/README.md @@ -528,19 +528,21 @@ version. An upgrade or downgrade keeps the previous install on disk. Only a same-version reinstall reuses the same root. `--prefix` changes this. The folder you name is used as-is for every version, so -successive installs into one prefix replace each other in place. A venv that -runs and matches is reused. Otherwise, a folder that is missing or empty gets a -new venv, and a folder with anything in it is used only if ROCm CLI can show it -created it: the `.rocm-cli-runtime.json` a wheel install writes, naming that -folder, or a place inside ROCm CLI's own managed runtimes folder. ROCm CLI then -removes only the venv's own files (`pyvenv.cfg`, `CACHEDIR.TAG`, -`bin`/`Scripts`, `lib`/`Lib`, `lib64`, `include`/`Include`), keeps everything -else in the folder, such as ComfyUI's models, workflows, and outputs under -`apps/comfyui`, and prints what it kept. If that clearing stops part-way, the -next install finishes it the same way. Any other non-empty folder, or one in a -protected system location, is refused with nothing changed; choose an empty -folder, or one ROCm CLI created, instead. `--dry-run` reports which of these -will happen. +successive installs into one prefix replace each other in place. A venv is +reused when its `pyvenv.cfg` is there and its Python runs as that venv with the +required version. Otherwise, a folder that is missing or empty gets a new venv, +and a folder with anything in it is used only if ROCm CLI can show a ROCm CLI +install was made there: the `.rocm-cli-runtime.json` a finished wheel install +writes, naming that folder, or a place inside ROCm CLI's own managed runtimes +folder. ROCm CLI then removes only the venv's own files (`bin`/`Scripts`, +`lib`/`Lib`, `lib64`, `include`/`Include`, `CACHEDIR.TAG`, `pyvenv.cfg`), +keeps everything else in the folder, such as ComfyUI's models, workflows, and +outputs under `apps/comfyui`, and prints what it kept. If that clearing stops +part-way, the next install sees an incomplete venv and clears it again. Any +other non-empty folder, or one in a protected system location, is refused with +nothing changed; choose an empty folder, or one where a ROCm CLI install +finished, instead. `--dry-run` reports which of these will happen, and prints +`command: none` for a folder the install would refuse. ROCm CLI never runs `uv venv` over a folder that has anything in it without `--allow-existing`, and sets `UV_VENV_CLEAR=0` for that command, so neither diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index d41b1d8b4f..5a8a3f9240 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -789,10 +789,10 @@ rocm install sdk --devel")] format: InstallFormat, /// Full folder path where the ROCm Python environment should be created. /// - /// Use an empty folder or one ROCm CLI created. In a folder that is - /// not empty, ROCm CLI reuses a working environment, or rebuilds only - /// its venv files if it can show it created the folder; any other - /// non-empty folder is refused with nothing changed. + /// Use an empty folder or one where a ROCm CLI install finished. In a + /// folder that is not empty, ROCm CLI reuses a working environment, or + /// rebuilds only its venv files if a ROCm CLI install was recorded + /// there; any other non-empty folder is refused with nothing changed. #[arg(long)] prefix: Option, /// Exact TheRock package version to install. diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 343cf06a8b..bd1cd28c35 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -20,6 +20,7 @@ use super::process::{ }; use super::source::SourceLayout; use super::venv_python_path; +use crate::shell_quote::shell_quote; use anyhow::{Context, Result, bail}; use rocm_core::{ AppPaths, ManagedToolConfig, RocmCliConfig, ensure_uv_binary, managed_tools_dir, @@ -122,24 +123,12 @@ pub(super) fn ensure_uv_venv( install_root: &Path, ) -> Result<()> { let env_python = venv_python_path(install_root); - if env_python.is_file() { - let reusable = run_command( - &env_python, - &["--version"], - "verify existing managed TheRock runtime Python", - ) - .is_ok() - && wheel_compatibility_for_python(&env_python).is_ok_and(|existing| { - wheel_compatibility_for_python(python_launcher) - .is_ok_and(|required| existing.python_tag == required.python_tag) - }); - if reusable { - return Ok(()); - } - // Same `install_root` can be reused across reinstalls (it's keyed on - // resolved version/build date, not on the interpreter), so an existing - // venv left over from a lower-tag requirement must not be mistaken for - // a compatible one just because it still runs. + // Same `install_root` can be reused across reinstalls (it's keyed on + // resolved version/build date, not on the interpreter), so an existing + // venv left over from a lower-tag requirement must not be mistaken for a + // compatible one just because it still runs. + if existing_venv_is_reusable(install_root, python_launcher) { + return Ok(()); } // Anything already in the folder goes through the ownership-checked // rebuild, not only a folder whose Python is present: a venv with no @@ -180,6 +169,37 @@ pub(super) fn ensure_uv_venv( Ok(()) } +/// Whether the venv already in `install_root` can be used as it is. +/// +/// A Python that runs and reports the right wheel tag is not enough. On Linux +/// `bin/python` is a symlink to the base interpreter, and without `pyvenv.cfg` +/// beside it that is exactly what it runs as: same tag, but `sys.prefix` is the +/// base install, so `uv pip install --python /bin/python` would write +/// ROCm and torch into the user's own Python (a pyenv or conda one is +/// writable) and record the runtime as working. So reuse also needs +/// `pyvenv.cfg`, and the interpreter's own `sys.prefix` to be this folder. +fn existing_venv_is_reusable(install_root: &Path, python_launcher: &Path) -> bool { + let env_python = venv_python_path(install_root); + env_python.is_file() + && install_root.join("pyvenv.cfg").is_file() + && run_command( + &env_python, + &["--version"], + "verify existing managed TheRock runtime Python", + ) + .is_ok() + && capture_python_stdout( + &env_python, + "import sys; print(sys.prefix)", + "inspect existing managed TheRock runtime prefix", + ) + .is_ok_and(|prefix| paths_name_same_folder(Path::new(prefix.trim()), install_root)) + && wheel_compatibility_for_python(&env_python).is_ok_and(|existing| { + wheel_compatibility_for_python(python_launcher) + .is_ok_and(|required| existing.python_tag == required.python_tag) + }) +} + /// The `uv venv` arguments for an install root, shared by the install and its /// `--dry-run` preview so the preview shows the command that will run. /// @@ -187,7 +207,7 @@ pub(super) fn ensure_uv_venv( /// form that is safe on every uv: without it uv 0.7 deletes an existing venv /// whole and uv 0.10 refuses the folder; `--clear` deletes the whole folder. /// Only a missing or empty folder gets the plain form. -pub(super) fn uv_venv_command_args( +fn uv_venv_command_args( python_launcher: &Path, install_root: &Path, folder_has_entries: bool, @@ -217,17 +237,17 @@ fn uv_venv_command_env(paths: &AppPaths) -> Vec<(String, String)> { /// Windows (`Scripts`, `Lib`, `Include`). Clearing these and nothing else is /// what lets a broken venv be rebuilt without taking the rest of its folder. /// -/// `pyvenv.cfg` is first, so a clear that fails part-way (a file it may not -/// delete, a busy one on Windows) never leaves a folder that still looks like -/// a venv with nothing behind it. Whatever it does leave, the next run sends -/// back through [`venv_folder_state`]. +/// The interpreter goes first and `pyvenv.cfg` last. A clear that stops +/// part-way (a file it may not delete, a busy one on Windows) then leaves no +/// Python behind, or a Python whose venv is still marked as one; either way the +/// next run cannot mistake it for a working venv +/// ([`existing_venv_is_reusable`]) and sends the folder back through +/// [`venv_folder_state`], which finishes the clear. /// /// `share` is deliberately absent: packages install data there, but so can a /// person, and nothing distinguishes the two. A stale `share` costs nothing, /// because the reinstall that follows overwrites what it needs. const VENV_OWNED_ENTRIES: &[&str] = &[ - "pyvenv.cfg", - "CACHEDIR.TAG", "bin", "Scripts", "lib", @@ -235,6 +255,8 @@ const VENV_OWNED_ENTRIES: &[&str] = &[ "Lib", "include", "Include", + "CACHEDIR.TAG", + "pyvenv.cfg", ]; /// The in-tree runtime manifest `save_runtime_manifest` writes beside every @@ -303,7 +325,7 @@ fn venv_folder_state(paths: &AppPaths, install_root: &Path) -> Result Result { +fn folder_has_entries(path: &Path) -> Result { match fs::read_dir(path) { Ok(mut entries) => Ok(entries.next().is_some()), Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false), @@ -404,7 +426,9 @@ fn unowned_venv_rebuild_refusal(install_root: &Path, marker: &MarkerFinding) -> "files that are not a Python environment".to_owned() }]; found.push(match marker { - MarkerFinding::Missing => "no .rocm-cli-runtime.json from a ROCm CLI install".to_owned(), + MarkerFinding::Missing => { + "no finished ROCm CLI install recorded here (no .rocm-cli-runtime.json)".to_owned() + } MarkerFinding::Unreadable => "a .rocm-cli-runtime.json ROCm CLI cannot read".to_owned(), MarkerFinding::NamesOtherFolder(other) => format!( "a .rocm-cli-runtime.json that belongs to {}", @@ -417,7 +441,7 @@ fn unowned_venv_rebuild_refusal(install_root: &Path, marker: &MarkerFinding) -> MarkerFinding::WheelHere => "a .rocm-cli-runtime.json for this folder".to_owned(), }); format!( - "refusing to create the Python environment at {}: the folder is not empty and ROCm CLI cannot show it created it (found {}), so it will not delete or overwrite what is in it. Nothing was changed. Choose an empty folder, or one ROCm CLI created, with --prefix, for example `rocm install sdk --prefix `", + "refusing to create the Python environment at {}: the folder is not empty and ROCm CLI cannot show it holds a ROCm CLI install (found {}), so it will not delete or overwrite what is in it. Nothing was changed. Choose an empty folder, or one where a ROCm CLI install finished, with --prefix, for example `rocm install sdk --prefix `", install_root.display(), found.join("; ") ) @@ -458,15 +482,47 @@ fn venv_rebuild_line(install_root: &Path, had_python: bool, kept: &[String]) -> ) } -/// The `--dry-run` line for the venv step, from the same decision the -/// install takes, so the preview predicts a refusal instead of showing a -/// command that will not run. -pub(super) fn venv_step_preview(paths: &AppPaths, install_root: &Path) -> String { - match venv_folder_state(paths, install_root) { - Ok(VenvFolder::Empty) => "create a new Python environment in an empty folder".to_owned(), - Ok(VenvFolder::Owned) => "reuse the Python environment ROCm CLI created here if it runs and matches; otherwise rebuild only its venv files and keep everything else in the folder".to_owned(), - Err(error) => format!("the install will refuse this folder: {error}"), +/// The `--dry-run` lines for the venv step and the install command, from the +/// same decisions the install takes: reuse, a fresh venv, a rebuild in place +/// (`--allow-existing`), or a refusal. A refused folder gets no command at +/// all, since nothing would run. Returns `(python_env, command)`. +pub(super) fn dry_run_venv_lines( + paths: &AppPaths, + python_launcher: &Path, + install_root: &Path, + install_args: &[String], +) -> (String, String) { + let display = |args: &[String]| { + args.iter() + .map(|arg| shell_quote(arg)) + .collect::>() + .join(" ") + }; + let install = format!("uv {}", display(install_args)); + if existing_venv_is_reusable(install_root, python_launcher) { + return ( + "reuse the working Python environment already here".to_owned(), + install, + ); } + let (python_env, rebuilding) = match venv_folder_state(paths, install_root) { + Ok(VenvFolder::Empty) => ( + "create a new Python environment in an empty folder".to_owned(), + false, + ), + Ok(VenvFolder::Owned) => ( + "rebuild only the venv files ROCm CLI created here and keep everything else in the folder".to_owned(), + true, + ), + Err(error) => { + return ( + format!("the install will refuse this folder: {error}"), + "none; the install will refuse this folder".to_owned(), + ); + } + }; + let venv = uv_venv_command_args(python_launcher, install_root, rebuilding); + (python_env, format!("uv {} && {install}", display(&venv))) } fn python_venv_args(install_root: &Path) -> Vec { @@ -2897,7 +2953,8 @@ exit 1 /// way uv 0.10 does about an existing folder at `$4` (the env root /// `uv_venv_args` passes): it refuses one with entries unless /// `--allow-existing` is given, and wipes it on `--clear` or an inherited - /// `UV_VENV_CLEAR=1`. Then it creates a working interpreter there. So a + /// `UV_VENV_CLEAR=1`. Then it creates a working interpreter there, which + /// reports `$4` as its `sys.prefix`. So a /// code path that leans on uv to cope with an existing folder fails here /// the way it would against a real uv. #[cfg(unix)] @@ -2926,7 +2983,14 @@ if [ "$1" = "venv" ] && [ "$2" = "--python" ]; then fi fi /bin/mkdir -p "$target/bin" - printf '#!/bin/sh\nif [ "$1" = "-c" ]; then echo cp312; exit 0; fi\necho Python 3.12.10\n' > "$target/bin/python" + cat > "$target/bin/python" < "$target/pyvenv.cfg" exit 0 @@ -3032,7 +3096,7 @@ exit 1 let error = ensure_uv_venv(&paths, &uv, &launcher, &refused) .unwrap_err() .to_string(); - assert!(error.contains("Choose an empty folder, or one ROCm CLI created")); + assert!(error.contains("Choose an empty folder, or one where a ROCm CLI install finished")); let refused_before = tree_snapshot(&refused); let empty = root.join("empty-folder"); @@ -3151,10 +3215,10 @@ exit 1 /// A rebuild that fails part-way must not leave a folder the next run /// treats as fresh. Here a read-only directory inside `lib` stops the - /// clear after `pyvenv.cfg` and `bin` are gone; the next run, with the - /// directory deletable again, has no Python to test, and must still go - /// through the ownership-checked rebuild and `--allow-existing` rather - /// than a plain `uv venv`, which uv 0.7 answers by deleting the folder. + /// clear after `bin` is gone; the next run, with the directory deletable + /// again, has no Python to test, and must still go through the + /// ownership-checked rebuild and `--allow-existing` rather than a plain + /// `uv venv`, which uv 0.7 answers by deleting the folder. #[test] #[cfg(unix)] fn a_rebuild_that_fails_part_way_is_finished_by_the_next_run_keeping_comfyui_data() { @@ -3172,7 +3236,6 @@ exit 1 b"weights", "the failed first run must not touch ComfyUI data" ); - assert!(!install_root.join("pyvenv.cfg").exists()); assert!(!venv_python_path(&install_root).exists()); fs::remove_file(&uv_log).ok(); @@ -3229,9 +3292,8 @@ exit 1 use std::os::unix::fs::PermissionsExt; let locked = install_root.join("lib").join("locked"); if first_run_succeeded { - for name in ["bin", "pyvenv.cfg"] { - let _ = remove_venv_entry(&install_root.join(name)); - } + let _ = remove_venv_entry(&install_root.join("bin")); + fs::write(install_root.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); fs::create_dir_all(&locked).unwrap(); fs::write(locked.join("held.py"), b"held").unwrap(); } else { @@ -3242,7 +3304,9 @@ exit 1 /// The same partial-clear sequence against real uv releases, which differ /// in exactly the way that matters here: given a plain `uv venv` over a /// leftover venv, 0.7 deletes the folder, 0.9 builds over it, and 0.10 - /// refuses. Opt-in, since CI has no pinned uv set: + /// refuses. It then drives every `ClearStop` through the real uv, where a + /// `bin/python` left without `pyvenv.cfg` really does run as the base + /// interpreter. Opt-in, since CI has no pinned uv set: /// `ROCM_CLI_TEST_UV_BINARIES=/path/uv-0.7:/path/uv-0.10` plus /// `ROCM_CLI_TEST_PYTHON=/usr/bin/python3`. #[test] @@ -3301,6 +3365,7 @@ exit 1 .any(|line| line.starts_with("venv ") && line.ends_with(" --allow-existing")), "{label}: {calls}" ); + assert_every_clear_stop_converges(&uv, &log, &python, &label.to_string()); fs::remove_dir_all(root).ok(); } } @@ -3409,58 +3474,224 @@ exit 1 fs::remove_dir_all(root).ok(); } - /// The `--dry-run` preview takes the install's own decision: it names the - /// refusal for a folder the install would refuse, and shows - /// `--allow-existing` for one it would rebuild. + /// The `--dry-run` `python_env:` and `command:` lines `install_wheel_runtime` + /// prints, for each decision the install can take. A refused folder gets + /// no command at all; a rebuild shows `--allow-existing`; a reusable venv + /// shows only the package install. #[test] #[cfg(unix)] - fn the_dry_run_preview_predicts_what_the_venv_step_will_do() { + fn the_dry_run_lines_predict_what_the_venv_step_will_do() { let (root, paths) = venv_rebuild_sandbox("preview"); - let launcher = root.join("python3"); + let launcher = cp312_launcher(&root); + let install_args = vec!["pip".to_owned(), "install".to_owned(), "rocm".to_owned()]; + let venv_command = |folder: &Path| { + format!( + "uv venv --python {} {}", + launcher.display(), + folder.display() + ) + }; + let empty = root.join("missing"); + let (env, command) = dry_run_venv_lines(&paths, &launcher, &empty, &install_args); + assert_eq!(env, "create a new Python environment in an empty folder"); assert_eq!( - venv_step_preview(&paths, &empty), - "create a new Python environment in an empty folder" - ); - assert!( - !uv_venv_command_args(&launcher, &empty, false) - .contains(&"--allow-existing".to_owned()) + command, + format!("{} && uv pip install rocm", venv_command(&empty)) ); let home = root.join("home"); plant_failing_venv_python(&home); - let preview = venv_step_preview(&paths, &home); + let (env, command) = dry_run_venv_lines(&paths, &launcher, &home, &install_args); assert!( - preview.starts_with("the install will refuse this folder: refusing to create"), - "{preview}" + env.starts_with("the install will refuse this folder: refusing to create"), + "{env}" ); + assert_eq!(command, "none; the install will refuse this folder"); assert!(home.join("bin").exists(), "a preview changes nothing"); let owned = root.join("owned"); plant_failing_venv_python(&owned); plant_rocm_owned_venv_markers(&owned); - assert!( - venv_step_preview(&paths, &owned).starts_with("reuse the Python environment"), - "{}", - venv_step_preview(&paths, &owned) + let (env, command) = dry_run_venv_lines(&paths, &launcher, &owned, &install_args); + assert!(env.starts_with("rebuild only the venv files"), "{env}"); + assert_eq!( + command, + format!( + "{} --allow-existing && uv pip install rocm", + venv_command(&owned) + ) ); assert!( venv_python_path(&owned).is_file(), "a preview changes nothing" ); - assert!( - uv_venv_command_args(&launcher, &owned, true) - .ends_with(&["--allow-existing".to_owned()]) - ); + + let working = root.join("working"); + plant_rocm_owned_venv_markers(&working); + plant_working_venv_python(&working, &working); + let (env, command) = dry_run_venv_lines(&paths, &launcher, &working, &install_args); + assert_eq!(env, "reuse the working Python environment already here"); + assert_eq!(command, "uv pip install rocm"); + fs::remove_dir_all(root).ok(); + } + + /// A venv Python that runs, reports the `cp312` tag, and reports `prefix` + /// as its `sys.prefix`, the way a real one does with or without the + /// `pyvenv.cfg` that decides what that prefix really is. + #[cfg(unix)] + fn plant_working_venv_python(install_root: &Path, prefix: &Path) { + use std::os::unix::fs::PermissionsExt; + let python = venv_python_path(install_root); + fs::create_dir_all(python.parent().unwrap()).unwrap(); + let _ = fs::remove_file(&python); + fs::write( + &python, + format!( + "#!/bin/sh\nif [ \"$1\" = \"-c\" ]; then\n case \"$2\" in *sys.prefix*) echo \"{}\" ;; *) echo cp312 ;; esac\n exit 0\nfi\necho Python 3.12.10\n", + prefix.display() + ), + ) + .unwrap(); + fs::set_permissions(&python, fs::Permissions::from_mode(0o755)).unwrap(); + } + + /// Points where a clear of an owned venv can stop, as the states they + /// leave. Each must converge: the next run ends with a working venv whose + /// `pyvenv.cfg` is there and whose `sys.prefix` is the folder, keeps the + /// ComfyUI data, and the run after that reuses it without calling uv. + #[cfg(unix)] + #[derive(Debug, Clone, Copy)] + enum ClearStop { + /// Only `pyvenv.cfg` gone: on Linux the `bin/python` symlink now runs + /// as the base interpreter. + CfgRemoved, + CfgAndCacheTagRemoved, + /// Part of `bin` gone, the interpreter among it. + MidBinPythonRemoved, + /// Part of `bin` gone, the interpreter still there. + MidBinActivateRemoved, + BinRemoved, + } + + #[cfg(unix)] + const CLEAR_STOPS: [ClearStop; 5] = [ + ClearStop::CfgRemoved, + ClearStop::CfgAndCacheTagRemoved, + ClearStop::MidBinPythonRemoved, + ClearStop::MidBinActivateRemoved, + ClearStop::BinRemoved, + ]; + + #[cfg(unix)] + fn apply_clear_stop(install_root: &Path, stop: ClearStop) { + let remove = |name: &str| { + let _ = remove_venv_entry(&install_root.join(name)); + }; + match stop { + ClearStop::CfgRemoved => remove("pyvenv.cfg"), + ClearStop::CfgAndCacheTagRemoved => { + remove("pyvenv.cfg"); + remove("CACHEDIR.TAG"); + } + ClearStop::MidBinPythonRemoved => { + for entry in fs::read_dir(install_root.join("bin")).unwrap() { + let path = entry.unwrap().path(); + if path + .file_name() + .unwrap() + .to_string_lossy() + .starts_with("python") + { + let _ = remove_venv_entry(&path); + } + } + } + ClearStop::MidBinActivateRemoved => { + let _ = remove_venv_entry(&install_root.join("bin").join("activate")); + } + ClearStop::BinRemoved => remove("bin"), + } + } + + /// Drive every [`ClearStop`] through `ensure_uv_venv` with `uv` (which + /// appends its arguments to `log`) and assert convergence. + #[cfg(unix)] + fn assert_every_clear_stop_converges(uv: &Path, log: &Path, launcher: &Path, label: &str) { + for stop in CLEAR_STOPS { + let what = format!("{label} {stop:?}"); + let (root, paths) = venv_rebuild_sandbox("stop"); + let install_root = root.join("prefix"); + ensure_uv_venv(&paths, uv, launcher, &install_root) + .unwrap_or_else(|e| panic!("{what}: initial venv: {e:#}")); + write_runtime_marker(&install_root, &install_root, "wheel"); + fs::write(install_root.join("CACHEDIR.TAG"), b"Signature").unwrap(); + fs::write(install_root.join("bin").join("activate"), b"# activate").unwrap(); + let models = install_root.join("apps").join("comfyui").join("models"); + fs::create_dir_all(&models).unwrap(); + fs::write(models.join("x.safetensors"), b"weights").unwrap(); + apply_clear_stop(&install_root, stop); + + fs::remove_file(log).ok(); + ensure_uv_venv(&paths, uv, launcher, &install_root) + .unwrap_or_else(|e| panic!("{what}: {e:#}")); + assert!( + install_root.join("pyvenv.cfg").is_file(), + "{what}: no pyvenv.cfg" + ); + let prefix = capture_python_stdout( + &venv_python_path(&install_root), + "import sys; print(sys.prefix)", + "probe", + ) + .unwrap_or_else(|e| panic!("{what}: {e:#}")); + assert!( + paths_name_same_folder(Path::new(prefix.trim()), &install_root), + "{what}: the venv Python runs as {prefix}, not as the venv" + ); + assert_eq!( + fs::read(models.join("x.safetensors")).ok().as_deref(), + Some(&b"weights"[..]), + "{what}: ComfyUI data lost" + ); + if let Ok(calls) = fs::read_to_string(log) { + assert!( + calls + .lines() + .filter(|line| line.starts_with("venv ")) + .all(|line| line.ends_with(" --allow-existing")), + "{what}: {calls}" + ); + } + + fs::remove_file(log).ok(); + ensure_uv_venv(&paths, uv, launcher, &install_root) + .unwrap_or_else(|e| panic!("{what}: second run: {e:#}")); + assert!( + !log.exists(), + "{what}: the converged venv was not reused: {:?}", + fs::read_to_string(log) + ); + fs::remove_dir_all(root).ok(); + } + } + + #[test] + #[cfg(unix)] + fn every_point_a_clear_can_stop_at_converges_on_the_next_run() { + let (root, _) = venv_rebuild_sandbox("stops-fake"); + let (uv, log) = write_logging_fake_uv(&root); + let launcher = cp312_launcher(&root); + assert_every_clear_stop_converges(&uv, &log, &launcher, "fake uv"); fs::remove_dir_all(root).ok(); } /// Every shape a folder can have when `ensure_uv_venv` meets it with /// entries in it: what is left of a venv, what its runtime marker says, /// and whether it sits in the managed runtimes folder. The expected - /// outcome of each is written out, not computed, and every case also holds - /// user data at paths listed literally here; a rebuild must keep all of - /// them and a refusal must change nothing. + /// outcome of each is written out, not computed. Every venv-shaped case + /// also holds user data at paths listed literally here; a rebuild must keep + /// all of them, and a refusal or a reuse must change nothing. #[test] #[cfg(unix)] fn venv_rebuild_deletes_only_venv_files_and_only_from_an_owned_folder() { @@ -3468,11 +3699,20 @@ exit 1 enum Venv { /// `pyvenv.cfg`, `lib`, and a Python that fails `--version`. BrokenPython, + /// `lib` and a Python that runs with the right tag, but no + /// `pyvenv.cfg`: on Linux that is the base interpreter. + PythonWithoutCfg, + /// `pyvenv.cfg`, `lib`, and a Python that runs with the right tag + /// but whose `sys.prefix` is another folder. + ForeignPrefix, /// `pyvenv.cfg` and `lib`, no Python. NoPython, - /// Only `lib`: a clear that removed `pyvenv.cfg` and `bin` and - /// then failed. + /// Only `lib`: a clear that removed `bin` and then failed. Leftover, + /// `pyvenv.cfg`, `lib`, and a Python that runs as this venv. + Working, + /// Nothing but this one entry. + Only(&'static str), } #[derive(Debug, Clone, Copy)] enum Marker { @@ -3486,43 +3726,75 @@ exit 1 enum Expect { Rebuilt, Refused, + Reused, } - use Expect::{Rebuilt, Refused}; + use Expect::{Rebuilt, Refused, Reused}; use Marker::{Garbage, Missing, OtherFolder, TarballHere, WheelHere}; - use Venv::{BrokenPython, Leftover, NoPython}; + use Venv::{ + BrokenPython, ForeignPrefix, Leftover, NoPython, Only, PythonWithoutCfg, Working, + }; #[rustfmt::skip] let table = [ - // venv shape marker managed expected - (BrokenPython, Missing, false, Refused), - (BrokenPython, Garbage, false, Refused), - (BrokenPython, OtherFolder, false, Refused), - (BrokenPython, TarballHere, false, Refused), - (BrokenPython, WheelHere, false, Rebuilt), - (BrokenPython, Missing, true, Rebuilt), - (BrokenPython, Garbage, true, Rebuilt), - (BrokenPython, OtherFolder, true, Rebuilt), - (BrokenPython, TarballHere, true, Rebuilt), - (BrokenPython, WheelHere, true, Rebuilt), - (NoPython, Missing, false, Refused), - (NoPython, Garbage, false, Refused), - (NoPython, OtherFolder, false, Refused), - (NoPython, TarballHere, false, Refused), - (NoPython, WheelHere, false, Rebuilt), - (NoPython, Missing, true, Rebuilt), - (NoPython, Garbage, true, Rebuilt), - (NoPython, OtherFolder, true, Rebuilt), - (NoPython, TarballHere, true, Rebuilt), - (NoPython, WheelHere, true, Rebuilt), - (Leftover, Missing, false, Refused), - (Leftover, Garbage, false, Refused), - (Leftover, OtherFolder, false, Refused), - (Leftover, TarballHere, false, Refused), - (Leftover, WheelHere, false, Rebuilt), - (Leftover, Missing, true, Rebuilt), - (Leftover, Garbage, true, Rebuilt), - (Leftover, OtherFolder, true, Rebuilt), - (Leftover, TarballHere, true, Rebuilt), - (Leftover, WheelHere, true, Rebuilt), + // venv shape marker managed expected + (BrokenPython, Missing, false, Refused), + (BrokenPython, Garbage, false, Refused), + (BrokenPython, OtherFolder, false, Refused), + (BrokenPython, TarballHere, false, Refused), + (BrokenPython, WheelHere, false, Rebuilt), + (BrokenPython, Missing, true, Rebuilt), + (BrokenPython, Garbage, true, Rebuilt), + (BrokenPython, OtherFolder, true, Rebuilt), + (BrokenPython, TarballHere, true, Rebuilt), + (BrokenPython, WheelHere, true, Rebuilt), + (PythonWithoutCfg, Missing, false, Refused), + (PythonWithoutCfg, Garbage, false, Refused), + (PythonWithoutCfg, OtherFolder, false, Refused), + (PythonWithoutCfg, TarballHere, false, Refused), + (PythonWithoutCfg, WheelHere, false, Rebuilt), + (PythonWithoutCfg, Missing, true, Rebuilt), + (PythonWithoutCfg, Garbage, true, Rebuilt), + (PythonWithoutCfg, OtherFolder, true, Rebuilt), + (PythonWithoutCfg, TarballHere, true, Rebuilt), + (PythonWithoutCfg, WheelHere, true, Rebuilt), + (ForeignPrefix, Missing, false, Refused), + (ForeignPrefix, Garbage, false, Refused), + (ForeignPrefix, OtherFolder, false, Refused), + (ForeignPrefix, TarballHere, false, Refused), + (ForeignPrefix, WheelHere, false, Rebuilt), + (ForeignPrefix, Missing, true, Rebuilt), + (ForeignPrefix, Garbage, true, Rebuilt), + (ForeignPrefix, OtherFolder, true, Rebuilt), + (ForeignPrefix, TarballHere, true, Rebuilt), + (ForeignPrefix, WheelHere, true, Rebuilt), + (NoPython, Missing, false, Refused), + (NoPython, Garbage, false, Refused), + (NoPython, OtherFolder, false, Refused), + (NoPython, TarballHere, false, Refused), + (NoPython, WheelHere, false, Rebuilt), + (NoPython, Missing, true, Rebuilt), + (NoPython, Garbage, true, Rebuilt), + (NoPython, OtherFolder, true, Rebuilt), + (NoPython, TarballHere, true, Rebuilt), + (NoPython, WheelHere, true, Rebuilt), + (Leftover, Missing, false, Refused), + (Leftover, Garbage, false, Refused), + (Leftover, OtherFolder, false, Refused), + (Leftover, TarballHere, false, Refused), + (Leftover, WheelHere, false, Rebuilt), + (Leftover, Missing, true, Rebuilt), + (Leftover, Garbage, true, Rebuilt), + (Leftover, OtherFolder, true, Rebuilt), + (Leftover, TarballHere, true, Rebuilt), + (Leftover, WheelHere, true, Rebuilt), + // A venv that works is reused wherever it is: nothing is deleted. + (Working, Missing, false, Reused), + (Working, WheelHere, false, Reused), + (Working, Missing, true, Reused), + // A folder that holds anything at all, and no proof ROCm CLI + // made it, is refused, as `main` refuses it. + (Only("README.md"), Missing, false, Refused), + (Only(".DS_Store"), Missing, false, Refused), + (Only(".git"), Missing, false, Refused), ]; // Never part of a venv, so a rebuild must leave each exactly as it was. let user_paths: [&str; 4] = [ @@ -3531,6 +3803,7 @@ exit 1 "share/notes/todo.txt", "work.py", ]; + let elsewhere = Path::new("/usr/local"); for (venv, marker, managed, expected) in table { let shape = format!("{venv:?} {marker:?} managed={managed}"); let (root, paths) = venv_rebuild_sandbox("shapes"); @@ -3539,19 +3812,43 @@ exit 1 } else { root.join("prefix") }; - fs::create_dir_all(install_root.join("lib").join("python3.12")).unwrap(); - fs::write( - install_root.join("lib").join("python3.12").join("stale.py"), - b"old", - ) - .unwrap(); + fs::create_dir_all(&install_root).unwrap(); + let cfg = || fs::write(install_root.join("pyvenv.cfg"), "home = /x\n").unwrap(); + if let Only(entry) = venv { + if entry == ".git" { + fs::create_dir_all(install_root.join(".git").join("objects")).unwrap(); + } else { + fs::write(install_root.join(entry), b"not a venv").unwrap(); + } + } else { + fs::create_dir_all(install_root.join("lib").join("python3.12")).unwrap(); + fs::write( + install_root.join("lib").join("python3.12").join("stale.py"), + b"old", + ) + .unwrap(); + for user_path in user_paths { + let path = install_root.join(user_path); + fs::create_dir_all(path.parent().unwrap()).unwrap(); + fs::write(&path, format!("user data: {user_path}")).unwrap(); + } + } match venv { BrokenPython => { plant_failing_venv_python(&install_root); - fs::write(install_root.join("pyvenv.cfg"), "home = /x\n").unwrap(); + cfg(); } - NoPython => fs::write(install_root.join("pyvenv.cfg"), "home = /x\n").unwrap(), - Leftover => {} + PythonWithoutCfg => plant_working_venv_python(&install_root, &install_root), + ForeignPrefix => { + plant_working_venv_python(&install_root, elsewhere); + cfg(); + } + NoPython => cfg(), + Working => { + plant_working_venv_python(&install_root, &install_root); + cfg(); + } + Leftover | Only(_) => {} } match marker { Missing => {} @@ -3560,11 +3857,6 @@ exit 1 TarballHere => write_runtime_marker(&install_root, &install_root, "tarball"), WheelHere => write_runtime_marker(&install_root, &install_root, "wheel"), } - for user_path in user_paths { - let path = install_root.join(user_path); - fs::create_dir_all(path.parent().unwrap()).unwrap(); - fs::write(&path, format!("user data: {user_path}")).unwrap(); - } let (uv, uv_log) = write_logging_fake_uv(&root); let launcher = cp312_launcher(&root); let before = tree_snapshot(&install_root); @@ -3590,16 +3882,17 @@ exit 1 .exists(), "{shape}: the old venv was not cleared" ); + assert!(install_root.join("pyvenv.cfg").is_file(), "{shape}"); assert!(venv_python_path(&install_root).is_file(), "{shape}"); } - Refused => { - assert!(result.is_err(), "{shape}: rebuilt a folder it does not own"); + Refused | Reused => { + assert_eq!(result.is_ok(), expected == Reused, "{shape}: {result:?}"); assert_eq!( tree_snapshot(&install_root), before, - "{shape}: a refusal changed the folder" + "{shape}: the folder changed" ); - assert!(!uv_log.exists(), "{shape}"); + assert!(!uv_log.exists(), "{shape}: uv ran"); } } fs::remove_dir_all(root).ok(); diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 1c9b22d4d3..cabe87a144 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -196,12 +196,13 @@ Expected result: says a real install would prepare or use a managed Python. - rocm-cli creates or reuses a rocm-cli managed Python venv. - If the `--prefix` folder already has anything in it and its venv does not - run, rocm-cli rebuilds only that venv's own files, and only in a folder it - created (its `.rocm-cli-runtime.json` from a wheel install names the folder). + run, rocm-cli rebuilds only that venv's own files, and only in a folder where + a wheel install finished (its `.rocm-cli-runtime.json` names the folder). It prints what it kept, and anything else in the folder, such as `apps/comfyui`, is still there afterwards. A folder it did not create, such as your home folder with a broken `~/bin/python`, is refused with nothing - changed, and `--dry-run` predicts that refusal in its `python_env:` line. + changed, and `--dry-run` predicts that refusal in its `python_env:` line and + prints `command: none`. - pip installs pinned `rocm`, `torch`, and `torchvision` requirements with exactly one `device-` extra (`rocm` also requests `libraries`, and `devel` only when `--devel` is passed), alongside pinned diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index d9d4e50c7d..a0d6f24815 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -641,8 +641,8 @@ Feature: Runtime configuration # home folder whose `~/bin/python` fails `--version`. The install now refuses # a folder ROCm CLI cannot show it created, and the second half takes the # refusal's own advice to prove it is a way forward, not a dead end. The - # `--dry-run` preview comes first and has to predict that refusal, not show a - # command that will not run. + # `--dry-run` preview comes first: it has to predict that refusal and print + # `command: none`, since the install will run no command. # # No GPU or network: the index is a loopback fixture, and the install pins # ROCm 10 with an exact arch, the one path whose device payload comes from the diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 9db121d8ba..fd1185edda 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -2378,6 +2378,15 @@ async fn preview_predicts_home_refusal(world: &mut E2eWorld) { )), "the preview did not predict the refusal:\n{reported}" ); + // No command for an install that will not run one. + assert!( + reported.contains("command: none; the install will refuse this folder"), + "the preview did not say no command will run:\n{reported}" + ); + assert!( + !reported.contains("command: uv venv"), + "the preview shows a uv venv command the install will never run:\n{reported}" + ); assert_eq!( std::fs::read_to_string(home.join("Documents").join("thesis.txt")).ok(), Some("years of work".to_owned()), @@ -2392,7 +2401,7 @@ async fn preview_shows_rebuild_in_place(world: &mut E2eWorld) { let reported = reported(world); assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); assert!( - reported.contains("python_env: reuse the Python environment ROCm CLI created here"), + reported.contains("python_env: rebuild only the venv files ROCm CLI created here"), "the preview did not describe the in-place rebuild:\n{reported}" ); assert!( From e54540b72e9967a618b967f96113b83e8f90f8f9 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 7 Oct 2026 06:51:52 +0000 Subject: [PATCH 06/15] test(therock): name clear stops without a shared suffix Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/python.rs | 40 +++++++++++++++++---------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index bd1cd28c35..947837cc8c 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -3563,24 +3563,26 @@ exit 1 #[cfg(unix)] #[derive(Debug, Clone, Copy)] enum ClearStop { - /// Only `pyvenv.cfg` gone: on Linux the `bin/python` symlink now runs - /// as the base interpreter. - CfgRemoved, - CfgAndCacheTagRemoved, - /// Part of `bin` gone, the interpreter among it. - MidBinPythonRemoved, - /// Part of `bin` gone, the interpreter still there. - MidBinActivateRemoved, - BinRemoved, + /// Only `pyvenv.cfg` removed: on Linux the `bin/python` symlink now + /// runs as the base interpreter. + Cfg, + /// `pyvenv.cfg` and `CACHEDIR.TAG` removed. + CfgAndCacheTag, + /// Part of `bin` removed, the interpreter among it. + PartOfBinWithPython, + /// Part of `bin` removed, the interpreter still there. + PartOfBinKeepingPython, + /// All of `bin` removed. + WholeBin, } #[cfg(unix)] const CLEAR_STOPS: [ClearStop; 5] = [ - ClearStop::CfgRemoved, - ClearStop::CfgAndCacheTagRemoved, - ClearStop::MidBinPythonRemoved, - ClearStop::MidBinActivateRemoved, - ClearStop::BinRemoved, + ClearStop::Cfg, + ClearStop::CfgAndCacheTag, + ClearStop::PartOfBinWithPython, + ClearStop::PartOfBinKeepingPython, + ClearStop::WholeBin, ]; #[cfg(unix)] @@ -3589,12 +3591,12 @@ exit 1 let _ = remove_venv_entry(&install_root.join(name)); }; match stop { - ClearStop::CfgRemoved => remove("pyvenv.cfg"), - ClearStop::CfgAndCacheTagRemoved => { + ClearStop::Cfg => remove("pyvenv.cfg"), + ClearStop::CfgAndCacheTag => { remove("pyvenv.cfg"); remove("CACHEDIR.TAG"); } - ClearStop::MidBinPythonRemoved => { + ClearStop::PartOfBinWithPython => { for entry in fs::read_dir(install_root.join("bin")).unwrap() { let path = entry.unwrap().path(); if path @@ -3607,10 +3609,10 @@ exit 1 } } } - ClearStop::MidBinActivateRemoved => { + ClearStop::PartOfBinKeepingPython => { let _ = remove_venv_entry(&install_root.join("bin").join("activate")); } - ClearStop::BinRemoved => remove("bin"), + ClearStop::WholeBin => remove("bin"), } } From 393e5c7ca882207006d0acfacdf1ef2a72c939f2 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Wed, 7 Oct 2026 10:59:56 +0000 Subject: [PATCH 07/15] test(therock): pin the order a venv clear removes its entries in The interpreter goes first and pyvenv.cfg last, so a clear that stops part-way never leaves a Python that still looks like a venv. The reuse check now refuses such a Python on its own, so no convergence test fails when the order is reversed; pin the order directly. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/python.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 947837cc8c..a02e185eba 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -3678,6 +3678,29 @@ exit 1 } } + /// The reuse check alone already refuses a Python without `pyvenv.cfg`; + /// this order is the second layer `VENV_OWNED_ENTRIES` documents, and no + /// convergence test can see it because the first layer holds. Pin it here. + #[test] + fn a_clear_removes_the_interpreter_first_and_pyvenv_cfg_last() { + let position = |name: &str| { + VENV_OWNED_ENTRIES + .iter() + .position(|entry| *entry == name) + .unwrap_or_else(|| panic!("{name} is not a venv-owned entry")) + }; + assert_eq!(position("bin"), 0, "{VENV_OWNED_ENTRIES:?}"); + assert!( + position("Scripts") < position("lib"), + "{VENV_OWNED_ENTRIES:?}" + ); + assert_eq!( + VENV_OWNED_ENTRIES.last(), + Some(&"pyvenv.cfg"), + "{VENV_OWNED_ENTRIES:?}" + ); + } + #[test] #[cfg(unix)] fn every_point_a_clear_can_stop_at_converges_on_the_next_run() { From 13338cf0375f07c8ed6c850dc19e502b61329a56 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 9 Nov 2026 16:06:49 +0200 Subject: [PATCH 08/15] test(therock): gate the Unix-only test imports to Unix `managed_runtime_root` and `PROGRESS_LINE_SINK` are imported at the top of the test module, but only `#[cfg(unix)]` tests use them; the tests that run on every platform import the sink in their own bodies. On Windows both imports were unused, which `-D warnings` turns into a failed test build. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/python.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index a02e185eba..4e9388bbcf 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -1367,7 +1367,11 @@ fn python_venv_probe_temp_root() -> Result { #[cfg(test)] mod tests { + // Only the Unix tests use these two; the tests that run on every platform + // import the sink in their own bodies. + #[cfg(unix)] use super::super::managed_runtime_root; + #[cfg(unix)] use super::super::process::PROGRESS_LINE_SINK; use super::*; use crate::test_support::PROCESS_ENV_TEST_LOCK; From 2940fe4105a16e7e8b9af19e9bd00f424efa2ee6 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 9 Nov 2026 16:07:12 +0200 Subject: [PATCH 09/15] fix(therock): run nothing from the install folder in a dry run `install sdk --dry-run` ran `/bin/python` (`--version`, its `sys.prefix` and its wheel tag) to predict whether the venv there would be reused. `install_sdk_dry_run` is a model-callable tool that runs without approval and with a model-chosen `--prefix`, so a folder holding a hostile `bin/python` would be executed by a preview. The preview now decides the venv step from the folder's files only. Where those decide it (no Python, no `pyvenv.cfg`, an empty folder) it prints one outcome as before. Where only running the Python could tell, it says it cannot tell, prints `command:` for reuse and `command_if_rebuilt:` or `refusal_if_not_reused:` for the other outcome. The interpreter search a preview runs stops, without running it, when the Python it would check first (on PATH, or ROCM_CLI_PYTHON) is inside `--prefix`. The previewed `uv venv` carries the `UV_VENV_CLEAR=0` the install pins, and a refusal is printed once, on its own `refusal:` line. Two smaller review findings in the same code: - The refusal and the rebuild line said "does not run or does not match" whatever failed. They now name the condition: no `pyvenv.cfg`, a Python that does not run, a foreign `sys.prefix`, or a wheel-tag mismatch. - Clearing a venv entry treated every `symlink_metadata` error as "already gone". Only `NotFound` does now; any other error stops the clear before `uv venv --allow-existing` runs over a stale entry. Scenario runtime-31 plants a recording Python in a folder holding someone else's venv and checks that the preview runs it zero times; runtime-29 and runtime-30 now check the same of their previews. README, `--help`, docs/testing.md, docs/manual-testing.md and docs/llm-tool-use.md say what the preview does and does not run. Signed-off-by: Roman Inflianskas --- README.md | 38 +- apps/rocm/src/cli.rs | 5 + apps/rocm/src/therock.rs | 4 +- apps/rocm/src/therock/python.rs | 744 +++++++++++++++--- apps/rocm/src/therock/resolve/wheel.rs | 5 +- apps/rocm/src/therock/update.rs | 2 +- apps/rocm/src/therock/wheel_plan.rs | 63 +- docs/llm-tool-use.md | 6 + docs/manual-testing.md | 32 +- docs/testing.md | 27 +- .../features/runtime_setup.feature | 26 +- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 112 ++- 12 files changed, 866 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index c539703b2f..6f52ddd46e 100644 --- a/README.md +++ b/README.md @@ -529,20 +529,30 @@ same-version reinstall reuses the same root. `--prefix` changes this. The folder you name is used as-is for every version, so successive installs into one prefix replace each other in place. A venv is -reused when its `pyvenv.cfg` is there and its Python runs as that venv with the -required version. Otherwise, a folder that is missing or empty gets a new venv, -and a folder with anything in it is used only if ROCm CLI can show a ROCm CLI -install was made there: the `.rocm-cli-runtime.json` a finished wheel install -writes, naming that folder, or a place inside ROCm CLI's own managed runtimes -folder. ROCm CLI then removes only the venv's own files (`bin`/`Scripts`, -`lib`/`Lib`, `lib64`, `include`/`Include`, `CACHEDIR.TAG`, `pyvenv.cfg`), -keeps everything else in the folder, such as ComfyUI's models, workflows, and -outputs under `apps/comfyui`, and prints what it kept. If that clearing stops -part-way, the next install sees an incomplete venv and clears it again. Any -other non-empty folder, or one in a protected system location, is refused with -nothing changed; choose an empty folder, or one where a ROCm CLI install -finished, instead. `--dry-run` reports which of these will happen, and prints -`command: none` for a folder the install would refuse. +reused when its `pyvenv.cfg` is there and its Python runs, reports the required +wheel tag, and reports the folder as its `sys.prefix`. Otherwise, a folder that +is missing or empty gets a new venv, and a folder with anything in it is used +only if ROCm CLI can show a ROCm CLI install was made there: the +`.rocm-cli-runtime.json` a finished wheel install writes, naming that folder, +or a folder inside `runtimes/wheel` in ROCm CLI's data folder, where it puts +wheel runtimes itself. ROCm CLI then removes only the venv's own files +(`bin`/`Scripts`, `lib`/`Lib`, `lib64`, `include`/`Include`, `CACHEDIR.TAG`, +`pyvenv.cfg`), keeps everything else in the folder, such as ComfyUI's models, +workflows, and outputs under `apps/comfyui`, and prints what it kept and which +check the old venv failed. If that clearing stops part-way, the next install +sees an incomplete venv and clears it again. Any other non-empty folder, or one +in a protected system location, is refused with nothing changed, and the +refusal names what it found; choose an empty folder, or one where a ROCm CLI +install finished, instead. + +`--dry-run` runs nothing from the install folder, since the folder can hold any +`bin/python`. It reads the folder's files and reports which of these will +happen, with `command: none` and the install's refusal for a folder the install +would refuse. Whether a folder holding both a Python and `pyvenv.cfg` would be +reused depends on running that Python, so the preview says it cannot tell and +shows both outcomes. If the Python the preview would check first (on `PATH`, or +`ROCM_CLI_PYTHON`) is inside the `--prefix` folder, it stops and says it did not +run it. ROCm CLI never runs `uv venv` over a folder that has anything in it without `--allow-existing`, and sets `UV_VENV_CLEAR=0` for that command, so neither diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 5a8a3f9240..84417cfbfe 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -828,6 +828,11 @@ rocm install sdk --devel")] /// host with no uv installed, the plan marks the package versions it /// would need uv to choose, and everything made from them, as not /// resolved. + /// + /// Runs nothing from the install folder: what happens to a Python + /// environment already there is read from its files, and where only + /// running its Python could tell whether it is reused, the plan says + /// so and shows both outcomes. #[arg(long)] dry_run: bool, /// Approve replacing the current active default ROCm runtime (and diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 75bccb49b5..ed36e3c16a 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -385,7 +385,7 @@ fn install_wheel_runtime( // 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 python = python_for_install(paths, python_requirement, dry_run, prefix.as_deref())?; let wheel_compatibility = python.wheel_compatibility()?; progress_line(format!( "Checking TheRock {} packages for this AMD GPU...", @@ -489,7 +489,7 @@ fn install_wheel_runtime( let mut output = String::new(); write_wheel_plan(&mut output, &plan); if dry_run { - write_dry_run_tail(&mut output, &plan); + write_dry_run_tail(&mut output, &plan, Some(paths)); return Ok(SdkInstallResult::plan(output)); } diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 4e9388bbcf..3f9378417e 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -127,9 +127,9 @@ pub(super) fn ensure_uv_venv( // resolved version/build date, not on the interpreter), so an existing // venv left over from a lower-tag requirement must not be mistaken for a // compatible one just because it still runs. - if existing_venv_is_reusable(install_root, python_launcher) { + let Err(not_reusable) = existing_venv_reuse(install_root, python_launcher) else { return Ok(()); - } + }; // Anything already in the folder goes through the ownership-checked // rebuild, not only a folder whose Python is present: a venv with no // Python (an earlier rebuild that failed part-way, a deleted interpreter) @@ -140,13 +140,11 @@ pub(super) fn ensure_uv_venv( // the user named, and even a runtime ROCm CLI created holds data that // is not the venv's (ComfyUI keeps its models, workflows and outputs // under `/apps/comfyui`). Only the venv's own parts go. - let rebuilding = match venv_folder_state(paths, install_root)? { + let rebuilding = match venv_folder_state(paths, install_root, ¬_reusable)? { VenvFolder::Empty => false, VenvFolder::Owned => { - // Read before the clear, which removes the Python it reports on. - let had_python = env_python.is_file(); - let kept = clear_owned_venv_for_rebuild(paths, install_root)?; - progress_line(venv_rebuild_line(install_root, had_python, &kept)); + let kept = clear_owned_venv_for_rebuild(paths, install_root, ¬_reusable)?; + progress_line(venv_rebuild_line(install_root, ¬_reusable, &kept)); true } }; @@ -169,7 +167,9 @@ pub(super) fn ensure_uv_venv( Ok(()) } -/// Whether the venv already in `install_root` can be used as it is. +/// Whether the venv already in `install_root` can be used as it is: `Ok` when +/// it can, otherwise what was found instead, worded to follow "found" in the +/// refusal and to name the condition that failed, so the user can act on it. /// /// A Python that runs and reports the right wheel tag is not enough. On Linux /// `bin/python` is a symlink to the base interpreter, and without `pyvenv.cfg` @@ -178,26 +178,85 @@ pub(super) fn ensure_uv_venv( /// ROCm and torch into the user's own Python (a pyenv or conda one is /// writable) and record the runtime as working. So reuse also needs /// `pyvenv.cfg`, and the interpreter's own `sys.prefix` to be this folder. -fn existing_venv_is_reusable(install_root: &Path, python_launcher: &Path) -> bool { +/// +/// This runs the folder's Python, so only the install calls it; a `--dry-run` +/// preview reads the folder instead ([`dry_run_venv_plan`]). +fn existing_venv_reuse(install_root: &Path, python_launcher: &Path) -> Result<(), String> { + if let Some(finding) = venv_shape_finding(install_root) { + return Err(finding); + } let env_python = venv_python_path(install_root); - env_python.is_file() - && install_root.join("pyvenv.cfg").is_file() - && run_command( - &env_python, - &["--version"], - "verify existing managed TheRock runtime Python", + if run_command( + &env_python, + &["--version"], + "verify existing managed TheRock runtime Python", + ) + .is_err() + { + return Err(format!( + "a Python at {} that does not run", + env_python.display() + )); + } + let prefix = capture_python_stdout( + &env_python, + "import sys; print(sys.prefix)", + "inspect existing managed TheRock runtime prefix", + ) + .map_err(|_| { + format!( + "a Python at {} that does not report its sys.prefix", + env_python.display() ) - .is_ok() - && capture_python_stdout( - &env_python, - "import sys; print(sys.prefix)", - "inspect existing managed TheRock runtime prefix", + })?; + let prefix = prefix.trim(); + if !paths_name_same_folder(Path::new(prefix), install_root) { + return Err(format!( + "a Python at {} whose sys.prefix is {prefix}, not this folder", + env_python.display() + )); + } + let existing = wheel_compatibility_for_python(&env_python).map_err(|_| { + format!( + "a Python at {} whose wheel tag could not be read", + env_python.display() ) - .is_ok_and(|prefix| paths_name_same_folder(Path::new(prefix.trim()), install_root)) - && wheel_compatibility_for_python(&env_python).is_ok_and(|existing| { - wheel_compatibility_for_python(python_launcher) - .is_ok_and(|required| existing.python_tag == required.python_tag) - }) + })?; + let required = wheel_compatibility_for_python(python_launcher).map_err(|_| { + format!( + "a Python at {} that could not be compared with {}, whose wheel tag could not be read", + env_python.display(), + python_launcher.display() + ) + })?; + if existing.python_tag != required.python_tag { + return Err(format!( + "a Python at {} that reports wheel tag {} where {} is required", + env_python.display(), + existing.python_tag, + required.python_tag + )); + } + Ok(()) +} + +/// What the folder's files alone say against reusing its venv, or `None` when +/// it has both a Python and `pyvenv.cfg`, the shape a reusable venv has. Reads +/// the folder and runs nothing, so a `--dry-run` preview can ask it too: a +/// `Some` here is certain, while `None` leaves the answer to running the +/// Python, which only the install does. +fn venv_shape_finding(install_root: &Path) -> Option { + let python = venv_python_path(install_root); + let has_cfg = install_root.join("pyvenv.cfg").is_file(); + match (python.is_file(), has_cfg) { + (true, true) => None, + (true, false) => Some(format!( + "a Python at {} with no pyvenv.cfg beside it", + python.display() + )), + (false, true) => Some(format!("pyvenv.cfg but no Python at {}", python.display())), + (false, false) => Some("files that are not a Python environment".to_owned()), + } } /// The `uv venv` arguments for an install root, shared by the install and its @@ -312,7 +371,15 @@ enum VenvFolder { /// /// A `--prefix` folder is used verbatim, so without these checks a home /// directory whose `~/bin/python` fails `--version` was deleted whole. -fn venv_folder_state(paths: &AppPaths, install_root: &Path) -> Result { +/// +/// `python_finding` is what was found instead of a reusable venv (see +/// [`existing_venv_reuse`]); a refusal names it. Reads the folder and runs +/// nothing. +fn venv_folder_state( + paths: &AppPaths, + install_root: &Path, + python_finding: &str, +) -> Result { if !folder_has_entries(install_root)? { return Ok(VenvFolder::Empty); } @@ -322,7 +389,11 @@ fn venv_folder_state(paths: &AppPaths, install_root: &Path) -> Result Result { @@ -336,8 +407,12 @@ fn folder_has_entries(path: &Path) -> Result { /// Clear the venv files of a folder [`venv_folder_state`] reports as /// [`VenvFolder::Owned`], keeping everything else. Returns the names kept. /// Re-checks ownership itself, so no caller can reach the deletes without it. -fn clear_owned_venv_for_rebuild(paths: &AppPaths, install_root: &Path) -> Result> { - if venv_folder_state(paths, install_root)? != VenvFolder::Owned { +fn clear_owned_venv_for_rebuild( + paths: &AppPaths, + install_root: &Path, + python_finding: &str, +) -> Result> { + if venv_folder_state(paths, install_root, python_finding)? != VenvFolder::Owned { return Ok(Vec::new()); } for name in VENV_OWNED_ENTRIES { @@ -413,18 +488,12 @@ fn install_root_is_in_managed_wheel_root(paths: &AppPaths, install_root: &Path) && !rocm_core::runtime_paths_equivalent(&root, &managed) } -fn unowned_venv_rebuild_refusal(install_root: &Path, marker: &MarkerFinding) -> String { - let python = venv_python_path(install_root); - let mut found = vec![if python.is_file() { - format!( - "a Python at {} that does not run or does not match", - python.display() - ) - } else if install_root.join("pyvenv.cfg").is_file() { - format!("pyvenv.cfg but no Python at {}", python.display()) - } else { - "files that are not a Python environment".to_owned() - }]; +fn unowned_venv_rebuild_refusal( + install_root: &Path, + python_finding: &str, + marker: &MarkerFinding, +) -> String { + let mut found = vec![python_finding.to_owned()]; found.push(match marker { MarkerFinding::Missing => { "no finished ROCm CLI install recorded here (no .rocm-cli-runtime.json)".to_owned() @@ -449,9 +518,17 @@ fn unowned_venv_rebuild_refusal(install_root: &Path, marker: &MarkerFinding) -> /// Remove one venv entry without following a link out of the folder: `lib64` /// is a symlink to `lib` in a uv venv, and a link must go, not its target. +/// +/// Only an entry that is not there counts as removed. Any other failure to +/// look at it (permissions, I/O) is an error, so a clear that could not see an +/// entry stops instead of handing `uv venv --allow-existing` a stale one. fn remove_venv_entry(path: &Path) -> Result<()> { - let Ok(metadata) = fs::symlink_metadata(path) else { - return Ok(()); + let metadata = match fs::symlink_metadata(path) { + Ok(metadata) => metadata, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()), + Err(error) => { + return Err(error).with_context(|| format!("failed to inspect {}", path.display())); + } }; let result = if metadata.file_type().is_symlink() { fs::remove_file(path).or_else(|_| fs::remove_dir(path)) @@ -465,33 +542,56 @@ fn remove_venv_entry(path: &Path) -> Result<()> { /// The progress line for a rebuild, from the same list the rebuild returned, /// so what it says was kept is what is still on disk. -fn venv_rebuild_line(install_root: &Path, had_python: bool, kept: &[String]) -> String { +/// `python_finding` is the condition that stopped reuse, as +/// [`existing_venv_reuse`] reported it before the clear. +fn venv_rebuild_line(install_root: &Path, python_finding: &str, kept: &[String]) -> String { let kept = if kept.is_empty() { "nothing else was in the folder".to_owned() } else { format!("kept: {}", kept.join(", ")) }; - let state = if had_python { - "no longer runs or does not match the required interpreter" - } else { - "is incomplete" - }; format!( - "Existing Python environment at {} {state}; rebuilding only its venv files ({kept}).", + "Existing Python environment at {} cannot be used as it is (found {python_finding}); rebuilding only its venv files ({kept}).", install_root.display() ) } -/// The `--dry-run` lines for the venv step and the install command, from the -/// same decisions the install takes: reuse, a fresh venv, a rebuild in place -/// (`--allow-existing`), or a refusal. A refused folder gets no command at -/// all, since nothing would run. Returns `(python_env, command)`. -pub(super) fn dry_run_venv_lines( +/// What a `--dry-run` preview prints about the venv step. +#[derive(Debug)] +pub(super) struct DryRunVenvPlan { + /// The `python_env:` line's value. + pub(super) python_env: String, + /// The `key: value` lines printed after `mode: dry-run`, `command` first. + pub(super) lines: Vec<(&'static str, String)>, +} + +/// The `--dry-run` lines for the venv step and the install command. +/// +/// A preview runs nothing from the install folder. `install_sdk_dry_run` is a +/// model-callable tool that runs without approval and takes a model-chosen +/// `--prefix`, so a folder holding a hostile `bin/python` (a downloaded or +/// cloned tree) must not be executed by it. So this reads the folder and stops +/// there: [`venv_shape_finding`] and [`venv_folder_state`] only look at files. +/// +/// What only running the folder's Python could tell, whether a venv-shaped +/// folder is reused, it says it could not tell, and prints what happens either +/// way: `command` for reuse, and `command_if_rebuilt` or +/// `refusal_if_not_reused` for the other outcome. Where the files decide alone +/// it prints one outcome: a fresh venv, a rebuild in place (`--allow-existing`, +/// after removing the venv's own entries, which the command does not show), or +/// a refusal, which gets no command at all since nothing would run. +/// +/// The commands carry `UV_VENV_CLEAR=0`, which the install pins for `uv venv`, +/// and every argument is shell-quoted: the install root comes from a +/// `--prefix` the assistant can choose, and the line is one a user is invited +/// to paste. +pub(super) fn dry_run_venv_plan( paths: &AppPaths, - python_launcher: &Path, + venv_python_arg: &Path, install_root: &Path, + required_tag: &str, install_args: &[String], -) -> (String, String) { +) -> DryRunVenvPlan { let display = |args: &[String]| { args.iter() .map(|arg| shell_quote(arg)) @@ -499,30 +599,65 @@ pub(super) fn dry_run_venv_lines( .join(" ") }; let install = format!("uv {}", display(install_args)); - if existing_venv_is_reusable(install_root, python_launcher) { - return ( - "reuse the working Python environment already here".to_owned(), - install, - ); - } - let (python_env, rebuilding) = match venv_folder_state(paths, install_root) { - Ok(VenvFolder::Empty) => ( - "create a new Python environment in an empty folder".to_owned(), - false, - ), - Ok(VenvFolder::Owned) => ( - "rebuild only the venv files ROCm CLI created here and keep everything else in the folder".to_owned(), - true, - ), - Err(error) => { - return ( - format!("the install will refuse this folder: {error}"), - "none; the install will refuse this folder".to_owned(), - ); - } + let with_venv = |rebuilding: bool| { + format!( + "UV_VENV_CLEAR=0 uv {} && uv {}", + display(&uv_venv_command_args( + venv_python_arg, + install_root, + rebuilding + )), + display(install_args) + ) }; - let venv = uv_venv_command_args(python_launcher, install_root, rebuilding); - (python_env, format!("uv {} && {install}", display(&venv))) + let cleared = VENV_OWNED_ENTRIES.join(", "); + let shape = venv_shape_finding(install_root); + let finding = shape.clone().unwrap_or_else(|| { + format!( + "a Python at {} that this preview did not run", + venv_python_path(install_root).display() + ) + }); + let reuse = format!( + "reuse the Python environment here if its Python runs, reports wheel tag {required_tag} and has this folder as its sys.prefix; this preview runs nothing from the folder, so it cannot tell whether it does" + ); + let rebuild = format!( + "rebuild only the venv files ROCm CLI created here: remove {cleared} first, which the command does not show, then create the venv with --allow-existing; everything else in the folder is kept" + ); + match (shape, venv_folder_state(paths, install_root, &finding)) { + (_, Ok(VenvFolder::Empty)) => DryRunVenvPlan { + python_env: "create a new Python environment in an empty folder".to_owned(), + lines: vec![("command", with_venv(false))], + }, + (Some(found), Ok(VenvFolder::Owned)) => DryRunVenvPlan { + python_env: format!("{rebuild} (found {found})"), + lines: vec![("command", with_venv(true))], + }, + (None, Ok(VenvFolder::Owned)) => DryRunVenvPlan { + python_env: format!("{reuse}; if not, {rebuild}"), + lines: vec![ + ("command", install), + ("command_if_rebuilt", with_venv(true)), + ], + }, + (Some(_), Err(refusal)) => DryRunVenvPlan { + python_env: "the install will refuse this folder".to_owned(), + lines: vec![ + ( + "command", + "none; the install will refuse this folder".to_owned(), + ), + ("refusal", format!("{refusal:#}")), + ], + }, + (None, Err(refusal)) => DryRunVenvPlan { + python_env: format!("{reuse}; if not, the install will refuse this folder"), + lines: vec![ + ("command", install), + ("refusal_if_not_reused", format!("{refusal:#}")), + ], + }, + } } fn python_venv_args(install_root: &Path) -> Vec { @@ -867,13 +1002,18 @@ pub(super) fn resolve_python_launcher( /// 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. +/// +/// `prefix` is the `--prefix` the install was given. A preview runs nothing +/// from it, so an interpreter the search would have to run from inside it +/// refuses the preview instead (see [`refuse_preview_python_in_prefix`]). pub(super) fn python_for_install( paths: &AppPaths, requirement: PythonRequirement, dry_run: bool, + prefix: Option<&Path>, ) -> Result { let python = if dry_run { - plan_python_launcher(paths, requirement)? + plan_python_launcher(paths, requirement, prefix)? } else { PlannedPython::Ready(resolve_python_launcher(paths, requirement)?) }; @@ -897,17 +1037,20 @@ pub(super) fn python_for_install( pub(super) fn plan_python_launcher( paths: &AppPaths, requirement: PythonRequirement, + prefix: Option<&Path>, ) -> Result { let env = python_resolver_env_override().unwrap_or_else(PythonResolverEnv::from_process_env); - plan_python_launcher_in(paths, &env, requirement) + plan_python_launcher_in(paths, &env, requirement, prefix) } fn plan_python_launcher_in( paths: &AppPaths, env: &PythonResolverEnv, requirement: PythonRequirement, + prefix: Option<&Path>, ) -> Result { - let lookup = find_python_launcher_in(paths, env, requirement, LookupPurpose::Preview)?; + let lookup = + find_python_launcher_in(paths, env, requirement, LookupPurpose::Preview { prefix })?; Ok(match lookup { PythonLookup::Found(launcher) => PlannedPython::Ready(launcher), PythonLookup::NeedsManagedBootstrap => { @@ -1117,13 +1260,51 @@ 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. +/// +/// A preview also carries the install's `--prefix`, from which it runs nothing. #[derive(Clone, Copy, Debug)] -enum LookupPurpose { +enum LookupPurpose<'a> { Install, - Preview, + Preview { prefix: Option<&'a Path> }, } -impl LookupPurpose { +impl LookupPurpose<'_> { + /// Refuses a preview whose search would next run `candidate` (found + /// through `source`) from inside the install's `--prefix`. + /// + /// A preview runs nothing from the install folder: `install_sdk_dry_run` + /// is a model-callable tool with a model-chosen `--prefix`, and a folder + /// can hold a hostile `bin/python`. The search runs each interpreter it + /// meets, and skipping one would make the preview name a different + /// interpreter from the one the install would pick, so it stops and says + /// why instead. The interpreter's own folder is resolved but not the + /// interpreter: a venv's `bin/python` links to the base Python, and run + /// through that link it still reads the venv's `pyvenv.cfg` and imports + /// from its `site-packages`. An install is not affected. + fn refuse_preview_python_in_prefix(self, candidate: &Path, source: &str) -> Result<()> { + let Self::Preview { + prefix: Some(prefix), + } = self + else { + return Ok(()); + }; + let location = match (candidate.parent(), candidate.file_name()) { + (Some(parent), Some(name)) if !parent.as_os_str().is_empty() => { + rocm_core::resolve_path_through_symlinks(parent).join(name) + } + _ => return Ok(()), + }; + let prefix = rocm_core::resolve_path_through_symlinks(prefix); + if rocm_core::runtime_path_is_same_or_inside(&location, &prefix) { + bail!( + "this preview did not check the Python from {source} at {}: it is inside the install folder {}, and a preview runs nothing from the install folder. A real install would run it. Preview again with that Python out of the way (off PATH, or ROCM_CLI_PYTHON unset), or choose another --prefix", + candidate.display(), + prefix.display() + ); + } + Ok(()) + } + /// 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. @@ -1139,7 +1320,7 @@ impl LookupPurpose { ); match self { Self::Install => format!("{finding}; {install_next_step}."), - Self::Preview => format!("{finding}."), + Self::Preview { .. } => format!("{finding}."), } } } @@ -1172,9 +1353,24 @@ fn find_python_launcher_in( paths: &AppPaths, env: &PythonResolverEnv, requirement: PythonRequirement, - purpose: LookupPurpose, + purpose: LookupPurpose<'_>, ) -> Result { if let Some(value) = env.python_override.as_deref() { + // A bare name is run through `PATH`, so it is checked where it resolves. + let named = Path::new(value); + let runs = if named + .parent() + .is_some_and(|parent| !parent.as_os_str().is_empty()) + { + Some(named.to_path_buf()) + } else { + resolve_program_on_path(value, &env.search_dirs) + .into_iter() + .next() + }; + if let Some(runs) = runs.as_deref() { + purpose.refuse_preview_python_in_prefix(runs, "ROCM_CLI_PYTHON")?; + } python_launcher_install_ready(Path::new(value), requirement) .with_context(|| format!("ROCM_CLI_PYTHON is not usable for ROCm setup: {value}"))?; return Ok(PythonLookup::Found(PythonLauncher { @@ -1185,6 +1381,7 @@ fn find_python_launcher_in( let mut skipped_path_python = false; for candidate in python_path_candidates(&env.search_dirs) { + purpose.refuse_preview_python_in_prefix(&candidate, "PATH")?; match python_launcher_install_ready(&candidate, requirement) { Ok(()) => { return Ok(PythonLookup::Found(PythonLauncher { @@ -1213,6 +1410,8 @@ fn find_python_launcher_in( if let Some(manifest) = load_managed_python_manifest(paths)? && manifest.executable.is_file() { + purpose + .refuse_preview_python_in_prefix(&manifest.executable, "the saved managed Python")?; if python_launcher_install_ready(&manifest.executable, requirement).is_ok() { return Ok(PythonLookup::Found(PythonLauncher { executable: manifest.executable, @@ -1888,6 +2087,7 @@ exit 1 &self.paths, python_requirement(SourceLayout::Canonical), dry_run, + None, ) } @@ -1898,7 +2098,11 @@ exit 1 search_dirs: vec![self.search_dir.clone()], ..PythonResolverEnv::from_process_env() }); - plan_python_launcher(&self.paths, python_requirement(SourceLayout::Canonical)) + plan_python_launcher( + &self.paths, + python_requirement(SourceLayout::Canonical), + None, + ) } fn uv_was_run(&self) -> bool { @@ -2039,7 +2243,7 @@ exit 1 managed_bootstrap_disabled: disabled, }); PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().clear()); - let result = python_for_install(&paths, requirement, dry_run); + let result = python_for_install(&paths, requirement, dry_run, None); let lines = PROGRESS_LINE_SINK.with(|sink| sink.borrow().clone()); (result, lines) }; @@ -2187,7 +2391,7 @@ exit 1 ], ), ( - LookupPurpose::Preview, + LookupPurpose::Preview { prefix: None }, [ "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).", @@ -3072,7 +3276,10 @@ exit 1 "{error}" ); assert!( - error.contains("that does not run or does not match"), + error.contains(&format!( + "(found a Python at {} with no pyvenv.cfg beside it;", + venv_python_path(&home).display() + )), "{error}" ); assert!(error.contains("no .rocm-cli-runtime.json"), "{error}"); @@ -3206,8 +3413,9 @@ exit 1 assert_eq!( line, &format!( - "Existing Python environment at {} no longer runs or does not match the required interpreter; rebuilding only its venv files (kept: .rocm-cli-runtime.json, apps).", - install_root.display() + "Existing Python environment at {} cannot be used as it is (found a Python at {} that does not run); rebuilding only its venv files (kept: .rocm-cli-runtime.json, apps).", + install_root.display(), + venv_python_path(&install_root).display() ) ); for kept in [".rocm-cli-runtime.json", "apps"] { @@ -3261,7 +3469,10 @@ exit 1 assert!( printed .iter() - .any(|line| line.contains("is incomplete; rebuilding only its venv files")), + .any(|line| line.contains(&format!( + "cannot be used as it is (found pyvenv.cfg but no Python at {}); rebuilding only its venv files", + venv_python_path(&install_root).display() + ))), "{printed:?}" ); fs::remove_dir_all(root).ok(); @@ -3449,6 +3660,54 @@ exit 1 fs::remove_dir_all(root).ok(); } + /// A clear that cannot look at a venv entry stops with an error. Only an + /// entry that is not there counts as removed: an entry it could not + /// inspect (here, a folder that can be listed but not searched) may still + /// be on disk, and handing that to `uv venv --allow-existing` would build + /// over a stale venv while reporting a clean rebuild. + #[test] + #[cfg(unix)] + fn a_clear_that_cannot_inspect_a_venv_entry_stops_before_uv() { + use std::os::unix::fs::PermissionsExt; + let (root, paths) = venv_rebuild_sandbox("uninspectable"); + let install_root = managed_runtime_root(&paths, "wheel", "release-wheel-x"); + plant_failing_venv_python(&install_root); + fs::write(install_root.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); + let (uv, uv_log) = write_logging_fake_uv(&root); + let launcher = cp312_launcher(&root); + // Listable (r) but not searchable (no x): names read, entries do not stat. + fs::set_permissions(&install_root, fs::Permissions::from_mode(0o644)).unwrap(); + let restore = || { + fs::set_permissions(&install_root, fs::Permissions::from_mode(0o755)).unwrap(); + }; + if fs::symlink_metadata(install_root.join("bin")).is_ok() { + // Permissions are not enforced (running as root): nothing to show. + restore(); + fs::remove_dir_all(root).ok(); + return; + } + + let result = ensure_uv_venv(&paths, &uv, &launcher, &install_root); + restore(); + let error = format!("{:#}", result.unwrap_err()); + assert!( + error.contains(&format!( + "failed to inspect {}", + install_root.join("bin").display() + )), + "{error}" + ); + assert!( + !uv_log.exists(), + "uv must not run over an entry the clear could not inspect" + ); + assert!( + venv_python_path(&install_root).is_file(), + "the entry is still there" + ); + fs::remove_dir_all(root).ok(); + } + /// The protected-location check runs before ownership is looked at, on /// the path as given and on where it resolves. `/proc/self/cwd` is /// protected only by its spelling (it resolves to this test's working @@ -3460,7 +3719,9 @@ exit 1 let (root, paths) = venv_rebuild_sandbox("protected"); let spelled = Path::new("/proc/self/cwd"); - let error = venv_folder_state(&paths, spelled).unwrap_err().to_string(); + let error = venv_folder_state(&paths, spelled, "files") + .unwrap_err() + .to_string(); assert!( error.contains(": /proc/self/cwd is a protected system location"), "{error}" @@ -3468,7 +3729,9 @@ exit 1 let link = root.join("looks-like-mine"); std::os::unix::fs::symlink("/usr/share", &link).unwrap(); - let error = venv_folder_state(&paths, &link).unwrap_err().to_string(); + let error = venv_folder_state(&paths, &link, "files") + .unwrap_err() + .to_string(); assert!( error.contains(": /usr/share is a protected system location"), "{error}" @@ -3478,68 +3741,291 @@ exit 1 fs::remove_dir_all(root).ok(); } - /// The `--dry-run` `python_env:` and `command:` lines `install_wheel_runtime` - /// prints, for each decision the install can take. A refused folder gets - /// no command at all; a rebuild shows `--allow-existing`; a reusable venv - /// shows only the package install. + /// The `--dry-run` lines `install_wheel_runtime` prints for the venv step, + /// for every state an install folder can be in, and the guarantee they rest + /// on: a preview runs nothing from the install folder. Every folder here + /// holds a Python that records each time it is run, so the last assertion + /// fails if any branch of the preview executes it. + /// + /// Where the files decide alone, one outcome is printed: a fresh venv, a + /// rebuild with `--allow-existing`, or a refusal with no command. Where only + /// running the Python could tell (a folder with a Python and `pyvenv.cfg`), + /// the preview says it could not tell and prints both outcomes. #[test] #[cfg(unix)] - fn the_dry_run_lines_predict_what_the_venv_step_will_do() { + fn a_dry_run_reads_the_install_folder_and_runs_nothing_from_it() { let (root, paths) = venv_rebuild_sandbox("preview"); let launcher = cp312_launcher(&root); + let ran = root.join("prefix-python-ran.log"); let install_args = vec!["pip".to_owned(), "install".to_owned(), "rocm".to_owned()]; - let venv_command = |folder: &Path| { + let venv_command = |folder: &Path, allow: &str| { format!( - "uv venv --python {} {}", + "UV_VENV_CLEAR=0 uv venv --python {} {}{allow} && uv pip install rocm", launcher.display(), folder.display() ) }; + let plan = |folder: &Path| { + let plan = dry_run_venv_plan(&paths, &launcher, folder, "cp312", &install_args); + let lines = plan + .lines + .iter() + .map(|(key, value)| format!("{key}: {value}")) + .collect::>(); + (plan.python_env, lines) + }; + let reuse = "reuse the Python environment here if its Python runs, reports wheel tag cp312 and has this folder as its sys.prefix; this preview runs nothing from the folder, so it cannot tell whether it does"; + let rebuild = "rebuild only the venv files ROCm CLI created here: remove bin, Scripts, lib, lib64, Lib, include, Include, CACHEDIR.TAG, pyvenv.cfg first, which the command does not show, then create the venv with --allow-existing; everything else in the folder is kept"; + // Missing folder: a fresh venv. let empty = root.join("missing"); - let (env, command) = dry_run_venv_lines(&paths, &launcher, &empty, &install_args); + let (env, lines) = plan(&empty); assert_eq!(env, "create a new Python environment in an empty folder"); - assert_eq!( - command, - format!("{} && uv pip install rocm", venv_command(&empty)) - ); + assert_eq!(lines, [format!("command: {}", venv_command(&empty, ""))]); + // Someone's folder with a Python but no pyvenv.cfg: certainly refused. let home = root.join("home"); - plant_failing_venv_python(&home); - let (env, command) = dry_run_venv_lines(&paths, &launcher, &home, &install_args); + plant_recording_venv_python(&home, &home, &ran); + let (env, lines) = plan(&home); + assert_eq!(env, "the install will refuse this folder"); + assert_eq!( + lines[0], + "command: none; the install will refuse this folder" + ); + assert!( + lines[1].starts_with(&format!( + "refusal: refusing to create the Python environment at {}: the folder is not empty and ROCm CLI cannot show it holds a ROCm CLI install (found a Python at {} with no pyvenv.cfg beside it; no finished ROCm CLI install recorded here", + home.display(), + venv_python_path(&home).display() + )), + "{lines:?}" + ); + assert_eq!(lines.len(), 2, "{lines:?}"); + + // Someone's venv (a downloaded or cloned tree): reuse is undecidable + // without running it, and the install refuses it otherwise. + let cloned = root.join("cloned"); + plant_recording_venv_python(&cloned, &cloned, &ran); + fs::write(cloned.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); + let (env, lines) = plan(&cloned); + assert_eq!( + env, + format!("{reuse}; if not, the install will refuse this folder") + ); + assert_eq!(lines[0], "command: uv pip install rocm"); assert!( - env.starts_with("the install will refuse this folder: refusing to create"), - "{env}" + lines[1].starts_with(&format!( + "refusal_if_not_reused: refusing to create the Python environment at {}: the folder is not empty and ROCm CLI cannot show it holds a ROCm CLI install (found a Python at {} that this preview did not run;", + cloned.display(), + venv_python_path(&cloned).display() + )), + "{lines:?}" ); - assert_eq!(command, "none; the install will refuse this folder"); - assert!(home.join("bin").exists(), "a preview changes nothing"); + assert_eq!(lines.len(), 2, "{lines:?}"); + // A venv ROCm CLI made, intact on disk: reuse or a rebuild in place. let owned = root.join("owned"); - plant_failing_venv_python(&owned); plant_rocm_owned_venv_markers(&owned); - let (env, command) = dry_run_venv_lines(&paths, &launcher, &owned, &install_args); - assert!(env.starts_with("rebuild only the venv files"), "{env}"); + plant_recording_venv_python(&owned, &owned, &ran); + let (env, lines) = plan(&owned); + assert_eq!(env, format!("{reuse}; if not, {rebuild}")); assert_eq!( - command, + lines, + [ + "command: uv pip install rocm".to_owned(), + format!( + "command_if_rebuilt: {}", + venv_command(&owned, " --allow-existing") + ), + ] + ); + + // A venv ROCm CLI made whose clear stopped after pyvenv.cfg: certainly + // rebuilt, and the line names what was found. + let broken = root.join("broken"); + plant_rocm_owned_venv_markers(&broken); + plant_recording_venv_python(&broken, &broken, &ran); + fs::remove_file(broken.join("pyvenv.cfg")).unwrap(); + let (env, lines) = plan(&broken); + assert_eq!( + env, format!( - "{} --allow-existing && uv pip install rocm", - venv_command(&owned) + "{rebuild} (found a Python at {} with no pyvenv.cfg beside it)", + venv_python_path(&broken).display() ) ); + assert_eq!( + lines, + [format!( + "command: {}", + venv_command(&broken, " --allow-existing") + )] + ); + + assert!( + !ran.exists(), + "a preview ran a Python from the install folder:\n{}", + fs::read_to_string(&ran).unwrap_or_default() + ); + for folder in [&home, &cloned, &owned, &broken] { + assert!( + venv_python_path(folder).is_file(), + "a preview changed {}", + folder.display() + ); + } + assert!(cloned.join("pyvenv.cfg").is_file() && owned.join("pyvenv.cfg").is_file()); + fs::remove_dir_all(root).ok(); + } + + /// The interpreter search a preview runs is the other way a preview could + /// run something from the install folder: the folder's `bin` on `PATH`, or + /// `ROCM_CLI_PYTHON` naming a Python in it. A preview refuses there rather + /// than run it, and says so; the same search for an install, or a preview + /// with no `--prefix`, still runs it, which is what shows the refusal comes + /// from the guard and not from the Python. + #[test] + #[cfg(unix)] + fn a_dry_run_runs_no_python_from_the_install_folder_while_searching() { + let _lock = PROCESS_ENV_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let (root, paths) = venv_rebuild_sandbox("preview-search"); + let ran = root.join("prefix-python-ran.log"); + let prefix = root.join("prefix"); + plant_recording_venv_python(&prefix, &prefix, &ran); + let bin = prefix.join("bin"); + fs::rename(bin.join("python"), bin.join("python3")).unwrap(); + let requirement = python_requirement(SourceLayout::Canonical); + let on_path = PythonResolverEnv { + python_override: None, + search_dirs: vec![bin.clone()], + managed_python_version: None, + managed_bootstrap_disabled: false, + }; + let named = |value: &str| PythonResolverEnv { + python_override: Some(value.to_owned()), + ..on_path.clone() + }; + let in_prefix = bin.join("python3").display().to_string(); + + for (env, source) in [ + (on_path.clone(), "PATH"), + (named(&in_prefix), "ROCM_CLI_PYTHON"), + (named("python3"), "ROCM_CLI_PYTHON"), + ] { + let error = plan_python_launcher_in(&paths, &env, requirement, Some(&prefix)) + .unwrap_err() + .to_string(); + assert!( + error.starts_with(&format!( + "this preview did not check the Python from {source} at " + )) && error.contains(&format!( + "inside the install folder {}, and a preview runs nothing from the install folder", + prefix.display() + )), + "{error}" + ); + assert!(!ran.exists(), "the preview ran {in_prefix} ({source})"); + } + + // A folder beside the prefix is not inside it. + let beside = root.join("prefix-other"); + assert!( + plan_python_launcher_in(&paths, &on_path, requirement, Some(&beside)).is_ok() + && ran.exists(), + "with the Python outside the install folder, the preview checks it as before" + ); + fs::remove_file(&ran).unwrap(); assert!( - venv_python_path(&owned).is_file(), - "a preview changes nothing" + plan_python_launcher_in(&paths, &on_path, requirement, None).is_ok() && ran.exists(), + "without a --prefix, the preview checks the PATH Python as before" ); + fs::remove_dir_all(root).ok(); + } - let working = root.join("working"); - plant_rocm_owned_venv_markers(&working); - plant_working_venv_python(&working, &working); - let (env, command) = dry_run_venv_lines(&paths, &launcher, &working, &install_args); - assert_eq!(env, "reuse the working Python environment already here"); - assert_eq!(command, "uv pip install rocm"); + /// Each condition a venv must meet to be reused is named when it is the + /// one that failed, in the refusal of a folder ROCm CLI did not make, so a + /// user is not told a Python "does not run" when it runs fine and only its + /// `sys.prefix` (a conda env given as `--prefix`) or `pyvenv.cfg` is wrong. + #[test] + #[cfg(unix)] + fn a_refusal_names_the_condition_that_kept_the_venv_from_being_reused() { + let (root, paths) = venv_rebuild_sandbox("reuse-reasons"); + let launcher = cp312_launcher(&root); + let (uv, uv_log) = write_logging_fake_uv(&root); + let ran = root.join("ran.log"); + let elsewhere = root.join("conda-base"); + let cfg = + |folder: &Path| fs::write(folder.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); + + for label in ["does-not-run", "no-cfg", "foreign-prefix", "wrong-tag"] { + let folder = root.join(label); + let python = venv_python_path(&folder).display().to_string(); + let expected = match label { + "does-not-run" => { + plant_failing_venv_python(&folder); + cfg(&folder); + format!("a Python at {python} that does not run") + } + "no-cfg" => { + plant_recording_venv_python(&folder, &folder, &ran); + format!("a Python at {python} with no pyvenv.cfg beside it") + } + "foreign-prefix" => { + plant_recording_venv_python(&folder, &elsewhere, &ran); + cfg(&folder); + format!( + "a Python at {python} whose sys.prefix is {}, not this folder", + elsewhere.display() + ) + } + _ => { + plant_recording_venv_python(&folder, &folder, &ran); + // Same Python, but reporting the cp311 tag. + let script = fs::read_to_string(&python) + .unwrap() + .replace("cp312", "cp311"); + fs::write(&python, script).unwrap(); + cfg(&folder); + format!( + "a Python at {python} that reports wheel tag cp311 where cp312 is required" + ) + } + }; + let error = ensure_uv_venv(&paths, &uv, &launcher, &folder) + .unwrap_err() + .to_string(); + assert!( + error.contains(&format!("(found {expected};")), + "{label}: {error}" + ); + assert!(!error.contains("does not match"), "{label}: {error}"); + } + assert!(!uv_log.exists(), "uv must not run after a refusal"); fs::remove_dir_all(root).ok(); } + /// A venv Python that appends a line to `ran` every time it is run, then + /// behaves as [`plant_working_venv_python`]'s does: runs, reports `cp312`, + /// and reports `prefix` as its `sys.prefix`, and creates a venv when asked. + #[cfg(unix)] + fn plant_recording_venv_python(install_root: &Path, prefix: &Path, ran: &Path) { + use std::os::unix::fs::PermissionsExt; + let python = venv_python_path(install_root); + fs::create_dir_all(python.parent().unwrap()).unwrap(); + fs::write( + &python, + format!( + "#!/bin/sh\necho \"$0 $*\" >> \"{}\"\nif [ \"$1\" = \"-m\" ]; then /bin/mkdir -p \"$3\"; exit 0; fi\nif [ \"$1\" = \"-c\" ]; then\n case \"$2\" in *sys.prefix*) echo \"{}\" ;; *) echo cp312 ;; esac\n exit 0\nfi\necho Python 3.12.10\n", + ran.display(), + prefix.display() + ), + ) + .unwrap(); + fs::set_permissions(&python, fs::Permissions::from_mode(0o755)).unwrap(); + } + /// A venv Python that runs, reports the `cp312` tag, and reports `prefix` /// as its `sys.prefix`, the way a real one does with or without the /// `pyvenv.cfg` that decides what that prefix really is. diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index dc9c5ff937..ba6a7b4e6e 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -2963,6 +2963,7 @@ sdk install package_specs: not resolved by this preview package_policy: resolve the pinned target-complete rocm, torch, torchvision, and torchaudio plan from published package metadata, then install it in one uv transaction mode: dry-run + python_env: not resolved by this preview command: not resolved by this preview activation: use the managed venv Python; TheRock libraries are resolved from that venv by rocm_sdk.initialize_process manifest: not resolved by this preview @@ -3047,7 +3048,9 @@ sdk install }; let mut resolved = String::new(); write_wheel_plan(&mut resolved, &plan); - write_dry_run_tail(&mut resolved, &plan); + let (paths_root, paths) = super::super::super::test_support::test_paths("plan-keys"); + write_dry_run_tail(&mut resolved, &plan, Some(&paths)); + std::fs::remove_dir_all(paths_root).ok(); let mut expected = plan_keys(&resolved); let at = expected diff --git a/apps/rocm/src/therock/update.rs b/apps/rocm/src/therock/update.rs index a006fece71..b98f418625 100644 --- a/apps/rocm/src/therock/update.rs +++ b/apps/rocm/src/therock/update.rs @@ -508,7 +508,7 @@ fn resolve_latest_for_manifest( (wheel_compatibility_for_python(&python.executable)?, None) } (None, PythonAccess::SearchOnly) => { - let planned = plan_python_launcher(paths, requirement)?; + let planned = plan_python_launcher(paths, requirement, None)?; (planned.wheel_compatibility()?, planned.update_note()) } }; diff --git a/apps/rocm/src/therock/wheel_plan.rs b/apps/rocm/src/therock/wheel_plan.rs index fe60fafad7..8d4b966a48 100644 --- a/apps/rocm/src/therock/wheel_plan.rs +++ b/apps/rocm/src/therock/wheel_plan.rs @@ -15,15 +15,14 @@ //! `command`). [`PlanStack::NeedsUv`] says those are not resolved, and why, //! where [`PlanStack::Resolved`] carries their values. -use super::python::{PlannedPython, WheelCompatibility}; +use super::python::{PlannedPython, WheelCompatibility, dry_run_venv_plan}; use super::resolve::{AggregateDeviceTarget, TorchaudioPin, UnresolvedPipRuntime}; use super::source::{RuntimeVersionSelector, TheRockChannel}; use super::{ no_wheel_warning_for, render_canonical_provenance, runtime_version_display, venv_python_path, wheel_host_version_note, }; -use crate::shell_quote::shell_quote; -use rocm_core::{uv_pip_install_base, uv_venv_args}; +use rocm_core::{AppPaths, uv_pip_install_base}; use std::fmt::Write as _; use std::path::Path; @@ -211,12 +210,22 @@ pub(super) const UNRESOLVED_NOTE: &str = "no uv is installed, so a real install /// not.`). pub(super) const UNRESOLVED_PROGRESS: &str = "No uv is installed; a real install would fetch it and resolve the torch and torchvision versions with `uv pip compile`. This preview does not."; -/// The lines a preview adds after [`write_wheel_plan`]: the commands a real install -/// would run, and where it would record the runtime. -pub(super) fn write_dry_run_tail(output: &mut String, plan: &WheelPlan<'_>) { +/// The lines a preview adds after [`write_wheel_plan`]: what the venv step would +/// do, the commands a real install would run, and where it would record the +/// runtime. +/// +/// `paths` is needed only for a resolved plan, whose venv step is decided by +/// [`dry_run_venv_plan`] from the install folder's files, running nothing from +/// it; that function also shell-quotes the commands, which a user is invited to +/// paste and whose install root can come from a model-chosen `--prefix`. +pub(super) fn write_dry_run_tail( + output: &mut String, + plan: &WheelPlan<'_>, + paths: Option<&AppPaths>, +) { let _ = writeln!(output, " mode: dry-run"); - match &plan.stack { - PlanStack::Resolved(stack) => { + match (&plan.stack, paths) { + (PlanStack::Resolved(stack), Some(paths)) => { let env_python = venv_python_path(stack.install_root); let mut install_args = uv_pip_install_base(&env_python); install_args.extend(["--index-url".to_owned(), plan.index_url.to_owned()]); @@ -224,29 +233,23 @@ pub(super) fn write_dry_run_tail(output: &mut String, plan: &WheelPlan<'_>) { install_args.extend(["--prerelease".to_owned(), "allow".to_owned()]); } install_args.extend(stack.package_specs.iter().cloned()); - let venv_args = uv_venv_args(&plan.python.venv_python_arg(), stack.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 - // (`install_sdk_dry_run` is a model-callable tool), so a bare or - // double-quoted value here would be a model-chosen value in a line a - // user is invited to paste. - let venv_args_display = venv_args - .iter() - .map(|arg| shell_quote(arg)) - .collect::>() - .join(" "); - let install_args_display = install_args - .iter() - .map(|arg| shell_quote(arg)) - .collect::>() - .join(" "); - let _ = writeln!( - output, - " command: uv {venv_args_display} && uv {install_args_display}" + let venv_plan = dry_run_venv_plan( + paths, + &plan.python.venv_python_arg(), + stack.install_root, + &plan.wheel_compatibility.python_tag, + &install_args, ); + let _ = writeln!(output, " python_env: {}", venv_plan.python_env); + for (key, value) in &venv_plan.lines { + let _ = writeln!(output, " {key}: {value}"); + } } - PlanStack::NeedsUv { .. } => { + (PlanStack::Resolved(_), None) => { + unreachable!("a resolved plan's preview is written with the paths its venv step reads") + } + (PlanStack::NeedsUv { .. }, _) => { + let _ = writeln!(output, " python_env: {NOT_RESOLVED}"); let _ = writeln!(output, " command: {NOT_RESOLVED}"); } } @@ -328,6 +331,6 @@ pub(super) fn unresolved_wheel_preview(preview: &UnresolvedPreview<'_>) -> Strin }; let mut output = String::new(); write_wheel_plan(&mut output, &plan); - write_dry_run_tail(&mut output, &plan); + write_dry_run_tail(&mut output, &plan, None); output } diff --git a/docs/llm-tool-use.md b/docs/llm-tool-use.md index 9626d47799..a3c3b7d0de 100644 --- a/docs/llm-tool-use.md +++ b/docs/llm-tool-use.md @@ -14,6 +14,12 @@ rocm-cli local assistants use structured tools, not shell commands. before anything runs. - Read-only ROCm checks can run immediately and return their output to the model. +- A read-only check runs nothing from a location the model chose. The + `install_sdk_dry_run` preview takes a model-chosen `--prefix`, so it reads + that folder's files and never runs a `bin/python` or script found there; where + only running it could tell what the install would do, the preview says it + cannot tell. It also stops, without running it, when the Python it would check + first is inside that folder. - Installs, starts, stops, updates, deletes, settings changes, and other mutations must pause on the TUI approval screen. - The model should inspect first, then request a change only when the inspection diff --git a/docs/manual-testing.md b/docs/manual-testing.md index cabe87a144..a4e2b9f484 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -156,8 +156,11 @@ Expected result: `--approve-replacing-active-default` as the flag to add. - With `--approve-replacing-active-default`, the install proceeds without 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. +- `rocm install sdk ... --dry-run` never prompts, and never asks for + `--approve-replacing-active-default`, whatever the active default is: the + preview stops before that gate. It does still report refusals the install + would give for other reasons, such as the Python and install-folder checks + below. - 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:` @@ -198,11 +201,26 @@ Expected result: - If the `--prefix` folder already has anything in it and its venv does not run, rocm-cli rebuilds only that venv's own files, and only in a folder where a wheel install finished (its `.rocm-cli-runtime.json` names the folder). - It prints what it kept, and anything else in the folder, such as - `apps/comfyui`, is still there afterwards. A folder it did not create, such - as your home folder with a broken `~/bin/python`, is refused with nothing - changed, and `--dry-run` predicts that refusal in its `python_env:` line and - prints `command: none`. + It prints what it kept and why the venv could not be used (for example `no + pyvenv.cfg beside it`, or `whose sys.prefix is ..., not this folder`), and + anything else in the folder, such as `apps/comfyui`, is still there + afterwards. A folder it did not create, such as your home folder with a + broken `~/bin/python`, is refused with nothing changed, and the refusal names + the same reason. +- `--dry-run` runs nothing from the `--prefix` folder: put a `bin/python` there + that writes a file when run, and after the preview that file does not exist. + It reads the folder's files instead. For your home folder with a broken + `~/bin/python` and no `pyvenv.cfg`, `python_env:` says + `the install will refuse this folder`, `command:` is `none`, and a + `refusal:` line gives the install's message. For a folder with both a Python + and `pyvenv.cfg`, it cannot tell without running that Python whether the + venv would be reused, so `python_env:` says so, `command:` shows only the + `uv pip install`, and a `command_if_rebuilt:` or `refusal_if_not_reused:` + line gives the other outcome. The `uv venv` commands it shows start with + `UV_VENV_CLEAR=0`, as the install runs them; a rebuild first removes the + venv's own entries, which the command does not show. If the Python the + preview would check first (on `PATH`, or `ROCM_CLI_PYTHON`) is inside the + `--prefix` folder, the preview stops and says it did not run it. - pip installs pinned `rocm`, `torch`, and `torchvision` requirements with exactly one `device-` extra (`rocm` also requests `libraries`, and `devel` only when `--devel` is passed), alongside pinned diff --git a/docs/testing.md b/docs/testing.md index e7dcd96fd5..81010ee025 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -816,7 +816,9 @@ rocm install sdk --channel release --format wheel < /dev/null # expect the ref 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. +never prompts and never asks for that consent, whatever the active default is. +It can still fail, or report that the install would refuse, for the Python and +install-folder reasons below. 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 @@ -909,6 +911,29 @@ The `update_check` tool and the plain `rocm update` check (no `--apply`) are not previews in this sense: on a ROCm 10 or newer runtime they resolve with `uv` and can fetch it. They prepare no Python, though (see `update-09` and `update-10`). +The preview runs nothing from the install folder. `install_sdk_dry_run` is a +model-callable tool that runs without approval and with a model-chosen +`--prefix`, so a folder holding a hostile `bin/python` must not be executed by +it. The venv step is decided from the folder's files (`dry_run_venv_plan` in +[python.rs](../apps/rocm/src/therock/python.rs)); where only running the +folder's Python could tell whether its venv is reused, the preview says so and +prints both outcomes (`command:` plus `command_if_rebuilt:` or +`refusal_if_not_reused:`). The interpreter search stops the preview, saying it +did not run it, when the Python it would check first is inside `--prefix`. +`a_dry_run_reads_the_install_folder_and_runs_nothing_from_it` plants a Python +that records every run in each folder state and asserts the lines and an empty +record; `a_dry_run_runs_no_python_from_the_install_folder_while_searching` +covers `PATH`, an absolute `ROCM_CLI_PYTHON` and a bare one resolved through +`PATH`. End to end, scenarios `runtime-29` (an unowned home folder is refused, +by the preview and by the install, and the advised empty folder works), +`runtime-30` (a rebuild of a folder ROCm CLI made keeps the ComfyUI data and +says why the old venv was not reused) and `runtime-31` (a preview of a folder +holding someone else's venv says it cannot tell and runs nothing) run the real +CLI with a loopback index, a fake `uv` and planted Pythons that record every +run. They are Linux-only because those stand-ins are shell scripts; the guard +code is platform-neutral and the Windows CI job builds it, but no Windows test +runs a preview against a planted interpreter. + 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 a0d6f24815..cf6345601e 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -641,7 +641,8 @@ Feature: Runtime configuration # home folder whose `~/bin/python` fails `--version`. The install now refuses # a folder ROCm CLI cannot show it created, and the second half takes the # refusal's own advice to prove it is a way forward, not a dead end. The - # `--dry-run` preview comes first: it has to predict that refusal and print + # `--dry-run` preview comes first: it has to predict that refusal from the + # folder's files, without running the folder's Python, and print # `command: none`, since the install will run no command. # # No GPU or network: the index is a loopback fixture, and the install pins @@ -665,7 +666,8 @@ Feature: Runtime configuration # keeps the user's models, workflows and outputs under `apps/comfyui`. A # rebuild replaces the environment's own files and nothing else, and the line # it prints names what it kept — asserted together with the disk. The preview - # shows the `uv venv --allow-existing` a rebuild runs. Same hermetic setup and + # runs nothing from the folder, so it cannot tell reuse from a rebuild; it + # says so and shows the `uv venv --allow-existing` a rebuild runs. Same hermetic setup and # Linux-only reason as runtime-29; the fake uv refuses a non-empty folder # without `--allow-existing` and wipes it on `--clear`, as uv 0.10 does. @id:runtime-install-sdk-rebuild-keeps-comfyui-data @requires-os:linux @@ -676,3 +678,23 @@ Feature: Runtime configuration Then the preview shows a rebuild in place that keeps the folder When the user installs the SDK into the folder ROCm CLI installed into Then the install rebuilds only the environment's own files and reports keeping the ComfyUI data + + # A preview runs nothing from the install folder. `install_sdk_dry_run` is a + # tool the local assistant may call without approval and with a `--prefix` of + # its choosing, so a folder holding someone else's `bin/python` (a downloaded + # or cloned tree) must not be run by a preview. Whether a folder with a + # Python and `pyvenv.cfg` would be reused is something only running that + # Python can tell, so the preview says it cannot tell and prints the refusal + # the install gives if it is not reused. The planted Python records every + # run, and the Then checks the record together with the line. + # + # Same hermetic setup and Linux-only reason as runtime-29. The interpreter + # search a preview runs is held to the same rule by the unit test + # `a_dry_run_runs_no_python_from_the_install_folder_while_searching` in + # `apps/rocm/src/therock/python.rs`. + @id:runtime-install-preview-runs-nothing-from-prefix @requires-os:linux + Scenario: runtime-31 - Previewing an SDK install into a folder holding another Python environment runs nothing from it + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + And the user's folder holds a Python environment ROCm CLI did not make + When the user previews installing the SDK into that folder + Then the preview says it cannot tell whether that environment is reused, runs nothing from the folder, and changes nothing diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index fd1185edda..5df02cbb49 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -2166,6 +2166,8 @@ const EMPTY_INSTALL_FOLDER: &str = "empty-install-folder"; /// A runtime folder an earlier `install sdk --prefix` created, now holding /// ComfyUI's models as well as the venv. const ROCM_CLI_MADE_FOLDER: &str = "rocm-cli-made-prefix"; +/// A folder holding someone else's venv, such as a downloaded or cloned tree. +const CLONED_VENV_FOLDER: &str = "cloned-venv"; fn install_folder(world: &E2eWorld, name: &str) -> std::path::PathBuf { let folder = root(world).join(name); @@ -2187,8 +2189,37 @@ fn write_executable(path: &Path, body: &str) { } } -fn plant_python_that_no_longer_runs(folder: &Path) { - write_executable(&folder.join("bin").join("python"), "#!/bin/sh\nexit 1\n"); +/// A Python that fails, and first appends a line to [`prefix_python_log`] so a +/// step can tell whether anything ran it. +fn plant_python_that_no_longer_runs(world: &E2eWorld, folder: &Path) { + write_executable( + &folder.join("bin").join("python"), + &python_that_no_longer_runs(world), + ); +} + +/// The script [`plant_python_that_no_longer_runs`] plants. +fn python_that_no_longer_runs(world: &E2eWorld) -> String { + format!( + "#!/bin/sh\necho \"$0 $*\" >> '{}'\nexit 1\n", + prefix_python_log(world).display() + ) +} + +/// Where every Python planted in an install folder records that it was run. +/// Outside the folders, so recording changes none of them. +fn prefix_python_log(world: &E2eWorld) -> std::path::PathBuf { + root(world).join("prefix-python-ran.log") +} + +/// Fails the step if anything ran a Python planted in an install folder. +fn assert_no_prefix_python_ran(world: &E2eWorld, reported: &str) { + let log = prefix_python_log(world); + assert!( + !log.exists(), + "the preview ran a Python from the install folder:\n{}\n{reported}", + std::fs::read_to_string(&log).unwrap_or_default() + ); } /// Run a real (not `--dry-run`) wheel install into `folder`. @@ -2305,14 +2336,14 @@ fn reported(world: &E2eWorld) -> String { #[given("the user's home folder holds their files and a Python that no longer runs")] async fn home_folder_with_failing_python(world: &mut E2eWorld) { let home = install_folder(world, USER_HOME_FOLDER); - plant_python_that_no_longer_runs(&home); + plant_python_that_no_longer_runs(world, &home); write_fixture(&home.join("Documents").join("thesis.txt"), "years of work"); } #[given("a folder ROCm CLI installed into holds ComfyUI models and a Python that no longer runs")] async fn rocm_cli_folder_with_comfyui_models(world: &mut E2eWorld) { let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); - plant_python_that_no_longer_runs(&folder); + plant_python_that_no_longer_runs(world, &folder); write_fixture(&folder.join("pyvenv.cfg"), "home = /usr/bin\n"); write_fixture( &folder @@ -2371,12 +2402,16 @@ async fn preview_predicts_home_refusal(world: &mut E2eWorld) { let home = install_folder(world, USER_HOME_FOLDER); let reported = reported(world); assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); + assert!( + reported.contains("python_env: the install will refuse this folder\n"), + "the preview did not predict the refusal:\n{reported}" + ); assert!( reported.contains(&format!( - "python_env: the install will refuse this folder: refusing to create the Python environment at {}", + "refusal: refusing to create the Python environment at {}", home.display() )), - "the preview did not predict the refusal:\n{reported}" + "the preview did not give the install's refusal:\n{reported}" ); // No command for an install that will not run one. assert!( @@ -2393,6 +2428,7 @@ async fn preview_predicts_home_refusal(world: &mut E2eWorld) { "a preview changed the home folder" ); assert!(home.join("bin").join("python").is_file()); + assert_no_prefix_python_ran(world, &reported); } #[then("the preview shows a rebuild in place that keeps the folder")] @@ -2400,18 +2436,71 @@ async fn preview_shows_rebuild_in_place(world: &mut E2eWorld) { let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); let reported = reported(world); assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); + // The folder's Python and `pyvenv.cfg` are both there, so only running + // that Python could tell reuse from a rebuild. The preview does not run + // it: it says so and gives the rebuild as the other outcome. assert!( - reported.contains("python_env: rebuild only the venv files ROCm CLI created here"), + reported.contains( + "this preview runs nothing from the folder, so it cannot tell whether it does; if not, rebuild only the venv files ROCm CLI created here" + ), "the preview did not describe the in-place rebuild:\n{reported}" ); assert!( - reported.contains(&format!("{} --allow-existing &&", folder.display())), + reported.contains(&format!( + "command_if_rebuilt: UV_VENV_CLEAR=0 uv venv --python {}", + root(world).join("fake-python").join("python3.14").display() + )) && reported.contains(&format!("{} --allow-existing &&", folder.display())), "the previewed uv venv command is not the one a rebuild runs:\n{reported}" ); assert!( folder.join("lib").is_dir() && folder.join("pyvenv.cfg").is_file(), "a preview changed the folder" ); + assert_no_prefix_python_ran(world, &reported); +} + +#[given("the user's folder holds a Python environment ROCm CLI did not make")] +async fn folder_with_someone_elses_venv(world: &mut E2eWorld) { + let folder = install_folder(world, CLONED_VENV_FOLDER); + plant_python_that_no_longer_runs(world, &folder); + write_fixture(&folder.join("pyvenv.cfg"), "home = /usr/bin\n"); + write_fixture(&folder.join("README.md"), "a project the user downloaded"); +} + +#[when("the user previews installing the SDK into that folder")] +async fn preview_sdk_install_into_cloned_venv(world: &mut E2eWorld) { + let folder = install_folder(world, CLONED_VENV_FOLDER); + run_sdk_install_into(world, &folder, true); +} + +#[then( + "the preview says it cannot tell whether that environment is reused, runs nothing from the folder, and changes nothing" +)] +async fn preview_runs_nothing_from_cloned_venv(world: &mut E2eWorld) { + let folder = install_folder(world, CLONED_VENV_FOLDER); + let reported = reported(world); + assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); + assert!( + reported.contains( + "python_env: reuse the Python environment here if its Python runs, reports wheel tag cp314 and has this folder as its sys.prefix; this preview runs nothing from the folder, so it cannot tell whether it does; if not, the install will refuse this folder" + ), + "the preview did not say what it could not tell:\n{reported}" + ); + assert!( + reported.contains(&format!( + "refusal_if_not_reused: refusing to create the Python environment at {}: the folder is not empty and ROCm CLI cannot show it holds a ROCm CLI install (found a Python at {} that this preview did not run;", + folder.display(), + folder.join("bin").join("python").display() + )), + "the preview did not give the refusal for the other outcome:\n{reported}" + ); + assert_no_prefix_python_ran(world, &reported); + assert_eq!( + std::fs::read_to_string(folder.join("README.md")).ok(), + Some("a project the user downloaded".to_owned()), + "a preview changed the folder" + ); + assert!(folder.join("bin").join("python").is_file() && folder.join("pyvenv.cfg").is_file()); } #[when("the user installs the SDK into the folder ROCm CLI installed into")] @@ -2444,7 +2533,7 @@ async fn install_refuses_home_folder(world: &mut E2eWorld) { ); assert_eq!( std::fs::read_to_string(home.join("bin").join("python")).ok(), - Some("#!/bin/sh\nexit 1\n".to_owned()), + Some(python_that_no_longer_runs(world)), "the user's bin/python is gone or changed" ); assert!( @@ -2479,8 +2568,9 @@ async fn install_rebuilds_and_keeps_comfyui(world: &mut E2eWorld) { let folder = install_folder(world, ROCM_CLI_MADE_FOLDER); let reported = reported(world); let line = format!( - "Existing Python environment at {} no longer runs or does not match the required interpreter; rebuilding only its venv files (kept: .rocm-cli-runtime.json, apps).", - folder.display() + "Existing Python environment at {} cannot be used as it is (found a Python at {} that does not run); rebuilding only its venv files (kept: .rocm-cli-runtime.json, apps).", + folder.display(), + folder.join("bin").join("python").display() ); assert!( reported.contains(&line), From fadfb2b90ab211e39ab08e67bfed6e7d176d1e44 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 9 Nov 2026 16:41:27 +0200 Subject: [PATCH 10/15] fix(therock): keep folder code and text out of the preview's probes Follow-ups from an independent review of the dry-run change: - The venv-support probe runs `python -m venv`, and `-m` puts the working directory first on `sys.path`. With `--dry-run --prefix .` that directory is the install folder, so a `venv.py` there would run in place of the standard library's. The probe now starts in its own fresh folder. - A refusal or rebuild line prints text read from the folder (a marker's recorded path and format, a Python's `sys.prefix`, the kept entries). Control, format and line-separator characters in it are printed as `\u{..}` escapes, so a hostile folder cannot drive the terminal or the assistant's transcript. - The managed wheel-runtimes folder is named through `managed_format_root` in therock.rs instead of spelling `"runtimes"` in python.rs, which also writes the managed-Python registry; main's registry-writer scan flags a file that spells both and writes. - Scenario runtime-32 covers the preview stopping, without running it, when ROCM_CLI_PYTHON names a Python inside the install folder. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock.rs | 12 +- apps/rocm/src/therock/process.rs | 47 +++++-- apps/rocm/src/therock/python.rs | 121 ++++++++++++++++-- docs/architecture.md | 6 +- docs/testing.md | 4 +- .../features/runtime_setup.feature | 15 +++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 48 ++++++- 7 files changed, 218 insertions(+), 35 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index ed36e3c16a..b5796f1ffe 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -1011,11 +1011,13 @@ fn runtime_key( } fn managed_runtime_root(paths: &AppPaths, format: &str, runtime_key: &str) -> PathBuf { - paths - .data_dir - .join("runtimes") - .join(format) - .join(runtime_key) + managed_format_root(paths, format).join(runtime_key) +} + +/// The folder every managed runtime of `format` is created in, one per +/// runtime key. +fn managed_format_root(paths: &AppPaths, format: &str) -> PathBuf { + paths.data_dir.join("runtimes").join(format) } /// Where to build a runtime, resolved to its real location on disk first. diff --git a/apps/rocm/src/therock/process.rs b/apps/rocm/src/therock/process.rs index 0fe291d1fa..cf32831168 100644 --- a/apps/rocm/src/therock/process.rs +++ b/apps/rocm/src/therock/process.rs @@ -85,17 +85,25 @@ fn emit_progress_line(message: &str) { PROGRESS_LINE_SINK.with(|sink| sink.borrow_mut().push(message.to_owned())); } -fn capture_command_output(program: &Path, args: &[&str]) -> Result { +fn capture_command_output(program: &Path, args: &[&str], cwd: Option<&Path>) -> Result { if runtime_is_windows() { - return capture_command_output_with_temp_files(program, args); + return capture_command_output_with_temp_files(program, args, cwd); } - Command::new(program) - .args(args) + let mut command = Command::new(program); + command.args(args); + if let Some(cwd) = cwd { + command.current_dir(cwd); + } + command .output() .with_context(|| format!("failed to launch {}", program.display())) } -fn capture_command_output_with_temp_files(program: &Path, args: &[&str]) -> Result { +fn capture_command_output_with_temp_files( + program: &Path, + args: &[&str], + cwd: Option<&Path>, +) -> Result { let temp_dir = windows_temp_dir("rocm-cli-command")?; let stdout_path = temp_dir.join("stdout.txt"); let stderr_path = temp_dir.join("stderr.txt"); @@ -103,7 +111,11 @@ fn capture_command_output_with_temp_files(program: &Path, args: &[&str]) -> Resu .with_context(|| format!("failed to create {}", stdout_path.display()))?; let stderr_file = fs::File::create(&stderr_path) .with_context(|| format!("failed to create {}", stderr_path.display()))?; - let status = Command::new(program) + let mut command = Command::new(program); + if let Some(cwd) = cwd { + command.current_dir(cwd); + } + let status = command .args(args) .stdin(Stdio::null()) .stdout(Stdio::from(stdout_file)) @@ -170,7 +182,7 @@ pub(super) fn capture_python_stdout( context_text: &str, ) -> Result { if !runtime_is_windows() { - let output = capture_command_output(python_executable, &["-c", script])?; + let output = capture_command_output(python_executable, &["-c", script], None)?; if !output.status.success() { bail!( "{context_text}: {}", @@ -235,8 +247,25 @@ fn windows_child_path(path: &Path) -> String { } pub(super) fn run_command(program: &Path, args: &[&str], context_text: &str) -> Result<()> { + run_command_in(program, args, None, context_text) +} + +/// [`run_command`], started in `cwd` when one is given. `python -m` puts the +/// working directory first on `sys.path`, so a module run that way from a +/// folder someone else controls can import that folder's code instead of the +/// standard library's; a caller that runs one starts it in a folder it made. +pub(super) fn run_command_in( + program: &Path, + args: &[&str], + cwd: Option<&Path>, + context_text: &str, +) -> Result<()> { if runtime_is_windows() { - let status = Command::new(program) + let mut command = Command::new(program); + if let Some(cwd) = cwd { + command.current_dir(cwd); + } + let status = command .args(args) .stdin(Stdio::null()) .stdout(Stdio::null()) @@ -249,7 +278,7 @@ pub(super) fn run_command(program: &Path, args: &[&str], context_text: &str) -> bail!("{context_text}: command exited with status {status}"); } - let output = capture_command_output(program, args)?; + let output = capture_command_output(program, args, cwd)?; if output.status.success() { return Ok(()); } diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 3f9378417e..9866834725 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -15,11 +15,11 @@ use super::io::{linux_temp_dir, windows_temp_dir}; use super::process::{ - capture_python_stdout, progress_line, progress_output_suppressed, run_command, + capture_python_stdout, progress_line, progress_output_suppressed, run_command, run_command_in, run_command_with_env, }; use super::source::SourceLayout; -use super::venv_python_path; +use super::{managed_format_root, venv_python_path}; use crate::shell_quote::shell_quote; use anyhow::{Context, Result, bail}; use rocm_core::{ @@ -212,8 +212,9 @@ fn existing_venv_reuse(install_root: &Path, python_launcher: &Path) -> Result<() let prefix = prefix.trim(); if !paths_name_same_folder(Path::new(prefix), install_root) { return Err(format!( - "a Python at {} whose sys.prefix is {prefix}, not this folder", - env_python.display() + "a Python at {} whose sys.prefix is {}, not this folder", + env_python.display(), + shown_from_folder(prefix) )); } let existing = wheel_compatibility_for_python(&env_python).map_err(|_| { @@ -300,7 +301,7 @@ fn uv_venv_command_env(paths: &AppPaths) -> Vec<(String, String)> { /// part-way (a file it may not delete, a busy one on Windows) then leaves no /// Python behind, or a Python whose venv is still marked as one; either way the /// next run cannot mistake it for a working venv -/// ([`existing_venv_is_reusable`]) and sends the folder back through +/// ([`existing_venv_reuse`]) and sends the folder back through /// [`venv_folder_state`], which finishes the clear. /// /// `share` is deliberately absent: packages install data there, but so can a @@ -481,8 +482,7 @@ fn paths_name_same_folder(left: &Path, right: &Path) -> bool { /// Strictly inside `/runtimes/wheel`, where every folder is one /// `install sdk` made for itself. fn install_root_is_in_managed_wheel_root(paths: &AppPaths, install_root: &Path) -> bool { - let managed = - rocm_core::resolve_path_through_symlinks(&paths.data_dir.join("runtimes").join("wheel")); + let managed = rocm_core::resolve_path_through_symlinks(&managed_format_root(paths, "wheel")); let root = rocm_core::resolve_path_through_symlinks(install_root); rocm_core::runtime_path_is_same_or_inside(&root, &managed) && !rocm_core::runtime_paths_equivalent(&root, &managed) @@ -501,10 +501,13 @@ fn unowned_venv_rebuild_refusal( MarkerFinding::Unreadable => "a .rocm-cli-runtime.json ROCm CLI cannot read".to_owned(), MarkerFinding::NamesOtherFolder(other) => format!( "a .rocm-cli-runtime.json that belongs to {}", - other.display() + shown_from_folder(&other.display().to_string()) ), MarkerFinding::OtherFormat(format) => { - format!("a .rocm-cli-runtime.json from a {format} install, not a Python environment") + format!( + "a .rocm-cli-runtime.json from a {} install, not a Python environment", + shown_from_folder(format) + ) } // Unreachable for a refusal, but stated rather than hidden. MarkerFinding::WheelHere => "a .rocm-cli-runtime.json for this folder".to_owned(), @@ -516,6 +519,26 @@ fn unowned_venv_rebuild_refusal( ) } +/// Text read from the install folder (a marker's recorded path or format, a +/// Python's `sys.prefix`, the names of the entries kept), made safe to print. +/// The folder may be anyone's, and these lines reach a terminal and, through +/// `install_sdk_dry_run`, the assistant's model; a terminal control, format or +/// line-separator character in them is shown as its `\u{..}` escape instead of +/// acting, the same set the tool-argument check refuses. +fn shown_from_folder(text: &str) -> String { + text.chars() + .map(|character| { + if crate::shell_quote::has_terminal_control_character( + character.encode_utf8(&mut [0; 4]), + ) { + character.escape_unicode().to_string() + } else { + character.to_string() + } + }) + .collect() +} + /// Remove one venv entry without following a link out of the folder: `lib64` /// is a symlink to `lib` in a uv venv, and a link must go, not its target. /// @@ -548,7 +571,7 @@ fn venv_rebuild_line(install_root: &Path, python_finding: &str, kept: &[String]) let kept = if kept.is_empty() { "nothing else was in the folder".to_owned() } else { - format!("kept: {}", kept.join(", ")) + format!("kept: {}", shown_from_folder(&kept.join(", "))) }; format!( "Existing Python environment at {} cannot be used as it is (found {python_finding}); rebuilding only its venv files ({kept}).", @@ -1540,16 +1563,22 @@ fn python_tag_for_version(version: &str) -> Option { Some(format!("cp{major}{minor}")) } +/// Runs `python -m venv` into a fresh folder of its own, started in that +/// folder. `-m` puts the working directory first on `sys.path`, so started in +/// the user's working directory (which a `--dry-run --prefix .` makes the +/// install folder) a `venv.py` there would run in place of the standard +/// library's. fn verify_python_can_create_venv(program: &Path) -> Result<()> { let probe_root = python_venv_probe_temp_root()?; let probe_dir = probe_root.join("env"); let args = python_venv_args(&probe_dir); - let result = run_command( + let result = run_command_in( program, args.iter() .map(String::as_str) .collect::>() .as_slice(), + Some(&probe_root), "probe Python virtual environment support", ); let _ = fs::remove_dir_all(&probe_root); @@ -4006,6 +4035,76 @@ exit 1 fs::remove_dir_all(root).ok(); } + /// `python -m venv` puts its working directory first on `sys.path`, so the + /// venv-support probe a preview runs on the host Python starts in a folder + /// of its own, not in the user's working directory, which + /// `--dry-run --prefix .` makes the install folder and where a `venv.py` + /// would otherwise run in place of the standard library's. + #[test] + #[cfg(unix)] + fn the_venv_probe_runs_in_a_folder_of_its_own() { + let (root, _paths) = venv_rebuild_sandbox("probe-cwd"); + let log = root.join("probe-cwd.log"); + let python = root.join("python3"); + rocm_core::fake_executable::write_fake_executable( + &python, + format!( + "#!/bin/sh\nif [ \"$1\" = \"-m\" ]; then pwd -P >> \"{}\"; /bin/mkdir -p \"$3\"; fi\nexit 0\n", + log.display() + ), + ) + .unwrap(); + + verify_python_can_create_venv(&python).unwrap(); + + let ran_in = fs::read_to_string(&log).unwrap(); + let ran_in = Path::new(ran_in.trim()); + let caller = std::env::current_dir().unwrap().canonicalize().unwrap(); + assert_ne!( + ran_in, caller, + "the probe ran in the caller's working directory" + ); + assert!( + ran_in.file_name().is_some_and(|name| name + .to_string_lossy() + .starts_with("rocm-cli-python-venv-probe-")), + "the probe ran in {}, not its own folder", + ran_in.display() + ); + assert!(!ran_in.exists(), "the probe's folder is removed afterwards"); + fs::remove_dir_all(root).ok(); + } + + /// A marker in someone else's folder is text that folder chose, and the + /// refusal carries it to a terminal and, from a preview, to the + /// assistant's model. A control or bidi character in it is printed as an + /// escape, so it cannot clear the screen or reorder the line. + #[test] + #[cfg(unix)] + fn a_refusal_prints_marker_text_with_control_characters_escaped() { + let (root, paths) = venv_rebuild_sandbox("marker-text"); + let folder = root.join("cloned"); + plant_failing_venv_python(&folder); + write_runtime_marker( + &folder, + Path::new("/elsewhere/\u{1b}[2J\u{202e}gpj"), + "wheel", + ); + let error = venv_folder_state(&paths, &folder, "files") + .unwrap_err() + .to_string(); + assert!( + error.contains("belongs to /elsewhere/\\u{1b}[2J\\u{202e}gpj"), + "{error}" + ); + assert!( + !crate::shell_quote::has_terminal_control_character(&error), + "{error:?}" + ); + assert_eq!(shown_from_folder("C:\\envs\\rocm"), "C:\\envs\\rocm"); + fs::remove_dir_all(root).ok(); + } + /// A venv Python that appends a line to `ran` every time it is run, then /// behaves as [`plant_working_venv_python`]'s does: runs, reports `cp312`, /// and reports `prefix` as its `sys.prefix`, and creates a venv when asked. diff --git a/docs/architecture.md b/docs/architecture.md index 93dca4dc8d..91c8e70f60 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -108,21 +108,21 @@ Each per-crate module inventory lists one file per line. Flat inventories (every - [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) — shared CLI-output component (`shell_quote`): the CLI's name for `rocm-core`'s POSIX quoter, [`posix_shell_quote`](../crates/rocm-core/src/quoting.rs). `rocm-dash-tui` keeps a copy as `ui::exec::quote_display_arg` in [`exec.rs`](../crates/rocm-dash-tui/src/ui/exec.rs), since the crate-edge check forbids it `rocm-core`; a per-character walk and a property test here hold the two to the same output. It covers the remote `ssh` command line, the chat approval card and the plan for a free-form request, the install dry-run `command:` line, the [`service_hints.rs`](../apps/rocm/src/service_hints.rs) hints, the runtime-activation report, the `rocm services logs ` lines `rocm services` lists and the `rocm comfyui install --runtime-id` advice a failed ComfyUI reinstall prints — not every `rocm …` hint the CLI prints; older ones such as `rocm logs ` still interpolate their value bare. Also holds `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. - [`storage.rs`](../apps/rocm/src/storage.rs) — full domain extraction. Its report also lists each Lemonade install tree (`EngineInstallUsage`, built by `lemonade_install_usages` from the read-only view in [`footprint.rs`](../engines/lemonade/src/footprint.rs)) with its size and whether the install record uses it (`EngineInstallStatus`, decided by `classify_engine_install`), and whether `rocm runtimes uninstall` would delete it with its runtime. - [`system_packages.rs`](../apps/rocm/src/system_packages.rs) — full domain extraction, a leaf of the crate (split out of [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs)): the host system-package installs that `rocm install sdk` and `rocm engines install vllm` run through `sudo` apt, dnf or zypper. It owns the distro-aware OpenMPI, libatomic and libnuma flows (`ensure_openmpi_for_vllm`, `ensure_libatomic_for_torch`, `ensure_libnuma_for_torch`), the choice between printing the commands and running them (`SystemPackageInstallAction`, `system_package_install_action`), the guard that refuses an `apt-get install` which would remove ROCm packages, and reads the os-release every one of these plans is built from through `rocm_core::hardware_root::real_os_release`, which has no copy here. Production code uses only `std`, `anyhow` and `rocm_core`; the three `ensure_*` functions are `pub(crate)` and the rest is private. `runtime_install_finalize.rs` re-exports the three `ensure_*` names for [`install_cmd.rs`](../apps/rocm/src/install_cmd.rs) and [`engines_cmd.rs`](../apps/rocm/src/engines_cmd.rs). `SdkInstallConsents` stays in `runtime_install_finalize.rs` (it carries a `therock::SdkInstallConsent`); the functions here take its plain `system_packages` bool. `torch_runtime_dep_checks_disabled` is the E2E hook that skips the torch dependency checks; it only does anything under `e2e-test-hooks`. Its tests cover the consent decision (reaching `consents_for_install_sdk_argv` in `runtime_install_finalize.rs`'s test module) and, under `e2e-test-hooks` on Linux, that `rocm_core::hardware_root::real_os_release` and the three OpenMPI/libatomic/libnuma install hints ignore a simulated host root, and a scan that no source file of the binary reads os-release by hand. -- [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the plan itself being written by `therock/wheel_plan.rs`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token` and `slugify`, plus `ensure_tarball_install_target_is_clean`, the refusal to extract a tarball into a root that already holds a payload. What "holds a payload" means is not defined here: it is `rocm_core::install_root_has_payload`, the one rule shared with `runtime_registry.rs` and `therock/update.rs`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read five of them from here, so they stay in `therock.rs` for good: `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key` and `wheel_runtime_key` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) lives in [`cli.rs`](../apps/rocm/src/cli.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). +- [`therock.rs`](../apps/rocm/src/therock.rs) — full domain extraction; owns TheRock SDK install orchestration and is the parent of the `therock/` children below. It keeps `install_sdk` and `install_sdk_for_update` (with `SdkInstallRequest` and `SdkInstallResult`), the wheel and tarball install paths (`install_wheel_runtime`, `install_tarball_runtime`) with the provenance and notes they print (`render_canonical_provenance`, the plan itself being written by `therock/wheel_plan.rs`, the host-newer-ROCm and no-wheels messages, `quote_display_arg`), and the helpers that name an install and its folders: `runtime_key`, `wheel_runtime_key`, `managed_runtime_root`, `managed_format_root`, `resolved_install_root`, `venv_python_path`, `platform_tarball_token` and `slugify`, plus `ensure_tarball_install_target_is_clean`, the refusal to extract a tarball into a root that already holds a payload. What "holds a payload" means is not defined here: it is `rocm_core::install_root_has_payload`, the one rule shared with `runtime_registry.rs` and `therock/update.rs`. The runtime-manifest model and registry loaders it writes through live in [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs); `therock.rs` re-exports the names other modules reach as `therock::...`: `InstalledRuntimeManifest`, `WheelRuntimeComposition`, `RocmSdkPythonProbe`, `load_runtime_manifests` and `validate_rocm_sdk_runtime_probe` from `runtime_registry.rs` (plus `RocmSdkLibraryProbe`, for tests only), and from its child modules the `pub(crate)` names each child's entry below lists. The children read six of them from here, so they stay in `therock.rs` for good: `managed_format_root` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs), the managed wheel runtimes folder an ownership check accepts), `slugify` ([`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) and [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs)), `venv_python_path` ([`therock/python.rs`](../apps/rocm/src/therock/python.rs)), `platform_tarball_token` ([`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs)), and `runtime_key` and `wheel_runtime_key` ([`therock/update.rs`](../apps/rocm/src/therock/update.rs)). The `runtimes` subcommand's command enum (`RuntimesCommand`) lives in [`cli.rs`](../apps/rocm/src/cli.rs); its dispatch fn and most of its domain logic — rendering, activation, and manifest import — live in [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs). - [`therock/version.rs`](../apps/rocm/src/therock/version.rs) — full domain extraction, a leaf child of `therock.rs` (split out of it): the version grammar behind runtime selection and update checks. `parse_version` is the strict gate an install is routed on; `parse_version_for_ordering`, `compare_version_strings` and `version_relation` implement the PEP 440 ordering and the "is this a different version" question; `parse_host_version` reads a host-reported ROCm version through the same parser; `runtime_version_display`, `runtime_version_build_date`, `normalize_requested_build_date` and the calendar helpers behind them handle build dates; `is_stable_runtime_version` and the `ParsedVersion`/`VersionOrderKey`/`VersionStage` types back them. The items `therock.rs` and its property-test module use are `pub(super)` (including the `ParsedVersion` and `VersionOrderKey` fields they read); the parsing and calendar helpers behind them are private; and `runtime_version_display` is `pub(crate)`, re-exported by `therock.rs` for the other modules that render versions. Depends on nothing else in `therock`. `therock_version_proptests.rs` stays declared from `therock.rs` because it also reaches update, wheel and registry code. - [`therock/io.rs`](../apps/rocm/src/therock/io.rs) — full domain extraction, a leaf child of `therock.rs` (split out of it): unique scratch directories (`linux_temp_dir`, `windows_temp_dir`), both `pub(super)`. The atomic file writes that used to live here are rocm-core's shared [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs), which [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs), [`therock/update.rs`](../apps/rocm/src/therock/update.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs) call directly. - [`therock/process.rs`](../apps/rocm/src/therock/process.rs) — full domain extraction, a child of `therock.rs` that depends on `therock/io.rs` for scratch directories (split out of `therock.rs`): running and capturing child commands (`run_command*`, `capture_command_output*`, `capture_python_stdout*`, `run_uv_progress_command`, and the Windows temp-file variants with `windows_child_path`), the bounded wait (`wait_with_output_bounded`), the progress-line output with its `--json` suppression guard (`SuppressProgressOutput`, `progress_line`), and unpacking the SDK tarball (`extract_tarball`, `extract_tarball_and_discard_archive`, which is why it sits here and not in `io.rs`: it spawns `tar` through `run_command`). Its `archive_properties` property tests run on Unix only. The process-wide environment lock these tests take is the single `PROCESS_ENV_TEST_LOCK` in [`test_support.rs`](../apps/rocm/src/test_support.rs), shared with the tests left in `therock.rs`. - [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) — full domain extraction, a child of `therock.rs` that depends on rocm-core's [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) for atomic writes and on `slugify` in the parent for cache file names (split out of `therock.rs`): HTTP fetching for installs. `download_text_cached` is the metadata GET with its on-disk etag cache (`CachedHttp*`) and detached-signature verification (`MetadataSignaturePolicy`, `PINNED_METADATA_PUBLIC_KEY_PEM`, the unset trust root that `cargo xtask verify-pinned-keys` checks against the canonical published key, so its path is pinned in `xtask`); `download_file` is the streaming artifact download; `head_content_length` and `preflight_tarball_space` size the download and check free space first; `http_get` is the shared request. `truthy_env` is `pub(crate)` and re-exported by `therock.rs` for [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs); `download_text_cached`, `download_file`, `preflight_tarball_space` and the `CachedHttpText` struct (with its `text` field) that `download_text_cached` returns are `pub(super)` for the install and resolution code that stays in `therock.rs`; everything else is private. - [`therock/source.rs`](../apps/rocm/src/therock/source.rs) — full domain extraction, a child of `therock.rs` that depends only on `therock/version.rs` (split out of `therock.rs`): where an install reads from. `TheRockChannel` (release or nightly) and `SourceLayout` (the canonical stream, or ROCm 10's separately hosted next layout) are the two axes; `resolve_source` maps a pair to the `ResolvedSource` wheel-index and tarball-catalog bases, honouring a `ROCM_CLI_THEROCK_*_BASE` override only behind the explicit opt-in (`therock_base_override_allowed`, `select_base_override`, `env_override_base`); `select_source_layout`, `requested_source_layout` and `next_layout_requested` decide the layout from a pin; `RuntimeVersionSelector` is the version or build date a user pins (`pub(crate)`, re-exported by `therock.rs`). `FamilyResolution` lives here rather than in `therock/family.rs` because choosing the layout reads it; that keeps the dependency one-way, with `family.rs` building on this file. `TheRockChannel`, `SourceLayout`, `ResolvedSource` and `FamilyResolution` (with their methods and fields), `RuntimeVersionSelector`'s `describe` and `matches_version`, `resolve_source`, the three layout functions, and the `THEROCK_SOURCE_LAYOUT_GENERATION` and `THEROCK_NEXT_MIN_MAJOR` constants are `pub(super)` for `therock.rs` and its siblings; the base-override helpers and the other constants (the per-channel and next-layout base URLs, and the next layout's generation tag) are private to this file. - [`therock/family.rs`](../apps/rocm/src/therock/family.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` for `TheRockChannel` and `FamilyResolution` (split out of `therock.rs`): which package family a request targets. `resolve_family` picks it from `--family`, `ROCM_CLI_THEROCK_FAMILY`, a managed runtime or the host GPU, in that order, and refuses a GPU with no ROCm build (`unsupported_host_gpu_message`, `unsupported_requested_target_message`) instead of substituting another family; `family_override_or_recovered_arch` and `raw_arch_agreeing_with_family` recover the exact arch behind a grouped family; `family_resolution_hint` is the recovery text appended when no runtime is found. `resolve_family`, `family_override_or_recovered_arch` and `family_resolution_hint` are `pub(super)`; the rest is private. -- [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` creates, or recreates when the interpreter tag no longer matches, the runtime's virtual environment. `plan_python_launcher` is the same lookup for a caller that must change nothing, an install preview or an update check: it returns a `PlannedPython`, either `Ready` with the interpreter a real install would pick or `WouldPrepareManaged` with the managed Python a real install would prepare and this caller did not, and it raises the refusals the real resolution raises before that step. `python_for_install` is the install's one choice between that and `resolve_python_launcher`, and prints the progress line that names the interpreter; `PlannedPython` also writes the `python_note:` line from the decision itself, `note` for an install preview and `update_note` for an update check, so a note cannot name a version the install will not prepare. `venv_python_path` stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The items `therock.rs` reaches, `plan_python_launcher` with `PlannedPython`'s `wheel_compatibility` and `update_note`, which `therock/update.rs` reads, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. +- [`therock/python.rs`](../apps/rocm/src/therock/python.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/io.rs`, `therock/process.rs` and `therock/source.rs` (split out of `therock.rs`): the Python an install runs on. `python_requirement` maps a `SourceLayout` to the interpreter the layout needs (`PythonRequirement`: wheel tag and `uv` version), which is why `source.rs` had to move first; `resolve_python_launcher` finds one in order of an explicit `ROCM_CLI_PYTHON`, `PATH`, the saved managed Python, then `ensure_managed_python`, which installs one through `uv` and records it in the managed-Python manifest; the resolver reads its environment through `PythonResolverEnv`, so tests steer it with a thread-local override (`OverridePythonResolverEnv`) rather than rewriting `PATH`; `wheel_compatibility_for_python` and `current_platform_wheel_tags` report the wheel tags an interpreter and platform accept (`WheelCompatibility`); `ensure_uv_venv` reuses the runtime's virtual environment when it is a real venv for this folder with the required tag, creates one in a missing or empty folder, and otherwise rebuilds only the venv's own entries in a folder ROCm CLI can show it made (`venv_folder_state`), refusing any other non-empty folder; `dry_run_venv_plan` is the `--dry-run` view of the same decision, read from the folder's files without running anything in it. `plan_python_launcher` is the same lookup for a caller that must change nothing, an install preview or an update check: it returns a `PlannedPython`, either `Ready` with the interpreter a real install would pick or `WouldPrepareManaged` with the managed Python a real install would prepare and this caller did not, and it raises the refusals the real resolution raises before that step. `python_for_install` is the install's one choice between that and `resolve_python_launcher`, and prints the progress line that names the interpreter; `PlannedPython` also writes the `python_note:` line from the decision itself, `note` for an install preview and `update_note` for an update check, so a note cannot name a version the install will not prepare. `venv_python_path` and `managed_format_root` stay in `therock.rs` for good, with the other keys and roots helpers, and this module reads them from there. The items `therock.rs` reaches, `plan_python_launcher` with `PlannedPython`'s `wheel_compatibility` and `update_note`, which `therock/update.rs` reads, and `split_runtime_path`, which `therock/probe.rs` reads, are `pub(super)`; the rest is private, including `ensure_managed_python` and `resolve_python_launcher_in` (the resolver's entry point that takes its environment as an argument). Its Unix-only tests drive fake interpreters and `uv` scripts. - [`therock/probe.rs`](../apps/rocm/src/therock/probe.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/process.rs` and `therock/python.rs` (split out of `therock.rs`): asking an installed runtime about itself through its own interpreter. `probe_rocm_sdk_runtime` runs `ROCM_SDK_PROBE_SCRIPT` and parses what `rocm_sdk` reports into the `RocmSdkPythonProbe` that [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) owns and validates; `probe_runtime_devices` runs `RUNTIME_DEVICE_PROBE_SCRIPT` to count the devices the runtime's torch can open and whether one can run a kernel (`RuntimeDeviceProbe`); `probe_torch_alignment` reads the installed torch and the one an engine pins from distribution metadata without importing torch (`TorchAlignmentProbe`); and `split_local_version`, `requirement_pinned_version` and `install_pinned_package` are the torch-pin helpers [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) uses to put the SDK's torch back after an engine install. The `pub(crate)` items are re-exported by `therock.rs` for [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and [`runtimes_cmd.rs`](../apps/rocm/src/runtimes_cmd.rs); `probe_rocm_sdk_runtime_for_target`, which `install_wheel_runtime` calls with the device payload it just chose, is `pub(super)`. - [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) — a child of `therock.rs` that holds no logic (split out of `therock.rs`): only the `mod` declarations for the artifact-resolution modules under `therock/resolve/` and the `pub(super) use` lines through which `therock.rs` reads them. It is the parent the `resolve/` files hang from, so a module there is `pub(in crate::therock)` for the items `therock.rs` reaches and private otherwise. - [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/fetch.rs`, `therock/family.rs`, `therock/source.rs` and `therock/version.rs` (split out of `therock.rs`): resolving the SDK tarball a request installs. `resolve_tarball_artifact` (and `resolve_tarball_artifact_with_timeout`, which takes the metadata download timeout) resolves the family and source layout, downloads the catalog through the cached metadata fetch, and returns the `TarballArtifact` it chose; `parse_tarball_index_html` reads the catalog's embedded file list into `TarballIndexFile`s and `validate_tarball_file_name` refuses an entry that is not a plain file name; `select_tarball_candidate` picks the newest archive the request can install, with `tarball_family_token` spelling the family the way the next layout's catalog does. `platform_tarball_token`, which names the archives' platform, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. Only `resolve_tarball_artifact*` and `TarballArtifact` are visible beyond this file. - [`therock/resolve/wheel.rs`](../apps/rocm/src/therock/resolve/wheel.rs) — full domain extraction, a child of `therock/resolve.rs` that builds on `therock/family.rs`, `therock/fetch.rs`, `therock/process.rs`, `therock/python.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for `WheelRuntimeComposition` (split out of `therock.rs`): resolving the wheel stack a request installs. `resolve_pip_runtime` (and `resolve_pip_runtime_with_timeout`, which takes the metadata download timeout and an optional source layout) resolves the family and the layout, reads the aggregate root, decides the device payload and returns a `PipRuntimeResolution`; on the canonical layout `select_matching_pip_package_versions` then takes the newest `rocm` whose `torch`, `torchvision` and `torchaudio` listings agree, and on the next layout `torchaudio_pin` pins a torchaudio first (the hardware-verified release when it is published, read from the vLLM engine's table) and `resolve_published_pip_package_versions` has `uv pip compile` choose the rest. That compile is the one step that may fetch `uv`, so who may is decided in one pure function, [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs)'s `plan_version_resolution`, which takes the layout, a `UvAccess` and whether a `uv` is present, and answers scrape the indexes (canonical), compile with a `UvChoice` (acquire the managed `uv`, or use the present one) or skip. `resolve_pip_runtime` and `resolve_pip_runtime_with_timeout` (a real install and `rocm update`) are always `UvAccess::Acquire`, which never skips and never asks whether a `uv` is present; `preview_pip_runtime` is `UvAccess::PresentOnly`, which uses a present `uv` (`rocm_core::find_uv_binary`) and otherwise returns `PipRuntimePlan::NeedsUv` holding an `UnresolvedPipRuntime`: what was chosen without `uv` (the `rocm` version, the torchaudio pin, the requirements `uv` would be given) and no package versions, so nothing made from them can be built from it. `wheel.rs` acts on the answer; the real `find_uv_binary` and `ensure_uv_binary` reach it through a `UvPolicy` so that a test can count the calls. `wheel_runtime_composition` turns a resolution into the exact package specs (`therock_pip_package_specs`) an install gives `uv` and records in the manifest, `published_pip_requirements` is the matching requirement set for `uv pip compile`, and `canonical_auto_select_needs_next_python` peeks at the channel's own `rocm` listing so the interpreter can be picked before resolution. Beneath that, `parse_aggregate_package_links` and `parse_aggregate_device_targets` read the package links of the canonical aggregate root and the exact device targets it publishes, and `validate_aggregate_index_layout` refuses a root that lacks the expected packages or any device payload; `AggregateDeviceTarget::resolve` picks the one exact target a host gets, or records why it could not (`Undetermined`), and `AggregateDeviceTarget::prefer_recorded` is the one place a recorded target (an update apply's, or the one a runtime's manifest was built with) replaces the detected one, called by `therock.rs`, `therock/update.rs` and `therock/wheel_plan.rs`; `load_simple_index_versions` fetches a package's simple-index listing through the cached metadata download and `parse_simple_index_versions` reads the versions out of it, dropping wheels the interpreter's tags do not accept when given them (`wheel_stem_matches_compatibility` and the `wheel_*_tag_matches` helpers); `package_release_key` orders the PEP 440 versions found there (`PackageReleaseKey`). `slugify`, which keys the cached listing, stays in `therock.rs` for good, with the other keys and roots helpers, and this module reads it from there. The functions and types `therock.rs` and `therock/update.rs` name are `pub(in crate::therock)` and reach them through `therock/resolve.rs`; `PipRuntimeResolution` and `TheRockPipPackageVersions` are `pub(in crate::therock)` with the fields they read, and `TorchaudioPin` with its `describe`, so they can use what `resolve_pip_runtime` returns without naming the types; the rest is private. - [`therock/resolve/uv_access.rs`](../apps/rocm/src/therock/resolve/uv_access.rs) — full domain extraction, a leaf child of `therock/resolve.rs` that builds only on `therock/source.rs` for `SourceLayout` (split out of `therock/resolve/wheel.rs` to keep it within the module-size limit): who may fetch `uv` while a wheel stack is resolved. `UvAccess` says how far a resolution may go (`Acquire`, what a real install and `rocm update` pass, or `PresentOnly`, a preview's), `plan_version_resolution` turns that, the layout and whether a `uv` is present into a `VersionResolution` (scrape the indexes, compile with a `UvChoice`, or skip) without touching anything, and `uv_for_compile` hands the compile step the `uv` it runs, acquiring it only on `Acquire`, with the context a failed fetch has always carried. `UvPolicy` carries the access and the two real lookups (`find_uv_binary`, `ensure_uv_binary`) as closures so a test can count what a resolution asks for. Everything is `pub(super)` and read by `wheel.rs`; the state matrix over layout, access and presence lives in this module's tests. - [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private. -- [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) — full domain extraction, a leaf child of `therock.rs` (split out of `install_wheel_runtime`) that builds on `therock/python.rs` and `therock/resolve.rs` for the Python decision and the resolution it prints: the `sdk install` plan a wheel install prints, key by key. `WheelPlan` carries the facts, `write_wheel_plan` writes the lines a preview and a real install share, and `write_dry_run_tail` the lines only a preview adds (the `uv` commands it would run and the manifest path). `PlanStack` is the one place the plan differs: `Resolved` carries the package specs, runtime key, install folder and manifest path, and `NeedsUv` (a ROCm 10 preview on a host with no `uv`, see `UnresolvedPipRuntime` in `therock/resolve/wheel.rs`) prints those as `not resolved by this preview` and adds the `resolution_note:` line, so one writer serves both and a line the plan gains appears in both. `unresolved_wheel_preview` renders the second kind whole. `therock.rs` reads it through `pub(super)` items; it reads the provenance, host-note and `venv_python_path` helpers back from `therock.rs`. +- [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) — full domain extraction, a leaf child of `therock.rs` (split out of `install_wheel_runtime`) that builds on `therock/python.rs` and `therock/resolve.rs` for the Python decision and the resolution it prints: the `sdk install` plan a wheel install prints, key by key. `WheelPlan` carries the facts, `write_wheel_plan` writes the lines a preview and a real install share, and `write_dry_run_tail` the lines only a preview adds (what the venv step would do, from `therock/python.rs`'s `dry_run_venv_plan`, which reads the install folder's files and runs nothing from it; the `uv` commands it would run; and the manifest path). `PlanStack` is the one place the plan differs: `Resolved` carries the package specs, runtime key, install folder and manifest path, and `NeedsUv` (a ROCm 10 preview on a host with no `uv`, see `UnresolvedPipRuntime` in `therock/resolve/wheel.rs`) prints those as `not resolved by this preview` and adds the `resolution_note:` line, so one writer serves both and a line the plan gains appears in both. `unresolved_wheel_preview` renders the second kind whole. `therock.rs` reads it through `pub(super)` items; it reads the provenance, host-note and `venv_python_path` helpers back from `therock.rs`. - [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests and on rocm-core's [`atomic_write.rs`](../crates/rocm-core/src/atomic_write.rs) for the startup-check record (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and, with `RuntimeUpdatePlan`, which [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) reads its verdict from, re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private. - [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`, and `RestoredEnv`, which sets or removes process environment variables for one test and puts them back on drop, so a caller holds `PROCESS_ENV_TEST_LOCK` for as long as it holds one). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`. - [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) — the chat assistant's tool-call policy: which `rocm` commands and bridge tools a model may request, which run immediately and which need the user's approval first. It owns `ChatRocmCommandAction` (read-only, or approval with the titles the approval prompt shows) and `ChatToolApprovalRequest`, the validators (`validate_chat_tool_call`, the `validate_chat_*_tool_call` family, `validate_required_chat_string`, `validate_optional_chat_integer`, `reject_control_characters_in_tool_arguments` (which refuses a model-supplied tool name or argument carrying a terminal control character, for every tool except `rocm_command`, whose argv `normalized_chat_rocm_command_args` screens entry by entry), `validate_serve_command_safety`, the four rules a model-proposed `serve` must satisfy (no public bind, no CPU device, a loopback host, `--managed` without `--foreground`), and `validate_chat_rocm_command_safety`, which applies them to a `serve` argv and also refuses a system install folder (`chat_install_prefix_is_system`)), the classifiers (`chat_rocm_command_action`, `chat_rocm_command_action_from_args`, `chat_install_driver_action`, `canonicalize_chat_rocm_command`, `normalized_chat_rocm_command_args`, `chat_tool_call_is_read_only`), `chat_tool_approval_request`, and the readers that turn a tool call into its argv and one-line command (`rocm_chat_tool_requested_args`, `rocm_chat_tool_requested_command`, with `push_optional_json_cli_arg` and `json_string`). It moved verbatim from `chat.rs` with the tests that exercise only these items. It depends on [`rocm_argv.rs`](../apps/rocm/src/rocm_argv.rs), `providers::ChatToolCall`, `service_launch::is_loopback_host`, `services_text::validate_service_id`, `shell_quote::has_terminal_control_character`, `therock::RuntimeVersionSelector` and `driver_install::host_install_driver_only_reports`, none of which imports `chat`, so `freeform_planner.rs` calls `validate_serve_command_safety` and `validate_chat_rocm_command_safety` here instead of through `chat`, and keeps no copy of the serve rules. `chat.rs`'s child modules call into it and `chat.rs` re-exports `validate_chat_tool_call`, `chat_tool_call_is_read_only` and `chat_tool_approval_request` (read by `dash_seam.rs`), and `ChatRocmCommandAction`, `chat_install_driver_action`, `chat_rocm_command_action_from_args` and `rocm_chat_tool_requested_args`, which only other modules' tests read as `crate::chat::` (`driver_plan.rs`, `system_packages.rs`). diff --git a/docs/testing.md b/docs/testing.md index 81010ee025..40824e1ef6 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -928,7 +928,9 @@ covers `PATH`, an absolute `ROCM_CLI_PYTHON` and a bare one resolved through by the preview and by the install, and the advised empty folder works), `runtime-30` (a rebuild of a folder ROCm CLI made keeps the ComfyUI data and says why the old venv was not reused) and `runtime-31` (a preview of a folder -holding someone else's venv says it cannot tell and runs nothing) run the real +holding someone else's venv says it cannot tell and runs nothing) and +`runtime-32` (a preview whose `ROCM_CLI_PYTHON` is inside the folder stops +without running it) run the real CLI with a loopback index, a fake `uv` and planted Pythons that record every run. They are Linux-only because those stand-ins are shell scripts; the guard code is platform-neutral and the Windows CI job builds it, but no Windows test diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index cf6345601e..3bed55ea9a 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -698,3 +698,18 @@ Feature: Runtime configuration And the user's folder holds a Python environment ROCm CLI did not make When the user previews installing the SDK into that folder Then the preview says it cannot tell whether that environment is reused, runs nothing from the folder, and changes nothing + + # The same rule for the Python a preview checks before anything else: when it + # is inside the install folder (here `ROCM_CLI_PYTHON` names the folder's own + # `bin/python`; the same holds for one found on `PATH`), the preview stops + # rather than run it, and says why. The planted Python records every run, and + # the Then checks the record together with the message. Same hermetic setup + # and Linux-only reason as runtime-29; the `PATH` and bare-name cases are unit + # tested by `a_dry_run_runs_no_python_from_the_install_folder_while_searching`. + @id:runtime-install-preview-stops-at-prefix-python @requires-os:linux + Scenario: runtime-32 - Previewing an SDK install whose Python is inside the install folder stops without running it + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + And the user's folder holds a Python environment ROCm CLI did not make + When the user previews installing the SDK into that folder with that folder's Python as ROCM_CLI_PYTHON + Then the install fails + And the preview stops without running that Python and says why diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 5df02cbb49..65f27eca47 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -2240,6 +2240,21 @@ fn install_sdk_into(world: &mut E2eWorld, folder: &Path) { } fn run_sdk_install_into(world: &mut E2eWorld, folder: &Path, dry_run: bool) { + let launcher = root(world).join("fake-python").join("python3.14"); + write_executable( + &launcher, + "#!/bin/sh\nif [ \"$1\" = -c ]; then echo cp314; fi\nexit 0\n", + ); + run_sdk_install_into_with_python(world, folder, dry_run, &launcher); +} + +/// [`run_sdk_install_into`], with `ROCM_CLI_PYTHON` naming `python`. +fn run_sdk_install_into_with_python( + world: &mut E2eWorld, + folder: &Path, + dry_run: bool, + python: &Path, +) { let uv = root(world).join("fake-uv").join("uv"); write_executable( &uv, @@ -2279,18 +2294,13 @@ exit 1 "# ), ); - let launcher = root(world).join("fake-python").join("python3.14"); - write_executable( - &launcher, - "#!/bin/sh\nif [ \"$1\" = -c ]; then echo cp314; fi\nexit 0\n", - ); let home = install_folder(world, USER_HOME_FOLDER); world .command_env .push(("ROCM_CLI_UV_BINARY", uv.into_os_string())); world .command_env - .push(("ROCM_CLI_PYTHON", launcher.into_os_string())); + .push(("ROCM_CLI_PYTHON", python.as_os_str().to_owned())); world.command_env.push(("HOME", home.into_os_string())); // `command_env` is consumed by each command, so the fixture index the // `Given` pointed the CLI at has to be named again for every run here, or @@ -2473,6 +2483,32 @@ async fn preview_sdk_install_into_cloned_venv(world: &mut E2eWorld) { run_sdk_install_into(world, &folder, true); } +#[when( + "the user previews installing the SDK into that folder with that folder's Python as ROCM_CLI_PYTHON" +)] +async fn preview_sdk_install_with_python_from_folder(world: &mut E2eWorld) { + let folder = install_folder(world, CLONED_VENV_FOLDER); + let python = folder.join("bin").join("python"); + run_sdk_install_into_with_python(world, &folder, true, &python); +} + +#[then("the preview stops without running that Python and says why")] +async fn preview_stops_before_running_folder_python(world: &mut E2eWorld) { + let folder = install_folder(world, CLONED_VENV_FOLDER); + let reported = reported(world); + assert_ne!(world.cli_rc, Some(0), "the preview succeeded:\n{reported}"); + assert!( + reported.contains(&format!( + "this preview did not check the Python from ROCM_CLI_PYTHON at {}: it is inside the install folder {}, and a preview runs nothing from the install folder", + folder.join("bin").join("python").display(), + folder.display() + )), + "the preview did not say why it stopped:\n{reported}" + ); + assert_no_prefix_python_ran(world, &reported); + assert!(folder.join("bin").join("python").is_file() && folder.join("pyvenv.cfg").is_file()); +} + #[then( "the preview says it cannot tell whether that environment is reused, runs nothing from the folder, and changes nothing" )] From 2ae9ebdfd9aff92f85db4397d8acf80b7567be0a Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 10 Nov 2026 12:00:00 +0200 Subject: [PATCH 11/15] test(therock): pin reuse at a bin-only stop and test the decision on Windows Follow-ups from a second automated review: - The `PartOfBinKeepingPython` clear stop leaves a whole venv, so it is reused rather than rebuilt, and the convergence test passed whichever way it went. Every stop now asserts which way it converges: that one is reused, every other one is rebuilt through uv. - The folder decision (empty, refused with the condition named, owned by the wheel marker) reads only files. A new test runs it on every platform with that platform's venv layout, so the Windows job covers it; the tests that run an interpreter stay Unix-only. - The e2e steps write their stand-in scripts through `rocm_core::fake_executable::write_fake_executable`, which avoids the ETXTBSY race a plain write and chmod can hit under the suite's concurrency. - README and docs/manual-testing.md quote the refused folder's `command:` line as it is printed. Signed-off-by: Roman Inflianskas --- README.md | 5 +- apps/rocm/src/therock/python.rs | 97 ++++++++++++++++++- docs/manual-testing.md | 3 +- docs/testing.md | 9 +- tests/e2e-cucumber/tests/e2e/therock_steps.rs | 15 +-- 5 files changed, 116 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 6f52ddd46e..5e24e3d924 100644 --- a/README.md +++ b/README.md @@ -547,8 +547,9 @@ install finished, instead. `--dry-run` runs nothing from the install folder, since the folder can hold any `bin/python`. It reads the folder's files and reports which of these will -happen, with `command: none` and the install's refusal for a folder the install -would refuse. Whether a folder holding both a Python and `pyvenv.cfg` would be +happen, with `command: none; the install will refuse this folder` and a +`refusal:` line holding the install's message for a folder the install would +refuse. Whether a folder holding both a Python and `pyvenv.cfg` would be reused depends on running that Python, so the preview says it cannot tell and shows both outcomes. If the Python the preview would check first (on `PATH`, or `ROCM_CLI_PYTHON`) is inside the `--prefix` folder, it stops and says it did not diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 9866834725..5f58d41b10 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -4159,7 +4159,10 @@ exit 1 CfgAndCacheTag, /// Part of `bin` removed, the interpreter among it. PartOfBinWithPython, - /// Part of `bin` removed, the interpreter still there. + /// Part of `bin` removed (`activate`), the interpreter and + /// `pyvenv.cfg` still there. Nothing the venv needs is gone, so the + /// next run must reuse it, not rebuild it: this is the stop that pins + /// that a part-way clear of `bin` alone does not cost a rebuild. PartOfBinKeepingPython, /// All of `bin` removed. WholeBin, @@ -4226,6 +4229,15 @@ exit 1 fs::remove_file(log).ok(); ensure_uv_venv(&paths, uv, launcher, &install_root) .unwrap_or_else(|e| panic!("{what}: {e:#}")); + // Which way each stop converges: only the stop that left a whole + // venv is reused; every other one is rebuilt through uv. + let rebuilt = fs::read_to_string(log) + .is_ok_and(|calls| calls.lines().any(|line| line.starts_with("venv "))); + assert_eq!( + rebuilt, + !matches!(stop, ClearStop::PartOfBinKeepingPython), + "{what}: rebuilt={rebuilt}" + ); assert!( install_root.join("pyvenv.cfg").is_file(), "{what}: no pyvenv.cfg" @@ -4267,6 +4279,89 @@ exit 1 } } + /// The ownership and shape decisions read only files, so they are tested on + /// every platform, the Windows CI job included, with `venv_python_path`'s + /// own layout (`Scripts\\python.exe` there, `bin/python` elsewhere). The + /// interpreter is an empty file nothing runs. Covers what the Unix tests + /// drive through shell stand-ins: an empty folder, someone else's folder + /// refused with the condition named and the folder untouched, a venv shape + /// missing `pyvenv.cfg`, and a folder the wheel marker proves ROCm CLI made. + #[test] + fn the_venv_folder_decision_reads_files_on_every_platform() { + static SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + let root = std::env::temp_dir().join(format!( + "rocm-cli-venv-decision-{}-{}-{}", + std::process::id(), + unix_time_millis(), + SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + )); + fs::create_dir_all(root.join("data")).unwrap(); + let paths = AppPaths { + config_dir: root.join("config"), + data_dir: root.join("data"), + cache_dir: root.join("cache"), + }; + let plant_python = |folder: &Path| { + let python = venv_python_path(folder); + fs::create_dir_all(python.parent().unwrap()).unwrap(); + fs::write(&python, b"").unwrap(); + python + }; + + let missing = root.join("missing"); + assert_eq!( + venv_folder_state(&paths, &missing, "files").unwrap(), + VenvFolder::Empty + ); + + let cloned = root.join("cloned"); + let python = plant_python(&cloned); + fs::write(cloned.join("notes.txt"), b"the user's").unwrap(); + let finding = venv_shape_finding(&cloned).expect("no pyvenv.cfg is certain"); + assert_eq!( + finding, + format!( + "a Python at {} with no pyvenv.cfg beside it", + python.display() + ) + ); + let refusal = venv_folder_state(&paths, &cloned, &finding) + .unwrap_err() + .to_string(); + assert!(refusal.contains(&format!("(found {finding};")), "{refusal}"); + assert!(refusal.contains("no .rocm-cli-runtime.json"), "{refusal}"); + assert_eq!( + fs::read(cloned.join("notes.txt")).unwrap(), + b"the user's", + "a refusal changes nothing" + ); + + fs::write(cloned.join("pyvenv.cfg"), b"home = x").unwrap(); + assert_eq!( + venv_shape_finding(&cloned), + None, + "both files: only running it could tell" + ); + + let owned = root.join("owned"); + plant_python(&owned); + let marker = serde_json::json!({ + "runtime_key": "release-wheel-x", + "format": "wheel", + "install_root": owned, + }); + fs::write( + owned.join(".rocm-cli-runtime.json"), + serde_json::to_vec(&marker).unwrap(), + ) + .unwrap(); + assert_eq!( + venv_folder_state(&paths, &owned, "files").unwrap(), + VenvFolder::Owned + ); + fs::remove_dir_all(root).ok(); + } + /// The reuse check alone already refuses a Python without `pyvenv.cfg`; /// this order is the second layer `VENV_OWNED_ENTRIES` documents, and no /// convergence test can see it because the first layer holds. Pin it here. diff --git a/docs/manual-testing.md b/docs/manual-testing.md index a4e2b9f484..f057c23791 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -211,7 +211,8 @@ Expected result: that writes a file when run, and after the preview that file does not exist. It reads the folder's files instead. For your home folder with a broken `~/bin/python` and no `pyvenv.cfg`, `python_env:` says - `the install will refuse this folder`, `command:` is `none`, and a + `the install will refuse this folder`, `command:` is + `none; the install will refuse this folder`, and a `refusal:` line gives the install's message. For a folder with both a Python and `pyvenv.cfg`, it cannot tell without running that Python whether the venv would be reused, so `python_env:` says so, `command:` shows only the diff --git a/docs/testing.md b/docs/testing.md index 40824e1ef6..5776103098 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -932,9 +932,12 @@ holding someone else's venv says it cannot tell and runs nothing) and `runtime-32` (a preview whose `ROCM_CLI_PYTHON` is inside the folder stops without running it) run the real CLI with a loopback index, a fake `uv` and planted Pythons that record every -run. They are Linux-only because those stand-ins are shell scripts; the guard -code is platform-neutral and the Windows CI job builds it, but no Windows test -runs a preview against a planted interpreter. +run. They are Linux-only because those stand-ins are shell scripts. The +folder decision itself (empty, refused with the condition named, owned by the +wheel marker) reads only files, so +`the_venv_folder_decision_reads_files_on_every_platform` runs it on every +platform, the Windows CI job included, with that platform's venv layout; no +Windows test runs a preview or a rebuild against a planted interpreter. Then it verifies: diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 65f27eca47..4544c04083 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -2179,14 +2179,17 @@ fn install_folder(world: &E2eWorld, name: &str) -> std::path::PathBuf { .expect("failed to canonicalize install folder") } +/// Written through [`rocm_core::fake_executable::write_fake_executable`], not +/// `fs::write` and a chmod: a script exec'd while another thread's fork still +/// holds it open for writing fails with ETXTBSY, and the shared helper is the +/// one that avoids that race under the suite's concurrency. fn write_executable(path: &Path, body: &str) { - write_fixture(path, body); - #[cfg(unix)] - { - use std::os::unix::fs::PermissionsExt; - std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)) - .unwrap_or_else(|e| panic!("failed to chmod {}: {e}", path.display())); + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent) + .unwrap_or_else(|e| panic!("failed to create {}: {e}", parent.display())); } + rocm_core::fake_executable::write_fake_executable(path, body) + .unwrap_or_else(|e| panic!("failed to write {}: {e}", path.display())); } /// A Python that fails, and first appends a line to [`prefix_python_log`] so a From d80c8c31ac64d75fc77cda51c59829d17684ce23 Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Tue, 10 Nov 2026 12:08:08 +0200 Subject: [PATCH 12/15] test(therock): call cat by absolute path in the fake uv The fake uv the venv tests run wrote the stand-in Python with a bare `cat`, while its other commands use `/bin/...`. A test elsewhere in the crate empties PATH for a moment, and a fake uv started in that window found no `cat`, created the Python as an empty file and left the next exec failing with "Exec format error". `/bin/cat` takes PATH out of it. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/python.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 5f58d41b10..edf347e8b0 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -3220,7 +3220,7 @@ if [ "$1" = "venv" ] && [ "$2" = "--python" ]; then fi fi /bin/mkdir -p "$target/bin" - cat > "$target/bin/python" < "$target/bin/python" < Date: Mon, 16 Nov 2026 13:41:39 +0200 Subject: [PATCH 13/15] fix(therock): keep the preview static under the torch opt-out; accept a relative Python Answers the review of d80c8c3 and adapts this branch to what main added since (the torch-alignment opt-out in the SDK install). - With ROCM_CLI_DISABLE_TORCH_ALIGNMENT set, a dry run asked the install folder's own Python which torch it held, so a preview ran a bin/python from a model-chosen --prefix. A preview now runs nothing from the folder: its commands install the full stack, as the install does for a venv it creates or rebuilds, and where reuse cannot be decided from the files a torch_kept: line says it cannot tell which torch would be kept. The preview's commands and a real rebuild therefore name the same requirements. - The python -m venv support probe starts in a folder of its own, so an interpreter given relative to the user's folder (ROCM_CLI_PYTHON= .venv/bin/python) was looked up from there and reported unusable. The path is anchored to the current directory first; a bare name is left to PATH. - The preview printed UV_VENV_CLEAR=0 as a command prefix, which only POSIX shells accept. It is now an env: line beside the uv venv command, and a refused folder prints command: none. - Unit-test stand-ins go through write_fake_executable, the two untested reuse failures (no sys.prefix, no wheel tag) get rows, and the Unix-only fixtures' imports are gated so the Windows build stays clean. - New scenarios runtime-37 (opt-out preview runs nothing) and runtime-38 (relative ROCM_CLI_PYTHON); docs updated to match. Signed-off-by: Roman Inflianskas --- README.md | 25 ++-- apps/rocm/src/therock.rs | 27 ++-- apps/rocm/src/therock/kept_torch.rs | 13 ++ apps/rocm/src/therock/python.rs | 72 +++++++++- apps/rocm/src/therock/resolve/wheel.rs | 129 ++++++++++++------ apps/rocm/src/therock/test_support.rs | 11 +- apps/rocm/src/therock/venv.rs | 118 ++++++++++------ apps/rocm/src/therock/wheel_plan.rs | 36 ++--- docs/architecture.md | 8 +- docs/manual-testing.md | 33 +++-- docs/testing.md | 36 +++-- docs/vllm.md | 6 +- .../features/runtime_setup.feature | 24 ++++ tests/e2e-cucumber/tests/e2e/therock_steps.rs | 83 ++++++++++- 14 files changed, 461 insertions(+), 160 deletions(-) diff --git a/README.md b/README.md index 24895f1536..f678ea6c2a 100644 --- a/README.md +++ b/README.md @@ -660,13 +660,18 @@ install finished, instead. `--dry-run` runs nothing from the install folder, since the folder can hold any `bin/python`. It reads the folder's files and reports which of these will -happen, with `command: none; the install will refuse this folder` and a -`refusal:` line holding the install's message for a folder the install would -refuse. Whether a folder holding both a Python and `pyvenv.cfg` would be -reused depends on running that Python, so the preview says it cannot tell and -shows both outcomes. If the Python the preview would check first (on `PATH`, or -`ROCM_CLI_PYTHON`) is inside the `--prefix` folder, it stops and says it did not -run it. +happen, with `command: none` and a `refusal:` line holding the install's +message for a folder the install would refuse. Whether a folder holding both a +Python and `pyvenv.cfg` would be reused depends on running that Python, so the +preview says it cannot tell and shows both outcomes. A previewed `uv venv` +command is followed by an `env:` line naming the `UV_VENV_CLEAR=0` the install +sets for it, rather than a `VAR=value` prefix only POSIX shells accept. The +commands shown install the full torch stack. With +`ROCM_CLI_DISABLE_TORCH_ALIGNMENT` set, a venv the install reuses keeps the +torch it holds, so where the preview cannot tell whether the venv is reused a +`torch_kept:` line says it cannot tell which torch would be kept. If a Python the preview would check (`ROCM_CLI_PYTHON`, +the first on `PATH`, or the saved managed Python) is inside the `--prefix` +folder, it stops and says it did not run it. ROCm CLI never runs `uv venv` over a folder that has anything in it without `--allow-existing`, and sets `UV_VENV_CLEAR=0` for that command, so neither @@ -726,9 +731,9 @@ The `--dry-run` preview downloads no `uv` and creates no `tools` folder. For ROC 10 and newer, `uv pip compile` is what chooses the `torch` and `torchvision` versions, so the preview runs a `uv` that is already installed and gives the complete plan. With none installed it can't, and it says so in a -`resolution_note:` line: the package specs, runtime key, install folder, manifest -and `command:` (everything made from those versions) read `not resolved by this -preview`, and a real install fetches `uv` and resolves them. +`resolution_note:` line: the package specs, runtime key, install folder, manifest, +`python_env:`, `command:` and `env:` (everything made from those versions) read +`not resolved by this preview`, and a real install fetches `uv` and resolves them. A family label such as `--family gfx120X-all` is rejected for those versions instead of being resolved to a guess, because the ROCm 10 packages publish one diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index b7fde058e2..8a5a541dc7 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -494,13 +494,20 @@ fn install_wheel_runtime( &resolution.latest_version, ); // Under the alignment opt-out an environment that already holds torch keeps it: - // the install then asks `uv` for the ROCm packages alone. Decided here, from the - // environment the install will run in, so the preview and the install name the - // same requirements. + // the install then asks `uv` for the ROCm packages alone. Only running the + // environment's Python can tell which torch it holds, and a preview runs nothing + // from the install folder, so a preview shows the full command and, where the + // venv may be reused, says it cannot tell; a real install asks here and again + // once the environment is prepared. let planned_env_python = venv_python_path(&install_root); - let planned_kept = kept_torch::kept_torch_stack(rocm_core::torch_alignment_disabled(), || { - kept_torch::installed_torch_stack(&planned_env_python) - }); + let torch_alignment_disabled = rocm_core::torch_alignment_disabled(); + let planned_kept = if dry_run { + None + } else { + kept_torch::kept_torch_stack(torch_alignment_disabled, || { + kept_torch::installed_torch_stack(&planned_env_python) + }) + }; let plan = WheelPlan { channel, version_selector, @@ -521,10 +528,10 @@ fn install_wheel_runtime( install_root: &install_root, runtime_key: &runtime_key, package_specs: &wheel_composition.package_specs, - // A real install decides again once the environment is prepared (it may - // be recreated and lose its torch), and writes the one `torch_kept:` line - // then; a preview cannot know, so it prints the plan's. - kept_torch: if dry_run { planned_kept.as_ref() } else { None }, + // A real install writes its one `torch_kept:` line once the environment + // is prepared (it may be recreated and lose its torch); a preview says + // what it could not tell. + torch_alignment_disabled, manifest_path: &manifest_path, }), }; diff --git a/apps/rocm/src/therock/kept_torch.rs b/apps/rocm/src/therock/kept_torch.rs index f50136a91d..ca4216077c 100644 --- a/apps/rocm/src/therock/kept_torch.rs +++ b/apps/rocm/src/therock/kept_torch.rs @@ -109,6 +109,19 @@ pub(super) fn plan_line(kept: &KeptTorch) -> String { ) } +/// The `torch_kept:` line a preview prints under the opt-out when the folder's +/// venv may be reused: the install would then keep the torch that venv holds, +/// and only running its Python could say which. A preview runs nothing from the +/// install folder, so the line says it cannot tell. Every other preview plan +/// creates or rebuilds the venv, or refuses the folder, so nothing is kept there +/// and no line is printed. +pub(super) fn preview_line(env_python: &Path) -> String { + format!( + " torch_kept: cannot tell; ROCM_CLI_DISABLE_TORCH_ALIGNMENT is set, so if the venv whose Python is {} is reused and holds torch, the install keeps that torch and hands uv only the ROCm packages, without the torch, torchvision and torchaudio requirements the commands shown include; this preview runs nothing from the install folder, so it does not know which torch that venv holds", + env_python.display() + ) +} + /// The one `torch_kept:` line a real install prints, once the environment is /// prepared: the plan's line when the torch is kept, an explanation when the /// environment was recreated and the torch the plan counted on is gone. diff --git a/apps/rocm/src/therock/python.rs b/apps/rocm/src/therock/python.rs index 3bbe1e17ea..45469076ed 100644 --- a/apps/rocm/src/therock/python.rs +++ b/apps/rocm/src/therock/python.rs @@ -1109,8 +1109,9 @@ fn verify_python_can_create_venv(program: &Path) -> Result<()> { let probe_root = python_venv_probe_temp_root()?; let probe_dir = probe_root.join("env"); let args = python_venv_args(&probe_dir); + let program = anchored_to_current_dir(program); let result = run_command_in( - program, + &program, args.iter() .map(String::as_str) .collect::>() @@ -1122,6 +1123,21 @@ fn verify_python_can_create_venv(program: &Path) -> Result<()> { result } +/// `program` as a path that still names the same file once a child is started +/// in another folder. On Unix a program path that has a directory part +/// (`.venv/bin/python`, as `ROCM_CLI_PYTHON` or a relative `PATH` entry gives +/// one) is resolved against the child's working directory, so the probe's own +/// folder would otherwise stand in for the user's; Windows resolves it +/// differently, and an absolute path means the same on both. A bare name +/// (`python3`) is left alone: it is looked up on `PATH`, not in a folder, and +/// anchoring it would stop that. +fn anchored_to_current_dir(program: &Path) -> PathBuf { + if program.is_absolute() || program.components().count() < 2 { + return program.to_path_buf(); + } + std::path::absolute(program).unwrap_or_else(|_| program.to_path_buf()) +} + fn python_venv_probe_temp_root() -> Result { if runtime_is_windows() { windows_temp_dir("rocm-cli-python-venv-probe") @@ -2950,4 +2966,58 @@ echo Python 3.12.10 assert!(!ran_in.exists(), "the probe's folder is removed afterwards"); fs::remove_dir_all(root).ok(); } + + /// `ROCM_CLI_PYTHON=.venv/bin/python` reaches the probe as a relative path + /// that works from the user's directory. The probe starts in a folder of its + /// own, so the path has to be anchored first or the launch fails and a Python + /// that works is reported as unusable. The relative path starts with `src/`, + /// which the test's working directory (the crate root) has and the probe's + /// fresh folder does not, so it names nothing from the probe's folder however + /// deep the temp folder is; the process's directory is not changed. + #[test] + #[cfg(unix)] + fn the_venv_probe_accepts_an_interpreter_given_as_a_relative_path() { + let (root, _paths) = venv_rebuild_sandbox("probe-relative"); + let python = root.join("python3"); + rocm_core::fake_executable::write_fake_executable( + &python, + "#!/bin/sh\nif [ \"$1\" = \"-m\" ]; then /bin/mkdir -p \"$3\"; fi\nexit 0\n", + ) + .unwrap(); + let cwd = std::env::current_dir().unwrap(); + assert!( + cwd.join("src").is_dir(), + "cargo runs tests from the crate root" + ); + let mut relative = PathBuf::from("src"); + for _ in cwd.components() { + relative.push(".."); + } + relative.push(python.strip_prefix("/").unwrap()); + assert!(relative.is_relative() && relative.components().count() > 2); + + verify_python_can_create_venv(&relative) + .expect("a relative interpreter that works from here is usable"); + fs::remove_dir_all(root).ok(); + } + + /// What the probe is handed, on every platform: a relative path with a + /// folder in it becomes the same path under the current directory, and a + /// bare name or an absolute path is passed on as it is. + #[test] + fn a_relative_interpreter_path_is_anchored_to_the_current_directory() { + let cwd = std::env::current_dir().unwrap(); + let relative = Path::new(".venv").join("bin").join("python"); + assert_eq!( + anchored_to_current_dir(&relative), + cwd.join(".venv").join("bin").join("python") + ); + assert_eq!( + anchored_to_current_dir(Path::new("python3")), + Path::new("python3"), + "a bare name is looked up on PATH and stays as it is" + ); + let absolute = cwd.join("python3"); + assert_eq!(anchored_to_current_dir(&absolute), absolute); + } } diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index 5c3fb2c4cb..cc9d1f872d 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -2590,6 +2590,7 @@ sdk install mode: dry-run python_env: not resolved by this preview command: not resolved by this preview + env: not resolved by this preview activation: use the managed venv Python; TheRock libraries are resolved from that venv by rocm_sdk.initialize_process manifest: not resolved by this preview " @@ -2668,7 +2669,7 @@ sdk install install_root: &install_root, runtime_key: &runtime_key, package_specs: &composition.package_specs, - kept_torch: None, + torch_alignment_disabled: false, manifest_path: &manifest_path, }), }; @@ -2696,27 +2697,27 @@ sdk install assert!(!resolved.contains("resolution_note"), "{resolved}"); } - /// A kept torch changes what `uv` is handed and nothing the runtime is recorded as. - /// The preview's `command:` is the line a user is invited to run, so it has to - /// leave the torch stack out exactly as the install does, while `package_specs:` - /// stays the composition the manifest and the runtime key are made from. + /// Under the torch-alignment opt-out, the install keeps the torch a reused + /// venv holds, and only running the venv's Python can tell which. A preview + /// runs nothing from the install folder, so every command it shows installs + /// the full composition, and the `torch_kept:` line says it cannot tell in + /// exactly the plans where the venv may be reused. Every other plan creates + /// or rebuilds the venv (nothing to keep) or refuses the folder (nothing + /// runs), so no line is printed there. One row per folder shape, with and + /// without the opt-out; `package_specs:` stays the composition throughout. #[test] - fn a_kept_torch_is_left_out_of_the_command_but_not_out_of_the_composition() { - use super::super::super::kept_torch::{KeptTorch, kept_torch_stack}; + fn a_preview_under_the_alignment_opt_out_cannot_tell_whether_torch_is_kept() { + use super::super::super::venv_python_path; use super::super::super::wheel_plan::{ PlanStack, ResolvedStack, WheelPlan, write_dry_run_tail, write_wheel_plan, }; let resolution = resolved_runtime(); let composition = wheel_runtime_composition(&resolution, &resolution.device_target, false); - let install_root = PathBuf::from("/runtimes/kept"); let manifest_path = PathBuf::from("/manifests/kept"); let (python, compatibility) = clean_host_python(); - let kept = kept_torch_stack(true, || { - Ok(vec![("torch".to_owned(), "2.9.0+gitd0c8b1f".to_owned())]) - }); let (paths_root, paths) = super::super::super::test_support::test_paths("kept-torch"); - let render = |kept: Option<&KeptTorch>| { + let render = |opted_out: bool, install_root: &Path| { let plan = WheelPlan { channel: TheRockChannel::Release, version_selector: None, @@ -2734,10 +2735,10 @@ sdk install no_wheel_warning: None, stack: PlanStack::Resolved(ResolvedStack { compatibility_key: &resolution.package_versions.compatibility_key, - install_root: &install_root, + install_root, runtime_key: "kept", package_specs: &composition.package_specs, - kept_torch: kept, + torch_alignment_disabled: opted_out, manifest_path: &manifest_path, }), }; @@ -2749,38 +2750,80 @@ sdk install let line = |text: &str, key: &str| { text.lines() .find(|line| line.trim_start().starts_with(key)) - .unwrap_or_else(|| panic!("no `{key}` line in:\n{text}")) - .to_owned() + .map(str::to_owned) }; - - let plain = render(None); - assert!(!plain.contains("torch_kept:"), "{plain}"); - assert!( - line(&plain, "command:").contains("torch[device-gfx1200]==2.10.0+rocm10.0.0"), - "without a kept torch the command installs it: {plain}" - ); - - let kept_plan = render(kept.as_ref()); - assert!( - line(&kept_plan, "torch_kept:").contains("torch 2.9.0+gitd0c8b1f"), - "{kept_plan}" - ); - let command = line(&kept_plan, "command:"); - assert!( - command.contains("rocm["), - "the SDK is still installed: {command}" - ); - for left_out in ["torch[", "torchvision", "torchaudio"] { - assert!( - !command.contains(left_out), - "the command still installs `{left_out}`: {command}" + // A folder with a Python, and `pyvenv.cfg` beside it when `cfg`. + let plant = |folder: &Path, cfg: bool| { + std::fs::create_dir_all(venv_python_path(folder).parent().unwrap()).unwrap(); + std::fs::write(venv_python_path(folder), "not run by a preview").unwrap(); + if cfg { + std::fs::write(folder.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); + } + }; + let managed = paths.data_dir.join("runtimes").join("wheel"); + let missing = paths_root.join("missing"); + let reusable_owned = managed.join("reusable"); + plant(&reusable_owned, true); + let broken_owned = managed.join("broken"); + plant(&broken_owned, false); + let reusable_foreign = paths_root.join("cloned"); + plant(&reusable_foreign, true); + let broken_foreign = paths_root.join("home"); + plant(&broken_foreign, false); + let full_torch = "torch[device-gfx1200]==2.10.0+rocm10.0.0"; + let composition_line = line(&render(false, &missing), "package_specs:"); + + // (folder, the preview cannot tell whether its venv is reused) + for (folder, undecided) in [ + (&missing, false), + (&reusable_owned, true), + (&broken_owned, false), + (&reusable_foreign, true), + (&broken_foreign, false), + ] { + let plain = render(false, folder); + assert_eq!(line(&plain, "torch_kept:"), None, "{plain}"); + let previewed = render(true, folder); + // The line's claim about the real install (a reused venv keeps its torch and + // uv is handed only the ROCm packages) is proven by + // `an_opted_out_environment_with_torch_installs_only_the_rocm_packages` in + // `therock/kept_torch.rs` and end to end by `@id:runtime-torch-alignment-opt-out`. + let expected = undecided.then(|| { + format!( + " torch_kept: cannot tell; ROCM_CLI_DISABLE_TORCH_ALIGNMENT is set, so if the venv whose Python is {} is reused and holds torch, the install keeps that torch and hands uv only the ROCm packages, without the torch, torchvision and torchaudio requirements the commands shown include; this preview runs nothing from the install folder, so it does not know which torch that venv holds", + venv_python_path(folder).display() + ) + }); + assert_eq!( + line(&previewed, "torch_kept:"), + expected, + "{}:\n{previewed}", + folder.display() + ); + // The commands shown carry the full stack, as the line says. + let commands = previewed + .lines() + .map(str::trim_start) + .filter(|line| { + line.starts_with("command: uv ") || line.starts_with("command_if_rebuilt: uv ") + }) + .collect::>(); + assert_eq!( + commands.is_empty(), + folder == &broken_foreign, + "only a refused folder has no command:\n{previewed}" ); + for command in commands { + assert!(command.contains("rocm["), "{command}"); + for package in [full_torch, "torchvision", "torchaudio"] { + assert!( + command.contains(package), + "leaves out `{package}`: {command}" + ); + } + } + assert_eq!(line(&previewed, "package_specs:"), composition_line); } - assert_eq!( - line(&kept_plan, "package_specs:"), - line(&plain, "package_specs:"), - "the composition the manifest records does not change" - ); std::fs::remove_dir_all(paths_root).ok(); } diff --git a/apps/rocm/src/therock/test_support.rs b/apps/rocm/src/therock/test_support.rs index 94f51167e2..92175a70b7 100644 --- a/apps/rocm/src/therock/test_support.rs +++ b/apps/rocm/src/therock/test_support.rs @@ -7,10 +7,13 @@ //! holds the fixtures every module's tests share. use super::source::FamilyResolution; +#[cfg(unix)] use super::venv_python_path; use crate::runtime_registry::{InstalledRuntimeManifest, runtime_manifest_path}; use anyhow::Result; -use rocm_core::{AppPaths, unix_time_millis}; +use rocm_core::AppPaths; +#[cfg(unix)] +use rocm_core::unix_time_millis; use std::fs; use std::path::{Path, PathBuf}; @@ -198,14 +201,13 @@ pub(super) fn venv_rebuild_sandbox(label: &str) -> (PathBuf, AppPaths) { } /// A venv Python that appends a line to `ran` every time it is run, then -/// behaves as [`plant_working_venv_python`]'s does: runs, reports `cp312`, +/// behaves as `plant_working_venv_python` (in `venv.rs`'s tests) does: runs, reports `cp312`, /// and reports `prefix` as its `sys.prefix`, and creates a venv when asked. #[cfg(unix)] pub(super) fn plant_recording_venv_python(install_root: &Path, prefix: &Path, ran: &Path) { - use std::os::unix::fs::PermissionsExt; let python = venv_python_path(install_root); fs::create_dir_all(python.parent().unwrap()).unwrap(); - fs::write( + rocm_core::fake_executable::write_fake_executable( &python, format!( "#!/bin/sh\necho \"$0 $*\" >> \"{}\"\nif [ \"$1\" = \"-m\" ]; then /bin/mkdir -p \"$3\"; exit 0; fi\nif [ \"$1\" = \"-c\" ]; then\n case \"$2\" in *sys.prefix*) echo \"{}\" ;; *) echo cp312 ;; esac\n exit 0\nfi\necho Python 3.12.10\n", @@ -214,7 +216,6 @@ pub(super) fn plant_recording_venv_python(install_root: &Path, prefix: &Path, ra ), ) .unwrap(); - fs::set_permissions(&python, fs::Permissions::from_mode(0o755)).unwrap(); } #[cfg(test)] diff --git a/apps/rocm/src/therock/venv.rs b/apps/rocm/src/therock/venv.rs index 962608e0cb..7f9d9ae2b6 100644 --- a/apps/rocm/src/therock/venv.rs +++ b/apps/rocm/src/therock/venv.rs @@ -492,6 +492,11 @@ pub(super) struct DryRunVenvPlan { pub(super) python_env: String, /// The `key: value` lines printed after `mode: dry-run`, `command` first. pub(super) lines: Vec<(&'static str, String)>, + /// Whether reuse of the folder's venv is the one outcome the files cannot + /// decide: a Python and `pyvenv.cfg` are there, and only running that Python + /// could tell. Anything that depends on what the venv holds is unknown then, + /// and known (nothing reused) in every other plan. + pub(super) reuse_undecided: bool, } /// The `--dry-run` lines for the venv step and the install command. @@ -510,8 +515,10 @@ pub(super) struct DryRunVenvPlan { /// after removing the venv's own entries, which the command does not show), or /// a refusal, which gets no command at all since nothing would run. /// -/// The commands carry `UV_VENV_CLEAR=0`, which the install pins for `uv venv`, -/// and every argument is shell-quoted: the install root comes from a +/// A plan that shows a `uv venv` command also prints an `env:` line naming +/// `UV_VENV_CLEAR=0`, which the install sets for `uv venv`; it is a line of its +/// own rather than a `VAR=value` prefix, which only POSIX shells accept. Every +/// argument is shell-quoted: the install root comes from a /// `--prefix` the assistant can choose, and the line is one a user is invited /// to paste. pub(super) fn dry_run_venv_plan( @@ -530,7 +537,7 @@ pub(super) fn dry_run_venv_plan( let install = format!("uv {}", display(install_args)); let with_venv = |rebuilding: bool| { format!( - "UV_VENV_CLEAR=0 uv {} && uv {}", + "uv {} && uv {}", display(&uv_venv_command_args( venv_python_arg, install_root, @@ -556,31 +563,34 @@ pub(super) fn dry_run_venv_plan( match (shape, venv_folder_state(paths, install_root, &finding)) { (_, Ok(VenvFolder::Empty)) => DryRunVenvPlan { python_env: "create a new Python environment in an empty folder".to_owned(), - lines: vec![("command", with_venv(false))], + reuse_undecided: false, + lines: vec![("command", with_venv(false)), ("env", uv_venv_env())], }, (Some(found), Ok(VenvFolder::Owned)) => DryRunVenvPlan { python_env: format!("{rebuild} (found {found})"), - lines: vec![("command", with_venv(true))], + reuse_undecided: false, + lines: vec![("command", with_venv(true)), ("env", uv_venv_env())], }, (None, Ok(VenvFolder::Owned)) => DryRunVenvPlan { python_env: format!("{reuse}; if not, {rebuild}"), + reuse_undecided: true, lines: vec![ ("command", install), ("command_if_rebuilt", with_venv(true)), + ("env", uv_venv_env()), ], }, (Some(_), Err(refusal)) => DryRunVenvPlan { python_env: "the install will refuse this folder".to_owned(), + reuse_undecided: false, lines: vec![ - ( - "command", - "none; the install will refuse this folder".to_owned(), - ), + ("command", "none".to_owned()), ("refusal", format!("{refusal:#}")), ], }, (None, Err(refusal)) => DryRunVenvPlan { python_env: format!("{reuse}; if not, the install will refuse this folder"), + reuse_undecided: true, lines: vec![ ("command", install), ("refusal_if_not_reused", format!("{refusal:#}")), @@ -589,6 +599,12 @@ pub(super) fn dry_run_venv_plan( } } +/// The `env:` line beside a previewed `uv venv` command: what the install sets +/// for it, and why, in a form that does not depend on the user's shell. +pub(super) fn uv_venv_env() -> String { + "UV_VENV_CLEAR=0 for `uv venv`, as the install sets it so that a UV_VENV_CLEAR=1 in the environment cannot make uv clear the folder; set it before running the command".to_owned() +} + #[cfg(test)] mod tests { #[cfg(unix)] @@ -658,12 +674,10 @@ mod tests { #[cfg(unix)] fn plant_failing_venv_python(install_root: &Path) { - use std::os::unix::fs::PermissionsExt; let python = venv_python_path(install_root); fs::create_dir_all(python.parent().unwrap()).unwrap(); let _ = fs::remove_file(&python); - fs::write(&python, "#!/bin/sh\nexit 1\n").unwrap(); - fs::set_permissions(&python, fs::Permissions::from_mode(0o755)).unwrap(); + rocm_core::fake_executable::write_fake_executable(&python, "#!/bin/sh\nexit 1\n").unwrap(); } /// What `uv venv` and `save_runtime_manifest` leave in a runtime ROCm CLI @@ -701,7 +715,6 @@ mod tests { /// the way it would against a real uv. #[cfg(unix)] fn write_logging_fake_uv(dir: &Path) -> (PathBuf, PathBuf) { - use std::os::unix::fs::PermissionsExt; let log = dir.join("uv-calls.log"); let path = dir.join("uv"); let script = format!( @@ -741,8 +754,7 @@ exit 1 "#, log = log.display() ); - fs::write(&path, script).unwrap(); - fs::set_permissions(&path, fs::Permissions::from_mode(0o755)).unwrap(); + rocm_core::fake_executable::write_fake_executable(&path, script).unwrap(); (path, log) } @@ -1073,7 +1085,7 @@ exit 1 let (root, paths) = venv_rebuild_sandbox("real-uv"); let log = root.join("uv-calls.log"); let uv = root.join("uv"); - fs::write( + rocm_core::fake_executable::write_fake_executable( &uv, format!( "#!/bin/sh\necho \"$@\" >> \"{}\"\nexec \"{}\" \"$@\"\n", @@ -1082,10 +1094,6 @@ exit 1 ), ) .unwrap(); - { - use std::os::unix::fs::PermissionsExt; - fs::set_permissions(&uv, fs::Permissions::from_mode(0o755)).unwrap(); - } let install_root = root.join("prefix"); ensure_uv_venv(&paths, &uv, &python, &install_root) .unwrap_or_else(|e| panic!("{}: initial venv: {e:#}", real_uv.display())); @@ -1294,7 +1302,7 @@ exit 1 let install_args = vec!["pip".to_owned(), "install".to_owned(), "rocm".to_owned()]; let venv_command = |folder: &Path, allow: &str| { format!( - "UV_VENV_CLEAR=0 uv venv --python {} {}{allow} && uv pip install rocm", + "uv venv --python {} {}{allow} && uv pip install rocm", launcher.display(), folder.display() ) @@ -1309,23 +1317,28 @@ exit 1 (plan.python_env, lines) }; let reuse = "reuse the Python environment here if its Python runs, reports wheel tag cp312 and has this folder as its sys.prefix; this preview runs nothing from the folder, so it cannot tell whether it does"; + // Beside every `uv venv` command, in place of a POSIX-only prefix. + let env_line = "env: UV_VENV_CLEAR=0 for `uv venv`, as the install sets it so that a UV_VENV_CLEAR=1 in the environment cannot make uv clear the folder; set it before running the command".to_owned(); let rebuild = "rebuild only the venv files ROCm CLI created here: remove bin, Scripts, lib, lib64, Lib, include, Include, CACHEDIR.TAG, pyvenv.cfg first, which the command does not show, then create the venv with --allow-existing; everything else in the folder is kept"; // Missing folder: a fresh venv. let empty = root.join("missing"); let (env, lines) = plan(&empty); assert_eq!(env, "create a new Python environment in an empty folder"); - assert_eq!(lines, [format!("command: {}", venv_command(&empty, ""))]); + assert_eq!( + lines, + [ + format!("command: {}", venv_command(&empty, "")), + env_line.clone() + ] + ); // Someone's folder with a Python but no pyvenv.cfg: certainly refused. let home = root.join("home"); plant_recording_venv_python(&home, &home, &ran); let (env, lines) = plan(&home); assert_eq!(env, "the install will refuse this folder"); - assert_eq!( - lines[0], - "command: none; the install will refuse this folder" - ); + assert_eq!(lines[0], "command: none"); assert!( lines[1].starts_with(&format!( "refusal: refusing to create the Python environment at {}: the folder is not empty and ROCm CLI cannot show it holds a ROCm CLI install (found a Python at {} with no pyvenv.cfg beside it; no finished ROCm CLI install recorded here", @@ -1371,6 +1384,7 @@ exit 1 "command_if_rebuilt: {}", venv_command(&owned, " --allow-existing") ), + env_line.clone(), ] ); @@ -1390,10 +1404,10 @@ exit 1 ); assert_eq!( lines, - [format!( - "command: {}", - venv_command(&broken, " --allow-existing") - )] + [ + format!("command: {}", venv_command(&broken, " --allow-existing")), + env_line, + ] ); assert!( @@ -1427,7 +1441,25 @@ exit 1 let cfg = |folder: &Path| fs::write(folder.join("pyvenv.cfg"), "home = /usr/bin\n").unwrap(); - for label in ["does-not-run", "no-cfg", "foreign-prefix", "wrong-tag"] { + // A planted Python with one answer of the recording one changed. + let rewrite = |python: &str, from: &str, to: &str| { + let script = fs::read_to_string(python).unwrap(); + assert!(script.contains(from), "{script}"); + rocm_core::fake_executable::write_fake_executable( + Path::new(python), + script.replace(from, to), + ) + .unwrap(); + }; + + for label in [ + "does-not-run", + "no-cfg", + "foreign-prefix", + "no-prefix", + "no-tag", + "wrong-tag", + ] { let folder = root.join(label); let python = venv_python_path(&folder).display().to_string(); let expected = match label { @@ -1448,13 +1480,25 @@ exit 1 elsewhere.display() ) } + "no-prefix" => { + // Runs, but fails when asked for its sys.prefix. + plant_recording_venv_python(&folder, &folder, &ran); + rewrite(&python, "*sys.prefix*) echo", "*sys.prefix*) exit 1; echo"); + cfg(&folder); + format!("a Python at {python} that does not report its sys.prefix") + } + "no-tag" => { + // Reports this folder as its sys.prefix, but fails when + // asked for its wheel tag. + plant_recording_venv_python(&folder, &folder, &ran); + rewrite(&python, "*) echo cp312 ;;", "*) exit 1 ;;"); + cfg(&folder); + format!("a Python at {python} whose wheel tag could not be read") + } _ => { plant_recording_venv_python(&folder, &folder, &ran); // Same Python, but reporting the cp311 tag. - let script = fs::read_to_string(&python) - .unwrap() - .replace("cp312", "cp311"); - fs::write(&python, script).unwrap(); + rewrite(&python, "cp312", "cp311"); cfg(&folder); format!( "a Python at {python} that reports wheel tag cp311 where cp312 is required" @@ -1509,11 +1553,10 @@ exit 1 /// `pyvenv.cfg` that decides what that prefix really is. #[cfg(unix)] fn plant_working_venv_python(install_root: &Path, prefix: &Path) { - use std::os::unix::fs::PermissionsExt; let python = venv_python_path(install_root); fs::create_dir_all(python.parent().unwrap()).unwrap(); let _ = fs::remove_file(&python); - fs::write( + rocm_core::fake_executable::write_fake_executable( &python, format!( "#!/bin/sh\nif [ \"$1\" = \"-c\" ]; then\n case \"$2\" in *sys.prefix*) echo \"{}\" ;; *) echo cp312 ;; esac\n exit 0\nfi\necho Python 3.12.10\n", @@ -1521,7 +1564,6 @@ exit 1 ), ) .unwrap(); - fs::set_permissions(&python, fs::Permissions::from_mode(0o755)).unwrap(); } /// Points where a clear of an owned venv can stop, as the states they diff --git a/apps/rocm/src/therock/wheel_plan.rs b/apps/rocm/src/therock/wheel_plan.rs index 59a9e79fe7..ed445d16d0 100644 --- a/apps/rocm/src/therock/wheel_plan.rs +++ b/apps/rocm/src/therock/wheel_plan.rs @@ -15,7 +15,7 @@ //! `command`). [`PlanStack::NeedsUv`] says those are not resolved, and why, //! where [`PlanStack::Resolved`] carries their values. -use super::kept_torch::{self, KeptTorch}; +use super::kept_torch; use super::python::{PlannedPython, WheelCompatibility}; use super::resolve::{AggregateDeviceTarget, TorchaudioPin, UnresolvedPipRuntime}; use super::source::{RuntimeVersionSelector, TheRockChannel}; @@ -73,11 +73,12 @@ pub(super) struct ResolvedStack<'a> { pub(super) install_root: &'a Path, pub(super) runtime_key: &'a str, pub(super) package_specs: &'a [String], - /// The torch stack the install leaves alone, when the opt-out asked for that and - /// the environment has one. The specs above stay the runtime's composition, as - /// recorded in its manifest; what `uv` is handed is [`kept_torch::install_specs`] - /// of them. - pub(super) kept_torch: Option<&'a KeptTorch>, + /// Whether `ROCM_CLI_DISABLE_TORCH_ALIGNMENT` is set. A preview's commands + /// install `package_specs` in full, as the install does for an environment it + /// creates or rebuilds. Where the folder's venv may be reused, which only + /// running its Python could tell, the install would keep the torch it holds, + /// so the preview prints [`super::kept_torch::preview_line`] there. + pub(super) torch_alignment_disabled: bool, pub(super) manifest_path: &'a Path, } @@ -198,22 +199,10 @@ pub(super) fn write_wheel_plan(output: &mut String, plan: &WheelPlan<'_>) { let _ = writeln!(output, " package_specs: {NOT_RESOLVED}"); } } - let kept = match &plan.stack { - PlanStack::Resolved(ResolvedStack { kept_torch, .. }) => *kept_torch, - PlanStack::NeedsUv { .. } => None, - }; let _ = writeln!( output, - " package_policy: resolve the pinned target-complete rocm, torch, torchvision, and torchaudio plan from published package metadata, then install it in one uv transaction{}", - if kept.is_some() { - " (the torch, torchvision and torchaudio requirements are resolved but not installed; see torch_kept)" - } else { - "" - } + " package_policy: resolve the pinned target-complete rocm, torch, torchvision, and torchaudio plan from published package metadata, then install it in one uv transaction" ); - if let Some(kept) = kept { - let _ = writeln!(output, "{}", kept_torch::plan_line(kept)); - } if let Some(warning) = plan.no_wheel_warning { let _ = writeln!(output, " warning: {warning}"); } @@ -251,10 +240,7 @@ pub(super) fn write_dry_run_tail( if matches!(plan.channel, TheRockChannel::Nightly) { install_args.extend(["--prerelease".to_owned(), "allow".to_owned()]); } - install_args.extend(kept_torch::install_specs( - stack.package_specs, - stack.kept_torch, - )); + install_args.extend(stack.package_specs.iter().cloned()); let venv_plan = dry_run_venv_plan( paths, &plan.python.venv_python_arg(), @@ -263,6 +249,9 @@ pub(super) fn write_dry_run_tail( &install_args, ); let _ = writeln!(output, " python_env: {}", venv_plan.python_env); + if stack.torch_alignment_disabled && venv_plan.reuse_undecided { + let _ = writeln!(output, "{}", kept_torch::preview_line(&env_python)); + } for (key, value) in &venv_plan.lines { let _ = writeln!(output, " {key}: {value}"); } @@ -273,6 +262,7 @@ pub(super) fn write_dry_run_tail( (PlanStack::NeedsUv { .. }, _) => { let _ = writeln!(output, " python_env: {NOT_RESOLVED}"); let _ = writeln!(output, " command: {NOT_RESOLVED}"); + let _ = writeln!(output, " env: {NOT_RESOLVED}"); } } let _ = writeln!( diff --git a/docs/architecture.md b/docs/architecture.md index 0c77c632aa..9e2295f232 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -138,10 +138,10 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`therock/family.rs`](../apps/rocm/src/therock/family.rs) | Which TheRock package family a request targets (flag, environment, managed runtime or host GPU), refusing a GPU that has no ROCm build. | domain | | [`therock/fetch.rs`](../apps/rocm/src/therock/fetch.rs) | HTTP fetching for TheRock installs: the cached metadata GET (its signature check is opt-in until a production key is pinned), the streaming artifact download, and the tarball free-space preflight. | domain | | [`therock/io.rs`](../apps/rocm/src/therock/io.rs) | Unique scratch directories for TheRock installs. | domain | -| [`therock/kept_torch.rs`](../apps/rocm/src/therock/kept_torch.rs) | What `ROCM_CLI_DISABLE_TORCH_ALIGNMENT` means for the SDK install itself: whether the environment's torch stack is kept, the requirements left out of what `uv` is handed, and the `torch_kept:` line (a real install decides again once the environment is prepared, since a recreated one holds no torch; `therock/wheel_plan.rs` prints the preview's). | domain | +| [`therock/kept_torch.rs`](../apps/rocm/src/therock/kept_torch.rs) | What `ROCM_CLI_DISABLE_TORCH_ALIGNMENT` means for the SDK install itself: whether the environment's torch stack is kept, the requirements left out of what `uv` is handed, and the `torch_kept:` lines: a real install's, decided once the environment is prepared since a recreated one holds no torch, and a preview's, which says it cannot tell because a preview runs nothing from the install folder (`therock/wheel_plan.rs` prints it). | domain | | [`therock/probe.rs`](../apps/rocm/src/therock/probe.rs) | Probing an installed runtime through its own interpreter: what `rocm_sdk` reports, which devices its torch opens, and the torch-pin helpers. | domain | | [`therock/process.rs`](../apps/rocm/src/therock/process.rs) | Running and capturing child commands for TheRock installs, bounded waits, `--json`-aware progress lines, and unpacking the SDK tarball. | domain | -| [`therock/python.rs`](../apps/rocm/src/therock/python.rs) | The Python an install runs on: finding or provisioning an interpreter (`resolve_python_launcher`, `plan_python_launcher`), narrowing the requirement to an explicit `--python-version` or a runtime's recorded wheel tag, and the wheel tags it accepts. | domain | +| [`therock/python.rs`](../apps/rocm/src/therock/python.rs) | The Python an install runs on: finding or provisioning an interpreter (`resolve_python_launcher`, `plan_python_launcher`), narrowing the requirement to an explicit `--python-version` or a runtime's recorded wheel tag, and the wheel tags it accepts; the `python -m venv` support probe runs in a folder of its own, with a relative interpreter path anchored to the current directory first. | domain | | [`therock/python_config_props.rs`](../apps/rocm/src/therock/python_config_props.rs) | Property tests for how the managed-Python step, a `config.json` writer, treats a `config.json` it cannot read (it never replaces one with defaults, and creates a missing one), and for the legacy rocm-dash tick migration that could produce one. Declared from [`therock/python.rs`](../apps/rocm/src/therock/python.rs). | flat | | [`therock/resolve.rs`](../apps/rocm/src/therock/resolve.rs) | Module declarations and re-exports for artifact resolution under `therock/resolve/`; holds no logic. | domain | | [`therock/resolve/tarball.rs`](../apps/rocm/src/therock/resolve/tarball.rs) | Resolving the SDK tarball a request installs from the catalog's index (`resolve_tarball_artifact`). | domain | @@ -151,9 +151,9 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`therock/source.rs`](../apps/rocm/src/therock/source.rs) | Where an install reads from: channel, hosting layout (the next layout's `stable.repo.amd.com`/`nightly.repo.amd.com`, or the earlier stream kept for pins that exist only there) and artifact bases (with the opt-in base override), the one routing rule `layout_serving` and its refusals (`select_source_layout`, `gate_install_layout`), plus the pinned version selector and the resolved family. | domain | | [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) | Test-only fixtures shared by the `therock/` children's tests and the tests left in [`therock.rs`](../apps/rocm/src/therock.rs). | flat | | [`therock/update.rs`](../apps/rocm/src/therock/update.rs) | Whether an installed runtime has something newer (`runtime_update_plan`, `runtime_update_check`), the update report and JSON, and the bounded startup check. | domain | -| [`therock/venv.rs`](../apps/rocm/src/therock/venv.rs) | The runtime's virtual environment in an install folder: reused when it is a real venv for that folder with the required tag, created in a missing or empty folder, rebuilt (only the venv's own entries) in a folder ROCm CLI can show it made, and refused in any other non-empty folder (`venv_folder_state`); `dry_run_venv_plan` is the `--dry-run` view of the same decision, read from the folder's files without running anything in it. Builds on [`therock/python.rs`](../apps/rocm/src/therock/python.rs)'s wheel tags. | domain | +| [`therock/venv.rs`](../apps/rocm/src/therock/venv.rs) | The runtime's virtual environment in an install folder: reused when it is a real venv for that folder with the required tag, created in a missing or empty folder, rebuilt (only the venv's own entries) in a folder ROCm CLI can show it made, and refused in any other non-empty folder (`venv_folder_state`); `dry_run_venv_plan` is the `--dry-run` view of the same decision, read from the folder's files without running anything in it, with the `env:` line naming the `UV_VENV_CLEAR=0` the install sets and whether reuse is the one outcome the files cannot decide. Builds on [`therock/python.rs`](../apps/rocm/src/therock/python.rs)'s wheel tags. | domain | | [`therock/version.rs`](../apps/rocm/src/therock/version.rs) | Version grammar for TheRock runtimes: the strict install gate (`parse_version`), PEP 440 ordering, host-version parsing and the build-date helpers. | domain | -| [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) | The `sdk install` plan a wheel install prints, from one writer for a preview and a real install, resolved or not; a preview's venv step comes from `therock/venv.rs`'s `dry_run_venv_plan`. | domain | +| [`therock/wheel_plan.rs`](../apps/rocm/src/therock/wheel_plan.rs) | The `sdk install` plan a wheel install prints, from one writer for a preview and a real install, resolved or not; a preview's venv step comes from `therock/venv.rs`'s `dry_run_venv_plan`, and its `torch_kept:` line is printed where that plan cannot decide reuse. | domain | | [`therock_version_proptests.rs`](../apps/rocm/src/therock_version_proptests.rs) | Property tests for version ordering, update verdicts and update-source selection, declared from [`therock.rs`](../apps/rocm/src/therock.rs). | flat | | [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) | The chat assistant's tool-call policy: which `rocm` commands and bridge tools a model may request, which run at once, which need approval, and the validators that refuse unsafe calls. | flat | | [`uninstall.rs`](../apps/rocm/src/uninstall.rs) | `rocm uninstall` (`uninstall`): what only uninstall does beyond removing files: undoing the installer's `PATH` change, removing the fish completion script the Linux installer recorded writing (`plan_completion_removals` takes only a regular `completions/rocm.fish` whose first line is the installer's marker naming this install folder, tied to [`install.sh`](../install.sh) by a test; `execute_plan` rechecks the file before removing it and reports a removal failure as a warning instead of stopping, for the `SHELL_COMPLETIONS_KIND` plan entries it adds), and deleting the running `rocm.exe` on Windows. | relocation | diff --git a/docs/manual-testing.md b/docs/manual-testing.md index 9dd664b67c..c0dec780c9 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -212,7 +212,7 @@ Expected result: the `torch` and `torchvision` versions, so on a host with no `uv` installed it stops before that step: the data folder still has no `tools` folder, a `resolution_note:` line says why, and `target:`, `runtime_key:`, - `package_specs:`, `command:` and `manifest:` read `not resolved by this + `package_specs:`, `python_env:`, `command:`, `env:` and `manifest:` read `not resolved by this preview`. Run the real install (or any command that fetches `uv`), then the preview again, and it prints the complete plan; so does a preview with `ROCM_CLI_UV_BINARY` naming a `uv`. @@ -246,9 +246,12 @@ Expected result: the wheel tag it needs, and `rocm update` of that runtime builds the new one on Python 3.12 again. - rocm-cli creates or reuses a rocm-cli managed Python venv. -- If the `--prefix` folder already has anything in it and its venv does not - run, rocm-cli rebuilds only that venv's own files, and only in a folder where - a wheel install finished (its `.rocm-cli-runtime.json` names the folder). +- If the `--prefix` folder already has anything in it and its venv cannot be + reused (its Python does not run, has no `pyvenv.cfg` beside it, reports + another wheel tag, or reports another `sys.prefix`), rocm-cli rebuilds only + that venv's own files, and only in a folder ROCm CLI owns: one where a wheel + install finished (its `.rocm-cli-runtime.json` names the folder), or one + inside `runtimes/wheel` in ROCm CLI's data folder. It prints what it kept and why the venv could not be used (for example `no pyvenv.cfg beside it`, or `whose sys.prefix is ..., not this folder`), and anything else in the folder, such as `apps/comfyui`, is still there @@ -259,17 +262,25 @@ Expected result: that writes a file when run, and after the preview that file does not exist. It reads the folder's files instead. For your home folder with a broken `~/bin/python` and no `pyvenv.cfg`, `python_env:` says - `the install will refuse this folder`, `command:` is - `none; the install will refuse this folder`, and a + `the install will refuse this folder`, `command:` is `none`, and a `refusal:` line gives the install's message. For a folder with both a Python and `pyvenv.cfg`, it cannot tell without running that Python whether the venv would be reused, so `python_env:` says so, `command:` shows only the `uv pip install`, and a `command_if_rebuilt:` or `refusal_if_not_reused:` - line gives the other outcome. The `uv venv` commands it shows start with - `UV_VENV_CLEAR=0`, as the install runs them; a rebuild first removes the - venv's own entries, which the command does not show. If the Python the - preview would check first (on `PATH`, or `ROCM_CLI_PYTHON`) is inside the - `--prefix` folder, the preview stops and says it did not run it. + line gives the other outcome. A `uv venv` command it shows is followed by an + `env:` line naming `UV_VENV_CLEAR=0`, which the install sets for it; a + rebuild first removes the venv's own entries, which the command does not + show. If a Python the preview would check (`ROCM_CLI_PYTHON`, the first on + `PATH`, or the saved managed Python) is inside the `--prefix` folder, the + preview stops and says it did not run it. With + `ROCM_CLI_DISABLE_TORCH_ALIGNMENT=1` and a folder holding a `bin/python` and + `pyvenv.cfg`, a `torch_kept:` line says the preview cannot tell which torch a + reused venv would keep, the commands shown still install the full torch + stack, and the file the planted Python writes still does not exist. A folder + the preview knows is refused or rebuilt gets no `torch_kept:` line. +- `ROCM_CLI_PYTHON` given relative to the current folder (for example + `ROCM_CLI_PYTHON=.venv/bin/python`) is accepted by the install and the + preview when that Python works from the current folder. - pip installs pinned `rocm`, `torch`, and `torchvision` requirements with exactly one `device-` extra (`rocm` also requests `libraries`, and `devel` only when `--devel` is passed), alongside pinned diff --git a/docs/testing.md b/docs/testing.md index c534502a3b..b55fc83826 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1235,8 +1235,8 @@ picks only the ROCm version and the torchaudio pin), so the preview runs a `uv` that is already there (the one `ROCM_CLI_UV_BINARY` names, or the managed copy a previous install left) and, with none, stops before that step. It then prints what needs no `uv` (the ROCm version, the torchaudio pin, the requirements `uv` -would be asked about), marks `target`, `runtime_key`, `package_specs`, `command` -and `manifest` as `not resolved by this preview`, and says why in a +would be asked about), marks `target`, `runtime_key`, `package_specs`, +`python_env`, `command`, `env` and `manifest` as `not resolved by this preview`, and says why in a `resolution_note:` line and a progress line, in the voice of `python_note:`. It cannot say whether the published stack installs together either. A real install and `rocm update` still fetch `uv` as before, and a preview made after either @@ -1355,15 +1355,29 @@ did not run it, when the Python it would check first is inside `--prefix`. that records every run in each folder state and asserts the lines and an empty record; `a_dry_run_runs_no_python_from_the_install_folder_while_searching` in [python.rs](../apps/rocm/src/therock/python.rs) covers `PATH`, an absolute `ROCM_CLI_PYTHON` and a bare one resolved through -`PATH`. End to end, scenarios `runtime-33` (an unowned home folder is refused, -by the preview and by the install, and the advised empty folder works), -`runtime-34` (a rebuild of a folder ROCm CLI made keeps the ComfyUI data and -says why the old venv was not reused) and `runtime-35` (a preview of a folder -holding someone else's venv says it cannot tell and runs nothing) and -`runtime-36` (a preview whose `ROCM_CLI_PYTHON` is inside the folder stops -without running it) run the real -CLI with a loopback index, a fake `uv` and planted Pythons that record every -run. They are Linux-only because those stand-ins are shell scripts. The +`PATH`. End to end, these scenarios run the real CLI with a loopback index, a fake +`uv` and planted Pythons that record every run: + +- `runtime-33`: an unowned home folder is refused, by the preview and by the + install, and the advised empty folder works; +- `runtime-34`: a rebuild of a folder ROCm CLI made keeps the ComfyUI data and + says why the old venv was not reused; +- `runtime-35`: a preview of a folder holding someone else's venv says it + cannot tell and runs nothing; +- `runtime-36`: a preview whose `ROCM_CLI_PYTHON` is inside the folder stops + without running it; +- `runtime-37`: a preview with `ROCM_CLI_DISABLE_TORCH_ALIGNMENT` set says it + cannot tell which torch a reused venv would keep, and runs nothing. + +`runtime-38` uses the same setup with a launcher outside every install folder: +a `ROCM_CLI_PYTHON` relative to the folder the CLI runs in is accepted. All six +are Linux-only because those stand-ins are shell scripts. Which preview plans +print the `torch_kept:` line, one row per folder shape, is +`a_preview_under_the_alignment_opt_out_cannot_tell_whether_torch_is_kept` in +[wheel.rs](../apps/rocm/src/therock/resolve/wheel.rs), and +`a_relative_interpreter_path_is_anchored_to_the_current_directory` in +[python.rs](../apps/rocm/src/therock/python.rs) runs the path anchoring on +every platform. The folder decision itself (empty, refused with the condition named, owned by the wheel marker) reads only files, so `the_venv_folder_decision_reads_files_on_every_platform` runs it on every diff --git a/docs/vllm.md b/docs/vllm.md index c4914b8c2b..6ed51b0da3 100644 --- a/docs/vllm.md +++ b/docs/vllm.md @@ -74,8 +74,10 @@ holds torch. That command normally hands `uv` the SDK's `torch`, `torchvision` and `torchaudio` along with `rocm`, which replaces the stack the engine or you installed (and `triton` with it). With the variable set it asks for the ROCm packages alone and leaves the torch stack where it is: the plan prints a -`torch_kept:` line naming the torch it found, and `rocm install sdk --dry-run` -shows the same reduced `command:`. A runtime with no torch yet, or an +`torch_kept:` line naming the torch it found. `rocm install sdk --dry-run` +runs nothing from the install folder, so it cannot ask the environment which +torch it holds: the commands it shows install the full stack, and where the +environment may be reused its `torch_kept:` line says it cannot tell. A runtime with no torch yet, or an environment recreated for another Python, still gets the full stack, since there is nothing to keep. The runtime's recorded composition (and so its runtime key and `rocm update` comparison) is unchanged. diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 36cf317676..d5a13ac0a6 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -788,3 +788,27 @@ Feature: Runtime configuration When the user previews installing the SDK into that folder with that folder's Python as ROCM_CLI_PYTHON Then the install fails And the preview stops without running that Python and says why + + # The torch-alignment opt-out keeps the torch an environment already holds, + # and only that environment's Python can say which torch it holds. A preview + # runs nothing from the install folder, so with the opt-out set it says it + # cannot tell, rather than asking the folder's Python. The planted Python + # records every run, and the Then checks the record together with the line. + # Same hermetic setup and Linux-only reason as runtime-33. + @id:runtime-install-preview-opt-out-runs-nothing-from-prefix @requires-os:linux + Scenario: runtime-37 - Previewing an SDK install with the torch alignment opt-out runs nothing from the install folder + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + And the user's folder holds a Python environment ROCm CLI did not make + When the user previews installing the SDK into that folder with the torch alignment opt-out set + Then the preview says it cannot tell whether that environment's torch is kept and runs nothing from the folder + + # `ROCM_CLI_PYTHON` may name an interpreter relative to the folder the user + # runs the command from. The check that the Python can create a virtual + # environment starts it in a folder of its own, and a relative path read from + # there names nothing, so the Python was reported as unusable although it + # works. Same hermetic setup and Linux-only reason as runtime-33. + @id:runtime-install-preview-relative-python @requires-os:linux + Scenario: runtime-38 - Previewing an SDK install with ROCM_CLI_PYTHON relative to the current folder uses that Python + Given a canonical release pip index fixture and a ROCm 10 pip index fixture + When the user previews installing the SDK into an empty folder with ROCM_CLI_PYTHON relative to the current folder + Then the preview accepts that Python and plans a new Python environment diff --git a/tests/e2e-cucumber/tests/e2e/therock_steps.rs b/tests/e2e-cucumber/tests/e2e/therock_steps.rs index 7afe70bb89..eae1a620a3 100644 --- a/tests/e2e-cucumber/tests/e2e/therock_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/therock_steps.rs @@ -2954,7 +2954,7 @@ async fn preview_predicts_home_refusal(world: &mut E2eWorld) { ); // No command for an install that will not run one. assert!( - reported.contains("command: none; the install will refuse this folder"), + reported.contains(" command: none\n"), "the preview did not say no command will run:\n{reported}" ); assert!( @@ -2986,11 +2986,19 @@ async fn preview_shows_rebuild_in_place(world: &mut E2eWorld) { ); assert!( reported.contains(&format!( - "command_if_rebuilt: UV_VENV_CLEAR=0 uv venv --python {}", + "command_if_rebuilt: uv venv --python {}", root(world).join("fake-python").join("python3.14").display() )) && reported.contains(&format!("{} --allow-existing &&", folder.display())), "the previewed uv venv command is not the one a rebuild runs:\n{reported}" ); + // The pin is printed on a line of its own rather than as a `VAR=value` + // prefix, which only POSIX shells accept. That the install sets it is proven + // by the unit tests in `apps/rocm/src/therock/venv.rs` that read the fake + // uv's log for `UV_VENV_CLEAR=0`. + assert!( + reported.contains(" env: UV_VENV_CLEAR=0 for `uv venv`, as the install sets it so that a UV_VENV_CLEAR=1 in the environment cannot make uv clear the folder"), + "the preview did not name the variable the install sets for uv venv:\n{reported}" + ); assert!( folder.join("lib").is_dir() && folder.join("pyvenv.cfg").is_file(), "a preview changed the folder" @@ -3021,6 +3029,77 @@ async fn preview_sdk_install_with_python_from_folder(world: &mut E2eWorld) { run_sdk_install_into_with_python(world, &folder, true, &python); } +#[when( + "the user previews installing the SDK into that folder with the torch alignment opt-out set" +)] +async fn preview_sdk_install_with_alignment_opt_out(world: &mut E2eWorld) { + let folder = install_folder(world, CLONED_VENV_FOLDER); + world + .command_env + .push(("ROCM_CLI_DISABLE_TORCH_ALIGNMENT", "1".into())); + run_sdk_install_into(world, &folder, true); +} + +#[then( + "the preview says it cannot tell whether that environment's torch is kept and runs nothing from the folder" +)] +async fn preview_cannot_tell_kept_torch(world: &mut E2eWorld) { + let folder = install_folder(world, CLONED_VENV_FOLDER); + let reported = reported(world); + assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); + assert!( + reported.contains(&format!( + "torch_kept: cannot tell; ROCM_CLI_DISABLE_TORCH_ALIGNMENT is set, so if the venv whose Python is {} is reused and holds torch, the install keeps that torch and hands uv only the ROCm packages, without the torch, torchvision and torchaudio requirements the commands shown include; this preview runs nothing from the install folder, so it does not know which torch that venv holds\n", + folder.join("bin").join("python").display() + )), + "the preview did not say it cannot tell whether torch is kept:\n{reported}" + ); + // The line's claim about the real install (a reused venv keeps its torch and + // uv is handed only the ROCm packages) is proven by scenario + // `@id:runtime-torch-alignment-opt-out` and by the unit test + // `an_opted_out_environment_with_torch_installs_only_the_rocm_packages` in + // `apps/rocm/src/therock/kept_torch.rs`. + // The line says the commands shown carry the full torch stack; they do. + assert!( + reported + .lines() + .any(|line| line.starts_with(" command: uv pip install") + && line.contains("torchvision") + && line.contains("torchaudio")), + "the previewed command does not carry the torch stack the line says it does:\n{reported}" + ); + assert_no_prefix_python_ran(world, &reported); + assert!(folder.join("bin").join("python").is_file() && folder.join("pyvenv.cfg").is_file()); +} + +#[when( + "the user previews installing the SDK into an empty folder with ROCM_CLI_PYTHON relative to the current folder" +)] +async fn preview_sdk_install_with_relative_python(world: &mut E2eWorld) { + let folder = install_folder(world, EMPTY_INSTALL_FOLDER); + let launcher = root(world).join("fake-python").join("python3.14"); + write_executable( + &launcher, + "#!/bin/sh\nif [ \"$1\" = -c ]; then echo cp314; fi\nexit 0\n", + ); + world.command_dir = Some(root(world).to_path_buf()); + run_sdk_install_into_with_python(world, &folder, true, Path::new("fake-python/python3.14")); +} + +#[then("the preview accepts that Python and plans a new Python environment")] +async fn preview_accepts_relative_python(world: &mut E2eWorld) { + let reported = reported(world); + assert_eq!(world.cli_rc, Some(0), "the preview failed:\n{reported}"); + assert!( + !reported.contains("is not usable"), + "the preview rejected a Python that works:\n{reported}" + ); + assert!( + reported.contains("python_env: create a new Python environment in an empty folder"), + "the preview did not plan the environment:\n{reported}" + ); +} + #[then("the preview stops without running that Python and says why")] async fn preview_stops_before_running_folder_python(world: &mut E2eWorld) { let folder = install_folder(world, CLONED_VENV_FOLDER); From b808b3b13abe794319bc467bfda0b13d91cfe5ec Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 16 Nov 2026 15:17:05 +0200 Subject: [PATCH 14/15] test(therock): import unix_time_millis for the every-platform venv test the_venv_folder_decision_reads_files_on_every_platform runs on Windows too, but the import it needs was gated to Unix, so the Windows test build failed to compile. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock/venv.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/apps/rocm/src/therock/venv.rs b/apps/rocm/src/therock/venv.rs index 7f9d9ae2b6..2d51f76b6b 100644 --- a/apps/rocm/src/therock/venv.rs +++ b/apps/rocm/src/therock/venv.rs @@ -617,7 +617,6 @@ mod tests { plant_recording_venv_python, venv_rebuild_sandbox, write_fake_python_reporting, write_fake_uv_creating_venv, }; - #[cfg(unix)] use rocm_core::unix_time_millis; #[test] From 06c24646764bcce35659d5290ab5c0ea7b1c0e1b Mon Sep 17 00:00:00 2001 From: Roman Inflianskas Date: Mon, 16 Nov 2026 18:30:06 +0200 Subject: [PATCH 15/15] refactor(therock): carry the preview's paths on the resolved stack write_dry_run_tail took the paths as an Option beside the plan, so a resolved plan without them was a runtime unreachable!() rather than a type error. The paths now live on ResolvedStack, the one case whose venv step reads them, and the tail takes the plan alone. Signed-off-by: Roman Inflianskas --- apps/rocm/src/therock.rs | 3 ++- apps/rocm/src/therock/resolve/wheel.rs | 8 ++++--- apps/rocm/src/therock/wheel_plan.rs | 32 ++++++++++++-------------- 3 files changed, 22 insertions(+), 21 deletions(-) diff --git a/apps/rocm/src/therock.rs b/apps/rocm/src/therock.rs index 8a5a541dc7..bbf75bf2b8 100644 --- a/apps/rocm/src/therock.rs +++ b/apps/rocm/src/therock.rs @@ -524,6 +524,7 @@ fn install_wheel_runtime( torchaudio_pin: resolution.torchaudio_pin.as_ref(), no_wheel_warning: no_wheel_warning.as_deref(), stack: PlanStack::Resolved(ResolvedStack { + paths, compatibility_key: &resolution.package_versions.compatibility_key, install_root: &install_root, runtime_key: &runtime_key, @@ -538,7 +539,7 @@ fn install_wheel_runtime( let mut output = String::new(); write_wheel_plan(&mut output, &plan); if dry_run { - write_dry_run_tail(&mut output, &plan, Some(paths)); + write_dry_run_tail(&mut output, &plan); return Ok(SdkInstallResult::plan(output)); } diff --git a/apps/rocm/src/therock/resolve/wheel.rs b/apps/rocm/src/therock/resolve/wheel.rs index cc9d1f872d..b3774a02b4 100644 --- a/apps/rocm/src/therock/resolve/wheel.rs +++ b/apps/rocm/src/therock/resolve/wheel.rs @@ -2649,6 +2649,7 @@ sdk install let install_root = PathBuf::from("/runtimes").join(&runtime_key); let manifest_path = PathBuf::from("/manifests").join(&runtime_key); let (python, compatibility) = clean_host_python(); + let (paths_root, paths) = super::super::super::test_support::test_paths("plan-keys"); let plan = WheelPlan { channel: TheRockChannel::Release, version_selector: None, @@ -2665,6 +2666,7 @@ sdk install torchaudio_pin: resolution.torchaudio_pin.as_ref(), no_wheel_warning: None, stack: PlanStack::Resolved(ResolvedStack { + paths: &paths, compatibility_key: &resolution.package_versions.compatibility_key, install_root: &install_root, runtime_key: &runtime_key, @@ -2675,8 +2677,7 @@ sdk install }; let mut resolved = String::new(); write_wheel_plan(&mut resolved, &plan); - let (paths_root, paths) = super::super::super::test_support::test_paths("plan-keys"); - write_dry_run_tail(&mut resolved, &plan, Some(&paths)); + write_dry_run_tail(&mut resolved, &plan); std::fs::remove_dir_all(paths_root).ok(); let mut expected = plan_keys(&resolved); @@ -2734,6 +2735,7 @@ sdk install torchaudio_pin: resolution.torchaudio_pin.as_ref(), no_wheel_warning: None, stack: PlanStack::Resolved(ResolvedStack { + paths: &paths, compatibility_key: &resolution.package_versions.compatibility_key, install_root, runtime_key: "kept", @@ -2744,7 +2746,7 @@ sdk install }; let mut text = String::new(); write_wheel_plan(&mut text, &plan); - write_dry_run_tail(&mut text, &plan, Some(&paths)); + write_dry_run_tail(&mut text, &plan); text }; let line = |text: &str, key: &str| { diff --git a/apps/rocm/src/therock/wheel_plan.rs b/apps/rocm/src/therock/wheel_plan.rs index ed445d16d0..56ff25f266 100644 --- a/apps/rocm/src/therock/wheel_plan.rs +++ b/apps/rocm/src/therock/wheel_plan.rs @@ -69,6 +69,11 @@ pub(super) enum PlanStack<'a> { } pub(super) struct ResolvedStack<'a> { + /// What a preview's venv step reads the install folder against (the managed + /// runtimes folder, for ownership). Carried by the resolved stack, the one + /// case whose venv step is decided, so a resolved plan cannot be previewed + /// without it. + pub(super) paths: &'a AppPaths, pub(super) compatibility_key: &'a str, pub(super) install_root: &'a Path, pub(super) runtime_key: &'a str, @@ -222,18 +227,14 @@ pub(super) const UNRESOLVED_PROGRESS: &str = "No uv is installed; a real install /// do, the commands a real install would run, and where it would record the /// runtime. /// -/// `paths` is needed only for a resolved plan, whose venv step is decided by -/// [`dry_run_venv_plan`] from the install folder's files, running nothing from -/// it; that function also shell-quotes the commands, which a user is invited to -/// paste and whose install root can come from a model-chosen `--prefix`. -pub(super) fn write_dry_run_tail( - output: &mut String, - plan: &WheelPlan<'_>, - paths: Option<&AppPaths>, -) { +/// A resolved plan's venv step is decided by [`dry_run_venv_plan`] from the +/// install folder's files, running nothing from it; that function also +/// shell-quotes the commands, which a user is invited to paste and whose install +/// root can come from a model-chosen `--prefix`. +pub(super) fn write_dry_run_tail(output: &mut String, plan: &WheelPlan<'_>) { let _ = writeln!(output, " mode: dry-run"); - match (&plan.stack, paths) { - (PlanStack::Resolved(stack), Some(paths)) => { + match &plan.stack { + PlanStack::Resolved(stack) => { let env_python = venv_python_path(stack.install_root); let mut install_args = uv_pip_install_base(&env_python); install_args.extend(["--index-url".to_owned(), plan.index_url.to_owned()]); @@ -242,7 +243,7 @@ pub(super) fn write_dry_run_tail( } install_args.extend(stack.package_specs.iter().cloned()); let venv_plan = dry_run_venv_plan( - paths, + stack.paths, &plan.python.venv_python_arg(), stack.install_root, &plan.wheel_compatibility.python_tag, @@ -256,10 +257,7 @@ pub(super) fn write_dry_run_tail( let _ = writeln!(output, " {key}: {value}"); } } - (PlanStack::Resolved(_), None) => { - unreachable!("a resolved plan's preview is written with the paths its venv step reads") - } - (PlanStack::NeedsUv { .. }, _) => { + PlanStack::NeedsUv { .. } => { let _ = writeln!(output, " python_env: {NOT_RESOLVED}"); let _ = writeln!(output, " command: {NOT_RESOLVED}"); let _ = writeln!(output, " env: {NOT_RESOLVED}"); @@ -343,6 +341,6 @@ pub(super) fn unresolved_wheel_preview(preview: &UnresolvedPreview<'_>) -> Strin }; let mut output = String::new(); write_wheel_plan(&mut output, &plan); - write_dry_run_tail(&mut output, &plan, None); + write_dry_run_tail(&mut output, &plan); output }