Treeland

treeland is a wayland compositor based on wlroots and QtQuick, designed to provide efficient and flexible graphical interface support.

Dependencies

Check the debian/control file to understand specific build and runtime dependencies, or use cmake to check for missing necessary components.

Core build dependencies:

• waylib: A Wayland compositor development library based on wlroots and QtQuick
  • Qt >= 6.8.0
  • wlroots = 0.19
• treeland-protocols: Private Wayland protocols used by treeland

Recommended runtime dependencies:

• ddm: A display manager optimized for multiple users

Building

Treeland uses cmake for building. The WITH_SUBMODULE_WAYLIB option can force the use of the waylib code from the submodule. If you want to use the system-provided waylib, set this option to OFF.

Using the system-provided waylib:

$ git clone git@github.com:linuxdeepin/treeland.git
$ cd treeland
$ cmake -Bbuild -DWITH_SUBMODULE_WAYLIB=OFF
$ cmake --build build

Using the waylib from the submodule:

$ git clone git@github.com:linuxdeepin/treeland.git --recursive
$ cd treeland
$ cmake -Bbuild -DWITH_SUBMODULE_WAYLIB=ON
$ cmake --build build

Packaging

A debian folder is provided to build the package under the deepin linux desktop distribution. To build the package, use the following command:

$ sudo apt build-dep . # install build dependencies
$ dpkg-buildpackage -uc -us -nc -b # build binary package(s)

treeland-debug

treeland-debug is an adb-style command-line inspector and controller for the running Treeland compositor. It connects to Treeland's debug Remote Object over Qt Remote Objects and exposes subcommands for inspecting the window tree, controlling windows, injecting input events and grabbing screenshots. Like adb, it runs in two modes:

• Non-shell (one-shot) mode — the default: treeland-debug <command> [args].
• Shell mode — an interactive REPL: treeland-debug shell.

The client builds as part of the normal Treeland build (it is on by default; pass -DBUILD_TREELAND_DEBUG=OFF to skip it):

cmake -B build
cmake --build build --target treeland-debug
sudo cmake --install build --component treeland-debug

Enabling the debug source

The debug Remote Object is opt-in. Enable the debugSource DConfig option as the dde user (Treeland runs as dde in global mode and its local socket is owner-only), then restart Treeland:

sudo -u dde -- dde-dconfig set \
  -a org.deepin.dde.treeland \
  -r org.deepin.dde.treeland \
  -k debugSource \
  -v true

All commands below are run as the dde user, e.g. sudo -u dde -- treeland-debug windows.

Global options

Option	Default	Description
--url <url>	local:org.deepin.dde.treeland.debug	Remote object host URL.
--name <name>	WindowTree	Remote object name.
--timeout-ms <n>	30000	Request timeout in ms (non-negative integer).
--json	off	Emit machine-readable JSON for tree/cursor/windows/clients.
--preview	auto	Force inline image preview in terminal (auto-detected by default).
--no-preview	off	Disable inline image preview.
-h, --help	—	Show help.
-v, --version	—	Show version.
--tree / --cursor	—	Backward-compatible aliases for the tree / cursor commands.

Command reference

Window-control commands accept a target given by numeric id (printed by windows / clients / top) or by appId (the first matching window is used).

Inspection

Command	Arguments	Output
tree	(none, default)	Layout tree (human-readable; --json for JSON).
cursor	(none)	Cursor position x=… y=… (--json for {"x","y"}).
windows	(none)	Window table; --json for a JSON array.
clients	(none)	Client + window table; --json for a JSON array.
top	[interval-ms] (default 1000)	Live, top-like refreshing client view (Ctrl+C to quit).

Window control

Command	Arguments	Output
activate	<id>	ok / failed.
close	<id>	ok / failed.
minimize	<id>	ok / failed.
maximize	<id>	ok / failed (toggles maximized).
fullscreen	<id>	ok / failed (toggles fullscreen).
move	<id> <x> <y>	ok / failed.
resize	<id> <w> <h>	ok / failed.
workspace	<id> <ws-id>	ok / failed (move window to a workspace).

Input / event injection

Command	Arguments	Output
move-cursor	<x> <y>	ok / failed.
event motion	<x> <y>	ok / failed.
event button	<left|right|middle|code> [press|release|click]	ok / failed (default click).
event key	<name|evdev-code> [press|release|tap]	ok / failed (default tap).

