libx11-compat is an in-process implementation of the X Window System client library (Xlib) layered on top of SDL2, SDL2_ttf, and pixman.
It is intended as a transition tool:
existing Xlib clients can keep their source unchanged while running on platforms where no X server is available:
Android, headless CI, macOS without XQuartz, Wayland-only sessions, and similar environments.
The library is not a re-implementation of the X11 wire protocol and does not replace a real X server. Its goal is to keep legacy Xlib code building and running while it is being migrated to a different toolkit or display stack.
The build is Makefile-based, organized as small mk/ fragments.
The required dependencies are SDL2, SDL2_ttf, and pixman.
make
make checkVerbose diagnostics for unimplemented or fall-back paths are gated behind a build flag:
make CFLAGS_EXTRA=-DDEBUG_LIBX11_COMPATThe output artifact is build/libX11-compat.so.
Clients link against it the same way they would link against the system libX11.so.
examples/ bundles real Xlib clients built against the local libX11-compat.so:
make examples
build/examples/2048The bundle covers a 2048 game, a paint demo, Conway's Game of Life, an analog clock, an interactive Mandelbrot viewer, a single-runner Processing-style showcase, an SDL-backed clipboard TARGETS probe, and the upstream X.Org x11perf benchmark.
See docs/EXAMPLES.md for the API each example exercises.
The library exports 615 public Xlib symbols listed in tests/api-symbols.txt,
covering window, drawable, GC, pixmap, image, event, input, atom, property, color, font, cursor, and region subsystems for the cases that real Xlib clients exercise.
Selection, property, and resource-manager support is partial;
MIT-SHM is a thin wrapper over the regular image path;
GLX, Xcms, and input methods are intentionally stubbed.
See docs/COVERAGE.md for the per-subsystem status table, surface notes (window manager hints, raster ops, mouse wheel mapping), and compatibility limits.
Most Xlib sources need no edits (porting is a build-system and runtime-environment exercise). The general shape:
- Link the application against
build/libX11-compat.soplus SDL2, SDL2_ttf, and pixman, replacing the system-lX11. - Keep the existing Xlib source unchanged.
- Drive the event loop with
XPending/XNextEventandConnectionNumber+select(); the library pumps SDL internally. - Use
WM_DELETE_WINDOWviaXSetWMProtocolsso the SDL close button produces a clean shutdown. - Run with
SDL_VIDEODRIVER=dummyfor headless CI.
See docs/PORTING.md for the full guide,
including code snippets keyed to the bundled examples and a checklist of cases where the library is a stepping stone rather than a destination (GLX, real XIM, ICC color management, cross-process selection).
Reports of incorrect Xlib semantics, missing entry points that block real applications, and patches that tighten coverage against the manifest in tests/api-symbols.txt are particularly useful.
libX11-compat is available under a permissive MIT-style license.
Use of this source code is governed by an MIT license that can be found in the LICENSE file.