yukijoou/kwin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: modernise HACKING -> CONTRIBUTING guidelines and information

Browse source
This commit is contained in:
Jan Blackquill 2021-08-31 22:10:58 +00:00 committed by David Edmundson
parent 0b74aa62c9
commit f6005a28cd
4 changed files with 129 additions and 101 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

125
CONTRIBUTING.md Normal file
View file

@ -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).

98
HACKING.md
View file

@ -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).

7
README.md
View file

@ -9,6 +9,10 @@ KWin is an easy to use, but flexible, composited Window Manager for Xorg windowi
* a minimalistic window manager
* designed for use without compositing or for X11 network transparency, though both are possible.
# Contributing to KWin
Please refer to the [contributing document](CONTRIBUTING.md) for everything you need to know to get started contributing to KWin.
# Contacting KWin development team
* mailing list: [kwin@kde.org](https://mail.kde.org/mailman/listinfo/kwin)
@ -25,9 +29,6 @@ Please contact the support channels of your Linux distribution for user support.
Please use [KDE's bugtracker](https://bugs.kde.org) and report for [product KWin](https://bugs.kde.org/enter_bug.cgi?product=kwin).
# Developing on KWin
Please refer to [hacking documentation](HACKING.md) for how to build and start KWin. Further information about KWin's test suite can be found in [TESTING.md](TESTING.md).
## Guidelines for new features
A new Feature can only be added to KWin if:

0
TESTING.md → doc/TESTING.md
View file