Pointer buttons use Linux input codes (left=0x110, right=0x111, middle=0x112, or a numeric code). Keyboard keys use Linux evdev keycodes; common names are recognised (esc, enter, space, tab, a–z, 0–9, arrow keys, f1–f12, home/end/pageup/pagedown/insert/del, …) or a raw code may be passed. Keys are delivered to the keyboard-focused surface — activate a window first to target it; pointer buttons go to the surface under the cursor.

Image capture

Screenshots are rendered server-side and returned to the treeland-debug client as PNG bytes; the client writes them to a file and prints the path. The compositor itself never touches the filesystem. If file is omitted a path under /tmp is generated.

Command	Arguments	Output
screenshot output	[name] [file]	PNG file path (stdout).
screenshot window	<id> [file]	PNG file path (stdout).

Interactive

Command	Arguments	Output
shell	(none)	REPL (treeland>) accepting all commands plus help/exit.
help	(none)	Full help text.

Output formats

tree and cursor print a human-readable format by default; pass --json for machine-readable JSON. windows and clients also default to human-readable tables and use --json for JSON. Window JSON object (WindowInfo):

Field	Type	Notes
id	integer	Stable window id (the wl_surface wl_resource pointer); globally unique, accepted by control commands.
appId	string	Application id.
title	string	Window title.
output	string	Output name.
container	string	Container name.
workspace	integer	Workspace id.
layer	integer	Layer id.
z	integer	Z order.
type	integer	Window type.
state	integer	0 Normal, 1 Maximized, 2 Minimized, 3 Fullscreen, 4 Tiling.
visible	boolean	Visibility.
active	boolean	Active / focused flag.
geometry	object	{"x","y","width","height"}.
titlebarGeometry	object	Same shape.
boundingRect	object	Same shape.
iconGeometry	object	Same shape.
position	object	{"x","y"}.
frames	integer	Number of committed frames (from wlr_surface).
damage	object	Last committed buffer-damage rectangle {"x","y","width","height"}.

Client JSON object (ClientInfo): id (integer), appId (string), pid (integer, 0 when unavailable), executable (string), windows (array of WindowInfo).

The tree JSON is {"currentMode": str, "layers": [{"name", "layer", "windows": [WindowInfo], "workspaces": [{"id", "isActive", "windows": [WindowInfo]}]}]}.

Exit codes

0 on success; 1 on connection failure, RPC failure, an unknown command, or a control command that returns failed.

Usage examples

All commands run as the dde user:

# Inspect the window tree (human-readable, default command)
sudo -u dde -- treeland-debug tree

# Cursor position
sudo -u dde -- treeland-debug cursor
# → x=960 y=540

# List windows
sudo -u dde -- treeland-debug windows

# List clients and their windows
sudo -u dde -- treeland-debug clients

# Live refreshing top view (1 s interval)
sudo -u dde -- treeland-debug top
# (Ctrl+C to quit)

# Activate a window by id
sudo -u dde -- treeland-debug activate 1407374883553280

# Activate a window by appId
sudo -u dde -- treeland-debug activate dde-file-manager

# Move a window
sudo -u dde -- treeland-debug move 1407374883553280 100 200

# Resize a window
sudo -u dde -- treeland-debug resize 1407374883553280 800 600

# Move a window to workspace 2
sudo -u dde -- treeland-debug workspace 1407374883553280 2

# Move cursor
sudo -u dde -- treeland-debug move-cursor 960 540

# Send a pointer click
sudo -u dde -- treeland-debug event button left click

# Send a key tap
sudo -u dde -- treeland-debug event key enter tap

# Screenshot the primary output to a file
sudo -u dde -- treeland-debug screenshot output /tmp/ss.png

# Screenshot a window (with terminal preview if supported)
sudo -u dde -- treeland-debug screenshot window 1407374883553280

# Interactive shell mode
sudo -u dde -- treeland-debug shell
treeland> help
treeland> windows
treeland> exit

# Machine-readable JSON output
sudo -u dde -- treeland-debug --json windows
sudo -u dde -- treeland-debug --json cursor

The top view refreshes every interval-ms (default 1000 ms) using a QTimer. Each cycle calls getClients() via Qt Remote Objects, clears the terminal (\033[2J\033[H), and re-prints a header with the current timestamp and client count, followed by the client + window table. Press Ctrl+C to stop.

GitHub Actions / CI

This project uses GitHub Actions for continuous integration. The following workflows are configured:

• waylib builds: Triggered when waylib/** files are modified
• treeland builds: Main project builds

Getting Involved

• Code contribution via GitHub
• Submit bug or suggestions to GitHub Issues or GitHub Discussions

License

treeland is licensed under Apache-2.0 OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only.