fix(linux): dlopen appindicator at runtime so release trays are never stubs (#73)

The Linux cef/webview release artifacts shipped the tray as a stub
(trayId always 0): CMake probed for appindicator3-0.1 / ayatana, but
tray_linux.cc unconditionally included the legacy
<libappindicator/app-indicator.h>, so installing the Ayatana dev
package broke the build and CI deliberately built without it.

Load the library at runtime instead: tray_linux.cc dlopen()s
libayatana-appindicator3.so.1, falling back to libappindicator3.so.1,
declaring the four ABI-stable symbols it uses locally. This removes
the appindicator build dependency everywhere (probes and
LAUFEY_HAVE_APPINDICATOR dropped from backend-common/webview/cef
CMakeLists, dead include dropped from cef runtime_loader_linux.cc),
keeps release binaries free of a hard DT_NEEDED on a library many
distros don't preinstall, works with whichever flavor the system has,
and degrades to trayId 0 — now with a one-time g_warning naming the
missing libraries instead of failing silently.

Gate the regression: native_e2e grows LAUFEY_E2E_REQUIRE_TRAY, which
turns a stub tray into a FAIL instead of N/A; the native-e2e cef/linux
leg sets it and installs the Ayatana runtime lib, so a backend whose
tray creation path regresses to trayId 0 can no longer pass CI.

Verified in an Ubuntu 24.04 container: compiles with no appindicator
dev headers; CreateTrayIconLinux returns a nonzero id with only
libayatana-appindicator3-1 installed (the dlopened app_indicator_new
executes) and 0 with no appindicator lib present; the webview backend
builds and links with no appindicator DT_NEEDED.

docs/tray.md now documents the runtime dependency for .deb/.rpm
packagers and the StatusNotifier-host requirement.

Fixes #63

Author: crowlKats

.github/workflows/ci.yml

@@ -169,10 +169,10 @@ jobs:
 
       # Per-backend deps mirror the proven build-{winit,webview,cef} jobs, plus
       # the runtime libs the *run* step needs (xvfb, dbus, libxkbcommon-x11 for
-      # winit). Note: the backend-common (cef/webview) tray needs no
-      # appindicator dev package — installing one makes cmake define
-      # LAUFEY_HAVE_APPINDICATOR while tray_linux.cc includes the non-ayatana
-      # header, breaking the build; without it the tray compiles as a stub (N/A).
+      # winit). The backend-common (cef/webview) tray dlopens the appindicator
+      # library at runtime — no dev package is needed to build; the cef leg
+      # installs the Ayatana *runtime* lib so the real (non-stub) tray path is
+      # exercised and gated via LAUFEY_E2E_REQUIRE_TRAY (issue #63).
       - name: Install dependencies (Linux, winit)
         if: runner.os == 'Linux' && matrix.backend == 'winit'
         run: |
@@ -197,7 +197,7 @@ jobs:
             libatk1.0-dev libatk-bridge2.0-dev libcups2-dev libdrm-dev libgtk-3-dev \
             libgbm-dev libasound2-dev libpango1.0-dev libcairo2-dev libxcomposite-dev \
             libxdamage-dev libxrandr-dev libxkbcommon-dev libdbus-1-dev libxext-dev \
-            libxfixes-dev
+            libxfixes-dev libayatana-appindicator3-1
 
       - name: Install dependencies (macOS)
         if: runner.os == 'macOS'
@@ -237,13 +237,17 @@ jobs:
 
       - name: Layer 0 — readback / events / clipboard / menu+tray clicks
         shell: bash
+        env:
+          # On the cef/linux leg the Ayatana runtime lib is installed above, so
+          # a tray id of 0 means the dlopen path regressed to a stub — fail
+          # instead of reporting N/A (issue #63).
+          LAUFEY_E2E_REQUIRE_TRAY: ${{ (runner.os == 'Linux' && matrix.backend == 'cef') && '1' || '' }}
         run: scripts/native-e2e-run.sh ${{ matrix.backend }}
 
       # Layer 1 (Linux D-Bus StatusNotifier/dbusmenu observer) is built above
-      # (compile-checked on real Linux) but not run here: the only tray impl
-      # that registers an SNI is the winit backend's tray-icon crate, and
-      # winit/linux is excluded above pending its GTK-menu fix. Re-enable the
-      # driver run once a tray-capable Linux leg is in the matrix.
+      # (compile-checked on real Linux) but not run here yet: the cef leg now
+      # creates a real appindicator tray (runtime lib installed above), so
+      # running the driver there is the next step once it's been proven green.
 
   build-webview:
     name: webview / ${{ matrix.target }}

backend-common/CMakeLists.txt

@@ -102,25 +102,19 @@ elseif(APPLE)
 elseif(UNIX)
   find_package(PkgConfig REQUIRED)
   pkg_check_modules(LAUFEY_COMMON_GTK REQUIRED gtk+-3.0)
-  pkg_check_modules(LAUFEY_COMMON_APPINDICATOR appindicator3-0.1)
-  if(NOT LAUFEY_COMMON_APPINDICATOR_FOUND)
-    pkg_check_modules(LAUFEY_COMMON_APPINDICATOR ayatana-appindicator3-0.1)
-  endif()
   target_include_directories(laufey_backend_common PUBLIC
     ${LAUFEY_COMMON_GTK_INCLUDE_DIRS}
-    ${LAUFEY_COMMON_APPINDICATOR_INCLUDE_DIRS}
   )
+  # No appindicator build dependency: tray_linux.cc dlopen()s the
+  # Ayatana or legacy appindicator library at runtime. CMAKE_DL_LIBS
+  # covers dlopen/dlsym on toolchains that still need -ldl.
   target_link_libraries(laufey_backend_common PUBLIC
     ${LAUFEY_COMMON_GTK_LIBRARIES}
-    ${LAUFEY_COMMON_APPINDICATOR_LIBRARIES}
+    ${CMAKE_DL_LIBS}
   )
   target_compile_options(laufey_backend_common PUBLIC
     ${LAUFEY_COMMON_GTK_CFLAGS_OTHER}
-    ${LAUFEY_COMMON_APPINDICATOR_CFLAGS_OTHER}
   )
-  if(LAUFEY_COMMON_APPINDICATOR_FOUND)
-    target_compile_definitions(laufey_backend_common PUBLIC LAUFEY_HAVE_APPINDICATOR=1)
-  endif()
 endif()
 
 set_target_properties(laufey_backend_common PROPERTIES

backend-common/include/laufey_backend_common.h

@@ -396,13 +396,14 @@ void* BuildGtkMenuFromValue(laufey_value_t* val,
 #endif
 
 // ---------------------------------------------------------------------------
-// Tray / status-bar icon (Linux, libappindicator)
+// Tray / status-bar icon (Linux, appindicator)
 // ---------------------------------------------------------------------------
 //
 // All functions must be called on the GTK main thread; backends with
 // off-main-thread callers should marshal first (CEF uses CefPostTask).
-// When libappindicator is not available (LAUFEY_HAVE_APPINDICATOR not
-// defined), CreateTrayIconLinux returns 0 and all other calls no-op.
+// The Ayatana or legacy appindicator library is dlopen()ed at runtime;
+// when neither is present on the system, CreateTrayIconLinux returns 0
+// and all other calls no-op.
 //
 // AppIndicator has no left-click event — a click anywhere pops the
 // indicator's menu — so SetTrayClickHandlerLinux and

backend-common/src/tray_linux.cc

@@ -5,9 +5,16 @@
 // these from any thread. tray_id is allocated synchronously so the
 // caller gets a useful return value immediately.
 //
-// When libappindicator is not available (no LAUFEY_HAVE_APPINDICATOR
-// define), CreateTrayIconLinux returns 0 and the other functions no-op.
-
+// The appindicator library is dlopen()ed at runtime — Ayatana first,
+// then the legacy libappindicator — instead of being linked at build
+// time. Release artifacts must work both on distros that ship only the
+// Ayatana fork and on ones with the legacy library, and must still
+// start on systems with neither; the two flavors are ABI-compatible for
+// the handful of symbols used here (the fork kept names and
+// signatures). When no library can be loaded, CreateTrayIconLinux
+// returns 0 and the other functions no-op.
+
+#include <dlfcn.h>
 #include <gtk/gtk.h>
 
 #include "laufey_backend_common.h"
@@ -20,18 +27,67 @@
 #include <string>
 #include <vector>
 
-#ifdef LAUFEY_HAVE_APPINDICATOR
-extern "C" {
-#include <libappindicator/app-indicator.h>
-}
-#endif
-
 namespace laufey_common {
 
-#ifdef LAUFEY_HAVE_APPINDICATOR
-
 namespace {
 
+// Minimal appindicator ABI. AppIndicator is opaque; the enum values are
+// stable across both flavors (APP_INDICATOR_CATEGORY_APPLICATION_STATUS,
+// APP_INDICATOR_STATUS_{PASSIVE,ACTIVE}).
+typedef struct _AppIndicator AppIndicator;
+
+constexpr int kAppIndicatorCategoryApplicationStatus = 0;
+constexpr int kAppIndicatorStatusPassive = 0;
+constexpr int kAppIndicatorStatusActive = 1;
+
+struct AppIndicatorApi {
+  AppIndicator* (*app_indicator_new)(const gchar* id, const gchar* icon_name,
+                                     int category);
+  void (*set_status)(AppIndicator* self, int status);
+  void (*set_menu)(AppIndicator* self, GtkMenu* menu);
+  void (*set_icon_full)(AppIndicator* self, const gchar* icon_name,
+                        const gchar* icon_desc);
+};
+
+// Loads the appindicator library once; nullptr if unavailable. Safe to
+// call from any thread (dlopen is thread-safe and the initializer is a
+// C++11 magic static).
+const AppIndicatorApi* GetAppIndicatorApi() {
+  static AppIndicatorApi api;
+  static const bool loaded = [] {
+    static const char* const kSonames[] = {
+        "libayatana-appindicator3.so.1",
+        "libappindicator3.so.1",
+    };
+    void* lib = nullptr;
+    for (const char* soname : kSonames) {
+      // RTLD_GLOBAL: the library registers GObject types whose symbols
+      // its dbusmenu helpers may resolve across module boundaries.
+      lib = dlopen(soname, RTLD_NOW | RTLD_GLOBAL);
+      if (lib) break;
+    }
+    if (!lib) {
+      // Say why the tray id will be 0 — a silent stub cost real debugging
+      // time downstream (issue #63).
+      g_warning(
+          "laufey: tray icons unavailable: could not load "
+          "libayatana-appindicator3.so.1 or libappindicator3.so.1");
+      return false;
+    }
+    api.app_indicator_new = reinterpret_cast<decltype(api.app_indicator_new)>(
+        dlsym(lib, "app_indicator_new"));
+    api.set_status = reinterpret_cast<decltype(api.set_status)>(
+        dlsym(lib, "app_indicator_set_status"));
+    api.set_menu = reinterpret_cast<decltype(api.set_menu)>(
+        dlsym(lib, "app_indicator_set_menu"));
+    api.set_icon_full = reinterpret_cast<decltype(api.set_icon_full)>(
+        dlsym(lib, "app_indicator_set_icon_full"));
+    return api.app_indicator_new && api.set_status && api.set_menu &&
+           api.set_icon_full;
+  }();
+  return loaded ? &api : nullptr;
+}
+
 struct LinuxTrayEntry {
   AppIndicator* indicator;
   GtkWidget* menu;
@@ -68,17 +124,19 @@ void OnGtkMain(Fn&& fn) {
 }  // namespace
 
 uint32_t CreateTrayIconLinux() {
+  const AppIndicatorApi* api = GetAppIndicatorApi();
+  if (!api) return 0;
   uint32_t tray_id =
       g_next_tray_id_linux.fetch_add(1, std::memory_order_relaxed);
-  OnGtkMain([tray_id] {
+  OnGtkMain([api, tray_id] {
     std::string idstr = "laufey-tray-" + std::to_string(tray_id);
-    AppIndicator* ind = app_indicator_new(
-        idstr.c_str(), "", APP_INDICATOR_CATEGORY_APPLICATION_STATUS);
+    AppIndicator* ind = api->app_indicator_new(
+        idstr.c_str(), "", kAppIndicatorCategoryApplicationStatus);
     if (!ind) return;
-    app_indicator_set_status(ind, APP_INDICATOR_STATUS_ACTIVE);
+    api->set_status(ind, kAppIndicatorStatusActive);
     GtkWidget* placeholder = gtk_menu_new();
     gtk_widget_show_all(placeholder);
-    app_indicator_set_menu(ind, GTK_MENU(placeholder));
+    api->set_menu(ind, GTK_MENU(placeholder));
 
     LinuxTrayEntry entry{};
     entry.indicator = ind;
@@ -90,27 +148,29 @@ uint32_t CreateTrayIconLinux() {
 }
 
 void DestroyTrayIconLinux(uint32_t tray_id) {
-  OnGtkMain([tray_id] {
+  const AppIndicatorApi* api = GetAppIndicatorApi();
+  if (!api) return;
+  OnGtkMain([api, tray_id] {
     std::lock_guard<std::mutex> lock(LinuxTrayMutex());
     auto it = LinuxTrayMap().find(tray_id);
     if (it == LinuxTrayMap().end()) return;
     if (it->second.indicator) {
-      app_indicator_set_status(it->second.indicator,
-                               APP_INDICATOR_STATUS_PASSIVE);
+      api->set_status(it->second.indicator, kAppIndicatorStatusPassive);
       g_object_unref(it->second.indicator);
     }
     LinuxTrayMap().erase(it);
   });
 }
 
 void SetTrayIconLinux(uint32_t tray_id, const void* png_bytes, size_t len) {
-  if (!png_bytes || len == 0) return;
+  const AppIndicatorApi* api = GetAppIndicatorApi();
+  if (!api || !png_bytes || len == 0) return;
   // AppIndicator on most DEs reads icons by name from the icon theme,
   // not from raw bytes. Write the bytes to a per-tray temp file and
   // point the indicator at its full path.
   std::vector<uint8_t> bytes(static_cast<const uint8_t*>(png_bytes),
                               static_cast<const uint8_t*>(png_bytes) + len);
-  OnGtkMain([tray_id, bytes = std::move(bytes)]() mutable {
+  OnGtkMain([api, tray_id, bytes = std::move(bytes)]() mutable {
     std::string path = "/tmp/laufey-tray-" + std::to_string(tray_id) + ".png";
     FILE* f = fopen(path.c_str(), "wb");
     if (!f) return;
@@ -119,7 +179,7 @@ void SetTrayIconLinux(uint32_t tray_id, const void* png_bytes, size_t len) {
     std::lock_guard<std::mutex> lock(LinuxTrayMutex());
     auto it = LinuxTrayMap().find(tray_id);
     if (it == LinuxTrayMap().end() || !it->second.indicator) return;
-    app_indicator_set_icon_full(it->second.indicator, path.c_str(), "");
+    api->set_icon_full(it->second.indicator, path.c_str(), "");
   });
 }
 
@@ -138,7 +198,12 @@ void SetTrayTooltipLinux(uint32_t /*tray_id*/,
 void SetTrayMenuLinux(uint32_t tray_id, laufey_value_t* menu_template,
                        const laufey_backend_api_t* api,
                        laufey_menu_click_fn on_click, void* on_click_data) {
-  OnGtkMain([tray_id, menu_template, api, on_click, on_click_data] {
+  const AppIndicatorApi* ind_api = GetAppIndicatorApi();
+  if (!ind_api) {
+    if (menu_template && api) api->value_free(menu_template);
+    return;
+  }
+  OnGtkMain([ind_api, tray_id, menu_template, api, on_click, on_click_data] {
     // tray_id passed as window_id so the shared click dispatcher routes
     // back through on_click with the right tray identifier.
     GtkWidget* new_menu = nullptr;
@@ -156,12 +221,12 @@ void SetTrayMenuLinux(uint32_t tray_id, laufey_value_t* menu_template,
       return;
     }
     if (new_menu) {
-      app_indicator_set_menu(it->second.indicator, GTK_MENU(new_menu));
+      ind_api->set_menu(it->second.indicator, GTK_MENU(new_menu));
       it->second.menu = new_menu;
     } else {
       GtkWidget* empty = gtk_menu_new();
       gtk_widget_show_all(empty);
-      app_indicator_set_menu(it->second.indicator, GTK_MENU(empty));
+      ind_api->set_menu(it->second.indicator, GTK_MENU(empty));
       it->second.menu = empty;
     }
     it->second.menu_click_fn = on_click;
@@ -181,20 +246,4 @@ void SetTrayDoubleClickHandlerLinux(uint32_t /*tray_id*/,
   // Same: no double-click event from AppIndicator.
 }
 
-#else  // !LAUFEY_HAVE_APPINDICATOR
-
-uint32_t CreateTrayIconLinux() { return 0; }
-void DestroyTrayIconLinux(uint32_t) {}
-void SetTrayIconLinux(uint32_t, const void*, size_t) {}
-void SetTrayIconDarkLinux(uint32_t, const void*, size_t) {}
-void SetTrayTooltipLinux(uint32_t, const char*) {}
-void SetTrayMenuLinux(uint32_t, laufey_value_t* tmpl, const laufey_backend_api_t* api,
-                       laufey_menu_click_fn, void*) {
-  if (tmpl && api) api->value_free(tmpl);
-}
-void SetTrayClickHandlerLinux(uint32_t, laufey_tray_click_fn, void*) {}
-void SetTrayDoubleClickHandlerLinux(uint32_t, laufey_tray_click_fn, void*) {}
-
-#endif  // LAUFEY_HAVE_APPINDICATOR
-
 }  // namespace laufey_common

cef/CMakeLists.txt

@@ -227,14 +227,12 @@ elseif(OS_LINUX)
     )
   endif()
 
-  # GTK3 (for GDK/X11 headers) and XI2 (for input event monitoring)
+  # GTK3 (for GDK/X11 headers) and XI2 (for input event monitoring).
+  # No appindicator build dependency: the tray in backend-common
+  # dlopen()s the Ayatana or legacy appindicator library at runtime.
   find_package(PkgConfig REQUIRED)
   pkg_check_modules(GTK3 REQUIRED gtk+-3.0)
   pkg_check_modules(XI2 REQUIRED xi)
-  pkg_check_modules(APPINDICATOR appindicator3-0.1)
-  if(NOT APPINDICATOR_FOUND)
-    pkg_check_modules(APPINDICATOR ayatana-appindicator3-0.1)
-  endif()
 
   set(LAUFEY_SRCS_COMMON
     src/app.cc
@@ -258,22 +256,15 @@ elseif(OS_LINUX)
   # not part of Chromium's runtime, so its entry-time canary no longer matches
   # at return, tripping __stack_chk_fail. Disable stack protection to bypass.
   target_compile_options(${CEF_TARGET} PRIVATE -fno-stack-protector)
-  target_link_libraries(${CEF_TARGET} libcef_dll_wrapper ${CEF_LIB_RELEASE} ${CEF_STANDARD_LIBS} ${GTK3_LIBRARIES} ${XI2_LIBRARIES} ${APPINDICATOR_LIBRARIES} laufey_backend_common)
-  target_link_directories(${CEF_TARGET} PRIVATE ${GTK3_LIBRARY_DIRS} ${XI2_LIBRARY_DIRS} ${APPINDICATOR_LIBRARY_DIRS})
+  target_link_libraries(${CEF_TARGET} libcef_dll_wrapper ${CEF_LIB_RELEASE} ${CEF_STANDARD_LIBS} ${GTK3_LIBRARIES} ${XI2_LIBRARIES} laufey_backend_common)
+  target_link_directories(${CEF_TARGET} PRIVATE ${GTK3_LIBRARY_DIRS} ${XI2_LIBRARY_DIRS})
   target_include_directories(${CEF_TARGET} PRIVATE
     "${CMAKE_CURRENT_SOURCE_DIR}/src"
     "${LAUFEY_INCLUDE_DIR}"
     ${GTK3_INCLUDE_DIRS}
     ${XI2_INCLUDE_DIRS}
-    ${APPINDICATOR_INCLUDE_DIRS}
   )
 
-  if(APPINDICATOR_FOUND)
-    target_compile_definitions(${CEF_TARGET} PRIVATE LAUFEY_HAVE_APPINDICATOR=1)
-  else()
-    message(STATUS "libappindicator not found — tray icon will be a no-op on this build")
-  endif()
-
   # Set RPATH so the executable finds libcef.so next to it
   set_target_properties(${CEF_TARGET} PROPERTIES
     INSTALL_RPATH "$ORIGIN"

cef/src/runtime_loader_linux.cc

@@ -1,8 +1,8 @@
 // Copyright 2025 Divy Srivastava. All rights reserved. MIT license.
 
-// Linux-specific backend implementations: tray (via libappindicator) and
-// context menu (via GtkMenu popup). Neither needs a GtkWindow parent, so
-// both work alongside CEF Views' raw X11 windows.
+// Linux-specific backend implementations: tray (via appindicator, dlopened
+// in backend-common) and context menu (via GtkMenu popup). Neither needs a
+// GtkWindow parent, so both work alongside CEF Views' raw X11 windows.
 //
 // set_application_menu (an in-window menu bar) is NOT implemented here: it
 // requires packing a GtkMenuBar into a GtkBox above the browser widget,
@@ -27,12 +27,6 @@
 #include "laufey.h"
 #include "laufey_backend_common.h"
 
-#ifdef LAUFEY_HAVE_APPINDICATOR
-extern "C" {
-#include <libappindicator/app-indicator.h>
-}
-#endif
-
 // ---------------------------------------------------------------------------
 // GTK lazy init. CEF's Chromium process initializes GTK internally for its
 // own dialogs/theming, but we don't rely on that — call gtk_init_check once
@@ -87,7 +81,7 @@ void Backend_ShowContextMenu_Linux(void* data, uint32_t window_id, int /*x*/,
 }
 
 // ---------------------------------------------------------------------------
-// Tray / status-bar icon (libappindicator)
+// Tray / status-bar icon (appindicator)
 // ---------------------------------------------------------------------------
 //
 // Trampolines over backend-common/src/tray_linux.cc, which handles its

docs/architecture.md

@@ -87,7 +87,7 @@ Currently shared:
 | **Dock**                           | `dock_mac.mm` (badge / bounce / visible / dock menu storage / reopen handler)                                    | per-backend (FlashWindowEx) + `title_badge.cc` for the badge   | per-backend (gtk_window_set_urgency_hint) + `title_badge.cc` for the badge |
 | **Key mapping**                    | `keymap_mac.mm` (NSEvent → W3C)                                                                                  | `keymap_vk.cc` (VK → W3C; CEF uses on every platform)          | `keymap_gdk.cc` (GDK → W3C)                                                |
 | **App / context menu**             | `menu_mac.mm` (NSMenu)                                                                                           | `capi/include/win32_menu.h` (HMENU + SetMenu / TrackPopupMenu) | `menu_linux.cc` (GtkMenu / GtkMenuBar)                                     |
-| **Tray icons**                     | `tray_mac.mm` (NSStatusItem)                                                                                     | `tray_win.cc` (Shell_NotifyIcon + WIC + HMENU)                 | `tray_linux.cc` (libappindicator + g_idle_add)                             |
+| **Tray icons**                     | `tray_mac.mm` (NSStatusItem)                                                                                     | `tray_win.cc` (Shell_NotifyIcon + WIC + HMENU)                 | `tray_linux.cc` (appindicator via dlopen + g_idle_add)                     |
 | **Option parsing**                 | `parse_options.cc` (compiled on every platform; bridges `laufey_value_t` → plain structs)                        |                                                                |                                                                            |
 | **Title-prefix badge bookkeeping** | `title_badge.cc` (`ApplyTitlePrefixBadge` — used by CEF Win+Linux and webview Win+Linux for Dock-badge fallback) |                                                                |                                                                            |