Add Linux CEF 146 native-windowed embedding support

CEF 146 on Ubuntu 24 (GNOME/Wayland) requires several coordinated fixes
to embed the browser in a native X11 window without a separate GUI toolkit
in user code.  This commit implements all of them.

Embedding / window management
- WindowInfo.SetAsChild() on Linux now substitutes the X11 root window as
  CEF's parent to avoid the Xwayland cross-client MatchError, and stores
  the real parent XID in _linux_embed_info for deferred reparenting.
- _linux_schedule_xembed() polls until Chrome's window is IsViewable, then
  XUnmapWindow + 100 ms GLib timer + XReparentWindow into the real parent.
  Called from CreateBrowserSync() on both the direct and pending-browser
  paths so the reparent always fires regardless of when Initialize() returns.
- When CreateBrowserSync() is called with no parent on Linux, the library
  now auto-creates a GTK toplevel, embeds the browser, and registers
  configure-event (resize) and delete-event (close) handlers — making
  hello_world.py fully platform-agnostic.

Platform init helpers (window_utils_linux.pyx)
- _linux_gtk_init(): sets GDK_BACKEND=x11 before gtk_init() so GDK opens
  an X11/Xwayland display connection regardless of the desktop session.
- _linux_apply_initialize_defaults(): auto-applies CEF 146 switches
  (ozone-platform=x11, disable-zygote, disable-gpu, disable-features=…)
  so apps don't need to set them manually.
- _linux_setup_profile(): pre-seeds Chrome profile files to prevent the
  kProfileCreationFlow keepalive from blocking OnContextInitialized.
- _linux_message_loop(): runs gtk_main() with a 10 ms GLib timer driving
  CefDoMessageLoopWork(), satisfying CEF's Ozone X11 GLib-loop requirement.

Subprocess fixes
- Strip --pseudonymization-salt-handle from argv in subprocess/main.cpp
  (Chrome 130+ passes it to non-zygote subprocesses without pre-populating
  GlobalDescriptors[7], causing an immediate crash).
- Strip both --pseudonymization-salt-handle and --change-stack-guard-on-fork
  in OnBeforeChildProcessLaunch via _StripPseudonymizationSaltHandle().
- subprocess/CMakeLists.txt: add BROWSER_PROCESS define and set
  BUILD_RPATH/INSTALL_RPATH=$ORIGIN so the subprocess finds libcef.so
  from its installed directory on nosuid filesystems (VMware HGFS).

Other fixes
- cefpython3/__init__.py: set GDK_BACKEND=x11 at import time, before
  libcef.so is loaded, as the earliest safe point.
- x11.cpp: add null guards in SetX11WindowBounds/SetX11WindowTitle;
  document the XEMBED side-effect of CefBrowser_GetGtkWindow().
- cef_command_line.pxd: expose Reset, GetProgram/SetProgram, GetSwitches,
  GetArguments, AppendArgument needed by _StripPseudonymizationSaltHandle.
- linux.pxd: expose g_main_context_iteration for GLib pump in Initialize.
- tools/build.py: fix CEF glob for numbered dirs, write dev .pth file,
  pass PYTHONPATH when running unittests.
- examples/hello_world.py: remove all Linux-specific GTK/env boilerplate;
  now identical in structure to the Windows/Mac usage pattern.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: linesight

cefpython3/__init__.py

@@ -20,6 +20,10 @@
 os.environ["CEFPYTHON3_PATH"] = package_dir
 
 if platform.system() == "Linux":
