fix: cef engine: support multi-process and update guix instructions

Author: franzos

.gitignore

@@ -1,2 +1,3 @@
 target
+target-cef
 default

README.md

@@ -24,7 +24,17 @@ This library supports
 - litehtml requires `clang`/`libclang` for building `litehtml-sys`
 - Servo requires `fontconfig`, `make`, `cmake`, `clang` (recent version), and `nasm` at build time
 - CEF downloads the Chromium Embedded Framework binary (~200-300 MB) at build time; requires subprocess handling (see below)
-- CEF on Guix: use `manifest-cef.scm` — `guix shell -m manifest-cef.scm` then `eval "$(./cef-link-flags.sh)" && CC=gcc cargo run --example webview --no-default-features --features cef`
+- CEF on Guix: use `manifest-cef.scm` with FHS emulation:
+  ```sh
+  guix shell --container --emulate-fhs --network \
+    --share=$HOME/.cargo --share=$HOME/.cache \
+    --expose=$XDG_RUNTIME_DIR --expose=/var/run/dbus \
+    -m manifest-cef.scm -- sh -c \
+    "XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR WAYLAND_DISPLAY=$WAYLAND_DISPLAY \
+     DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS \
+     CARGO_TARGET_DIR=target-cef LD_LIBRARY_PATH=/lib:/lib/nss CC=gcc \
+     cargo run --example webview --no-default-features --features cef"
+  ```
 
 #### examples:
 
@@ -109,7 +119,7 @@ Blitz and litehtml are not full browsers — there's no JavaScript, and renderin
 
 ### CEF
 
