diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 913f2005b..3b7a7dfdd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,6 +98,7 @@ clang -v - **Web-only development** needs Node, pnpm, and the Rust toolchain present in the repo. You can usually ignore desktop-only system packages. - **Desktop development** needs the vendored Tauri/CEF setup. The preferred entrypoint is `pnpm --filter openhuman-app dev:app`, which ensures the vendored Tauri CLI is installed and configures `CEF_PATH`. - **Linux desktop builds** require extra system packages beyond Node/Rust. Follow the distro-specific Tauri dependency list before running desktop commands, then use the OpenHuman scripts below. For deeper platform troubleshooting, see [`gitbooks/developing/getting-set-up.md`](gitbooks/developing/getting-set-up.md). +- **Windows 10 WSL + classic X11 forwarding** is unsupported for the desktop app. The Tauri/CEF stack can hang, render blank windows, or crash before useful app logs are available. Use native Windows development, or Windows 11 WSLg if you need a Linux GUI workflow. OpenHuman logs a startup warning when it detects WSL with `DISPLAY` set but no `WAYLAND_DISPLAY`/WSLg markers. - **Windows desktop builds** additionally require Visual Studio C++ Build Tools (MSVC v143), LLVM/Clang, and CMake. See [Windows-specific setup](#windows-specific-setup) for the full list and install order. - **Skills development** happens in the separate [`tinyhumansai/openhuman-skills`](https://github.com/tinyhumansai/openhuman-skills) repository. This repo consumes built skill bundles from GitHub or a local override path; it does not vendor the skills source as a submodule. diff --git a/app/src-tauri/src/lib.rs b/app/src-tauri/src/lib.rs index 2e2ed5508..9aeae1cae 100644 --- a/app/src-tauri/src/lib.rs +++ b/app/src-tauri/src/lib.rs @@ -1214,6 +1214,64 @@ fn shutdown_app_sync(app_handle: &AppHandle, exit_code: i32) { app_handle.exit(exit_code); } +#[cfg(target_os = "linux")] +const WSL_X11_DESKTOP_WARNING: &str = "[startup] likely unsupported desktop environment: WSL with classic X11 forwarding detected (DISPLAY is set, but WAYLAND_DISPLAY/WSLg markers are absent). OpenHuman's Tauri/CEF desktop flow is fragile in this setup; use native Windows development or Windows 11 WSLg for desktop GUI work."; + +#[cfg(any(target_os = "linux", test))] +fn should_warn_for_wsl_x11_desktop( + is_wsl: bool, + display_set: bool, + wayland_display_set: bool, + wslg_marker_set: bool, +) -> bool { + is_wsl && display_set && !wayland_display_set && !wslg_marker_set +} + +#[cfg(target_os = "linux")] +fn is_wsl_environment() -> bool { + if std::env::var("WSL_DISTRO_NAME") + .ok() + .filter(|v| !v.trim().is_empty()) + .is_some() + { + return true; + } + + std::fs::read_to_string("/proc/sys/kernel/osrelease") + .ok() + .map(|release| release.to_ascii_lowercase().contains("microsoft")) + .unwrap_or(false) +} + +#[cfg(target_os = "linux")] +fn has_non_empty_env(key: &str) -> bool { + std::env::var(key) + .ok() + .filter(|v| !v.trim().is_empty()) + .is_some() +} + +#[cfg(target_os = "linux")] +fn has_wslg_marker() -> bool { + has_non_empty_env("WSLG_RUNTIME_DIR") || std::path::Path::new("/mnt/wslg").exists() +} + +#[cfg(target_os = "linux")] +fn warn_if_wsl_x11_desktop_launch() { + if should_warn_for_wsl_x11_desktop( + is_wsl_environment(), + has_non_empty_env("DISPLAY"), + has_non_empty_env("WAYLAND_DISPLAY"), + has_wslg_marker(), + ) { + log::warn!("{WSL_X11_DESKTOP_WARNING}"); + eprintln!("{WSL_X11_DESKTOP_WARNING}"); + } +} + +#[cfg(not(target_os = "linux"))] +fn warn_if_wsl_x11_desktop_launch() {} + pub fn run() { // Initialize Sentry for the Tauri shell (desktop host) process before any // other startup work. Reads `OPENHUMAN_TAURI_SENTRY_DSN` at runtime first, @@ -1323,6 +1381,8 @@ pub fn run() { log::info!("[startup] platform: arch={arch} os={os} os_version={os_ver}"); } + warn_if_wsl_x11_desktop_launch(); + // The vendored tauri-cef dev-server proxy builds a reqwest 0.13 client // (see vendor/tauri-cef/crates/tauri/src/protocol/tauri.rs) which calls // rustls 0.23's `CryptoProvider::get_default()`. rustls 0.23 no longer @@ -2599,6 +2659,27 @@ mod tests { ); } + // ------------------------------------------------------------------------- + // WSL + X11 desktop startup warning (issue #1653) + // ------------------------------------------------------------------------- + + #[test] + fn wsl_x11_warning_detects_classic_x11_forwarding() { + assert!(should_warn_for_wsl_x11_desktop(true, true, false, false)); + } + + #[test] + fn wsl_x11_warning_skips_non_wsl_or_headless_runs() { + assert!(!should_warn_for_wsl_x11_desktop(false, true, false, false)); + assert!(!should_warn_for_wsl_x11_desktop(true, false, false, false)); + } + + #[test] + fn wsl_x11_warning_skips_wslg_or_wayland_runs() { + assert!(!should_warn_for_wsl_x11_desktop(true, true, true, false)); + assert!(!should_warn_for_wsl_x11_desktop(true, true, false, true)); + } + // ------------------------------------------------------------------------- // Platform constants (issue #1012 Sentry tagging) // -------------------------------------------------------------------------