Getting Started

This page is the fastest path from a fresh clone to a running PlexyDesk build.

Recommended environment

PlexyDesk is currently easiest to build on Debian or Ubuntu style systems with a working GPU stack, DRM/KMS access, and a user session where you can start the compositor from a TTY.

Install dependencies

Run the dependency installer from the repository root:

./install-deps.sh

The script installs:

build tools such as gcc, g++, meson, and ninja
graphics libraries including DRM, GBM, EGL, OpenGL, GLEW, and related Mesa packages
input and system libraries such as libinput, libudev, and libsystemd
Wayland and X11/Xorg development packages
font and text rendering packages including Pango, FreeType, and Fontconfig
optional WebKitGTK support for browser-oriented examples

Build the project

Release build:

make

Debug build with verbose logging:

BUILD_MODE=debug make

The Makefile defaults to a release build and applies aggressive optimization flags there. Debug mode keeps symbols and turns on additional logging macros.

Run PlexyDesk

The simplest direct launch is:

./plexyshell

Run with systemd user units

System installs and package installs place user units for the shell runtime:

plexy.slice
plexyshell.service

Typical flow:

make install
systemctl --user start plexyshell.service
./scripts/systemd/status-plexyshell-service.sh

For a development machine where you do not want a system-wide install, use:

./scripts/systemd/install-user-units.sh

Build a .deb package

The repository includes a Docker-assisted package flow for Ubuntu:

chmod +x scripts/docker-build-ubuntu-deb.sh
./scripts/docker-build-ubuntu-deb.sh 22.04 dist
# or
./scripts/docker-build-ubuntu-deb.sh 24.04 dist

The package is written into dist/. After installing it on a target machine, launch PlexyDesk with:

plexydesk

Run it as your normal user from a TTY session, not as root.

Configuration

The example configuration file documents the supported sections and defaults. Expected locations are:

$XDG_CONFIG_HOME/plexyshell/plexyshell.conf
/etc/plexyshell/plexyshell.conf

Common sections include:

[appearance] for theme and scale factor
[display] and [display_layout:...] for monitor placement
[background] for wallpaper or animated background
[compositor] for window chrome and effect tuning
[dock] and [menubar] for shell behavior
[terminal] for terminal fonts and colors

Basic controls

Input	Action
Mouse drag	Move a window
Corner drag	Resize a window
Tab	Cycle windows
F6	Toggle cylindrical desktop mode
W / Q	Close focused window
Esc	Exit

Where to go next

Architecture for how the compositor and client stack fit together
Developer Guide for the important source files and build entry points
Examples for code you can compile and extend