raylib: add headless backend (#93)

* raylib: add headless backend (EGL surfaceless, no display server)

Third backend built from the new PLATFORM_HEADLESS raylib platform.
Replaces xvfb for running raylib apps in CI: RAYLIB_BACKEND=headless
renders offscreen to an EGL pbuffer via Mesa llvmpipe.

Linux x86_64 wheels now ship desktop+headless, aarch64 ships all
three backends. An explicit RAYLIB_BACKEND at build time still builds
just that backend.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* raylib: bump to 6.0.0.1, EGL/GLES build deps for headless

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* raylib: pin merged headless commit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: adeebshihadeh

build.sh

@@ -54,7 +54,8 @@ if [[ -n "${BUILD_SH_IN_MANYLINUX:-}" ]]; then
   if command -v dnf &>/dev/null; then
     dnf install -y -q \
       libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel libXi-devel \
-      mesa-libGL-devel wayland-devel wayland-protocols-devel libxkbcommon-devel \
+      mesa-libGL-devel mesa-libEGL-devel mesa-libGLES-devel \
+      wayland-devel wayland-protocols-devel libxkbcommon-devel \
       xorg-x11-server-Xvfb xorg-x11-xkb-utils xkeyboard-config
   fi
 fi

raylib/build.sh

@@ -22,24 +22,19 @@ if [ -n "${RAYLIB_PLATFORM:-}" ]; then
   exit 1
 fi
 
+# An explicit RAYLIB_BACKEND builds only that backend; otherwise all of the
+# host's backends are built (matches host_backends() in raylib/_backend.py)
 RAYLIB_BACKEND="${RAYLIB_BACKEND:-}"
-if [ -z "$RAYLIB_BACKEND" ]; then
-  RAYLIB_BACKEND="desktop"
-  if [ -f /AGNOS ] || [ -f /TICI ]; then
-    RAYLIB_BACKEND="comma"
-  fi
-fi
-
 case "$RAYLIB_BACKEND" in
-  desktop|comma) ;;
+  ""|desktop|comma|headless) ;;
   *)
-    echo "Unsupported RAYLIB_BACKEND=$RAYLIB_BACKEND; expected desktop or comma" >&2
+    echo "Unsupported RAYLIB_BACKEND=$RAYLIB_BACKEND; expected desktop, comma or headless" >&2
     exit 1
     ;;
 esac
 
 # Clone and build raylib C library
-RAYLIB_COMMIT="c2fb96ea0ebfceae28ccf7cb436a33a7d7857244"
+RAYLIB_COMMIT="caa64e15ac20a47804a8048029c921ac091fef12"
 
 if [ ! -d "raylib-src/.git" ]; then
   rm -rf raylib-src
@@ -48,7 +43,9 @@ fi
 
 cd raylib-src
 git remote set-url origin https://github.com/commaai/raylib.git
-git fetch --depth 1 origin "$RAYLIB_COMMIT"
+if ! git cat-file -e "$RAYLIB_COMMIT" 2>/dev/null; then
+  git fetch --depth 1 origin "$RAYLIB_COMMIT"
+fi
 git reset --hard "$RAYLIB_COMMIT"
 
 cd "$DIR"
@@ -70,20 +67,30 @@ build_raylib() {
   cd "$DIR"
 }
 
-if is_linux_aarch64; then
-  echo "Building desktop backend..."
-  build_raylib PLATFORM_DESKTOP libraylib_desktop.a
+backend_platform() {
+  case "$1" in
+    desktop) echo PLATFORM_DESKTOP ;;
+    comma) echo PLATFORM_COMMA ;;
+    headless) echo PLATFORM_HEADLESS ;;
+  esac
+}
 
-  echo "Building comma backend..."
-  build_raylib PLATFORM_COMMA libraylib_comma.a
-else
-  if [ "$RAYLIB_BACKEND" = "comma" ]; then
-    build_raylib PLATFORM_COMMA libraylib_comma.a
-  else
-    build_raylib PLATFORM_DESKTOP libraylib_desktop.a
+if [ -n "$RAYLIB_BACKEND" ]; then
+  BACKENDS="$RAYLIB_BACKEND"
+elif [ "$(uname)" == "Linux" ]; then
+  BACKENDS="desktop headless"
+  if is_linux_aarch64; then
+    BACKENDS="$BACKENDS comma"
   fi
+else
+  BACKENDS="desktop"
 fi
 
+for backend in $BACKENDS; do
+  echo "Building $backend backend..."
+  build_raylib "$(backend_platform "$backend")" "libraylib_${backend}.a"
+done
+
 # Download raygui header
 RAYGUI_COMMIT="1e03efca48c50c5ea4b4a053d5bf04bad58d3e43"
 curl -fsSLo "$INSTALL_DIR/include/raygui.h" \