+    # Force GDK to use X11/XWayland backend before libcef.so loads and
+    # initialises GDK.  Without this, GDK picks the Wayland backend on
+    # GNOME/Wayland sessions, making gdk_x11_window_get_xid() return 0.
+    os.environ.setdefault("GDK_BACKEND", "x11")
     _ld = os.environ.get("LD_LIBRARY_PATH", "")
     os.environ["LD_LIBRARY_PATH"] = (
         package_dir + os.pathsep + _ld if _ld else package_dir

examples/hello_world.py

@@ -8,38 +8,18 @@
 # Setting DPI awareness programmatically via a call to cef.DpiAware.EnableHighDpiSupport
 # is problematic in Python, may not work and can cause display glitches.
 
+import sys
+
 from cefpython3 import cefpython as cef
 import platform
-import sys
 from packaging.version import Version as parse_version
 
 
 def main():
     check_versions()
-    sys.excepthook = cef.ExceptHook  # To shutdown all CEF processes on error
-    switches = {}
-    if sys.platform.startswith("linux"):
-        # cefpython does not ship a chrome-sandbox (setuid) binary.
-        # Disable both the setuid and namespace sandboxes so Chrome runs
-        # subprocesses without sandboxing. Unlike --no-sandbox, these two
-        # flags do NOT suppress the Mojo IPC bootstrap fd registration
-        # (GlobalDescriptors key 7), so subprocesses can still communicate.
-        switches["disable-setuid-sandbox"] = ""
-        switches["disable-namespace-sandbox"] = ""
-        # /dev/shm may be too small in VMs and containers.
-        switches["disable-dev-shm-usage"] = ""
-        # Suppress the GNOME Keyring unlock prompt on desktop sessions.
-        switches["password-store"] = "basic"
-        # Virtual GPU hardware (e.g. VMware) may not expose the DMA-BUF / GBM
-        # interface required by Chrome's GPU process. Keep the GPU in-process.
-        switches["disable-gpu"] = ""
-        switches["disable-gpu-compositing"] = ""
-        switches["in-process-gpu"] = ""
-        # Keep storage and network services in-process to reduce subprocess
-        # spawning overhead.
-        switches["disable-features"] = "StorageServiceOutOfProcess"
-        switches["enable-features"] = "NetworkServiceInProcess"
-    cef.Initialize(switches=switches)
+    sys.excepthook = cef.ExceptHook  # shut down all CEF processes on error
+    settings = {}
+    cef.Initialize(settings=settings)
     cef.CreateBrowserSync(url="https://www.google.com/",
                           window_title="Hello World!")
     cef.MessageLoop()
@@ -54,7 +34,8 @@ def check_versions():
     print("[hello_world.py] Python {ver} {arch}".format(
            ver=platform.python_version(),
            arch=platform.architecture()[0]))
-    assert parse_version(cef.__version__) >= parse_version("57.0"), "CEF Python v57.0+ required to run this"
+    assert parse_version(cef.__version__) >= parse_version("57.0"), \
+        "CEF Python v57.0+ required to run this"
 
 
 if __name__ == '__main__':

src/cefpython.pyx

@@ -307,6 +307,11 @@ cdef py_bool g_cef_initialized = False
 cdef py_bool g_context_initialized = False
 cdef list g_pending_browsers = []
 
+IF UNAME_SYSNAME == "Linux":
+    # Keeps ctypes callback objects alive for the duration of gtk_main() and
+    # any pending one-shot GLib timers (Xwayland XReparentWindow scheduling).
+    g_linux_reparent_callbacks = []
+
 cdef dict g_globalClientCallbacks = {}
 
 # -----------------------------------------------------------------------------
@@ -571,6 +576,18 @@ def Initialize(applicationSettings=None, commandLineSwitches=None, **kwargs):
         if "use-angle" not in g_commandLineSwitches:
             g_commandLineSwitches["use-angle"] = "gl"
 
+    IF UNAME_SYSNAME == "Linux":
+        # Initialize GTK so GDK has a display connection before CefInitialize.
+        _linux_gtk_init()
+        # Auto-apply switches/settings required for CEF 146 on Linux/Xwayland.
+        # Uses setdefault so user-supplied values are never overwritten.
+        _linux_apply_initialize_defaults(application_settings,
+                                         g_commandLineSwitches)
+        # Pre-seed Chrome profile files to prevent the profile-picker keepalive
+        # from blocking OnContextInitialized (Chrome 146).
+        if application_settings.get("cache_path"):
+            _linux_setup_profile(application_settings["cache_path"])
+
     cdef CefRefPtr[CefApp] cefApp = <CefRefPtr[CefApp]?>new CefPythonApp()
 
     IF UNAME_SYSNAME == "Windows":
@@ -658,13 +675,23 @@ def Initialize(applicationSettings=None, commandLineSwitches=None, **kwargs):
     # a null browser from CefBrowserHost::CreateBrowserSync().
     # Use a generous ceiling (30s) for CI environments where utility
     # subprocesses (storage service) crash and delay context initialization.
+    # On Linux, also call g_main_context_iteration() explicitly so that GLib
+    # sources (X11 fd events, IPC pipes) are dispatched even if
+    # CefDoMessageLoopWork() uses only non-blocking GLib iteration internally.
     if ret:
-        for _ in range(3000):
-            with nogil:
-                CefDoMessageLoopWork()
-            if g_context_initialized:
-                break
-            time.sleep(0.01)
+        # On Linux, skip this pump entirely: the Ozone X11 backend needs
+        # gtk_main() (a blocking GLib main loop) running before
+        # OnContextInitialized can fire.  The external caller (hello_world.py,
+        # test harnesses) must enter gtk_main() immediately after Initialize()
+        # and drive the loop via the GLib timer callback.
+        # On Windows/macOS, pump up to 30 s as before.
+        IF UNAME_SYSNAME != "Linux":
+            for _ in range(3000):
+                with nogil:
+                    CefDoMessageLoopWork()
+                if g_context_initialized:
+                    break
+                time.sleep(0.01)
         if not g_context_initialized:
             Debug("CefInitialize() WARNING: OnContextInitialized not received"
                   " within 30 seconds")
@@ -710,12 +737,13 @@ def CreateBrowserSync(windowInfo=None,
     if not g_context_initialized:
         Debug("CreateBrowserSync(): OnContextInitialized not yet received,"
               " pumping message loop")
-        for _ in range(3000):
-            with nogil:
-                CefDoMessageLoopWork()
-            if g_context_initialized:
-                break
-            time.sleep(0.01)
+        IF UNAME_SYSNAME != "Linux":
+            for _ in range(3000):
+                with nogil:
+                    CefDoMessageLoopWork()
+                if g_context_initialized:
+                    break
+                time.sleep(0.01)
     if not g_context_initialized:
         Debug("CreateBrowserSync() deferred until OnContextInitialized")
         g_pending_browsers.append({
@@ -773,6 +801,18 @@ def CreateBrowserSync(windowInfo=None,
     elif not isinstance(windowInfo, WindowInfo):
         raise Exception("CreateBrowserSync() failed: windowInfo: invalid object")
 
+    # On Linux, when no parent window is given, auto-create a GTK toplevel
+    # so callers need no GTK-specific code (same API as Windows/Mac).
+    _linux_toplevel_state = None
+    IF UNAME_SYSNAME == "Linux":
+        if windowInfo.windowType == "child" and windowInfo.parentWindowHandle == 0:
+            _linux_toplevel_state = _linux_create_toplevel(
+                    window_title or "CEF Browser")
+            windowInfo.SetAsChild(
+                    _linux_toplevel_state['xid'],
+                    [0, 0, _linux_toplevel_state['width'],
+                           _linux_toplevel_state['height']])
+
     if window_title and windowInfo.parentWindowHandle == 0:
         windowInfo.windowName = window_title
 
@@ -871,6 +911,12 @@ def CreateBrowserSync(windowInfo=None,
             MacSetWindowTitle(cefBrowser,
                               PyStringToChar(windowInfo.windowName))
 
+    IF UNAME_SYSNAME == "Linux":
+        if windowInfo._linux_embed_info:
+            _linux_schedule_xembed(pyBrowser, windowInfo._linux_embed_info)
+        if _linux_toplevel_state is not None:
+            _linux_register_window_callbacks(pyBrowser, _linux_toplevel_state)
+
     return pyBrowser
 
 def MessageLoop():
@@ -880,8 +926,11 @@ def MessageLoop():
         global g_MessageLoop_called
         g_MessageLoop_called = True
 
-    with nogil:
-        CefRunMessageLoop()
+    IF UNAME_SYSNAME == "Linux":
+        _linux_message_loop()
+    ELSE:
+        with nogil:
+            CefRunMessageLoop()
 
 def MessageLoopWork():
     # Perform a single iteration of CEF message loop processing.
@@ -907,6 +956,9 @@ def SingleMessageLoop():
 
 def QuitMessageLoop():
     Debug("QuitMessageLoop()")
+    IF UNAME_SYSNAME == "Linux":
+        import ctypes as _ct
+        _ct.CDLL("libgtk-3.so.0").gtk_main_quit()
     with nogil:
         CefQuitMessageLoop()
 

src/client_handler/x11.cpp

@@ -36,6 +36,7 @@ void SetX11WindowBounds(CefRefPtr<CefBrowser> browser,
                         int x, int y, int width, int height) {
     ::Window xwindow = browser->GetHost()->GetWindowHandle();
     ::Display* xdisplay = cef_get_xdisplay();
+    if (!xdisplay || !xwindow) return;
     XWindowChanges changes = {0};
     changes.x = x;
     changes.y = y;
@@ -48,12 +49,21 @@ void SetX11WindowBounds(CefRefPtr<CefBrowser> browser,
 void SetX11WindowTitle(CefRefPtr<CefBrowser> browser, char* title) {
     ::Window xwindow = browser->GetHost()->GetWindowHandle();
     ::Display* xdisplay = cef_get_xdisplay();
+    if (!xdisplay || !xwindow) return;
     XStoreName(xdisplay, xwindow, title);
 }
 
 GtkWindow* CefBrowser_GetGtkWindow(CefRefPtr<CefBrowser> browser) {
   // TODO: Should return NULL when using the Views framework
   // -- REWRITTEN FOR CEF PYTHON USE CASE --
+  //
+  // WARNING (CEF 146 Ozone X11): gtk_plug_new_for_display() below sends an
+  // XEMBED_EMBEDDED_NOTIFY to the browser's X11 window, which causes GTK to
+  // call XReparentWindow and move the browser window into a new GtkSocket.
+  // This breaks embedded-window positioning.  Only call this function when
+  // showing a transient dialog (file chooser, print dialog) where the browser
+  // window displacement is acceptable or the dialog is temporary.
+  //
   // X11 window handle
   ::Window xwindow = browser->GetHost()->GetWindowHandle();
   // X11 display
@@ -99,7 +109,7 @@ GtkWindow* CefBrowser_GetGtkWindow(CefRefPtr<CefBrowser> browser) {
 XImage* CefBrowser_GetImage(CefRefPtr<CefBrowser> browser) {
     ::Display* display = cef_get_xdisplay();
     if (!display) {
-        LOG(ERROR) << "XOpenDisplay failed in CefBrowser_GetImage";
+        LOG(ERROR) << "cef_get_xdisplay() returned NULL in CefBrowser_GetImage";
         return NULL;
     }
     ::Window browser_window = browser->GetHost()->GetWindowHandle();

src/extern/cef/cef_command_line.pxd

@@ -9,6 +9,8 @@ include "compile_time_constants.pxi"
 
 from cef_string cimport CefString
 from libcpp cimport bool as cpp_bool
+from libcpp.vector cimport vector as cpp_vector
+from libcpp.map cimport map as cpp_map
 
 cdef extern from "include/cef_command_line.h":
     cdef cppclass CefCommandLine:
@@ -17,3 +19,9 @@ cdef extern from "include/cef_command_line.h":
         CefString GetCommandLineString()
         cpp_bool HasSwitch(const CefString& name)
         CefString GetSwitchValue(const CefString& name)
+        void Reset()
+        CefString GetProgram()
+        void SetProgram(const CefString& program)
+        void GetSwitches(cpp_map[CefString, CefString]& switches)
+        void GetArguments(cpp_vector[CefString]& arguments)
+        void AppendArgument(const CefString& argument)

src/extern/linux.pxd

@@ -6,6 +6,8 @@ cdef extern from "gtk/gtk.h" nogil:
     ctypedef void* GtkWidget
     cdef GtkWidget* gtk_plug_new(unsigned long socket_id)
     cdef void gtk_widget_show(GtkWidget* widget)
+    ctypedef void* GMainContext
+    int g_main_context_iteration(GMainContext* context, int may_block)
 
     ctypedef char* XPointer
     ctypedef struct XImage: