Developer Guide
Everything you need to build, extend, and contribute to PlexyDesk.
Quick Start
Get up and running in 5 minutes
1. Install dependencies
# Debian/Ubuntu
sudo apt install libwayland-dev libdrm-dev libinput-dev libseat-dev \
libgbm-dev libegl-dev libglew-dev libfreetype-dev build-essential
# Arch Linux
sudo pacman -S wayland libdrm libinput seatd gbm glew freetype2 base-devel2. Clone and build
git clone https://github.com/plexydesk/plexydesk.git
cd plexydesk
make -j$(nproc)3. Run
./plexyshellNeed help? Check the issue tracker or join our discussions.
Build Instructions
System Requirements
Minimum
- • Linux kernel 5.10+
- • Mesa 21.0+ for OpenGL ES
- • GCC 9+ or Clang 10+
- • 2GB RAM
Recommended
- • Linux kernel 6.0+
- • AMD/Intel GPU with DMA-BUF
- • 4+ CPU cores for physics
- • SSD for fast builds
Configuration
Edit plexyshell.conf to customize your setup:
# Display settings
resolution=1920x1080
refresh_rate=60
# Physics parameters
physics_enabled=true
spring_constant=0.5
damping=0.15
# Visual effects
glass_alpha=0.85
shadows=true
cylindrical_mode=false
Full configuration reference is available in plexyshell.conf.example.
Architecture Overview
PlexyDesk is a bare-metal compositor that runs directly on DRM/KMS, bypassing the need for X11 or Wayland intermediaries.
Display Layer
- DRM/KMS — Display control and mode setting
- GBM — GPU buffer allocation
- EGL/OpenGL ES — Hardware rendering
- libseat — Session management
Input Handling
- libinput — Keyboard and pointer events
- Multi-seat — Device enumeration
- Hotplug — Dynamic device management
Physics Engine
- 12×12 mesh — Per-window cloth simulation
- Spring physics — Natural oscillation
- Multi-threaded — No global bottleneck
Wayland Bridge
- Protocol adapter — wl_compositor, xdg_shell
- DMA-BUF — Zero-copy buffer sharing
- App support — GTK, Qt, Firefox
Component Diagram
┌─────────────────────────────────────────────────────────────────┐
│ Applications │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Native C │ │ GTK4 │ │ Qt6 │ │ Firefox │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Plexy Protocol │ │
│ │ Unix Socket: /tmp/plexy.sock │ │
│ └─────────────────────────┬─────────────────────────────────┘ │
└────────────────────────────│────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PlexyDesk Compositor │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Server │ │ Physics │ │ Renderer │ │
│ │ Protocol │◄─│ Engine │─▶│ OpenGL ES / Shaders │ │
│ │ Handler │ │ Per-Window │ │ Cloth Mesh Rendering │ │
│ └──────┬──────┘ └─────────────┘ └───────────┬─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ libinput │ │ DRM/KMS │ │
│ │ Keyboard │ │ Display │ │
│ │ Pointer │ │ Output │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘For API details, see the API Reference and Protocol Specification.
Contributing
We welcome contributions of all kinds. Here's how to get started:
Code Contributions
- 1. Fork the repository on GitHub
- 2. Create a feature branch from
main - 3. Make your changes and test thoroughly
- 4. Submit a pull request with a clear description
Bug Reports
Found a bug? Open an issue with:
- • Your Linux distribution and kernel version
- • GPU model and driver version
- • Steps to reproduce the issue
- • Expected vs actual behavior
Documentation
Help improve this documentation by submitting corrections or additions.
Documentation source is in the website/ directory.