5.2 KiB
Contributing to KWin
Chatting
Come on by and ask about anything you run into when hacking on KWin!
KWin's Matrix room on our instance is located here: https://matrix.to/#/#kwin:kde.org. You can grab an Matrix account at https://webchat.kde.org/ if you don't already have one from us or another provider.
The Matrix room is bridged to #kde-kwin on Libera, allowing IRC users to access it.
What Needs Doing
There's a large amount of bugs open for KWin on our Bugzilla instance.
Where Stuff Is
Everything codewise for KWin itself is located in the src directory.
Settings Pages / KCMs
All the settings pages for KWin found in System Settings are located in src/kcmkwin.
Default Decorations
The Breeze decorations theme is not located in the KWin repository, and is in fact part of the Breeze repository here, in kdecoration.
Tab Switcher
The default visual appearance of the tab switcher is located in src/tabbox/switchers.
Other window switchers usually shipped by default are located in Plasma Addons, located in the kwin/windowswitchers directory.
Window Management
Most window management stuff (layouting, movement, properties, communication between client<->server) is defined in files ending with client, such as x11client.cpp and xdgshellclient.cpp.
Window Effects
Window effects are located in src/plugins, one effect plugin per folder. Folder src/plugins/private contains the plugin (org.kde.kwin.private.effects) that exposes layouting properties and WindowHeap.qml for QML effects. Not everything here is an effect as exposed in the configuration UI, such as the colour picker in src/plugins/colorpicker.
Of note, the Effects QML engine is shared with the Scripting components (see src/scripting).
Scripting API
Many objects in KWin are exposed directly to the scripting API; scriptable properties are marked with Q_PROPERTY and functions that scripts can invoke on them.
Other scripting stuff is located in src/scripting.
Conventions
Coding Conventions
KWin's coding conventions are located here.
KWin additionally follows KDE's Frameworks Coding Style.
Commits
We usually use this convention for commits in KWin:
component/subcomponent: Do a thing
This is a body of the commit message,
elaborating on why we're doing thing.
While this isn't a hard rule, it's appreciated for easy scanning of commits by their messages.
Contributing
KWin uses KDE's GitLab instance for submitting code.
You can read about the KDE workflow here.
Running KWin From Source
KWin uses CMake like most KDE projects, so you can build it like this:
mkdir _build
cd _build
cmake ..
make
People hacking on much KDE software may want to set up kdesrc-build.
Once built, you can either install it over your system KWin (not recommended) or run it from the build directory directly.
Running it from your build directory looks like this:
# from the root of your build directory
source prefix.sh
cd bin
# for wayland, starts nested session: with console
env QT_PLUGIN_PATH="$(pwd)":"$QT_PLUGIN_PATH" dbus-run-session ./kwin_wayland --xwayland konsole
# or for x11, replaces current kwin instance:
env QT_PLUGIN_PATH="$(pwd)":"$QT_PLUGIN_PATH" ./kwin_x11 --replace
QT_PLUGIN_PATH tells Qt to load KWin's plugins from the build directory, and not from your system KWin.
The dbus-run-session is needed to prevent the nested KWin instance from conflicting with your session KWin instance when exporting objects onto the bus, or with stuff like global shortcuts.
If you need to run a whole Wayland plasma session, you should install a development session by first building plasma-workspace and executing the login-sessions/install-sessions.sh in the build directory. This can be done using kdesrc-build.
kdesrc-build plasma-workspace
# assuming the root directory for kdesrc-build is ~/kde
bash ~/kde/build/plasma-workspace/login-sessions/install-sessions.sh
Then you can select the develop session in the sddm login screen.
You can look up the current boot kwin log via journalctl --user-unit plasma-kwin_wayland --boot 0.
Using A Debugger
Trying to attach a debugger to a running KWin instance from within itself will likely be the last thing you do in the session, as KWin will freeze until you resume it from your debugger, which you need KWin to interact with.
Instead, either attach a debugger to a nested KWin instance or debug over SSH.
Tests
KWin has a series of unit tests and integration tests that ensure everything is running as expected.
If you're adding substantial new code, it's expected that you'll write tests for it to ensure that it's working as expected.
If you're fixing a bug, it's appreciated, but not expected, that you add a test case for the bug you fix.
You can read more about KWin's testing infrastructure here.