Plexydesk: Add getting started guide

2026-03-21T19:32:54Z

Add getting started guide

New page

= 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:

<pre>
./install-deps.sh
</pre>

The script installs:
* build tools such as <code>gcc</code>, <code>g++</code>, <code>meson</code>, and <code>ninja</code>
* graphics libraries including DRM, GBM, EGL, OpenGL, GLEW, and related Mesa packages
* input and system libraries such as <code>libinput</code>, <code>libudev</code>, and <code>libsystemd</code>
* 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:

<pre>
make
</pre>

Debug build with verbose logging:

<pre>
BUILD_MODE=debug make
</pre>

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:

<pre>
./plexyshell
</pre>

== Run with systemd user units ==
System installs and package installs place user units for the shell runtime:
* <code>plexy.slice</code>
* <code>plexyshell.service</code>

Typical flow:

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

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

<pre>
./scripts/systemd/install-user-units.sh
</pre>

== Build a .deb package ==
The repository includes a Docker-assisted package flow for Ubuntu:

<pre>
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
</pre>

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

<pre>
plexydesk
</pre>

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:
* <code>$XDG_CONFIG_HOME/plexyshell/plexyshell.conf</code>
* <code>/etc/plexyshell/plexyshell.conf</code>

Common sections include:
* <code>[appearance]</code> for theme and scale factor
* <code>[display]</code> and <code>[display_layout:...]</code> for monitor placement
* <code>[background]</code> for wallpaper or animated background
* <code>[compositor]</code> for window chrome and effect tuning
* <code>[dock]</code> and <code>[menubar]</code> for shell behavior
* <code>[terminal]</code> for terminal fonts and colors

== Basic controls ==
{| class="wikitable"
|-
! 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

Getting Started - Revision history

Plexydesk: Add getting started guide