diff --git a/README.md b/README.md index 340d3c8a52..621a328a7b 100644 --- a/README.md +++ b/README.md @@ -712,7 +712,9 @@ exits without prompting or making changes. `adopt` registers an existing TheRock-based Python environment as a managed runtime. It does not work with standard ROCm package installs (for example, -`/opt/rocm`); use `rocm install sdk` instead. +`/opt/rocm`); use `rocm install sdk` instead. Without `--root`, the environment +folder is the one that holds the `--python` interpreter's `bin` (or `Scripts`) +folder; an interpreter anywhere else is refused until you pass `--root`. ### Disk space diff --git a/apps/rocm/src/cli.rs b/apps/rocm/src/cli.rs index 50f3caa662..1a842e7320 100644 --- a/apps/rocm/src/cli.rs +++ b/apps/rocm/src/cli.rs @@ -888,7 +888,7 @@ left, so it cannot undo more than one activation." /// Python executable inside the existing ROCm environment. #[arg(long)] python: PathBuf, - /// Optional SDK root path. + /// Python environment folder. Taken from --python when that sits in a bin or Scripts folder; required otherwise. #[arg(long)] root: Option, /// Runtime id to assign. diff --git a/apps/rocm/src/comfyui/runtime_env.rs b/apps/rocm/src/comfyui/runtime_env.rs index 3e496900be..babb58f48e 100644 --- a/apps/rocm/src/comfyui/runtime_env.rs +++ b/apps/rocm/src/comfyui/runtime_env.rs @@ -22,7 +22,7 @@ use crate::therock; use anyhow::{Context, Result, bail}; use rocm_core::{ AppPaths, RocmCliConfig, runtime_is_linux, runtime_is_windows, runtime_path_list_join, - runtime_path_list_split, runtime_paths_equivalent, + runtime_path_list_split, runtime_paths_equivalent, runtime_python_env_root_for_executable, }; use std::ffi::OsString; use std::path::{Path, PathBuf}; @@ -237,7 +237,7 @@ pub(super) fn runtime_environment_for_manifest( } let mut env = ComfyUiRuntimeEnvironment { - venv_root: infer_python_env_root(&manifest.python_executable), + venv_root: runtime_python_env_root_for_executable(&manifest.python_executable), rocm_root: Some(manifest.runtime_root.clone()), path_entries: Vec::new(), library_entries: Vec::new(), @@ -254,7 +254,7 @@ pub(super) fn runtime_environment_from_runtime( python: &Path, ) -> ComfyUiRuntimeEnvironment { let mut env = ComfyUiRuntimeEnvironment { - venv_root: infer_python_env_root(python), + venv_root: runtime_python_env_root_for_executable(python), rocm_root: manifest .rocm_sdk .as_ref() @@ -307,15 +307,6 @@ fn collect_rocm_runtime_paths(root: &Path, env: &mut ComfyUiRuntimeEnvironment) } } -fn infer_python_env_root(python: &Path) -> Option { - let bin_dir = python.parent()?; - let name = bin_dir.file_name()?.to_string_lossy().to_ascii_lowercase(); - if matches!(name.as_str(), "scripts" | "bin") { - return bin_dir.parent().map(Path::to_path_buf); - } - None -} - pub(super) fn apply_runtime_environment( command: &mut Command, env: &ComfyUiRuntimeEnvironment, @@ -964,4 +955,64 @@ mod tests { .find(|(name, _)| name.to_string_lossy() == key) .and_then(|(_, value)| value.map(OsString::from)) } + + /// The environment folder ComfyUI exports as `VIRTUAL_ENV`, by the folder + /// the interpreter sits in. Today only a `bin` or `Scripts` folder + /// (any case) identifies a venv; anything else leaves `VIRTUAL_ENV` unset + /// rather than pointing it at a guessed folder. + #[test] + fn runtime_environment_exports_virtual_env_only_for_a_bin_or_scripts_folder() -> Result<()> { + let cases: [(&str, Option<&str>); 7] = [ + ("/opt/venv/bin/python", Some("/opt/venv")), + ("/opt/venv/Scripts/python.exe", Some("/opt/venv")), + ("/opt/venv/SCRIPTS/python.exe", Some("/opt/venv")), + ("/opt/venv/BIN/python", Some("/opt/venv")), + ("/opt/venv/tools/python", None), + ("python", None), + ("/python", None), + ]; + for (python, expected) in cases { + let python = PathBuf::from(python); + let manifest = minimal_runtime_manifest(&python); + + let env = runtime_environment_from_runtime(&manifest, &python); + let mut command = Command::new(&python); + apply_runtime_environment(&mut command, &env)?; + + assert_eq!( + command_env_value(&command, "VIRTUAL_ENV").as_deref(), + expected.map(std::ffi::OsStr::new), + "{}", + python.display() + ); + } + Ok(()) + } + + fn minimal_runtime_manifest(python: &Path) -> therock::InstalledRuntimeManifest { + therock::InstalledRuntimeManifest { + runtime_key: "therock-release-gfx120x-all".to_owned(), + runtime_id: "therock-release:gfx120X-all".to_owned(), + channel: "release".to_owned(), + format: "wheel".to_owned(), + family: "gfx120X-all".to_owned(), + family_source: "test".to_owned(), + version: "7.13.0a20260511".to_owned(), + install_root: PathBuf::from("/nonexistent/runtime"), + selected_artifact_url: "https://example.invalid/simple".to_owned(), + source_layout_generation: None, + index_url: None, + tarball_file_name: None, + python_launcher: None, + python_executable: Some(python.display().to_string()), + pip_cache_dir: None, + rocm_sdk: None, + sdk_torch: None, + wheel_composition: None, + read_only: false, + imported_from: None, + devel: true, + installed_at_unix_ms: 100, + } + } } diff --git a/apps/rocm/src/runtime_adopt.rs b/apps/rocm/src/runtime_adopt.rs index 549753818a..d4a1e82388 100644 --- a/apps/rocm/src/runtime_adopt.rs +++ b/apps/rocm/src/runtime_adopt.rs @@ -19,7 +19,10 @@ use std::fs; use std::path::{Path, PathBuf}; use anyhow::{Context, Result, bail}; -use rocm_core::{AppPaths, RocmCliConfig, managed_pip_cache_dir, runtime_python_executable_in_env}; +use rocm_core::{ + AppPaths, RocmCliConfig, managed_pip_cache_dir, runtime_python_env_root_for_executable, + runtime_python_executable_in_env, +}; use crate::runtime_registry::{ paths_equivalent, runtime_manifest_path, runtime_registry_dir, @@ -230,7 +233,9 @@ fn resolve_adopt_python_input(input: &Path) -> Result<(PathBuf, Option) return Ok((python, Some(env_root))); } if absolute.is_file() { - let inferred_root = infer_python_env_root(&absolute); + // `None` for an interpreter outside a `bin`/`Scripts` folder: the + // request then asks for `--root` rather than adopting a guessed folder. + let inferred_root = runtime_python_env_root_for_executable(&absolute); return Ok((absolute, inferred_root)); } bail!( @@ -239,15 +244,6 @@ fn resolve_adopt_python_input(input: &Path) -> Result<(PathBuf, Option) ); } -fn infer_python_env_root(python_executable: &Path) -> Option { - let bin_dir = python_executable.parent()?; - let bin_name = bin_dir.file_name()?.to_string_lossy(); - if bin_name.eq_ignore_ascii_case("Scripts") || bin_name == "bin" { - return bin_dir.parent().map(Path::to_path_buf); - } - bin_dir.parent().map(Path::to_path_buf) -} - pub(crate) fn adopt_runtime_from_probe( paths: &AppPaths, request: AdoptRuntimeRequest, @@ -819,4 +815,68 @@ mod tests { let _ = fs::remove_dir_all(root); Ok(()) } + + /// `rocm runtimes adopt --python ` without `--root` takes the + /// environment folder from the shared rule (see + /// `rocm_core::runtime_python_env_root_for_executable`): only an + /// interpreter in a `bin` or `Scripts` folder, in any case, names one. An + /// interpreter in an unrelated folder yields no root, and the request is + /// then refused with `--root` guidance rather than adopting a guessed + /// folder. + #[test] + fn adopt_python_file_infers_a_root_only_from_a_bin_or_scripts_folder() -> Result<()> { + let (root, _) = test_paths("runtime-adopt-infer-root"); + for (folder, expected_root) in [ + ("bin", true), + ("Scripts", true), + ("SCRIPTS", true), + ("tools", false), + ] { + let env_root = root.join(format!("env-{folder}")); + let python = env_root.join(folder).join("python"); + fs::create_dir_all(python.parent().unwrap())?; + fs::write(&python, "python")?; + + let (resolved, inferred) = resolve_adopt_python_input(&python)?; + + assert_eq!(resolved, python, "{folder}"); + assert_eq!( + inferred.as_deref(), + expected_root.then_some(env_root.as_path()), + "{folder}" + ); + } + + let _ = fs::remove_dir_all(root); + Ok(()) + } + + /// What no inferred root costs the user: the request is refused and asks + /// for `--root`, and an explicit `--root` still adopts the same + /// interpreter. + #[test] + fn adopt_request_without_an_inferred_root_asks_for_root() { + let python = PathBuf::from("python"); + let request = |install_root: Option| { + infer_adopt_runtime_request( + python.clone(), + install_root, + None, + None, + None, + false, + &therock::RocmSdkPythonProbe { + rocm_sdk_version: Some("7.13.0".to_owned()), + resolved_target_family: Some("gfx120X-all".to_owned()), + ..therock::RocmSdkPythonProbe::default() + }, + ) + }; + + let error = request(None).unwrap_err().to_string(); + assert!(error.contains("pass --root"), "{error}"); + + let explicit = request(Some(PathBuf::from("/opt/rocm-env"))).unwrap(); + assert_eq!(explicit.install_root, PathBuf::from("/opt/rocm-env")); + } } diff --git a/crates/rocm-core/src/lib.rs b/crates/rocm-core/src/lib.rs index 69e2da9599..463c11ee61 100644 --- a/crates/rocm-core/src/lib.rs +++ b/crates/rocm-core/src/lib.rs @@ -205,7 +205,8 @@ pub use runtime::{ runtime_path_sort_key, runtime_path_text_is_absolute_for_host, runtime_path_text_is_absolute_for_platform, runtime_paths_equivalent, runtime_python_activation_hint, runtime_python_activation_script, runtime_python_bin_dir_name, - runtime_python_env_bin_dir, runtime_python_executable_in_env, runtime_python_executable_name, + runtime_python_env_bin_dir, runtime_python_env_root_for_executable, + runtime_python_executable_in_env, runtime_python_executable_name, runtime_rocm_library_filename, shell_command_for_host, user_runtime_dir, }; pub use service_identity::{ServiceId, generate_service_id}; diff --git a/crates/rocm-core/src/runtime.rs b/crates/rocm-core/src/runtime.rs index 3535035b07..b6a31d4f93 100644 --- a/crates/rocm-core/src/runtime.rs +++ b/crates/rocm-core/src/runtime.rs @@ -119,6 +119,31 @@ pub fn runtime_python_executable_in_env(env_root: &Path) -> PathBuf { runtime_python_env_bin_dir(env_root).join(runtime_python_executable_name()) } +/// The environment folder an interpreter belongs to, found from the +/// interpreter's own path: the inverse of [`runtime_python_executable_in_env`] +/// for a caller that holds only the interpreter. +/// +/// An interpreter belongs to an environment only when it sits directly in that +/// environment's `bin` or `Scripts` folder, and the answer is that folder's +/// parent. Both layouts are accepted, in any letter case, whatever the host: a +/// recorded interpreter path is not always from this host's layout, and a +/// Windows file system does not tell `Scripts` from `SCRIPTS`. +/// +/// Anything else gives `None`: an interpreter in some other folder, a bare file +/// name, or one at the file system root. A guess would name a folder that is +/// not an environment, and the caller would then export it as `VIRTUAL_ENV`, +/// look for `lib/python3.*` under it, or register it as a runtime. `None` lets +/// each caller refuse in its own words instead. +pub fn runtime_python_env_root_for_executable(python: &Path) -> Option { + let bin_dir = python.parent()?; + let name = bin_dir.file_name()?.to_str()?; + if name.eq_ignore_ascii_case("bin") || name.eq_ignore_ascii_case("Scripts") { + bin_dir.parent().map(Path::to_path_buf) + } else { + None + } +} + pub fn runtime_python_activation_script(env_root: &Path) -> PathBuf { let script = if runtime_is_windows() { "activate.bat" @@ -1026,6 +1051,57 @@ mod tests { use super::*; use std::fs; + /// The one rule every caller shares. Paths are built with `join`, not + /// written with a separator, so the table means the same on every host. + #[test] + fn env_root_for_executable_needs_a_bin_or_scripts_folder() { + let venv = Path::new("opt").join("venv"); + for (folder, python) in [ + ("bin", "python"), + ("BIN", "python"), + ("Scripts", "python.exe"), + ("SCRIPTS", "python.exe"), + ("scripts", "python.exe"), + ] { + assert_eq!( + runtime_python_env_root_for_executable(&venv.join(folder).join(python)), + Some(venv.clone()), + "{folder}" + ); + } + for folder in ["tools", "bin2", "my-bin", "venv"] { + assert_eq!( + runtime_python_env_root_for_executable(&venv.join(folder).join("python")), + None, + "{folder}" + ); + } + // A bare file name has an empty parent, and a root-level file's parent + // is the file system root: neither is inside a `bin` or `Scripts`. + assert_eq!( + runtime_python_env_root_for_executable(Path::new("python")), + None + ); + assert_eq!( + runtime_python_env_root_for_executable( + &Path::new(std::path::MAIN_SEPARATOR_STR).join("python") + ), + None + ); + } + + /// The inverse really is the inverse: the interpreter this host's layout + /// puts in an environment leads back to that environment. + #[test] + fn env_root_for_executable_inverts_the_hosts_layout() { + let env_root = Path::new("opt").join("venv"); + let python = runtime_python_executable_in_env(&env_root); + assert_eq!( + runtime_python_env_root_for_executable(&python).as_deref(), + Some(normalize_runtime_path_for_host(&env_root).as_path()) + ); + } + fn scratch_dir(name: &str) -> PathBuf { let root = std::env::temp_dir().join(format!( "rocm-core-resolve-{name}-{}-{:?}", diff --git a/docs/architecture.md b/docs/architecture.md index 724bc81c0f..d7cca22111 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -219,7 +219,7 @@ Further `rocm-core` modules, each with its own doc comment except where noted: - [`proc_lifecycle.rs`](../crates/rocm-core/src/proc_lifecycle.rs) — verified, bounded termination of a process by persisted PID, refusing to signal a PID whose start-time identity no longer matches. - [`report.rs`](../crates/rocm-core/src/report.rs) — the content of a Doctor report and the rule deciding whether one may exist; it sends nothing. - [`report_delivery.rs`](../crates/rocm-core/src/report_delivery.rs) — how a report leaves the machine: building its link and deciding whether a browser may be started. -- [`runtime.rs`](../crates/rocm-core/src/runtime.rs) — the host-platform layer: `RuntimePlatform`/`RuntimeHost`, OS-specific executable and Python-environment names, default config/data/cache directories, and path-text and path-list helpers (no module doc comment). +- [`runtime.rs`](../crates/rocm-core/src/runtime.rs) — the host-platform layer: `RuntimePlatform`/`RuntimeHost`, OS-specific executable and Python-environment names (including `runtime_python_env_root_for_executable`, the one rule for finding an environment's folder from its interpreter's path: only an interpreter directly inside a `bin` or `Scripts` folder, in any case, has one, and everything else gets `None`; the adopt command, the ComfyUI runtime environment and the vLLM launch all call it rather than keeping a copy, since the engine crate cannot reach `apps/rocm`), default config/data/cache directories, and path-text and path-list helpers (no module doc comment). - [`terminal.rs`](../crates/rocm-core/src/terminal.rs) — one ECMA-48 walk over untrusted terminal output, shared by every caller that has to quote or re-render it (`serve_summary.rs`, `vllm/startup_diagnostics.rs`, `vllm_oom.rs`, `diagnose/engine.rs`). - [`user_path.rs`](../crates/rocm-core/src/user_path.rs) — removing the install directory from the per-user Windows `Path` that the installer added it to. - [`uv.rs`](../crates/rocm-core/src/uv.rs) — acquiring the `uv` package manager into the managed cache, plus the argument/environment helpers `apps/rocm` and the vLLM engine share. diff --git a/docs/testing.md b/docs/testing.md index eb9f36502e..788c04833f 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -907,6 +907,10 @@ rocm runtimes adopt \ --runtime-key adopted-release-pip-gfx120x-all-7-13-0 ``` +`--root` may be left out when `--python` sits directly in the environment's `bin` +(or `Scripts`) folder; an interpreter anywhere else is refused until `--root` is +given (scenario `runtime-23`). + Focused unit coverage: ```bash diff --git a/engines/vllm/src/process.rs b/engines/vllm/src/process.rs index 1d6acf7c1e..87f3d4f9a5 100644 --- a/engines/vllm/src/process.rs +++ b/engines/vllm/src/process.rs @@ -459,16 +459,12 @@ fn vllm_venv_root(runtime: &VllmRuntime) -> Result { runtime.runtime_id ) })?; - python - .parent() - .and_then(Path::parent) - .map(Path::to_path_buf) - .ok_or_else(|| { - anyhow!( - "python executable `{}` is not inside a venv (bin/Scripts) layout", - python.display() - ) - }) + rocm_core::runtime_python_env_root_for_executable(python).ok_or_else(|| { + anyhow!( + "python executable `{}` is not inside a venv (bin/Scripts) layout", + python.display() + ) + }) } /// Finds `/lib/python3.*/site-packages`, the one location a venv keeps /// its packages under. Bails on anything other than exactly one `python3.*` @@ -1083,6 +1079,31 @@ mod tests { PathBuf::from("/opt/venv") ); } + /// The runtime's venv is found by the rule every caller shares (see + /// `rocm_core::runtime_python_env_root_for_executable`): an interpreter in + /// an unrelated folder is refused, not mapped to that folder's parent, + /// which would send the site-packages lookup into a folder that is not a + /// venv. + #[test] + fn vllm_venv_root_needs_a_bin_or_scripts_folder() { + for (python, expected) in [ + ("/opt/venv/bin/python", Some("/opt/venv")), + ("/opt/venv/Scripts/python.exe", Some("/opt/venv")), + ("/opt/venv/SCRIPTS/python.exe", Some("/opt/venv")), + ("/opt/venv/tools/python", None), + ("python", None), + ("/python", None), + ] { + let runtime = test_vllm_runtime(Some(PathBuf::from(python)), None); + let root = vllm_venv_root(&runtime); + if let Some(expected) = expected { + assert_eq!(root.unwrap(), PathBuf::from(expected), "{python}"); + } else { + let error = root.expect_err(python).to_string(); + assert!(error.contains("is not inside a venv"), "{python}: {error}"); + } + } + } #[test] fn venv_site_packages_dir_finds_the_single_python3_dir() -> Result<()> { let venv = tempfile::tempdir()?; diff --git a/tests/e2e-cucumber/features/runtime_setup.feature b/tests/e2e-cucumber/features/runtime_setup.feature index 2879432000..e5f59f3fdf 100644 --- a/tests/e2e-cucumber/features/runtime_setup.feature +++ b/tests/e2e-cucumber/features/runtime_setup.feature @@ -473,3 +473,22 @@ Feature: Runtime configuration When the user approves a natural-language SDK install into a folder whose name has a quote Then the request plan names that folder as a single argument And the executed command names that folder as a single argument + + # `rocm runtimes adopt --python` takes the environment folder from where the + # interpreter sits: the folder that holds its `bin` (or `Scripts`) folder. An + # interpreter anywhere else has no environment folder to infer, and a guess (the + # interpreter's grandparent, which is what the command used to adopt) would + # register a folder that is not an environment as a runtime. The command refuses + # instead and names the flag that supplies the folder; nothing is saved. + # + # Linux-only: the stand-in interpreter is a POSIX shell script. The "adopts with + # --root" half is covered by the unit test + # `adopt_request_without_an_inferred_root_asks_for_root`, which shows an explicit + # root clears the refusal; adopting for real needs a genuine ROCm SDK environment. + @id:runtime-adopt-outside-a-venv-asks-for-root @requires-os:linux + Scenario: runtime-23 - Adopting a Python that sits outside any environment's bin folder asks for --root + Given a Python interpreter that sits outside any environment's bin folder + When the user adopts that interpreter without naming an environment folder + Then the adoption is refused + And the refusal asks for the environment folder with --root + And no runtime is registered diff --git a/tests/e2e-cucumber/tests/e2e/runtime_steps.rs b/tests/e2e-cucumber/tests/e2e/runtime_steps.rs index 4150c9a679..6cf219fd41 100644 --- a/tests/e2e-cucumber/tests/e2e/runtime_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/runtime_steps.rs @@ -1515,3 +1515,66 @@ async fn assert_freeform_execution_prefix_is_one_word(world: &mut E2eWorld) { &freeform_prefix_with_quote(world), ); } + +/// Where scenario runtime-23 plants its interpreter: inside a folder called `tools`, +/// which is neither `bin` nor `Scripts`, so nothing about its location names an +/// environment. +fn interpreter_outside_a_venv(world: &E2eWorld) -> std::path::PathBuf { + world + .isolated_root + .as_ref() + .expect("scenario has no isolated root") + .path() + .join("not-a-venv") + .join("tools") + .join("python") +} + +/// A stand-in interpreter that answers the SDK probe with the smallest document the +/// CLI parses. The refusal under test happens after the probe and before anything is +/// read from the environment, so nothing else about the interpreter matters. +/// +/// A POSIX shell script, so the scenario is Linux-only (`@requires-os:linux`). +#[given("a Python interpreter that sits outside any environment's bin folder")] +async fn setup_interpreter_outside_a_venv(world: &mut E2eWorld) { + let python = interpreter_outside_a_venv(world); + std::fs::create_dir_all(python.parent().expect("interpreter has a folder")) + .expect("failed to create the interpreter's folder"); + rocm_core::fake_executable::write_fake_executable( + &python, + "#!/bin/sh\necho '{\"import_ok\": true}'\n", + ) + .expect("failed to write the stand-in interpreter"); +} + +#[when("the user adopts that interpreter without naming an environment folder")] +async fn user_adopts_interpreter_without_root(world: &mut E2eWorld) { + let python = interpreter_outside_a_venv(world) + .to_string_lossy() + .into_owned(); + let (stdout, stderr, rc) = crate::run_rocm(world, &["runtimes", "adopt", "--python", &python]); + world.cli_output = Some(stdout); + world.cli_stderr = Some(stderr); + world.cli_rc = Some(rc); +} + +#[then("the refusal asks for the environment folder with --root")] +async fn assert_adopt_refusal_asks_for_root(world: &mut E2eWorld) { + let stdout = world.cli_output.as_deref().unwrap_or(""); + let stderr = world.cli_stderr.as_deref().unwrap_or(""); + let combined = format!("{stdout}{stderr}"); + assert!( + combined.contains("could not infer the Python environment folder") + && combined.contains("pass --root"), + "the refusal does not ask for --root:\n{combined}" + ); +} + +#[then("no runtime is registered")] +async fn assert_no_runtime_registered(world: &mut E2eWorld) { + let (stdout, _, _) = crate::run_rocm(world, &["runtimes", "list"]); + assert!( + stdout.contains("installed: none") || stdout.contains("managed_runtimes: 0"), + "the refused adoption left a runtime registered:\n{stdout}" + ); +}