doc: modernise HACKING -> CONTRIBUTING guidelines and information
Jan Blackquill
3 years ago
committed by
David Edmundson
parent
0b74aa62c9
commit
f6005a28cd
@ -0,0 +1,125 @@
|
||||
# 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](https://bugs.kde.org/describecomponents.cgi?product=kwin).
|
||||
|
||||
## 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](https://invent.kde.org/plasma/breeze), in `kdecoration`.
|
||||
|
||||
### Tab Switcher
|
||||
|
||||
The default visual appearance of the tab switcher is not located in the KWin repository, and is in fact part of [Plasma Workspace](https://invent.kde.org/plasma/plasma-workspace), located at `lookandfeel/contents/windowswitcher`.
|
||||
|
||||
Other window switchers usually shipped by default are located in [Plasma Addons](https://invent.kde.org/plasma/kdeplasma-addons), located in the `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 the `effects` folder in `src`, with one folder per effect.
|
||||
Not everything here is an effect as exposed in the configuration UI, such as the colour picker in `src/effects/colorpicker`.
|
||||
|
||||
### 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](doc/coding-conventions.md).
|
||||
|
||||
KWin additionally follows [KDE's Frameworks Coding Style]((https://techbase.kde.org/Policies/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](https://community.kde.org/Infrastructure/GitLab).
|
||||
|
||||
## Running KWin From Source
|
||||
|
||||
KWin uses CMake like most KDE projects, so you can build it like this:
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
# from the root of your build directory
|
||||
|
||||
cd bin
|
||||
|
||||
# for wayland, starts nested session: with console
|
||||
|
||||
env QT_PLUGIN_PATH=`pwd` dbus-run-session ./kwin_wayland --xwayland konsole
|
||||
|
||||
# or for x11, replaces current kwin instance:
|
||||
|
||||
env QT_PLUGIN_PATH=`pwd` ./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.
|
||||
|
||||
## 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](doc/TESTING.md).
|
||||
@ -1,98 +0,0 @@
|
||||
# Quick building
|
||||
|
||||
KWin uses CMake. This means that KWin can be build in a normal cmake-style out of source tree.
|
||||
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ../
|
||||
make
|
||||
|
||||
# Dependencies
|
||||
|
||||
All of KWin's dependencies are found through CMake. CMake will report what is missing. The dependencies can be installed using system packages. For the master branch it is possible that system packages are not up to date. KWin master sometimes depends from the master branch of some KDE frameworks (mostly KWayland and KWindowSystems) and other components inside Plasma (KDecoration). KWin never depends on unreleased third party components. In such a case it is required to build these components also from master. Alternatively some distributions provide daily build packages which can also be used instead. Stable branches never depend on unstable components. On Debian based distributions the easiest way to install all build dependencies is
|
||||
|
||||
sudo apt build-dep kwin-wayland
|
||||
|
||||
# Running the build KWin
|
||||
KWin can be executed directly from the build directory. All binaries are put into a subdirectory bin. From there KWin and its tests can be started.
|
||||
|
||||
## Nested KWin/Wayland
|
||||
The best way to test changes in KWin is through using the nested KWin Wayland in a running X11 or Wayland session.
|
||||
|
||||
To start a nested KWin Wayland use:
|
||||
|
||||
cd build
|
||||
cd bin
|
||||
QT_PLUGIN_PATH=`pwd` dbus-run-session ./kwin_wayland --xwayland --socket=wayland-1
|
||||
|
||||
The socket option is not required if KWin is started from an X11 session. On Wayland of course a socket not matching the session's socket must be chosen. To show windows in the nested KWin adjust the environment variables DISPLAY (for X11 windows) and WAYLAND_DISPLAY (for Wayland windows). Alternatively it's possible to pass applications to launch as command line arguments to kwin_wayland command. E.g.
|
||||
|
||||
QT_PLUGIN_PATH=`pwd` dbus-run-session ./kwin_wayland --xwayland --socket=wayland-1 konsole
|
||||
|
||||
Will start a konsole in the nested KWin.
|
||||
|
||||
### Why adjusting QT_PLUGIN_PATH?
|
||||
|
||||
Qt's plugin path needs to point to the build directory so that KWin can load the plugins from the build directory instead of using the system installed plugins which would normally be preferred.
|
||||
|
||||
### Why start a dedicated DBus session?
|
||||
|
||||
KWin interacts with kglobalaccel, so starting KWin without a dedicated DBus session would steal all global shortcuts from the running session. KGlobalaccel is just a very prominent example, there are further DBus interaction problems without a dedicated DBus session.
|
||||
|
||||
## DRM platform
|
||||
|
||||
The nested setup only works for the X11 and Wayland platform plugins. Changes in the DRM platform plugin or libinput cannot be tested in a nested setup. To test these, change to a tty, login and start kwin_wayland with the same command as for nested. KWin automatically picks the DRM platform as neither DISPLAY nor WAYLAND_DISPLAY environment variables should be defined.
|
||||
|
||||
## KWin/X11
|
||||
|
||||
KWin for the X11 windowing system cannot be tested with a nested Wayland setup. Instead the common way is to run KWin and replace the existing window manager of the X session:
|
||||
|
||||
cd build
|
||||
cd bin
|
||||
QT_PLUGIN_PATH=`pwd` ./kwin_x11 --replace
|
||||
|
||||
In this case also the current DBus session should be used and dbus-run-session should not be used. Of course it's only possible to start kwin_x11 in an X session. On Wayland kwin_x11 will refuse to start.
|
||||
|
||||
### Xephyr
|
||||
|
||||
It is possible to run kwin_x11 in a Xephyr window, but this is rather limited and especially the OpenGL compositor cannot really be tested. For X11 it's better to replace the running session. On Wayland using Xephyr is better than nothing.
|
||||
|
||||
## Containers
|
||||
While it is possible to run KWin through container technologies such as docker this is not recommended. KWin needs to interact with the actual hardware such as the OpenGL drivers, input devices, etc. Getting this setup is possible, but complicated. With containers one can only achieve a nested setup and this requires passing through the socket of the host's windowing system, device files for graphics stack, etc.
|
||||
|
||||
# Attaching a debugger
|
||||
|
||||
Debugging KWin is challenging as KWin is drawing the screen. If you gdb into a running kwin_x11 or kwin_wayland from your current session, it's probably the last thing you'll do in the session. The session hard locks the moment the debugger is attached to the process. Due to that never attach a debugger from your running session.
|
||||
|
||||
It is possible to attach gdb from another tty, but that is only a solution for X11. On Wayland one would not be able to switch back to the tty once a breakpoint is hit as KWin is responsible for tty switching.
|
||||
|
||||
Overall the only sensible solution for attaching gdb is from another system through ssh.
|
||||
|
||||
## Better ways of debugging
|
||||
As attaching gdb to a running session is not a satisfying solution it is better to run nested KWin Wayland in gdb. E.g.
|
||||
|
||||
cd build
|
||||
cd bin
|
||||
QT_PLUGIN_PATH=`pwd` dbus-run-session gdb --args ./kwin_wayland --xwayland --socket=wayland-1
|
||||
|
||||
Another solution is using KWin's extensive test suite and run the appropriate test binary through gdb.
|
||||
|
||||
# Automatic tests
|
||||
KWin's test suite is explained in document [TESTING](TESTING.md).
|
||||
|
||||
# Contributing patches
|
||||
|
||||
KWin uses [KDE's phabricator instance](https://phabricator.kde.org) for code review. Patches can be uploaded automatically using the tool arcanist. A possible workflow could look like:
|
||||
|
||||
git checkout -b my-feature-branch
|
||||
git add ...
|
||||
git commit
|
||||
arc diff
|
||||
|
||||
More complete documentation can be found in [KDE's wiki](https://community.kde.org/Infrastructure/Phabricator). Please add "#KWin" as reviewers. Please run KWin's automated test suite prior to uploading a patch to ensure that the change does not break existing code.
|
||||
|
||||
# Coding conventions
|
||||
KWin's coding conventions are explained in document [coding-conventions.md](doc/coding-conventions.md).
|
||||
|
||||
# Coding style
|
||||
KWin code follows the [Frameworks coding style](https://techbase.kde.org/Policies/Frameworks_Coding_Style).
|
||||
Loading…
Reference in New Issue