diff --git a/crates/rocm-core/src/examine/framework.rs b/crates/rocm-core/src/examine/framework.rs index 420f7b0755..6817a16a9f 100644 --- a/crates/rocm-core/src/examine/framework.rs +++ b/crates/rocm-core/src/examine/framework.rs @@ -125,6 +125,9 @@ fn runtime_library_path_env( } fn probe_pytorch_on_path(e: &mut Examination) { + // On Windows `which` also accepts any `PATHEXT` spelling (`python.PY`, `.PS1`), + // while the probe starts the bare name through `Command`, which only starts an + // `.exe`: the same caveat as in `probe_llama_cpp`. let py = if which("python") { "python" } else if which("python3") { @@ -222,6 +225,10 @@ fn record_pytorch_probe(e: &mut Examination, rc: i32, out: &str, err: &str) { } fn probe_llama_cpp(e: &mut Examination) { + // `which` follows `PATHEXT` on Windows, so a name can read as found through an + // extension this probe cannot run (`llama-cli.PS1`): the probe starts the bare + // name through `Command`, which only starts an `.exe`. The report can then + // name a binary it cannot start; the later run fails and says so. let binary = ["llama-cli", "llama-server", "main"] .into_iter() .find(|name| which(name)); diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index fa08dd40c7..c1854ac0d8 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -12,13 +12,13 @@ //! [`crate::confirm`] and is re-exported here too, so the //! `crate::host_gpu::interactive_terminal` path keeps resolving. //! -//! The probes live in child modules: `capture` (optional-command capture and the -//! tool-on-`PATH` lookup), `os_facts` (kernel, distro, CPU and RAM), `linux` -//! (sysfs, KFD and DRM), `gpu_visibility` (which GPUs this process may use), -//! `windows_inventory` (the Windows display-adapter inventory), `wsl` (WSL -//! detection and the Windows host driver as seen from the guest), `render` (the -//! `rocm examine` text of an `ExamineSummary`), `diagnostics` (the GPU -//! detection diagnostics text) and `engine_default` (the default serve engine). +//! The probes live in child modules: `capture` (optional-command capture), +//! `os_facts` (kernel, distro, CPU and RAM), `linux` (sysfs, KFD and DRM), +//! `gpu_visibility` (which GPUs this process may use), `windows_inventory` (the +//! Windows display-adapter inventory), `wsl` (WSL detection and the Windows host +//! driver as seen from the guest), `render` (the `rocm examine` text of an +//! `ExamineSummary`), `diagnostics` (the GPU detection diagnostics text) and +//! `engine_default` (the default serve engine). //! //! The `examine` child modules and `fix.rs` still reach several items here //! through `lib.rs`'s flat `crate::` re-export paths rather than diff --git a/crates/rocm-core/src/host_gpu/capture.rs b/crates/rocm-core/src/host_gpu/capture.rs index fa2c1c68fe..7aef97001d 100644 --- a/crates/rocm-core/src/host_gpu/capture.rs +++ b/crates/rocm-core/src/host_gpu/capture.rs @@ -5,11 +5,12 @@ //! Optional-command capture for the host probes. //! //! Runs a tool that may not be installed under a short timeout and keeps its -//! stdout only on success, resolving the program the way the platform does -//! (`PATHEXT` and the fixed Windows system locations included). A missing, -//! slow or failing tool reads as `None`, never as an error. +//! stdout only on success, trying each spelling of the program that +//! [`crate::probe_exec::tool_path_candidates`] gives (`PATHEXT` and the fixed +//! Windows system locations included). A missing, slow or failing tool reads as +//! `None`, never as an error. -use crate::runtime_is_windows; +use crate::probe_exec::tool_path_candidates; use std::io::Read; use std::path::Path; use std::process::{Command, Stdio}; @@ -111,55 +112,3 @@ fn debug_command_capture_failure(program: &Path, stage: &str, detail: &str) { program.display() ); } - -pub(super) fn tool_on_path(program: &str) -> bool { - std::env::var_os("PATH").is_some_and(|path| { - std::env::split_paths(&path).any(|dir| { - tool_path_candidates(program) - .into_iter() - .any(|name| dir.join(name).is_file()) - }) - }) -} - -pub(super) fn tool_path_candidates(program: &str) -> Vec { - let path = Path::new(program); - if path.extension().is_some() || !runtime_is_windows() { - return vec![program.to_owned()]; - } - let mut names = Vec::new(); - names.push(program.to_owned()); - let pathext = std::env::var("PATHEXT").unwrap_or_else(|_| ".COM;.EXE;.BAT;.CMD".to_owned()); - for ext in pathext - .split(';') - .map(str::trim) - .filter(|ext| !ext.is_empty()) - { - names.push(format!("{program}{ext}")); - names.push(format!("{program}{}", ext.to_ascii_lowercase())); - } - names.extend(windows_absolute_tool_candidates(program)); - names.sort(); - names.dedup(); - names -} - -fn windows_absolute_tool_candidates(program: &str) -> Vec { - if !runtime_is_windows() { - return Vec::new(); - } - let program = program.trim().to_ascii_lowercase(); - let system_root = std::env::var("SystemRoot") - .or_else(|_| std::env::var("WINDIR")) - .unwrap_or_else(|_| r"C:\Windows".to_owned()); - match program.as_str() { - "cmd" | "cmd.exe" => vec![format!(r"{system_root}\System32\cmd.exe")], - "pnputil" | "pnputil.exe" => vec![format!(r"{system_root}\System32\pnputil.exe")], - "powershell" | "powershell.exe" => vec![ - format!(r"{system_root}\System32\WindowsPowerShell\v1.0\powershell.exe"), - "powershell.exe".to_owned(), - ], - "pwsh" | "pwsh.exe" => vec!["pwsh.exe".to_owned()], - _ => Vec::new(), - } -} diff --git a/crates/rocm-core/src/host_gpu/diagnostics.rs b/crates/rocm-core/src/host_gpu/diagnostics.rs index 1a456f361a..bc190d2f24 100644 --- a/crates/rocm-core/src/host_gpu/diagnostics.rs +++ b/crates/rocm-core/src/host_gpu/diagnostics.rs @@ -5,8 +5,6 @@ //! The text `rocm install sdk` prints when it cannot resolve a GPU: what the //! detection saw, and on Windows the raw output of each inventory query. -#[cfg(windows)] -use super::capture::tool_path_candidates; use super::detect_host_gpu_summary; use super::linux::{detect_linux_primary_gpu_name, detect_linux_sysfs_gfx_target}; #[cfg(windows)] @@ -21,6 +19,8 @@ use crate::gfx_target::{ amd_pci_device_id_from_pnp_id, gfx_target_from_amd_marketing_name, gfx_target_from_amd_pci_device_id, }; +#[cfg(windows)] +use crate::probe_exec::tool_path_candidates; use crate::{runtime_is_linux, runtime_is_windows, runtime_os_name}; #[cfg(windows)] use std::io::Read; diff --git a/crates/rocm-core/src/host_gpu/wsl.rs b/crates/rocm-core/src/host_gpu/wsl.rs index 098d99ef22..c5900a039a 100644 --- a/crates/rocm-core/src/host_gpu/wsl.rs +++ b/crates/rocm-core/src/host_gpu/wsl.rs @@ -5,9 +5,7 @@ //! WSL detection and the Windows host driver as seen from the guest: the WSL2 //! signals, the librocdxg chain, and the local and WSL host-driver probes. -use super::capture::{ - capture_optional_command, capture_optional_command_with_timeout, tool_on_path, -}; +use super::capture::{capture_optional_command, capture_optional_command_with_timeout}; use super::windows_inventory::{ WINDOWS_INVENTORY_QUERY_TIMEOUT, WINDOWS_VIDEO_CONTROLLER_INVENTORY_SCRIPT, WindowsExamineInventory, detect_windows_examine_inventory_with_driver_facts, @@ -15,6 +13,7 @@ use super::windows_inventory::{ }; use super::{DriverSummary, WslSummary}; use crate::gfx_target::parse_windows_display_gfx_target; +use crate::probe_exec::which; use crate::{discover_rocm_installs, host_path, runtime_is_linux, runtime_is_windows}; use std::fs; use std::path::{Path, PathBuf}; @@ -372,8 +371,8 @@ pub(crate) fn detect_wsl_summary() -> Option { // The roots are already re-rooted through `host_path`, so this existence check // takes the path as given. let librocdxg_beside_runtime = librocdxg_beside_runtime(&roots, Path::exists); - let rocminfo = tool_on_path("rocminfo"); - let cargo = tool_on_path("cargo"); + let rocminfo = which("rocminfo"); + let cargo = which("cargo"); let missing = missing_plumbing( dxg_device, dxcore, diff --git a/crates/rocm-core/src/probe_exec.rs b/crates/rocm-core/src/probe_exec.rs index 86f807cfa4..37dca2b437 100644 --- a/crates/rocm-core/src/probe_exec.rs +++ b/crates/rocm-core/src/probe_exec.rs @@ -11,9 +11,9 @@ //! importing the module that owns the `Examination` document. use crate::runtime_is_windows; -use std::ffi::OsString; +use std::ffi::{OsStr, OsString}; use std::io::Read; -use std::path::Path; +use std::path::{Path, PathBuf}; use std::process::{Command, Stdio}; use std::thread; use std::time::{Duration, Instant}; @@ -134,27 +134,140 @@ pub(crate) fn read_host_text(path: &str) -> String { std::fs::read_to_string(crate::host_path(path)).unwrap_or_default() } -/// Whether `program` resolves on `PATH` (best-effort, no execution). +/// Whether `program` is installed, by `PATH` lookup plus a few fixed Windows +/// locations (best-effort, no execution). +/// +/// The one PATH lookup of the host probes: the examination stack's capability +/// checks and the summary stack's WSL facts both ask it, so a tool reads as +/// installed or not the same way in every part of `rocm examine`. It tries +/// each spelling [`tool_path_candidates`] gives, in each directory of `PATH`, +/// and answers `true` for the first one that is a file. +/// +/// - An empty `PATH` entry is skipped, not read as the current directory as a +/// shell or `execvp` would. A file named like the tool in the directory the +/// CLI was started from therefore does not read as the tool being installed +/// through an empty entry, which matters for the checks that gate a +/// privileged step (`sudo`, `usermod`). An explicit `.` or other relative +/// entry is an ordinary directory and is searched. The cost is that a +/// program the CLI later starts by bare name can still resolve from the +/// current directory when `PATH` has an empty entry, because the operating +/// system resolves it, not this lookup. +/// - A `PATH` that is not valid Unicode is searched: it is split as an +/// `OsString`, and the entries that are not Unicode are looked in as they are. +/// - The directories are split the way [`std::env::split_paths`] splits them on +/// this platform, so on Windows an entry may be quoted to hold a `;`. +/// - On Windows a program without an extension is tried with every `PATHEXT` +/// entry in both cases. A name that already has an extension (`python3.11`, +/// `wsl.exe`) is tried as given and nothing else; the examination's old copy +/// also tried `.exe`, `.bat` and `.cmd` after it, and no caller passes a +/// dotted name that relied on that (`wsl.exe` is found as given). +/// - On Windows `cmd`, `pnputil` and `powershell` are also found at their fixed +/// System32 locations (`pwsh` has no fixed location: its only extra candidate +/// is the bare `pwsh.exe`). An absolute candidate is tested once as it is, not +/// joined onto each `PATH` directory, so it is found whether or not `PATH` is +/// set, on `PATH` or not: the lookup then agrees with what the capture runner, +/// which starts those locations, can run. No caller asks for those names +/// today; they stay in the shared candidate list because the runner needs +/// them and one list cannot drift from the other. pub(crate) fn which(program: &str) -> bool { - let Ok(path) = std::env::var("PATH") else { - return false; - }; - let (sep, exts): (char, &[&str]) = if runtime_is_windows() { - (';', &[".exe", ".bat", ".cmd", ""]) - } else { - (':', &[""]) - }; - for dir in path.split(sep) { - if dir.is_empty() { - continue; - } - for ext in exts { - if Path::new(dir).join(format!("{program}{ext}")).is_file() { - return true; - } - } + let dirs = std::env::var_os("PATH") + .map(|path| path_dirs(&path)) + .unwrap_or_default(); + found_in(&dirs, &tool_path_candidates(program), Path::is_file) +} + +/// The directories of a `PATH` value, empty entries dropped. +fn path_dirs(path: &OsStr) -> Vec { + std::env::split_paths(path) + .filter(|dir| !dir.as_os_str().is_empty()) + .collect() +} + +/// Whether any of `candidates` is a file according to `is_file`. +/// +/// A relative candidate is joined onto each of `dirs`: directories are tried in +/// order, and within a directory the candidates in order. An absolute candidate +/// names its own location, so it is tested once as it is, after the directories, +/// and does not depend on `dirs` at all. `is_file` is injected so a test can say +/// which files exist without a file system. +fn found_in(dirs: &[PathBuf], candidates: &[String], is_file: impl Fn(&Path) -> bool) -> bool { + let in_a_dir = dirs.iter().any(|dir| { + candidates + .iter() + .filter(|candidate| !Path::new(candidate).is_absolute()) + .any(|candidate| is_file(&dir.join(candidate))) + }); + in_a_dir + || candidates + .iter() + .map(Path::new) + .filter(|candidate| candidate.is_absolute()) + .any(is_file) +} + +/// The spellings of `program` to try, in the order to try them. +/// +/// On Linux, just `program`. On Windows a program with no extension is also +/// spelled with each `PATHEXT` entry, in both cases, and `cmd`, `pnputil`, +/// `powershell` and `pwsh` add their fixed locations. Used by [`which`] and by +/// the capture runner, which starts each spelling in turn. +pub(crate) fn tool_path_candidates(program: &str) -> Vec { + path_candidates( + program, + runtime_is_windows(), + std::env::var("PATHEXT").ok().as_deref(), + &system_root_from_env(), + ) +} + +/// `SystemRoot`, else `WINDIR`, else `C:\Windows`. +fn system_root_from_env() -> String { + std::env::var("SystemRoot") + .or_else(|_| std::env::var("WINDIR")) + .unwrap_or_else(|_| r"C:\Windows".to_owned()) +} + +/// [`tool_path_candidates`] with the platform, `PATHEXT` (`None` when unset or +/// not Unicode) and system root passed in, so the Windows spellings can be +/// checked on every host. +fn path_candidates( + program: &str, + windows: bool, + pathext: Option<&str>, + system_root: &str, +) -> Vec { + if Path::new(program).extension().is_some() || !windows { + return vec![program.to_owned()]; + } + let mut names = vec![program.to_owned()]; + let pathext = pathext.unwrap_or(".COM;.EXE;.BAT;.CMD"); + for ext in pathext + .split(';') + .map(str::trim) + .filter(|ext| !ext.is_empty()) + { + names.push(format!("{program}{ext}")); + names.push(format!("{program}{}", ext.to_ascii_lowercase())); + } + names.extend(windows_absolute_tool_candidates(program, system_root)); + names.sort(); + names.dedup(); + names +} + +/// The fixed locations of the Windows tools the host probes run. +fn windows_absolute_tool_candidates(program: &str, system_root: &str) -> Vec { + let program = program.trim().to_ascii_lowercase(); + match program.as_str() { + "cmd" | "cmd.exe" => vec![format!(r"{system_root}\System32\cmd.exe")], + "pnputil" | "pnputil.exe" => vec![format!(r"{system_root}\System32\pnputil.exe")], + "powershell" | "powershell.exe" => vec![ + format!(r"{system_root}\System32\WindowsPowerShell\v1.0\powershell.exe"), + "powershell.exe".to_owned(), + ], + "pwsh" | "pwsh.exe" => vec!["pwsh.exe".to_owned()], + _ => Vec::new(), } - false } pub(crate) const SHORT: Duration = Duration::from_secs(5); @@ -215,3 +328,451 @@ mod tests { assert_eq!(truncate_to_chars("short".to_owned(), 4000), "short"); } } + +/// The PATH lookup ([`which`]) and the spellings it tries +/// ([`tool_path_candidates`]), which the summary stack and the examination stack +/// share. Before they were one, each stack had its own copy and the copies +/// answered differently for an empty `PATH` entry, a `PATH` that is not Unicode +/// and the Windows spellings (see `docs/host-probing.md`, "PATH lookup"); the +/// tests here pin the one answer they now give. +/// +/// The pure functions are tested on every host with the platform, `PATHEXT` and +/// the files that exist passed in. The lookup as a whole reads the process's own +/// `PATH`, and one case needs a different working directory, which a test thread +/// cannot change without disturbing every other test in the process (they spawn +/// children by bare name and call `which` themselves). So those cases run in a +/// child: this test binary again, started with the `PATH`, `PATHEXT` and working +/// directory the case needs and asked to run only +/// [`which_child_reports_its_answer`]. In a normal run that test finds no +/// program to ask about and passes without doing anything. +#[cfg(test)] +mod path_lookup_tests { + use super::{found_in, path_candidates, path_dirs, which}; + use std::cell::RefCell; + use std::ffi::{OsStr, OsString}; + use std::path::{Path, PathBuf}; + use std::process::Command; + + const PROGRAM_ENV: &str = "ROCM_CORE_TEST_WHICH_PROGRAM"; + const ANSWER_PREFIX: &str = "which-answer:"; + /// A name no host has installed, so only the planted file can answer for it. + const PROGRAM: &str = "rocm-core-which-tool"; + + fn names(candidates: &[&str]) -> Vec { + candidates.iter().map(|name| (*name).to_owned()).collect() + } + + #[test] + fn candidates_off_windows_are_the_program_alone_whatever_pathext_says() { + assert_eq!( + path_candidates("tool", false, Some(".COM;.EXE"), r"C:\Windows"), + names(&["tool"]) + ); + } + + #[test] + fn candidates_on_windows_for_a_name_with_an_extension_are_the_name_alone() { + // The early return also keeps the System32 spelling of `cmd.exe` out of + // the list: only the extension-less `cmd` reaches it. + assert_eq!( + path_candidates("cmd.exe", true, Some(".COM;.EXE"), r"C:\Windows"), + names(&["cmd.exe"]) + ); + assert_eq!( + path_candidates("tool.ps1", true, Some(".PS1"), r"C:\Windows"), + names(&["tool.ps1"]) + ); + // A dotted name is not a bare name with an unknown extension: PATHEXT is + // not tried after it, so `python3.11` is looked for as `python3.11` only. + // The examination's old copy also tried `.exe`, `.bat` and `.cmd`; no + // caller passes such a name (they are all bare, or `wsl.exe`). + assert_eq!( + path_candidates( + "python3.11", + true, + Some(".COM;.EXE;.BAT;.CMD"), + r"C:\Windows" + ), + names(&["python3.11"]) + ); + } + + #[test] + fn candidates_on_windows_try_every_pathext_entry_in_both_cases() { + // Sorted as bytes, so the upper-case spelling of an extension comes + // before its lower-case one, and the bare name before both. `.PS1` is + // outside the old examination list (`.exe`, `.bat`, `.cmd`). + assert_eq!( + path_candidates("tool", true, Some(".COM;.EXE;.PS1"), r"C:\Windows"), + names(&[ + "tool", "tool.COM", "tool.EXE", "tool.PS1", "tool.com", "tool.exe", "tool.ps1", + ]) + ); + } + + #[test] + fn candidates_on_windows_trim_pathext_entries_and_skip_empty_ones() { + assert_eq!( + path_candidates("tool", true, Some(" .BAT ;; ;.CMD;"), r"C:\Windows"), + names(&["tool", "tool.BAT", "tool.CMD", "tool.bat", "tool.cmd"]) + ); + } + + #[test] + fn candidates_on_windows_fall_back_to_the_default_pathext_when_it_is_unset() { + assert_eq!( + path_candidates("tool", true, None, r"C:\Windows"), + names(&[ + "tool", "tool.BAT", "tool.CMD", "tool.COM", "tool.EXE", "tool.bat", "tool.cmd", + "tool.com", "tool.exe", + ]) + ); + } + + #[test] + fn candidates_on_windows_add_the_fixed_system32_locations() { + let root = r"C:\Win"; + // A `PATHEXT` without `.EXE`, so `powershell.exe` and `pwsh.exe` can only + // come from the fixed list: with `.EXE` in it the expansion adds them + // anyway and these assertions would not notice the list losing them. + let with = |program: &str| path_candidates(program, true, Some(".BAT"), root); + + assert!( + with("cmd").contains(&r"C:\Win\System32\cmd.exe".to_owned()), + "{:?}", + with("cmd") + ); + assert!(with("pnputil").contains(&r"C:\Win\System32\pnputil.exe".to_owned())); + let powershell = with("powershell"); + assert!( + powershell + .contains(&r"C:\Win\System32\WindowsPowerShell\v1.0\powershell.exe".to_owned()) + ); + assert!(powershell.contains(&"powershell.exe".to_owned())); + assert!(with("pwsh").contains(&"pwsh.exe".to_owned())); + // Matched without regard to case, like the file system. + assert!(with("CMD").contains(&r"C:\Win\System32\cmd.exe".to_owned())); + // The location comes first when it sorts first, which is the order the + // capture runner starts them in. + assert_eq!( + with("cmd").first().map(String::as_str), + Some(r"C:\Win\System32\cmd.exe") + ); + } + + #[test] + fn candidates_on_windows_for_other_tools_have_no_fixed_location() { + assert_eq!( + path_candidates("python", true, Some(".EXE"), r"C:\Win"), + names(&["python", "python.EXE", "python.exe"]) + ); + } + + #[test] + fn candidates_off_windows_never_name_a_system32_location() { + assert_eq!( + path_candidates("cmd", false, Some(".EXE"), r"C:\Win"), + names(&["cmd"]) + ); + } + + #[test] + fn path_dirs_drop_every_empty_entry() { + let path = std::env::join_paths([ + OsStr::new(""), + OsStr::new("first"), + OsStr::new(""), + OsStr::new("second"), + OsStr::new(""), + ]) + .expect("no entry holds a separator"); + assert_eq!( + path_dirs(&path), + vec![PathBuf::from("first"), PathBuf::from("second")] + ); + assert!(path_dirs(OsStr::new("")).is_empty()); + } + + #[cfg(unix)] + #[test] + fn path_dirs_keep_an_entry_that_is_not_unicode() { + use std::os::unix::ffi::OsStrExt as _; + + let odd = OsStr::from_bytes(b"/odd-\xff"); + let path = std::env::join_paths([OsStr::new("/usr/bin"), odd]).expect("no separator"); + assert_eq!( + path_dirs(&path), + vec![PathBuf::from("/usr/bin"), PathBuf::from(odd)] + ); + } + + #[test] + fn found_in_asks_each_candidate_in_each_directory_in_order_and_stops_at_the_first_file() { + let dirs = [PathBuf::from("first"), PathBuf::from("second")]; + let candidates = names(&["tool", "tool.exe"]); + let asked = RefCell::new(Vec::new()); + + let found = found_in(&dirs, &candidates, |file| { + asked.borrow_mut().push(file.to_owned()); + file == Path::new("second").join("tool") + }); + + assert!(found); + assert_eq!( + asked.into_inner(), + vec![ + Path::new("first").join("tool"), + Path::new("first").join("tool.exe"), + Path::new("second").join("tool"), + ] + ); + assert!(!found_in(&dirs, &candidates, |_| false)); + assert!(!found_in(&[], &candidates, |_| true)); + } + + #[test] + fn found_in_asks_about_an_absolute_candidate_once_as_it_is_whatever_the_directories() { + // This is why a System32 location is found "without being on PATH", and + // found even when PATH is unset or all empty: it is tested on its own, + // once, not joined onto each directory. + let absolute = std::env::temp_dir().join("rocm-core-absolute-candidate"); + let candidates = [absolute.to_string_lossy().into_owned()]; + + for dirs in [ + Vec::new(), + vec![PathBuf::from("anywhere")], + vec![PathBuf::from("anywhere"), PathBuf::from("elsewhere")], + ] { + let asked = RefCell::new(Vec::new()); + let found = found_in(&dirs, &candidates, |file| { + asked.borrow_mut().push(file.to_owned()); + true + }); + // With directories listed the absolute candidate is never joined + // onto them, so the only thing asked about is the candidate itself. + assert!(found, "{} directories", dirs.len()); + assert_eq!( + asked.into_inner(), + vec![absolute.clone()], + "{} directories", + dirs.len() + ); + } + assert!(!found_in(&[], &candidates, |_| false)); + } + + #[test] + fn found_in_still_tries_relative_candidates_in_directories_beside_an_absolute_one() { + let absolute = std::env::temp_dir().join("rocm-core-absolute-candidate"); + let candidates = [ + absolute.to_string_lossy().into_owned(), + "tool.exe".to_owned(), + ]; + let dirs = [PathBuf::from("first")]; + + assert!(found_in(&dirs, &candidates, |file| file + == Path::new("first").join("tool.exe"))); + assert!(!found_in(&[], &candidates, |file| file + == Path::new("first").join("tool.exe"))); + } + + /// The child's side of [`ask_for`]: print the answer for the program named in + /// the environment. Does nothing in a normal test run. + #[test] + fn which_child_reports_its_answer() { + let Some(program) = std::env::var_os(PROGRAM_ENV) else { + return; + }; + println!("{ANSWER_PREFIX} {}", which(&program.to_string_lossy())); + } + + /// Run [`which`] for `program` in a child whose `PATH` is `path` (unset when + /// `None`), working directory is `cwd` and extra environment is `env`. + fn ask_for(program: &str, path: Option<&OsStr>, cwd: &Path, env: &[(&str, &str)]) -> bool { + let this_test = module_path!() + .split_once("::") + .expect("module path has a crate prefix") + .1; + let mut child = Command::new(std::env::current_exe().expect("path of the test binary")); + child + .args([ + "--exact", + &format!("{this_test}::which_child_reports_its_answer"), + "--nocapture", + "--test-threads=1", + ]) + .env(PROGRAM_ENV, program) + .current_dir(cwd); + match path { + Some(path) => child.env("PATH", path), + None => child.env_remove("PATH"), + }; + for (key, value) in env { + child.env(key, value); + } + let output = child.output().expect("start the test binary again"); + let stdout = String::from_utf8_lossy(&output.stdout); + let answer = stdout + .lines() + .find_map(|line| line.split_once(ANSWER_PREFIX).map(|(_, answer)| answer)) + .unwrap_or_else(|| { + panic!( + "the child printed no answer (status {}):\n{stdout}\n{}", + output.status, + String::from_utf8_lossy(&output.stderr) + ) + }); + answer.trim() == "true" + } + + fn ask(path: Option<&OsStr>, cwd: &Path) -> bool { + ask_for(PROGRAM, path, cwd, &[]) + } + + fn join(dirs: &[&Path]) -> OsString { + std::env::join_paths(dirs).expect("no directory name holds a path separator") + } + + /// Create `name` under `parent`, holding a file called `file_name`. + fn dir_holding(parent: &Path, name: &OsStr, file_name: &str) -> PathBuf { + let dir = parent.join(name); + std::fs::create_dir_all(&dir).expect("create the planted directory"); + crate::fake_executable::write_fake_executable(&dir.join(file_name), "#!/bin/sh\n") + .expect("plant the program"); + dir + } + + fn empty_dir(parent: &Path, name: &str) -> PathBuf { + let dir = parent.join(name); + std::fs::create_dir_all(&dir).expect("create the empty directory"); + dir + } + + #[test] + fn which_finds_a_program_in_a_path_directory_and_not_otherwise() { + let scratch = tempfile::tempdir().expect("scratch directory"); + let present = dir_holding(scratch.path(), OsStr::new("present"), PROGRAM); + let absent = empty_dir(scratch.path(), "absent"); + let cwd = empty_dir(scratch.path(), "cwd"); + + assert!( + ask(Some(&join(&[&absent, &present])), &cwd), + "a program in the second PATH directory is found" + ); + assert!( + !ask(Some(&join(&[&absent])), &cwd), + "a PATH without the program finds nothing" + ); + assert!(!ask(None, &cwd), "an unset PATH finds nothing"); + } + + #[test] + fn which_does_not_take_a_directory_named_like_the_program_for_the_program() { + let scratch = tempfile::tempdir().expect("scratch directory"); + let bin = empty_dir(scratch.path(), "bin"); + std::fs::create_dir_all(bin.join(PROGRAM)).expect("plant a directory with the name"); + assert!(!ask(Some(&join(&[&bin])), scratch.path())); + } + + /// The decision this lookup was merged on: an empty `PATH` entry is skipped, + /// so a file in the directory the CLI runs from is not "installed". The + /// summary stack's old copy read the entry as the current directory and + /// answered `true` here; the control below shows the same file does count + /// once a real entry names its directory. + #[cfg(unix)] + #[test] + fn which_does_not_read_an_empty_path_entry_as_the_current_directory() { + let scratch = tempfile::tempdir().expect("scratch directory"); + let cwd = dir_holding(scratch.path(), OsStr::new("cwd"), PROGRAM); + let bin = empty_dir(scratch.path(), "bin"); + let bin_text = bin.to_str().expect("UTF-8 scratch path"); + + for (shape, path) in [ + ("leading", format!(":{bin_text}")), + ("middle", format!("{bin_text}::{bin_text}")), + ("trailing", format!("{bin_text}:")), + ("the whole PATH", String::new()), + ] { + assert!( + !ask(Some(OsStr::new(&path)), &cwd), + "an empty entry ({shape}) must not read the current directory" + ); + } + assert!( + ask(Some(&join(&[&cwd])), &cwd), + "the same file is found when a PATH entry names its directory" + ); + } + + /// The other half of the decision: a `PATH` that is not valid Unicode is + /// still searched. The examination stack's old copy read `PATH` with + /// `std::env::var`, which fails on it, and answered `false` for every tool. + #[cfg(unix)] + #[test] + fn which_searches_a_path_that_is_not_unicode() { + use std::os::unix::ffi::OsStrExt as _; + + let scratch = tempfile::tempdir().expect("scratch directory"); + let cwd = empty_dir(scratch.path(), "cwd"); + let valid = dir_holding(scratch.path(), OsStr::new("valid"), PROGRAM); + // A directory whose own name is not Unicode (it holds the byte 0xff). + let odd = dir_holding(scratch.path(), OsStr::from_bytes(b"odd-\xff"), PROGRAM); + let missing_odd = scratch.path().join(OsStr::from_bytes(b"missing-\xff")); + + assert!( + ask(Some(&join(&[&odd])), &cwd), + "the program sits in a directory whose name is not Unicode" + ); + assert!( + ask(Some(&join(&[&missing_odd, &valid])), &cwd), + "a Unicode directory after an entry that is not Unicode is still searched" + ); + assert!( + !ask(Some(&join(&[&missing_odd])), &cwd), + "a PATH that is not Unicode does not find a program that is not on it" + ); + } + + /// A `.ps1` listed in `PATHEXT` is found, where the examination stack's old + /// copy tried only `.exe`, `.bat`, `.cmd` and the bare name. + #[cfg(windows)] + #[test] + fn which_tries_a_pathext_extension_outside_exe_bat_and_cmd() { + let scratch = tempfile::tempdir().expect("scratch directory"); + let ps1 = dir_holding(scratch.path(), OsStr::new("ps1"), &format!("{PROGRAM}.ps1")); + let pathext = [("PATHEXT", ".COM;.EXE;.BAT;.CMD;.PS1")]; + assert!(ask_for( + PROGRAM, + Some(&join(&[&ps1])), + scratch.path(), + &pathext + )); + } + + /// An entry in quotes keeps a `;` inside it, as `std::env::split_paths` + /// reads it on Windows; the examination stack's old copy split on every `;`. + #[cfg(windows)] + #[test] + fn which_searches_a_quoted_path_entry_that_holds_a_semicolon() { + let scratch = tempfile::tempdir().expect("scratch directory"); + let dir = dir_holding( + scratch.path(), + OsStr::new("semi;colon"), + &format!("{PROGRAM}.exe"), + ); + let quoted = format!("\"{}\"", dir.display()); + assert!(ask(Some(OsStr::new("ed)), scratch.path())); + } + + /// `cmd` is found at its System32 location without being on `PATH`, as the + /// summary stack's old copy found it; the examination stack's did not. + #[cfg(windows)] + #[test] + fn which_finds_cmd_at_its_system32_location_without_it_being_on_path() { + let scratch = tempfile::tempdir().expect("scratch directory"); + let empty = empty_dir(scratch.path(), "empty"); + assert!(ask_for("cmd", Some(&join(&[&empty])), scratch.path(), &[])); + // And with no PATH at all, as the capture runner could still start it. + assert!(ask_for("cmd", None, scratch.path(), &[])); + } +} diff --git a/docs/architecture.md b/docs/architecture.md index ad51f2aaf6..81249309cb 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -187,8 +187,8 @@ Already-extracted subsystem modules, following the same full-domain-extraction p - [`gguf.rs`](../crates/rocm-core/src/gguf.rs) — reads the shape of a GGUF model (layers, KV heads, head width, parameter count, data offset) from its header over any `Read + Seek`, never touching the weights. - [`gguf_fit.rs`](../crates/rocm-core/src/gguf_fit.rs) — pure arithmetic over that header: weights + KV cache at a context size and KV type + compute buffer + runtime reserve against dedicated VRAM, the largest context that fits, and what would make a model that does not fit, fit. - [`gguf_source.rs`](../crates/rocm-core/src/gguf_source.rs) — where a header comes from: a local file, or a Hugging Face file, found by one repository-listing request (and a `HEAD` request for a file the listing does not size) and read by HTTP range requests (`HF_ENDPOINT` selects a mirror; redirects are followed by hand, up to five, and never from https to plain http). The only code in the estimate that reads a file or the network. -- [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) — (ROCMAI-85, Phase 7a of ROCMAI-27's sequencing) GPU/host hardware detection — see the module's own doc comment for what it owns. Its leaf concerns are child modules under `host_gpu/`, with `host_gpu.rs` kept as the module root: [`capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs) (running an optional tool under a timeout and the tool-on-`PATH` lookup), [`os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) (kernel version, distro name, CPU model and installed RAM), [`linux.rs`](../crates/rocm-core/src/host_gpu/linux.rs) (the sysfs, KFD and DRM probes), [`gpu_visibility.rs`](../crates/rocm-core/src/host_gpu/gpu_visibility.rs) (which AMD GPUs this process may use, from the KFD/DRM counts and the `HIP_VISIBLE_DEVICES`/`ROCR_VISIBLE_DEVICES` masks, plus `windows_amd_gpu_listing`, the native-Windows adapter bound `rocm serve --gpu ` is checked against), [`windows_inventory.rs`](../crates/rocm-core/src/host_gpu/windows_inventory.rs) (the Windows display-adapter inventory and its parsers, including the AMD-adapter count behind `windows_amd_gpu_listing`), [`wsl.rs`](../crates/rocm-core/src/host_gpu/wsl.rs) (WSL detection, the librocdxg chain and the Windows host driver as seen from the guest), [`render.rs`](../crates/rocm-core/src/host_gpu/render.rs) (the `rocm examine` text of an `ExamineSummary`, as a second `impl` block), [`diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs) (the GPU detection diagnostics text) and [`engine_default.rs`](../crates/rocm-core/src/host_gpu/engine_default.rs) (the default serve engine, and the vLLM preference for the TheRock families that serve through it). -- [`host-probing.md`](host-probing.md) — a design note, not a module: [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) and [`examine.rs`](../crates/rocm-core/src/examine.rs) are two separate host-probing stacks that still read some of the same facts twice (kernel version, CPU model, the Windows GPU query, the marketing-name table, the `PATH` lookup and the subprocess runners). It proposes which of each pair should survive, how the two differ today and the order in which they could converge; it changes no code. It is a snapshot, to be retired when the convergence tickets close. +- [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) — (ROCMAI-85, Phase 7a of ROCMAI-27's sequencing) GPU/host hardware detection — see the module's own doc comment for what it owns. Its leaf concerns are child modules under `host_gpu/`, with `host_gpu.rs` kept as the module root: [`capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs) (running an optional tool under a timeout, trying each spelling [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) gives for it), [`os_facts.rs`](../crates/rocm-core/src/host_gpu/os_facts.rs) (kernel version, distro name, CPU model and installed RAM), [`linux.rs`](../crates/rocm-core/src/host_gpu/linux.rs) (the sysfs, KFD and DRM probes), [`gpu_visibility.rs`](../crates/rocm-core/src/host_gpu/gpu_visibility.rs) (which AMD GPUs this process may use, from the KFD/DRM counts and the `HIP_VISIBLE_DEVICES`/`ROCR_VISIBLE_DEVICES` masks, plus `windows_amd_gpu_listing`, the native-Windows adapter bound `rocm serve --gpu ` is checked against), [`windows_inventory.rs`](../crates/rocm-core/src/host_gpu/windows_inventory.rs) (the Windows display-adapter inventory and its parsers, including the AMD-adapter count behind `windows_amd_gpu_listing`), [`wsl.rs`](../crates/rocm-core/src/host_gpu/wsl.rs) (WSL detection, the librocdxg chain and the Windows host driver as seen from the guest), [`render.rs`](../crates/rocm-core/src/host_gpu/render.rs) (the `rocm examine` text of an `ExamineSummary`, as a second `impl` block), [`diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs) (the GPU detection diagnostics text) and [`engine_default.rs`](../crates/rocm-core/src/host_gpu/engine_default.rs) (the default serve engine, and the vLLM preference for the TheRock families that serve through it). +- [`host-probing.md`](host-probing.md) — a design note, not a module: [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) and [`examine.rs`](../crates/rocm-core/src/examine.rs) are two separate host-probing stacks that read some of the same facts twice (kernel version, CPU model, the Windows GPU query, the marketing-name table and the subprocess runners). It proposes which of each pair should survive, how the two differ and the order in which they could converge, and records what each convergence decided; it changes no code itself. The `PATH` lookup is the first pair converged: [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs)'s `which` is now the only copy. It is a snapshot, to be retired when the convergence tickets close. - [`jsonl_store.rs`](../crates/rocm-core/src/jsonl_store.rs) — the JSONL store engine behind the automation stores: the sibling `.lock` file (`jsonl_lock_path`, re-exported at the crate root), single-line appends, torn-tail repair, size-based rotation (`JsonlRotation`) and the tail-first readers that span rotated generations. It is generic over the record type; [`automation.rs`](../crates/rocm-core/src/automation.rs) supplies the record types and each store's policy, and nothing in this module depends on it, in production or in its own tests: those drive the engine with a small record type of their own. The module is private; its engine items are `pub(crate)`. - [`managed_runtime.rs`](../crates/rocm-core/src/managed_runtime.rs) — (ROCMAI-85, Phase 7a) the TheRock managed-runtime-environment surface — see the module's own doc comment for what it owns. - [`model_catalog.rs`](../crates/rocm-core/src/model_catalog.rs) — (ROCMAI-152, Phase 7c) the curated model catalog's types, built-in catalog JSON loading, signed external recipe indexes, and artifact cache-marker bookkeeping — see the module's own doc comment for what it owns. @@ -196,7 +196,7 @@ Already-extracted subsystem modules, following the same full-domain-extraction p - [`net.rs`](../crates/rocm-core/src/net.rs) — (ROCMAI-154) networking primitives: the default local host and port, URL/endpoint formatting and parsing, and the hand-rolled loopback HTTP/TCP client (`http_get_text*`, `http_post_json_with_auth`, `read_http_response_bounded`). It depends on no other service module: the managed-service readiness probes built on it live in [`endpoint_readiness.rs`](../crates/rocm-core/src/endpoint_readiness.rs) and the streaming downloads in [`download.rs`](../crates/rocm-core/src/download.rs). - [`paths.rs`](../crates/rocm-core/src/paths.rs) — (ROCMAI-154, Phase 7b) `AppPaths` and its filesystem-location primitives. - [`placeholder.rs`](../crates/rocm-core/src/placeholder.rs) — the `` placeholder rendered reports print for an empty value: `empty_as_unknown` (returns the value untouched) and `trimmed_or_unknown` (trims first), shared by `apps/rocm`'s driver-install plan and chat tool summaries and by [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs)'s Windows GPU diagnostics, replacing the copy those two `apps/rocm` callers shared in [`runtime_install_finalize.rs`](../apps/rocm/src/runtime_install_finalize.rs) and `host_gpu.rs`'s own trimming copy. -- [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) — the host probes' subprocess and file-read helpers, split out of [`examine.rs`](../crates/rocm-core/src/examine.rs) so `fix.rs`, `process.rs` and the child modules of [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) reach them without importing the module that owns the `Examination` document: `run`/`run_with_env`/`run_raw` (run a command under a timeout; `rc` is `127` when it cannot be spawned and `124` on timeout), `run_utf16le`/`decode_utf16le` (for `wsl.exe`'s UTF-16LE output), `read_text`/`read_host_text`, `which`, the `SHORT`/`MEDIUM` timeouts and `truncate_to_chars`. All are `pub(crate)` except `run_raw`, which stays private to the module. The module itself is private to the crate and is not re-exported. +- [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs) — the host probes' subprocess and file-read helpers, split out of [`examine.rs`](../crates/rocm-core/src/examine.rs) so `fix.rs`, `process.rs` and the child modules of [`host_gpu.rs`](../crates/rocm-core/src/host_gpu.rs) reach them without importing the module that owns the `Examination` document: `run`/`run_with_env`/`run_raw` (run a command under a timeout; `rc` is `127` when it cannot be spawned and `124` on timeout), `run_utf16le`/`decode_utf16le` (for `wsl.exe`'s UTF-16LE output), `read_text`/`read_host_text`, `which` (the one `PATH` lookup, used by both host-probing stacks: it skips an empty `PATH` entry, searches a `PATH` that is not valid Unicode and follows `PATHEXT` on Windows) with `tool_path_candidates`, the spellings it tries and the capture runner in [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs) starts in turn, the `SHORT`/`MEDIUM` timeouts and `truncate_to_chars`. All are `pub(crate)` except `run_raw`, which stays private to the module. The module itself is private to the crate and is not re-exported. - [`process.rs`](../crates/rocm-core/src/process.rs) — (ROCMAI-154, Phase 7b) process-spawn/terminate primitives, including `FileLock`, plus `run_with_timeout`: it drains both pipes on their own threads from the moment the child starts, so output size cannot stall a command into its own timeout, and it bounds how much of a timed-out child's output the error quotes, because that text reaches persisted automation logs. It is not yet the *only* such helper — [`therock/process.rs`](../apps/rocm/src/therock/process.rs)'s `wait_with_output_bounded`, [`probe_exec.rs`](../crates/rocm-core/src/probe_exec.rs)'s `run_raw`, and [`host_gpu/capture.rs`](../crates/rocm-core/src/host_gpu/capture.rs)'s `capture_optional_command_candidate_with_timeout` (plus the Windows-only `capture_diagnostic_command` in [`host_gpu/diagnostics.rs`](../crates/rocm-core/src/host_gpu/diagnostics.rs)) still join their reader threads with no time limit, so a grandchild holding the pipe can outlast their timeout; converging them onto `run_with_timeout` is follow-up work to ROCMAI-448 tracked in [#623](https://github.com/ROCm/rocm-cli/issues/623). - [`quoting.rs`](../crates/rocm-core/src/quoting.rs) — (ROCMAI-727) argument-quoting helpers with real execution stakes (POSIX shell, PowerShell), consolidated out of `apps/rocm`-side near-duplicates — see the module's own doc comment for what it owns. `posix_shell_quote` also renders the command lines the CLI shows (through `apps/rocm`'s `shell_quote`); only `comfyui.rs`'s log-line quoter stays separate. - [`report_rollup.rs`](../crates/rocm-core/src/report_rollup.rs) — (ROCMAI-492) counts read Doctor reports at every level of `Report::group_key`, with refused and unread reports kept apart. Pure, with no transport: the mailbox adapter that feeds it is maintainer tooling in `xtask`, behind `cargo xtask report-rollup`. diff --git a/docs/host-probing.md b/docs/host-probing.md index bfed94a007..057f5517e0 100644 --- a/docs/host-probing.md +++ b/docs/host-probing.md @@ -6,7 +6,7 @@ SPDX-License-Identifier: MIT # Host probing: which stack owns each fact -Status: proposal. This note changes no code and no behaviour. It decides nothing by itself: it lists the host facts that `rocm-core` reads twice (on the hosts each is read on, see "Which host reads which fact"), says how the two reads differ, and proposes which one should survive and in what order a later series of changes could remove the other. Each pair is meant to be a separate change with its own review. +Status: proposal, with the first pair delivered. This note changes no code and no behaviour itself, and what it proposes for a pair is decided by the change that converges that pair, which then records the decision here (the PATH lookup, pair 1, has: see "PATH lookup"). It lists the host facts that `rocm-core` reads twice (on the hosts each is read on, see "Which host reads which fact"), says how the two reads differ, and proposes which one should survive and in what order a later series of changes could remove the other. Each pair is meant to be a separate change with its own review. This note is a snapshot of `main` at the time of writing, not maintained documentation. It is to be retired (the file deleted, together with its entry in [architecture.md](architecture.md)) when the convergence tickets for these pairs close, so the inventory does not keep pointing at a stale design record. @@ -22,7 +22,7 @@ For each pair, the proposed survivor and the biggest difference a user can see t | [CPU model](#cpu-model) | one reader in `os_facts` returning model and vendor, called by `probe_cpu_linux` and `probe_cpu_windows` | on WSL the text shows the CPU while `cpu_model` is empty and `cpu_vendor` is `unknown`; the change leaves that as it is (option (a)) | | [Windows GPU query](#windows-gpu-query) | the summary stack's inventory, with `probe_gpus_windows` building `gpus[]` from it and NVIDIA kept in the JSON | an NVIDIA-only host reads "AMD GPU not detected yet" in the text beside `has_nvidia_gpu: true` in the JSON | | [Marketing name to gfx target](#marketing-name-to-gfx-target) | the `AMD_MARKETING_GFX_TARGETS` table, gaining the codenames `classify_amd_marketing_name` knows (finish [#521](https://github.com/ROCm/rocm-cli/pull/521)) | on Windows without a HIP SDK an RX 7900 XTX has an empty `gpus[].gfx_target` while `summary.detected_gfx_target` is `gfx1100` | -| [PATH lookup](#path-lookup) | the behaviour of `tool_on_path`, housed in `probe_exec.rs` under the name `which`; the empty-entry case is open | an empty `PATH` entry or a `PATH` that is not UTF-8 changes which tools read as present (for example `wsl.rocminfo`), so the change is not output-preserving | +| [PATH lookup](#path-lookup) | delivered: the behaviour of `tool_on_path`, housed in `probe_exec.rs` under the name `which`; an empty `PATH` entry is skipped | before the change, an empty `PATH` entry or a `PATH` that is not UTF-8 changed which tools read as present (for example `wsl.rocminfo`); now there is one answer, and the differences it moved are listed under "PATH lookup" | | [Subprocess runners](#subprocess-runners) | `run_with_timeout` as the one bounded executor, with `CommandCapture` extended by a typed outcome | a probe behind a hung grandchild returns at its deadline, and a successful capture can lose output a descendant writes more than 200 ms after the child exits | ## The two stacks @@ -50,7 +50,7 @@ Every pair below is read on a subset of the hosts, and the subset decides which | CPU model and vendor | both | summary only: the examination returns before `probe_cpu_linux`, so `cpu_model` is empty and `cpu_vendor` is `unknown` | both, plus the inventory row | neither: `cpu_model` empty | | Windows adapter list | not applicable | examination `gpus[]` stays empty (the WSL branch skips the GPU probes); the summary asks the Windows host for the display target only | both | not collected here; the host driver is read through the summary's inventory (`detect_local_windows_host_driver`) | | Marketing name to gfx target | examination only (the `lspci` scan); the summary reads sysfs and KFD, not names | summary only, through the Windows host's display name | both | not collected | -| PATH lookup | examination `which` only | both (`tool_on_path` and `which` for `rocminfo`) | examination `which` only | examination `which` for `wsl.exe` only | +| PATH lookup | `which` | `which`, asked by both stacks for `rocminfo` (before the change the summary asked `tool_on_path`, a second copy) | `which` | `which` for `wsl.exe` only | | Subprocess runners (which helpers exist on the host) | three: `capture_optional_command*`, `run`, `run_with_timeout` (`capture_diagnostic_command` is Windows only) | the same three | all four | `run` and `run_utf16le` (both over `run_raw`), plus the summary's capture helper through the inventory behind `detect_local_windows_host_driver` | A pair that one host reads with only one stack cannot disagree on that host, but it can still change when a shared helper is changed, so the characterisation tests below name the hosts they cover and say so where a row is empty. @@ -141,7 +141,7 @@ Proposal: the table survives. It is pure, data-driven and already the superset f ## PATH lookup -Verdict: confirmed duplicate. +Verdict: confirmed duplicate, now converged (see "Decided and delivered" below). The comparison that follows is how the two copies differed before that change, kept as the record of what it moved. | | Summary | Examination | |---|---|---| @@ -155,6 +155,26 @@ What a user can see: only on WSL, where both run on Linux: the summary's `wsl_gl Proposal: the behaviour of `tool_on_path` survives (it is the one that follows `PATHEXT`), housed where both stacks already import from, in `probe_exec.rs`, under the existing name `which` so the call sites do not change. `tool_path_candidates` moves with it, because the runner uses it to try each spelling. Keeping the call sites unchanged does not keep their answers unchanged: the differences listed above become the intended observable differences of this change (see the first item of the order below). The empty-entry case is a real choice, because either answer changes one side. Following `PATH` semantics matches what a shell or `execvp` does with an empty entry, and makes `which` read a file in the current directory as found, which widens what the examination calls installed (fifteen or so capability checks, including `sudo` and `usermod`). Skipping empty entries keeps the examination's answer and changes only the summary's on WSL, at the cost of disagreeing with `execvp` for a program the CLI later starts by bare name. The note does not pick one; the change has to, and its PR text states which. +### Decided and delivered + +The change took the survivor proposed above: `which` in [probe_exec.rs](../crates/rocm-core/src/probe_exec.rs) has the behaviour `tool_on_path` had, `tool_path_candidates` moved there with it (the capture runner in [capture.rs](../crates/rocm-core/src/host_gpu/capture.rs) and the Windows diagnostics capture import it from there), `detect_wsl_summary` asks `which` for `rocminfo` and `cargo`, and `tool_on_path` is gone. The Windows spellings are computed by `path_candidates`, which takes the platform, `PATHEXT` and the system root as arguments, and the search by `found_in`, which takes the directories and an existence test, so both are unit-tested on every host. + +The empty-entry question is decided as skip. An empty `PATH` entry is not read as the current directory. That keeps the examination's answer, which is what fifteen or so capability checks (including `sudo` and `usermod`) already relied on, so the only answer the empty-entry rule moves is the summary's on WSL, where a `rocminfo` or `cargo` file in the current directory no longer reads as installed. It also settles the Windows question the note could not answer: how `std::env::split_paths` treats an empty entry there no longer matters, because the entry is dropped either way. The cost is the one named above: a program the CLI later starts by bare name can still resolve from the current directory through the operating system when `PATH` has an empty entry, and the lookup, which does not start anything, no longer agrees with that. Guarding the runners against that (`capture_optional_command*` and `run` start a bare name through `Command`, so the operating system resolves an empty entry for them) is a property of how they spawn, not of the lookup, so it belongs to the subprocess-runners pair (item 6 below) and is not changed here. + +The differences that moved, each with the tests that pin it (the unit tests are in `probe_exec.rs`; the scenarios are in `examine.feature`): + +| Difference | Before | Now | Pinned by | +|---|---|---|---| +| Empty `PATH` entry, with a file of the program's name in the current directory | summary: found; examination: not found | not found | `which_does_not_read_an_empty_path_entry_as_the_current_directory`, `path_dirs_drop_every_empty_entry`, scenario `examine-36` (control `examine-35`) | +| `PATH` that is not valid Unicode | summary: searched; examination: not found for every program | searched | `which_searches_a_path_that_is_not_unicode`, `path_dirs_keep_an_entry_that_is_not_unicode`, scenario `examine-37` | +| Windows `PATHEXT` entries outside `.exe`, `.bat`, `.cmd`, in both cases | summary: tried; examination: not tried | tried | `which_tries_a_pathext_extension_outside_exe_bat_and_cmd` (Windows job), `candidates_on_windows_try_every_pathext_entry_in_both_cases`, `candidates_on_windows_fall_back_to_the_default_pathext_when_it_is_unset` | +| Windows `PATH` entry in quotes holding a `;` | summary: kept whole; examination: split | kept whole | `which_searches_a_quoted_path_entry_that_holds_a_semicolon` (Windows job) | +| A Windows name that already has an extension (`python3.11`, `tool.py`, `wsl.exe`) | examination: also tried `.exe`, `.bat` and `.cmd` after it; summary: as given only | as given only | `candidates_on_windows_for_a_name_with_an_extension_are_the_name_alone` | +| System32 locations of `cmd`, `pnputil` and `powershell` (`pwsh` has none; its only extra candidate is the bare `pwsh.exe`) | summary: found; examination: not found | found | `which_finds_cmd_at_its_system32_location_without_it_being_on_path` (Windows job), `candidates_on_windows_add_the_fixed_system32_locations`, `found_in_asks_about_an_absolute_candidate_once_as_it_is_whatever_the_directories` | +| A file in the current directory, with no empty entry | not found by either | not found | the control in `which_does_not_read_an_empty_path_entry_as_the_current_directory` | + +No `which` call site passes a name with an extension other than `wsl.exe` (found as given), so the dotted-name row moves no answer today: the call sites ask for python, python3, mokutil, lspci, rocminfo, dpkg, rpm, usermod, sudo, cargo and the llama.cpp names, all bare. The System32 candidates stay in the shared candidate list. The capture runner needs them to start `cmd`, `pnputil` and `powershell` at all on a host where they are not on `PATH`, and one list that both the runner and the lookup read cannot drift. No `which` call site asks for those four today, so the change is invisible there; a future caller of `which("powershell")` gets "would the runner find it", not "is it on `PATH`". An absolute candidate is tested once as it is and not joined onto each `PATH` directory, so it is found even when `PATH` is unset or all empty, which is what the runner can start. The near copy of `tool_path_candidates` in `apps/rocm` (`program_path_candidates`) did not join this change and stays open at the end of this note. The scenarios `examine-35`, `examine-36`, `examine-37` and `examine-38` in [examine.feature](../tests/e2e-cucumber/features/examine.feature) drive the first two rows on the Linux lane from a simulated WSL host, holding `summary.wsl.rocminfo` and `wsl.rocminfo` of one `rocm examine --json` run level: a tool in a `PATH` directory is found (the control), a tool only in the working directory behind an empty entry is not (with `.` as the entry instead it is, which `examine-38` holds as the control), and a tool in a directory whose name is not valid Unicode is found. The harness sets a `PATH` that is not Unicode without trouble, which settles the question the note left about it. The Windows rows cannot run on the Linux lane and are covered by the unit tests named above, which the Windows job runs. + ## Subprocess runners Verdict: confirmed duplicate, and a family rather than a pair. @@ -184,7 +204,7 @@ Proposal: `run_with_timeout` survives as the one bounded executor, with `Command One pair per change. Each begins with a commit that adds a characterisation test and is green against the code as it is: it pins what both copies return for the same input, and where they differ it pins each copy's answer, with a comment naming the pair. The convergence commit then flips the assertions that are meant to change and the PR text lists each one as a user-visible difference. Tests that need a program on `PATH` use the fake-executable helper in [fake_executable.rs](../crates/rocm-core/src/fake_executable.rs); Windows-only logic goes behind an injectable function so a unit test runs on the Windows job, as the inventory already does with `WindowsInventorySources`. -1. PATH lookup. Smallest, and it settles where `tool_path_candidates` lives before the runner work needs it. It is not output-preserving: the differences listed under "PATH lookup" change which tools are reported as present, and its PR text lists each one as intentional, with the characterisation test that pins it. Hosts covered: Linux, which is also WSL's code path, for the empty entry, the non-UTF-8 `PATH` (set through an `OsString` environment value) and the current-directory file; Windows through an injectable resolver for the `PATHEXT` spellings, the System32 candidates and the `;` splitting, since the Linux lane cannot run them. +1. PATH lookup (delivered: see "Decided and delivered" under "PATH lookup"). Smallest, and it settles where `tool_path_candidates` lives before the runner work needs it. It is not output-preserving: the differences listed under "PATH lookup" change which tools are reported as present, and its PR text lists each one as intentional, with the characterisation test that pins it. Hosts covered: Linux, which is also WSL's code path, for the empty entry, the non-UTF-8 `PATH` (set through an `OsString` environment value) and the current-directory file; Windows through an injectable resolver for the `PATHEXT` spellings, the System32 candidates and the `;` splitting, since the Linux lane cannot run them. 2. Kernel version. A single command; settles the timeout and the empty-versus-`None` question. Hosts covered as set out under "Kernel version". 3. CPU model. Adds the model-and-vendor reader; needs the Windows inventory row, which already exists. Its PR says which WSL option under "CPU model" it takes, (a) or (b); a PR that does not is not ready. 4. Marketing name to gfx target, by finishing [#521](https://github.com/ROCm/rocm-cli/pull/521). It must land before the next item, so that `gpus[]` is not rebuilt on top of two name tables. @@ -200,10 +220,10 @@ No item is output-preserving without qualification, and the PR for each says whi - How NVIDIA adapters are represented once the examination reads the inventory (a vendor on every row, or a separate check). - Whether one `rocm examine --json` run shares answers between the stacks (a single WSL summary and a single `ldconfig -p`, one inventory including its failure) or keeps calling shared code that asks again. - What an absent Windows inventory does once there is one inventory: remember the absence for the run, or drop the per-fact fallbacks. -- Whether an empty `PATH` entry counts as the current directory in the surviving lookup. - Whether `gpus[].name` should come from `pnputil` or from WMI. - Which timeout wins for the kernel and CPU reads, and whether `kernel_release` should be filled on Windows. - Whether the typed outcome belongs on `CommandCapture` or beside it. - Whether CPU facts should be collected on WSL at all (option (b) under "CPU model"), and if so how the Windows-hosted distro probe obtains them. - Whether the adapters over `run_with_timeout` take a per-call drain grace, so that a probe whose tool is known to leave a late-writing descendant keeps its output, or whether the 200 ms grace is accepted for every probe. - Whether the near copy of `tool_path_candidates` in `apps/rocm` joins the PATH lookup change. +- Whether the runners that replace the subprocess helpers should refuse to resolve a bare program name through an empty `PATH` entry, so that what the lookup calls absent is also what they do not start. diff --git a/docs/testing.md b/docs/testing.md index b3369520b6..8ce25506aa 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -3097,6 +3097,12 @@ cache nor the variable involved, which is the layout of a TheRock tarball stays `wsl_rocdxg_missing`, so the sibling runtime, and not the planted library, is what the verdict turns on. +`examine-35`, `examine-36`, `examine-37` and `examine-38` hold the two answers `rocm examine --json` gives to "is `rocminfo` installed" level on that same planted WSL machine: `summary.wsl.rocminfo` from the host summary and `wsl.rocminfo` from the examination, which share one `PATH` lookup. They plant a stand-in `rocminfo` that prints nothing, and build the `PATH` from the machine's stand-in directory followed by the runner's own entries that hold no `rocminfo`, so a runner with ROCm installed cannot be why the tool reads as found. `examine-35` is the control: the tool in a `PATH` directory is found by both. `examine-36` puts it only in the directory the command runs from, with an empty entry first on `PATH`: neither report finds it, because an empty entry is skipped and not read as the current directory (the harness's `command_dir` sets that directory). `examine-38` is its control: the same machine with `.` as the first entry instead, which both reports find, so it fails if `rocm` does not really run from that directory and `examine-36`'s answer cannot come from a harness that ignored `command_dir`. `examine-37` puts it in a `PATH` directory whose name is not valid Unicode: both find it, because a `PATH` that is not Unicode is still searched. The Windows spellings of the lookup (`PATHEXT`, a quoted entry holding a `;`, the System32 locations) cannot run on the Linux lane and are covered by the unit tests in `probe_exec.rs`, which the Windows job runs. + +```bash +RUSTC_WRAPPER= cargo xtask e2e -- -n 'examine-3[5-8] ' +``` + `serve-42` plants the same WSL machine with `LD_LIBRARY_PATH` empty and runs `rocm serve`: it is refused, its advice names the WSL `driver_status` and not `/dev/kfd`, and `rocm examine` on that machine reports `wsl_rocdxg_missing`, so the command the refusal names exists and shows the condition. The launch that follows when `LD_LIBRARY_PATH` does reach the library has no scenario, because it would start preparing a real engine; the serve gate's decision there is covered by unit tests in `gpu_visibility.rs`. ```bash diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 70b6de0eb4..7620e2d04a 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -548,3 +548,53 @@ Feature: GPU detection and system inspection Then the inspection reports the ROCDXG driver status "wsl_rocdxg_ready" And the inspection reports the ROCDXG library as beside the runtime and in neither the linker cache nor LD_LIBRARY_PATH And the inspection's driver detail does not send the user to register the library with ldconfig + + # `rocm examine --json` asks twice whether `rocminfo` is installed on WSL: the + # host summary (`summary.wsl.rocminfo`) and the examination (`wsl.rocminfo`). + # They used to use two different PATH lookups and could disagree; they now use + # one, and these scenarios hold the two answers level on the cases where + # the old lookups differed. The planted WSL machine is the one `examine-32` uses + # (a simulated host root with `/dev/dxg`); the runner's own PATH entries that + # hold a `rocminfo` are left out, so a runner with ROCm installed cannot be the + # reason a tool reads as found. The stand-in `rocminfo` prints nothing, so the + # scenarios are about whether the tool is found, not whether it sees a GPU. + # + # The control: a `rocminfo` in a PATH directory is found by both. + @id:examine-rocminfo-on-path-is-found-by-both-reports @requires-os:linux + Scenario: examine-35 - Both reports find a rocminfo that sits in a PATH directory + Given a WSL machine whose rocminfo is in a PATH directory + When the user inspects that machine in machine-readable form + Then both reports say rocminfo is installed + + # An empty PATH entry is not the current directory for this lookup: a file named + # `rocminfo` in the directory the command runs from is not "installed". The + # summary's old lookup read the entry as the current directory and said it was, + # while the examination's said it was not. The cost is that a program the CLI + # starts by bare name can still resolve from the current directory through the + # operating system, which the lookup does not follow. + @id:examine-rocminfo-in-working-directory-is-not-installed @requires-os:linux + Scenario: examine-36 - Neither report reads an empty PATH entry as the working directory + Given a WSL machine whose only rocminfo is in the directory the command runs from, with an empty entry on PATH + When the user inspects that machine in machine-readable form + Then both reports say rocminfo is not installed + + # A PATH that is not valid Unicode is searched. The examination's old lookup read + # PATH as a `String`, which fails on it, and so found no tool at all while the + # summary's old lookup still searched it. + @id:examine-rocminfo-on-a-path-that-is-not-unicode-is-found @requires-os:linux + Scenario: examine-37 - Both reports search a PATH that is not valid Unicode + Given a WSL machine whose rocminfo sits in a PATH directory with a name that is not valid Unicode + When the user inspects that machine in machine-readable form + Then both reports say rocminfo is installed + + # The control for `examine-36`: the same machine, with `.` as the first PATH + # entry instead of an empty one. A `.` entry is an ordinary directory, so the + # lookup finds the stand-in in the working directory. That only happens if the + # `rocm` child really runs from it, so this scenario fails when the harness does + # not apply the working directory, and `examine-36`'s "not installed" is then + # meaningful: the two differ in nothing but the entry. + @id:examine-rocminfo-in-working-directory-named-on-path-is-found @requires-os:linux + Scenario: examine-38 - Both reports find a rocminfo in the working directory when PATH names it + Given a WSL machine whose only rocminfo is in the directory the command runs from, with that directory named on PATH + When the user inspects that machine in machine-readable form + Then both reports say rocminfo is installed diff --git a/tests/e2e-cucumber/src/binary_path.rs b/tests/e2e-cucumber/src/binary_path.rs new file mode 100644 index 0000000000..93c959f428 --- /dev/null +++ b/tests/e2e-cucumber/src/binary_path.rs @@ -0,0 +1,100 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! How the harness names the `rocm` binary when it starts the child somewhere +//! else. +//! +//! `ROCM_CLI_BINARY` is either a path (`target/debug/rocm`, `./rocm`, an +//! absolute one) or a bare name (`rocm`) the operating system finds on `PATH`. +//! A scenario that moves the child to another working directory must pin a +//! relative path first, because it was written relative to the harness's own +//! directory. A bare name must be left alone: canonicalising it would find a +//! file called `rocm` in the harness's directory, if there is one, and run that +//! instead of the program `PATH` resolves. + +use std::io; +use std::path::PathBuf; + +/// Whether `binary` names a path rather than a bare program name: it is +/// absolute, or contains a separator (so `./rocm`, `bin/rocm` and `../x/rocm` +/// are paths, and `rocm` is not). +#[must_use] +pub fn names_a_path(binary: &str) -> bool { + std::path::Path::new(binary).is_absolute() || binary.contains(['/', std::path::MAIN_SEPARATOR]) +} + +/// The program to start for `binary` when the child runs from another directory. +/// +/// A path is made absolute with `canonicalize` (and kept as written when that +/// fails); a bare name is returned unchanged without asking. +pub fn program_for_moved_child( + binary: &str, + canonicalize: impl Fn(&str) -> io::Result, +) -> PathBuf { + if names_a_path(binary) { + canonicalize(binary).unwrap_or_else(|_| PathBuf::from(binary)) + } else { + PathBuf::from(binary) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::cell::RefCell; + + #[test] + fn paths_are_told_from_bare_names() { + let abs = std::env::temp_dir().join("rocm"); + for (binary, is_path) in [ + ("rocm", false), + ("rocm.exe", false), + ("./rocm", true), + ("bin/rocm", true), + ("../x/rocm", true), + (abs.to_str().expect("UTF-8 temp dir"), true), + ] { + assert_eq!(names_a_path(binary), is_path, "{binary}"); + } + } + + #[test] + fn a_path_is_canonicalised_and_a_bare_name_is_not_even_when_a_local_file_would_match() { + // A canonicalise that succeeds for everything stands for a `rocm` file + // existing in the harness's directory. + let asked = RefCell::new(Vec::new()); + let pin = |binary: &str| { + asked.borrow_mut().push(binary.to_owned()); + Ok(PathBuf::from("/pinned").join(binary)) + }; + + assert_eq!( + program_for_moved_child("rocm", pin), + PathBuf::from("rocm"), + "a bare name stays for PATH to resolve" + ); + assert!( + asked.borrow().is_empty(), + "a bare name must not be looked up on disk" + ); + for binary in ["./rocm", "bin/rocm", "../x/rocm"] { + assert_eq!( + program_for_moved_child(binary, pin), + PathBuf::from("/pinned").join(binary), + "{binary}" + ); + } + assert_eq!(asked.borrow().len(), 3); + } + + #[test] + fn a_path_that_cannot_be_canonicalised_is_kept_as_written() { + assert_eq!( + program_for_moved_child("./gone/rocm", |_| Err(io::Error::from( + io::ErrorKind::NotFound + ))), + PathBuf::from("./gone/rocm") + ); + } +} diff --git a/tests/e2e-cucumber/src/lib.rs b/tests/e2e-cucumber/src/lib.rs index acd458f969..0ea09d7e18 100644 --- a/tests/e2e-cucumber/src/lib.rs +++ b/tests/e2e-cucumber/src/lib.rs @@ -2,6 +2,7 @@ // // SPDX-License-Identifier: MIT +pub mod binary_path; pub mod capability; pub mod chat_request; pub mod expectation; @@ -16,6 +17,7 @@ pub mod monotonic_clock; pub mod paced_download; pub mod palette_rows; pub mod panic_capture; +pub mod planted_path; pub mod polled_deadline; pub mod powershell_text_rule; pub mod quit_and_wait; diff --git a/tests/e2e-cucumber/src/planted_path.rs b/tests/e2e-cucumber/src/planted_path.rs new file mode 100644 index 0000000000..e26c46d868 --- /dev/null +++ b/tests/e2e-cucumber/src/planted_path.rs @@ -0,0 +1,179 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! The `PATH` a scenario hands the `rocm` child when it plants a machine that +//! holds a `rocminfo` of its own. +//! +//! The scenarios about whether `rocminfo` is installed must not be decided by a +//! `rocminfo` the runner happens to have, so the runner's own `PATH` entries +//! that hold one are left out. The entries are written by the harness process +//! but read by the child, and the two can run from different directories (the +//! scenario's `command_dir`), so a relative entry such as `.` means two +//! different directories. [`planted_path_entries`] settles that before it +//! filters: each inherited relative entry is made absolute against the +//! harness's own working directory, and is kept or dropped by what that +//! directory holds. The fixture's own entries are never touched, because a +//! scenario writes them to be read from the child's directory (an empty entry +//! and `.` are the point of two of them). + +use std::ffi::OsStr; +use std::path::{Path, PathBuf}; + +/// The program the runner's entries are checked for. +pub const PLANTED_TOOL: &str = "rocminfo"; + +/// Whether `dir` would make [`PLANTED_TOOL`] resolve. +/// +/// It holds a regular file of that name, as the shared `which` lookup in +/// `rocm-core` requires. A directory called `rocminfo` does not, so it must not +/// get its `PATH` entry dropped. +#[must_use] +pub fn dir_holds_tool(dir: &Path) -> bool { + dir.join(PLANTED_TOOL).is_file() +} + +/// The entries of the planted `PATH`, in order: `fixture` exactly as written, +/// then `fake_bin`, then each non-empty entry of `inherited` that holds no +/// [`PLANTED_TOOL`]. +/// +/// An inherited relative entry is resolved against `harness_cwd` first, checked +/// there with `holds_tool`, and kept in its resolved (absolute) form, so it still +/// names the directory it named when the harness read it after the child has +/// moved. An inherited empty entry is dropped: it would be read as the child's +/// working directory, which the scenario decides and the runner must not. +pub fn planted_path_entries( + fixture: &[PathBuf], + fake_bin: &Path, + inherited: &OsStr, + harness_cwd: &Path, + holds_tool: impl Fn(&Path) -> bool, +) -> Vec { + let kept = std::env::split_paths(inherited) + .filter(|entry| !entry.as_os_str().is_empty()) + // `join` leaves an absolute entry as it is and roots a relative one. + .map(|entry| harness_cwd.join(entry)) + .filter(|resolved| !holds_tool(resolved)); + fixture + .iter() + .cloned() + .chain(std::iter::once(fake_bin.to_owned())) + .chain(kept) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + /// An absolute directory on any host, so the rows are about the resolution + /// rule and not about one platform's path syntax. + fn abs(name: &str) -> PathBuf { + std::env::temp_dir().join("planted-path-rows").join(name) + } + + fn joined(entries: &[PathBuf]) -> std::ffi::OsString { + std::env::join_paths(entries).expect("no entry holds a separator") + } + + /// The planted entries for a host whose `rocminfo` is in exactly `holding`, + /// with the harness running from `abs("harness")`. + fn planted(fixture: &[PathBuf], inherited: &[PathBuf], holding: &[PathBuf]) -> Vec { + planted_path_entries( + fixture, + &abs("fake-bin"), + &joined(inherited), + &abs("harness"), + |dir| holding.iter().any(|held| held == dir), + ) + } + + #[test] + fn an_inherited_dot_without_a_rocminfo_survives_as_the_harness_directory() { + // The child runs from elsewhere, where a bare `.` would name the planted + // directory and expose its stand-in, so it must not survive as `.`. + assert_eq!( + planted(&[], &[PathBuf::from(".")], &[]), + vec![abs("fake-bin"), abs("harness")] + ); + } + + #[test] + fn an_inherited_dot_with_a_rocminfo_in_the_harness_directory_is_dropped() { + assert_eq!( + planted(&[], &[PathBuf::from(".")], &[abs("harness")]), + vec![abs("fake-bin")] + ); + } + + #[test] + fn an_inherited_absolute_entry_is_checked_and_kept_as_it_is() { + assert_eq!( + planted(&[], &[abs("usr-bin"), abs("rocm-bin")], &[abs("rocm-bin")]), + vec![abs("fake-bin"), abs("usr-bin")] + ); + } + + #[test] + fn an_inherited_relative_name_is_resolved_against_the_harness_directory() { + assert_eq!( + planted( + &[], + &[PathBuf::from("bin"), PathBuf::from("tools")], + &[abs("harness").join("tools")] + ), + vec![abs("fake-bin"), abs("harness").join("bin")] + ); + } + + #[test] + fn inherited_empty_entries_are_dropped_wherever_they_stand() { + assert_eq!( + planted(&[], &[PathBuf::new(), abs("usr-bin"), PathBuf::new()], &[]), + vec![abs("fake-bin"), abs("usr-bin")] + ); + } + + #[test] + fn fixture_entries_come_first_and_are_left_exactly_as_written() { + // The empty entry, `.` and a name are what the scenarios are about; the + // harness directory holding a `rocminfo` makes no difference to them. + let fixture = [PathBuf::new(), PathBuf::from("."), PathBuf::from("odd")]; + assert_eq!( + planted( + &fixture, + &[PathBuf::from(".")], + &[abs("harness"), PathBuf::from("."), PathBuf::from("odd")] + ), + vec![ + PathBuf::new(), + PathBuf::from("."), + PathBuf::from("odd"), + abs("fake-bin") + ] + ); + } + + #[test] + fn a_directory_named_like_the_tool_does_not_hold_it_and_a_file_does() { + let scratch = tempfile::tempdir().expect("scratch directory"); + let with_dir = scratch.path().join("with-dir"); + let with_file = scratch.path().join("with-file"); + std::fs::create_dir_all(with_dir.join(PLANTED_TOOL)).expect("plant a directory"); + std::fs::create_dir_all(&with_file).expect("create the directory"); + std::fs::write(with_file.join(PLANTED_TOOL), "").expect("plant a file"); + + assert!(!dir_holds_tool(&with_dir)); + assert!(dir_holds_tool(&with_file)); + // Through the planting itself: the entry with only a directory of that + // name is kept, the entry with a file is dropped. + let entries = planted_path_entries( + &[], + &abs("fake-bin"), + &joined(&[with_dir.clone(), with_file]), + &abs("harness"), + dir_holds_tool, + ); + assert_eq!(entries, vec![abs("fake-bin"), with_dir]); + } +} diff --git a/tests/e2e-cucumber/tests/e2e.rs b/tests/e2e-cucumber/tests/e2e.rs index dee0ee502f..082cceac49 100644 --- a/tests/e2e-cucumber/tests/e2e.rs +++ b/tests/e2e-cucumber/tests/e2e.rs @@ -147,6 +147,11 @@ pub struct E2eWorld { /// records a behavioral precondition here; the When step remains a plain user /// action and consumes the fixture without exposing its mechanism in Gherkin. pub command_env: Vec<(&'static str, std::ffi::OsString)>, + /// The working directory for this scenario's next `rocm` invocation, for a + /// scenario whose subject is what the CLI finds in the directory it is run + /// from. Consumed by [`run_rocm_with_scenario_env`] like `command_env`; `None` + /// leaves the harness's own working directory. + pub command_dir: Option, /// The interactive dash/chat TUI spawned under a pseudo-terminal for this /// scenario, if any (see `e2e::tui_driver`). Torn down in `Drop` before the /// mock server and isolated directory so the child process never outlives @@ -352,6 +357,7 @@ impl Default for E2eWorld { serve_timeout_override: None, expect_xfail: false, command_env: Vec::new(), + command_dir: None, tui: None, chat_use_mock: false, comfyui_baseline_torch_stack: None, @@ -1016,12 +1022,26 @@ pub fn run_rocm_with_env_and_unset( /// consume it so it cannot leak into a later action in the same scenario. pub fn run_rocm_with_scenario_env(world: &mut E2eWorld, args: &[&str]) -> (String, String, i32) { let binary = rocm_binary(); - let mut cmd = std::process::Command::new(&binary); + // A binary given as a relative path was meant relative to this process's + // directory, not to the scenario's, so it is made absolute before the child + // moves. A bare name (`rocm`, found on `PATH`) stays as it is, even if the + // harness's directory happens to hold a file of that name. + let program = if world.command_dir.is_some() { + e2e_cucumber::binary_path::program_for_moved_child(&binary, |path| { + std::fs::canonicalize(path) + }) + } else { + PathBuf::from(&binary) + }; + let mut cmd = std::process::Command::new(program); cmd.args(args); world.isolate_cmd(&mut cmd); for (key, value) in std::mem::take(&mut world.command_env) { cmd.env(key, value); } + if let Some(dir) = world.command_dir.take() { + cmd.current_dir(dir); + } let output = cmd .output() .unwrap_or_else(|e| panic!("failed to run {binary}: {e}")); diff --git a/tests/e2e-cucumber/tests/e2e/examine_steps.rs b/tests/e2e-cucumber/tests/e2e/examine_steps.rs index 93f0999f2f..8d8af1abea 100644 --- a/tests/e2e-cucumber/tests/e2e/examine_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/examine_steps.rs @@ -2369,6 +2369,181 @@ async fn assert_rocdxg_detail_names_the_cache(world: &mut E2eWorld) { ); } +// ── Both reports agree whether `rocminfo` is installed ───────────── + +/// Plant a stand-in `rocminfo` in `dir`. It prints nothing and succeeds, so the +/// probe finds the tool installed and, having seen no agent in its output, does +/// not claim the GPU works: the scenarios turn on whether it is found, not on +/// what it says. +fn plant_stand_in_rocminfo(dir: &std::path::Path) { + std::fs::create_dir_all(dir).expect("failed to create the stand-in rocminfo directory"); + rocm_core::fake_executable::write_fake_executable(&dir.join("rocminfo"), "#!/bin/sh\nexit 0\n") + .expect("failed to write the stand-in rocminfo"); +} + +/// Replace the `PATH` the planted WSL machine gives the next `rocm` run with +/// `entries`, then the machine's `fake-bin` (its stand-in `ldconfig`), then the +/// runner's own entries that hold no `rocminfo`, so a runner with ROCm installed +/// cannot be the reason the tool reads as found. How the runner's entries are +/// resolved and filtered is [`e2e_cucumber::planted_path::planted_path_entries`]. +/// +/// An entry that is an empty path is how a test writes the empty `PATH` entry +/// the shell reads as the current directory. +fn set_planted_wsl_path(world: &mut E2eWorld, entries: &[PathBuf]) { + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .to_owned(); + // The runner's relative entries are resolved from this process's directory + // before they are checked, because the child may run from another one. + let path = std::env::join_paths(e2e_cucumber::planted_path::planted_path_entries( + entries, + &root.join("fake-bin"), + &std::env::var_os("PATH").unwrap_or_default(), + &std::env::current_dir().expect("the harness has a working directory"), + e2e_cucumber::planted_path::dir_holds_tool, + )) + .expect("PATH entries cannot hold a separator"); + world.command_env.retain(|(key, _)| *key != "PATH"); + world.command_env.push(("PATH", path)); +} + +#[given("a WSL machine whose rocminfo is in a PATH directory")] +async fn wsl_machine_with_rocminfo_on_path(world: &mut E2eWorld) { + plant_wsl_machine_with_unregistered_rocdxg(world, ""); + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .to_owned(); + let tools = root.join("rocminfo-bin"); + plant_stand_in_rocminfo(&tools); + set_planted_wsl_path(world, &[tools]); +} + +/// The machine of `examine-36` and `examine-38`: the only `rocminfo` is in +/// `work`, the directory `rocm` is started from, and `path_entry` is the first +/// entry of its `PATH`. The two scenarios differ in nothing else, so the answer +/// can only turn on whether that entry names the working directory: `.` does, +/// and an empty entry does not (the lookup skips it). That is also what shows +/// `command_dir` reaches the `rocm` child: with `.` the stand-in is found only +/// if `rocm` really runs from `work`. +fn plant_wsl_machine_with_rocminfo_only_in_the_working_directory( + world: &mut E2eWorld, + path_entry: PathBuf, +) { + plant_wsl_machine_with_unregistered_rocdxg(world, ""); + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .to_owned(); + let work = root.join("work"); + plant_stand_in_rocminfo(&work); + set_planted_wsl_path(world, &[path_entry]); + // A "not installed" answer would also come out if the stand-in could not be + // reached at all, so show it can: started by bare name from `work` with this + // PATH, it must run, which only an entry that names `work` (or the empty + // entry, which `execvp` reads as `work`) makes possible. + let path = world + .command_env + .iter() + .rev() + .find_map(|(key, value)| (*key == "PATH").then(|| value.clone())) + .expect("the planted PATH was just set"); + let reached = std::process::Command::new("rocminfo") + .env("PATH", path) + .current_dir(&work) + .status() + .expect("the stand-in must resolve through the first PATH entry"); + assert!(reached.success(), "the stand-in rocminfo failed: {reached}"); + world.command_dir = Some(work); +} + +#[given( + "a WSL machine whose only rocminfo is in the directory the command runs from, with an empty entry on PATH" +)] +async fn wsl_machine_with_rocminfo_only_behind_an_empty_path_entry(world: &mut E2eWorld) { + plant_wsl_machine_with_rocminfo_only_in_the_working_directory(world, PathBuf::new()); +} + +#[given( + "a WSL machine whose only rocminfo is in the directory the command runs from, with that directory named on PATH" +)] +async fn wsl_machine_with_rocminfo_only_on_a_path_entry_naming_the_working_directory( + world: &mut E2eWorld, +) { + plant_wsl_machine_with_rocminfo_only_in_the_working_directory(world, PathBuf::from(".")); +} + +/// A directory name that is not valid Unicode: the byte 0xff is never UTF-8. +#[cfg(unix)] +fn directory_name_that_is_not_unicode() -> std::ffi::OsString { + use std::os::unix::ffi::OsStrExt as _; + + std::ffi::OsStr::from_bytes(b"rocminfo-bin-\xff").to_owned() +} + +/// Windows file names are UTF-16 and a lone surrogate would stand in for the +/// byte; the scenario that asks for this name is `@requires-os:linux`, so +/// reaching this is a harness mistake. +#[cfg(not(unix))] +fn directory_name_that_is_not_unicode() -> std::ffi::OsString { + panic!("a directory name that is not valid Unicode is planted on Linux only") +} + +#[given( + "a WSL machine whose rocminfo sits in a PATH directory with a name that is not valid Unicode" +)] +async fn wsl_machine_with_rocminfo_in_a_directory_that_is_not_unicode(world: &mut E2eWorld) { + plant_wsl_machine_with_unregistered_rocdxg(world, ""); + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .to_owned(); + let tools = root.join(directory_name_that_is_not_unicode()); + plant_stand_in_rocminfo(&tools); + set_planted_wsl_path(world, &[tools]); +} + +/// Both reports of one `rocm examine --json` run say whether `rocminfo` is +/// installed: `summary.wsl.rocminfo` from the host summary and `wsl.rocminfo` +/// from the examination. Asked together so the pair cannot disagree unseen. +fn rocminfo_answers(world: &E2eWorld) -> (bool, bool) { + assert_eq!(world.cli_rc, Some(0), "`rocm examine --json` failed"); + let json = parsed_json(world); + let answer = |pointer: &str| { + json.pointer(pointer) + .and_then(serde_json::Value::as_bool) + .unwrap_or_else(|| panic!("`examine --json` has no boolean at {pointer}:\n{json:#}")) + }; + (answer("/summary/wsl/rocminfo"), answer("/wsl/rocminfo")) +} + +#[then("both reports say rocminfo is installed")] +async fn assert_rocminfo_installed_in_both_reports(world: &mut E2eWorld) { + assert_eq!( + rocminfo_answers(world), + (true, true), + "(host summary, examination)" + ); +} + +#[then("both reports say rocminfo is not installed")] +async fn assert_rocminfo_not_installed_in_either_report(world: &mut E2eWorld) { + assert_eq!( + rocminfo_answers(world), + (false, false), + "(host summary, examination)" + ); +} + // ── `rocm serve` on a WSL host whose ROCDXG library the loader cannot find ── #[when("the user serves a model under the GPU-required default on that machine")]