raylib/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "raylib"
-version = "6.0.0.0"
+version = "6.0.0.1"
 description = "raylib + pyray Python bindings (commaai fork)"
 requires-python = ">=3.8"
 dependencies = ["cffi>=1.17.1"]

raylib/raylib/__init__.py

@@ -1,7 +1,7 @@
 import importlib
 import os
 
-from ._backend import BACKEND_ARCHIVES, BACKEND_CFFI_MODULES, detect_backend, is_dual_backend_host
+from ._backend import BACKEND_ARCHIVES, BACKEND_CFFI_MODULES, detect_backend, host_backends
 from .version import __version__
 
 DIR = os.path.join(os.path.dirname(__file__), "install")
@@ -12,9 +12,10 @@
 
 
 def _expected_archives():
-  if is_dual_backend_host():
-    return BACKEND_ARCHIVES.values()
-  return (BACKEND_ARCHIVES[_BACKEND],)
+  # explicit RAYLIB_BACKEND also selects a single-backend build (see setup.py)
+  if os.environ.get("RAYLIB_BACKEND"):
+    return (BACKEND_ARCHIVES[_BACKEND],)
+  return tuple(BACKEND_ARCHIVES[b] for b in host_backends())
 
 
 def smoketest():

raylib/raylib/_backend.py

@@ -3,40 +3,49 @@
 
 DESKTOP = "desktop"
 COMMA = "comma"
-BACKENDS = (DESKTOP, COMMA)
+HEADLESS = "headless"
+BACKENDS = (DESKTOP, COMMA, HEADLESS)
 DEFAULT_BACKEND = DESKTOP
 
 BACKEND_CFFI_MODULES = {
   DESKTOP: "_raylib_cffi_desktop",
   COMMA: "_raylib_cffi_comma",
+  HEADLESS: "_raylib_cffi_headless",
 }
 
 BACKEND_ARCHIVES = {
   DESKTOP: "libraylib_desktop.a",
   COMMA: "libraylib_comma.a",
+  HEADLESS: "libraylib_headless.a",
 }
 
 BACKEND_LINK_ARGS = {
   DESKTOP: ("-lGL", "-lX11"),
   COMMA: ("-lGLESv2", "-lEGL", "-lgbm", "-ldrm"),
+  HEADLESS: ("-lGLESv2", "-lEGL"),
 }
 
 COMMA_DEVICE_MARKERS = ("/AGNOS", "/TICI")
 
 
-def is_dual_backend_host():
-  return platform.system() == "Linux" and platform.machine() in ("aarch64", "arm64")
+def host_backends():
+  """Backends built into this host's wheels."""
+  if platform.system() != "Linux":
+    return (DESKTOP,)  # headless needs EGL, which macOS doesn't have
+  if platform.machine() in ("aarch64", "arm64"):
+    return (DESKTOP, COMMA, HEADLESS)
+  return (DESKTOP, HEADLESS)
 
 
 def detect_backend(environ=None, exists=os.path.exists):
   environ = os.environ if environ is None else environ
   if environ.get("RAYLIB_PLATFORM"):
-    raise ValueError("RAYLIB_PLATFORM is no longer supported; use RAYLIB_BACKEND=comma|desktop")
+    raise ValueError(f"RAYLIB_PLATFORM is no longer supported; use RAYLIB_BACKEND={'|'.join(BACKENDS)}")
 
   explicit = environ.get("RAYLIB_BACKEND", "").strip().lower()
   if explicit:
     if explicit not in BACKENDS:
-      raise ValueError("RAYLIB_BACKEND must be 'comma' or 'desktop'")
+      raise ValueError(f"RAYLIB_BACKEND must be one of {', '.join(repr(b) for b in BACKENDS)}")
     return explicit
 
   if any(exists(marker) for marker in COMMA_DEVICE_MARKERS):

raylib/raylib/version.py

@@ -1 +1 @@
-__version__ = "6.0.0.0"
+__version__ = "6.0.0.1"

raylib/setup.py

@@ -11,7 +11,7 @@
 
 PKG_DIR = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, os.path.join(PKG_DIR, "raylib"))
-from _backend import BACKENDS, BACKEND_CFFI_MODULES, detect_backend, is_dual_backend_host  # noqa: E402
+from _backend import BACKEND_CFFI_MODULES, detect_backend, host_backends  # noqa: E402
 
 
 class BuildRaylib(build_py):
@@ -30,7 +30,8 @@ def run(self):
     # Always regenerate CFFI extensions: the cached raylib source pin may have changed.
     for old_cffi in glob.glob(os.path.join(PKG_DIR, "raylib", "_raylib_cffi*")):
       os.remove(old_cffi)
-    backends = BACKENDS if is_dual_backend_host() else (detect_backend(),)
+    # explicit RAYLIB_BACKEND builds only that backend (matches build.sh)
+    backends = (detect_backend(),) if os.environ.get("RAYLIB_BACKEND") else host_backends()
     for backend in backends:
       self._build_cffi(backend)