WindowServer.app

Native GNUstep Display Server for Linux — KMS/DRM + GPU Compositing

1. Architecture Overview

WindowServer.app is a native GNUstep display server that eliminates the X11 and Wayland dependency entirely. It follows Apple's macOS model: WindowServer owns the display hardware, and all GUI applications render through it. The architecture maximizes use of GNUstep/Apple-native frameworks.

2. Technology Stack

3. GNUstep Repositories Required

These GNUstep repositories need to be cloned and built as part of the Gershwin system. The first six are already in Checkout.sh. The last two are new additions.

Additions to Checkout.sh

# Add to the REPOS list:
https://github.com/gnustep/libs-opal.git
https://github.com/gnustep/libs-quartzcore.git

Build Order

1.  swift-corelibs-libdispatch   (CMake)
2.  tools-make                    (configure)
3.  libobjc2                      (CMake)
4.  libs-base                     (configure)
5.  libs-opal                     (GNUstep Make)     ← NEW
6.  libs-gui                      (configure)
7.  libs-back --enable-server=drm --enable-graphics=opal  (configure)
8.  libs-quartzcore               (GNUstep Make)     ← NEW
9.  gershwin-windowserver         (GNUstep Make)     ← NEW
10. gershwin-* components

4. Devuan Linux Packages Required

Target: Devuan GNU/Linux 6 (Excalibur), amd64. Devuan uses eudev instead of systemd-udev. All package names verified via apt-cache search on a live Devuan 6 system.

Already in devuan.txt (existing dependencies)

New packages for WindowServer.app

One-liner install command

apt-get install -y \
  libdrm-dev libgbm-dev libegl-dev libgles-dev libgl-dev libglu1-mesa-dev \
  mesa-common-dev libinput-dev libxkbcommon-dev libeudev-dev \
  liblcms2-dev libfreetype-dev libfontconfig-dev

5. Phase 1: DRM Backend in libs-back

Phase 1 Get pixels on screen with GPU compositing. A new --enable-server=drm backend.

5.1 New files in libs-back/Source/drm/

5.2 New files in libs-back/Source/cairo/

5.3 Modified existing files

5.4 DRMServer initialization flow

-initWithAttributes:
  1. Open DRM device directly:  open("/dev/dri/card0", O_RDWR)
  2. drmModeGetResources()  →  enumerate connectors, CRTCs, encoders
  3. For each connected output, create DRMOutput:
     a. Find preferred mode from connector
     b. gbm_create_device(drm_fd)
     c. eglGetDisplay(gbm_device)  →  EGL context
     d. Create GBM surface for scanout
     e. drmModeSetCrtc() for initial mode
  4. libinput_udev_create_context()  →  input handling
  5. xkb_context_new()  →  keyboard layout
  6. Add DRM fd + libinput fd to [NSRunLoop currentRunLoop]
     via NSFileHandle or -addEvent:type:watcher:forMode:

5.5 Compositing with Core Animation

DRMCompositor wraps libs-quartzcore's CARenderer:

  - Root CALayer sized to screen resolution
  - Each window gets a child CALayer
    - layer.contents = CGImageRef from the window's CairoSurface bitmap
    - layer.frame = window position and size
    - layer.zPosition = window level / z-order
  - CARenderer renders the layer tree via OpenGL into the EGL/GBM surface
  - drmModePageFlip() presents the frame

  Window animations (minimize, zoom, fade) come from CABasicAnimation
  on the window's CALayer properties (transform, opacity, bounds).

5.6 Input handling

DRMServerEvent.m:

  libinput fd → NSRunLoop callback → libinput_dispatch()

  LIBINPUT_EVENT_POINTER_MOTION    →  NSMouseMoved / NSLeftMouseDragged
  LIBINPUT_EVENT_POINTER_BUTTON    →  NSLeftMouseDown / NSLeftMouseUp / NSRightMouse*
  LIBINPUT_EVENT_KEYBOARD_KEY      →  NSKeyDown / NSKeyUp  (via libxkbcommon)
  LIBINPUT_EVENT_POINTER_SCROLL_*  →  NSScrollWheel

  Hit-test pointer against window registry for target window.
  Post via [self postEvent:atStart:]

6. Phase 2: WindowServer.app Application

Phase 2 A standalone NSApplication that uses the DRM backend, runs as PID 1 of the graphical session.

Application structure

gershwin-windowserver/
  GNUmakefile
  GNUmakefile.preamble
  WindowServerApplication.h / .m   ← NSApplication subclass
  WSCompositor.h / .m               ← CARenderer + layer tree management
  WSDisplayManager.h / .m           ← Multi-monitor DRM output management
  WSInputManager.h / .m             ← libinput → NSEvent translation
  WSWindowRegistry.h / .m           ← Window list, z-order, focus policy
  WSCursorManager.h / .m            ← Hardware/software cursor
  WSSessionManager.h / .m           ← VT switching via ioctl
  Resources/
    Info-gnustep.plist
    WindowServer.png
  main.m

GNUstep APIs used in WindowServer.app

Startup flow

