vodkanull/pudu

1. What this repository is

- pudu is a single-process Wayland compositor built on wlroots.

- Architecturally, it sits at the boundary between Wayland clients and the Linux input/output stack, acting as both display server and window manager.

2. Top-level structure

- The repo is small and centered around src/.

- src/pudu.c is the main compositor implementation.

- src/pudu.h is the shared header for the compositor’s internal types and declarations.

- src/Makefile drives compilation.

- src/pudu.desktop packages it as a Wayland session for a display manager.

- src/config is the example/user config template.

3. Core runtime architecture

- The compositor starts from pudu, creates the Wayland server state, initializes wlroots backend components, and then enters the event loop.

- At runtime it mediates:

- input events from keyboard/mouse/touch via libinput/wlroots,

- surface events from Wayland clients,

- rendering/output updates through wlroots’ output/backend abstraction.

4. Main dependency stack

- The README makes the dependency boundary explicit: wlroots 0.19, Wayland, libxkbcommon, libinput, cairo, seatd, and a terminal app such as kitty.

- This indicates pudu is not a self-contained graphics stack; it relies on wlroots for most platform integration and protocol plumbing.

5. Wayland protocol boundary

- src/protocols/ contains protocol XMLs used by the compositor.

- Standard protocols include:

- xdg-shell.xml for normal application windows,

- wlr-layer-shell-unstable-v1.xml for panels/overlays,

- pointer-constraints-unstable-v1.xml for pointer confinement/locking.

- Custom extension protocols include:

- ext-session-lock-v1.xml for lock-screen/session-lock behavior,

- ext-workspace-v1.xml for workspace awareness.

- These XML files define the compositor’s external API surface and are important for diagramming client interaction points.

6. Window management model

- The README describes it as a minimal tiling compositor.

- That suggests the core logic in pudu.c manages:

- mapping new xdg-shell surfaces,

- arranging windows into tiling layout,

- handling focus and surface lifecycle,

- supporting manual movement/closing via compositor shortcuts.

- User interaction is centered on simple keyboard/mouse bindings rather than a separate window-manager process.

7. Input and session control

- Input flows from the seat/input layer into compositor actions:

- Super + Left Click drag moves windows,

- Super + C closes the focused window,

- Super + Enter launches the configured terminal.

- The need for seatd and the note about adding the user to input,seat show that direct TTY/session ownership is part of the runtime boundary.

8. Configuration path

- Configuration lives at ~/.config/pudu/config.

- The example config in src/config indicates runtime behavior is customizable without recompiling.

- The config likely controls keybindings and default terminal command, making it a small but important control plane separate from compositor code.

9. Build and packaging flow

- The build is local and source-based: clone repo → cd src → make.

- The output binary is copied into /usr/local/bin/.

- pudu.desktop is installed into /usr/share/wayland-sessions/ so a display manager can launch it as a session.

- This means packaging is intentionally lightweight and distro integration is manual.

10. External behavior and project constraints

- The README explicitly says XWayland is not supported, so the architecture is pure Wayland only.

- That is a meaningful boundary: legacy X11 clients are excluded from the supported client set.

- The project is also tested only on Arch Linux, which matters for the deployment/runtime assumptions around dependencies and seat management.

11. How to draw the architecture

- A useful diagram would show:

- Wayland clients on one side,

- pudu compositor in the center,

- wlroots + system libraries beneath it,

- seatd / kernel input-output stack below that,

- and config file + protocol XMLs as supporting inputs to the compositor build/runtime behavior.

- The compositor itself appears to be a single monolithic core, not a multi-service architecture.

12. Overall repo shape

- This repository is intentionally compact: one core compositor, a small set of protocol definitions, one example config, and install metadata.

- The key architecture question is not service decomposition, but rather which Wayland protocols and wlroots subsystems pudu enables and how it manages windows, focus, and input inside one event-driven process.