-- **Single-process mode** — runs all Chromium threads in one process (`--single-process`). CEF's multi-process model requires resources (`.pak`, `icudtl.dat`, GL libs) to be discoverable by subprocesses, which is fragile on non-FHS systems (Guix, Nix). Single-process avoids this. `cef_subprocess_check()` is still available for multi-process setups.
+- **Multi-process mode** — CEF runs with standard multi-process architecture (renderer, GPU, utility subprocesses). On non-FHS systems (Guix, Nix), use an FHS-emulated container (`guix shell --container --emulate-fhs`) so subprocesses can find `.pak` resources, `icudtl.dat`, and shared libraries at standard paths. Call `cef_subprocess_check()` at the top of `main()`.
 - **Large runtime** — ships ~200-300 MB of Chromium binaries alongside your application.
 - **Not Rust-native** — C++ under the hood, Rust bindings via [cef-rs](https://github.com/tauri-apps/cef-rs).
 - **CEF binary download** — the `cef-dll-sys` build script downloads the CEF binary distribution at build time.

build.rs

@@ -1,4 +1,37 @@
 fn main() {
     println!("cargo:rerun-if-changed=build.rs");
     println!("cargo:rerun-if-changed=Cargo.lock");
+
+    // When the cef feature is enabled, add the CEF distribution directory
+    // to the binary's RPATH so libcef.so can be found at runtime without
+    // requiring LD_LIBRARY_PATH.
+    if std::env::var("CARGO_FEATURE_CEF").is_ok() {
+        if let Ok(out_dir) = std::env::var("OUT_DIR") {
+            let build_dir = std::path::Path::new(&out_dir)
+                .ancestors()
+                .find(|p| p.file_name().map_or(false, |n| n == "build"));
+
+            if let Some(build_dir) = build_dir {
+                if let Ok(entries) = std::fs::read_dir(build_dir) {
+                    for entry in entries.flatten() {
+                        let name = entry.file_name();
+                        if name.to_string_lossy().starts_with("cef-dll-sys-") {
+                            let cef_dir = entry.path().join("out").join(format!(
+                                "cef_{}_{}",
+                                std::env::consts::OS,
+                                std::env::consts::ARCH
+                            ));
+                            if cef_dir.exists() {
+                                println!(
+                                    "cargo:rustc-link-arg=-Wl,-rpath,{}",
+                                    cef_dir.display()
+                                );
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
 }

cef-link-flags.sh

@@ -23,6 +23,11 @@ type Engine = iced_webview::Litehtml;
 static URL: &str = "https://docs.rs/iced/latest/iced/index.html";
 
 fn main() -> iced::Result {
+    #[cfg(feature = "cef")]
+    if iced_webview::cef_subprocess_check() {
+        return Ok(());
+    }
+
     iced::application(App::new, App::update, App::view)
         .title("An embedded web view")
         .subscription(App::subscription)

examples/embedded_webview.rs

@@ -27,6 +27,11 @@ static URL1: &str = "https://docs.rs/iced/latest/iced/index.html";
 static URL2: &str = "https://github.com/franzos/iced_webview_v2";
 
 fn main() -> iced::Result {
+    #[cfg(feature = "cef")]
+    if iced_webview::cef_subprocess_check() {
+        return Ok(());
+    }
+
     iced::application(App::new, App::update, App::view)
         .title("An multi webview application")
         .subscription(App::subscription)

examples/multi_webview.rs

@@ -19,6 +19,11 @@ type Engine = iced_webview::Litehtml;
 static URL: &str = "https://docs.rs/iced/latest/iced/index.html";
 
 fn main() -> iced::Result {
+    #[cfg(feature = "cef")]
+    if iced_webview::cef_subprocess_check() {
+        return Ok(());
+    }
+
     iced::application(App::new, App::update, App::view)
         .title("Web view")
         .subscription(App::subscription)

examples/webview.rs

@@ -1,13 +1,24 @@
-;; Guix manifest for building with the CEF engine.
+;; Guix manifest for building and running with the CEF engine.
 ;;
-;; CEF's libcef.so links against many system libraries (GTK, NSS, ALSA, etc.)
-;; that live in package-specific store paths. This manifest collects them and
-;; exposes their lib dirs via LIBRARY_PATH so the linker can resolve them.
+;; Uses --container --emulate-fhs to create an FHS-compatible environment
+;; so CEF subprocesses can find .pak resources, icudtl.dat, and shared
+;; libraries at standard paths (/usr/lib, /usr/share, etc.).
 ;;
-;; Usage:
-;;   guix shell -m manifest-cef.scm
-;;   eval "$(./cef-link-flags.sh)"
-;;   CC=gcc cargo run --example webview --no-default-features --features cef
+;; Build and run:
+;;
+;;   guix shell --container --emulate-fhs --network \
+;;     --share=$HOME/.cargo --share=$HOME/.cache \
+;;     --expose=$XDG_RUNTIME_DIR --expose=/var/run/dbus \
+;;     -m manifest-cef.scm -- sh -c \
+;;     "XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR WAYLAND_DISPLAY=$WAYLAND_DISPLAY \
+;;      DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS \
+;;      CARGO_TARGET_DIR=target-cef LD_LIBRARY_PATH=/lib:/lib/nss CC=gcc \
+;;      cargo run --example webview --no-default-features --features cef"
+;;
+;; CARGO_TARGET_DIR  — separate target dir; host-built binaries won't run
+;;                     inside the FHS container (different dynamic linker).
+;; LD_LIBRARY_PATH   — gcc-toolchain's linker doesn't search /lib by default;
+;;                     NSS puts .so files in /lib/nss/.
 
 (use-modules (guix packages)
              (guix search-paths)
@@ -16,6 +27,7 @@
              (gnu packages commencement)
              (gnu packages tls)
              (gnu packages base)
+             (gnu packages bash)
              (gnu packages llvm)
              (gnu packages pkg-config)
              (gnu packages freedesktop)
@@ -55,6 +67,10 @@
        gdb
        openssl-with-dir
 
+       ;; container essentials
+       bash
+       coreutils
+
        ;; shared deps (also in manifest.scm)
        wayland
        wayland-protocols

manifest-cef.scm

@@ -27,7 +27,7 @@ struct SharedState {
     scale_factor: f32,
 }
 
-// -- CEF App handler (single-process + disable GPU for OSR) --
+// -- CEF App handler --
 
 wrap_app! {
     struct OsrApp;
@@ -39,14 +39,22 @@ wrap_app! {
             command_line: Option<&mut CommandLine>,
         ) {
             if let Some(cmd) = command_line {
-                // Run everything in a single process. CEF's multi-process
-                // model requires resources (.pak, icudtl.dat, GL libs) to
-                // be discoverable by subprocesses, which is fragile on
-                // non-FHS systems (Guix, Nix). Single-process avoids this.
-                cmd.append_switch(Some(&CefString::from("single-process")));
-                // Disable hardware GPU — OSR delivers pixels via on_paint.
+                // CEF defaults to X11. When WAYLAND_DISPLAY is set, tell
+                // Chromium's ozone layer to use the Wayland backend.
+                if std::env::var("WAYLAND_DISPLAY").is_ok() {
+                    cmd.append_switch_with_value(
+                        Some(&CefString::from("ozone-platform")),
+                        Some(&CefString::from("wayland")),
+                    );
+                }
+
+                // OSR delivers pixels via on_paint() — GPU compositing
+                // inside CEF isn't needed. Disable it and run any
+                // remaining GL calls in-process so the GPU subprocess
+                // doesn't need real driver access (containers, Flatpak).
                 cmd.append_switch(Some(&CefString::from("disable-gpu")));
                 cmd.append_switch(Some(&CefString::from("disable-gpu-compositing")));
+                cmd.append_switch(Some(&CefString::from("in-process-gpu")));
             }
         }
     }
@@ -195,9 +203,14 @@ struct CefView {
 ///
 /// ## Subprocess requirement
 ///
-/// CEF launches helper sub-processes using the same binary. Call
-/// [`cef_subprocess_check`] at the very top of `main()` — if it returns
-/// `true`, the process is a CEF subprocess and should exit immediately.
+/// CEF uses multi-process mode — helper sub-processes (renderer, GPU,
+/// utility) are spawned from the same binary. Call [`cef_subprocess_check`]
+/// at the very top of `main()` — if it returns `true`, the process is a
+/// CEF subprocess and should exit immediately.
+///
+/// On non-FHS systems (Guix, Nix), run inside an FHS-emulated container
+/// so subprocesses can discover `.pak` resources, `icudtl.dat`, and shared
+/// libraries at standard paths.
 ///
 /// ```rust,ignore
 /// fn main() -> iced::Result {