main.m:
  [WindowServerApplication sharedApplication]
  [NSApp run]

-finishLaunching:
  1. WSDisplayManager opens /dev/dri/card0 directly (running as root via LoginWindow)
  2. WSDisplayManager enumerates outputs, sets modes, creates EGL/GBM surfaces
  3. WSInputManager opens libinput, adds fd to [NSRunLoop currentRunLoop]
  4. WSCompositor creates root CALayer, initializes CARenderer with EGL context
  5. DRM page-flip fd added to NSRunLoop

Compositing loop (driven by vsync):
  DRM page-flip completion event  →  NSRunLoop callback
    →  WSCompositor checks damage
    →  Updates CALayer contents for dirty windows
    →  [CARenderer render]
    →  eglSwapBuffers / drmModePageFlip()

7. Phase 3: Multi-Process Client-Server

Phase 3 Client GNUstep apps run as separate processes, communicating with WindowServer.app via Distributed Objects.

Protocol (using GNUstep DO)

@protocol WSWindowServerProtocol <NSObject>

// Window lifecycle
- (int)createWindowWithFrame:(NSRect)frame
                backingStore:(NSBackingStoreType)type
                       style:(unsigned int)style
                      screen:(int)screen;
- (void)destroyWindow:(int)windowId;

// Window operations
- (void)orderWindow:(int)windowId operation:(int)op relativeTo:(int)other;
- (void)moveWindow:(int)windowId toPoint:(NSPoint)point;
- (void)resizeWindow:(int)windowId toSize:(NSSize)size;
- (void)setWindowLevel:(int)level forWindow:(int)windowId;
- (void)setWindowTitle:(NSString *)title forWindow:(int)windowId;
- (void)setInputFocus:(int)windowId;

// Rendering (shared memory path)
- (NSString *)sharedMemoryPathForWindow:(int)windowId;
- (void)flushRect:(NSRect)rect forWindow:(int)windowId;

// Screen info
- (NSArray *)screenList;
- (NSRect)boundsForScreen:(int)screen;

// Cursor
- (void)setCursorImage:(NSData *)imageData hotspot:(NSPoint)hotspot;
- (void)hideCursor;
- (void)showCursor;

@end

Shared memory rendering path

Client Process:
  shm_open(path)  →  mmap()
  cairo_image_surface_create_for_data(shm_ptr, ARGB32, w, h, stride)
  ↓ normal GNUstep drawing via Core Graphics (libs-opal) / CairoGState
  ↓ flushwindowrect:: triggers
  ↓ [proxy flushRect:forWindow:]     (lightweight DO call)

WindowServer.app:
  ← receives flushRect notification
  ← reads pixels from shared memory  (same physical pages, zero-copy)
  ← uploads to CALayer.contents as CGImageRef / GL texture
  ← [CARenderer render]
  ← drmModePageFlip()

WSClientServer (new libs-back server type)

8. Phase 4: Window Decorations & Menus

Phase 4 Server-side window chrome and global menu bar.

9. Phase 5: Multi-Monitor, VT Switching, Polish

Phase 5 Production readiness.

• Multi-monitor: Multiple DRMOutput objects, one per CRTC. Each gets its own GBM surface and EGL context. NSScreen objects reflect each output.
• VT switching: Handle VT switch via ioctl(fd, VT_SETMODE, ...) and signals directly. WindowServer pauses rendering, releases DRM master, restores on return.
• Display hotplug: Monitor udev events for connector changes via NSRunLoop. Dynamically add/remove DRMOutput objects.
• Resolution changes: drmModeSetCrtc() with new mode, reallocate GBM surface and EGL context.
• Power management: DPMS control via DRM connector properties.

10. Key Reference Files

11. Verification Plan

Phase 1 Smoke Test

# Build libs-back with DRM backend
cd libs-back
./configure --enable-server=drm --enable-graphics=opal
make
sudo -E make install

# Minimal test program
#import <AppKit/AppKit.h>
int main() {
    [NSApplication sharedApplication];
    NSWindow *win = [[NSWindow alloc]
        initWithContentRect:NSMakeRect(100, 100, 400, 300)
                  styleMask:NSTitledWindowMask
                    backing:NSBackingStoreBuffered
                      defer:NO];
    [win setTitle:@"Hello KMS"];
    [win makeKeyAndOrderFront:nil];
    [NSApp run];
}

# Run from a Linux TTY (NOT inside X11/Wayland):
./test_app
# Should see a window rendered on the bare framebuffer

Phase 2 Integration Test

# Launch WindowServer from TTY:
/System/Library/Services/WindowServer.app/WindowServer

# Should see: desktop background, hardware cursor
# Keyboard and mouse input should work

Phase 3 Full Test

# WindowServer running, then launch a client app:
/System/Library/Services/WindowServer.app/WindowServer &
TextEdit.app/TextEdit

# Verify: window appears, move, resize, focus,
# keyboard input, mouse clicks, menu bar

Gershwin Desktop — WindowServer.app Development Plan
Generated 2026-03-31 — Target: Devuan GNU/Linux 6 (Excalibur)