Skip to content

AGENTS.md

Latest commit

 

History

History
43 lines (35 loc) · 3 KB

AGENTS.md

File metadata and controls

43 lines (35 loc) · 3 KB
Raw

Treeland Agent Notes

Big Picture

  • treeland is a Wayland compositor built on wlroots + Qt6/QtQuick (Scene Graph rendering).
  • wlroots is vendored in-tree: upstream sources under 3rdparty/wlroots, built as a CMake module by wlroots/CMakeLists.txt (CMake target Wlroots::wlroots). waylib talks to wlroots through its raw C API directly — include <wlr_all.h>, not individual <wlr/...> headers — and supplies the Qt/C++ object/lifetime layer (WObject/WServerInterface, WPointer, scoped wl_signal listeners).
  • waylib/ builds on wlroots to provide a QtQuick-friendly compositor framework (outputs <-> QQuickWindow, surfaces <-> QQuickItem).
  • Treeland-specific policies live in src/ (workspace/seat/input/output, effects/plugins, XWayland integration).

Where to Look

  • src/core/: lifecycle + QML engine glue (for example src/core/qmlengine.*, src/core/treeland.*).
  • src/surface/: surface/window wrappers, state/visibility/geometry (for example src/surface/surfacewrapper.cpp).
  • src/seat/: compositor seat management, Helper initialization hub, protocol wiring entry point (for example src/seat/helper.*).
  • src/workspace/: workspace model and switching.
  • src/plugins/ + src/modules/: integration points and feature composition.
  • src/common/treelandlogging.*: centralized treeland logging categories.

Build & Test

cmake --preset ci
cmake --build --preset ci
ctest --preset ci
  • For daily development prefer the ci preset: it mirrors CI's -Wall -Wextra -Werror flags, so warnings that would fail CI are caught locally before push. Other presets in CMakePresets.json: default, clang, ci-clang.
  • WITH_SUBMODULE_WAYLIB=ON|OFF selects submodule vs system waylib. Default preference is ON.

Project Rules

  • Use C++20 and Qt6 only.
  • Prefer member function pointers over lambdas for connect() and signal listeners when the lambda only forwards to a single member function.
  • Avoid complex lambdas; if a lambda body grows beyond a few lines, extract it into a named member function.
  • Keep diffs minimal: touch only task-related files and symbols.
  • Avoid broad refactors, unrelated renames, and unrelated reformatting.
  • New source files must include an SPDX line consistent with this repo, typically SPDX-License-Identifier: Apache-2.0 OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only.
  • Logging changes must use .agents/skills/logging-guidelines/SKILL.md.
  • If real task work shows that a repo-local skill is wrong, outdated, or incomplete, update the skill proactively instead of preserving known-bad guidance.

Wayland Protocol Routing

When a task is about adding, modifying, or debugging a Wayland protocol integration, route it to exactly one of these skills:

  • Treeland private protocol: .agents/skills/treeland-private-wayland-protocol/SKILL.md
  • Upstream wlroots/waylib protocol: .agents/skills/upstream-wayland-protocol-wrapper/SKILL.md

Do not mix the two paths in one implementation unless the task is explicitly about refactoring boundaries.