Posted on

Introducing a virtual framebuffer Wayland server in KWayland

The next KDE framework release will include a small addition in KWayland which will make it much easier to run auto tests for Wayland based applications. KWayland now installs a small virtual framebuffer test server into libexec directory.

This means it’s an application inspired by Xvfb which allows to run a graphical application with a virtual framebuffer. The new tool is the same for Wayland. KWayland makes testing already quite easy, but we noticed that we don’t have a good setup for the case that we want to test an application which uses QtWayland QPA plugin as that is not possible with the test support so far in KWayland.

The idea behind the server is that every test gets it’s own dedicated test Wayland server. The test Wayland server will start the test and terminate itself once the test finished (either successful, failure or crash). All output from the test – including exit code – is forwarded, which makes integration into a ctest based system really easy.

In fact if you use CMake as a build system to define your tests, this becomes super easy:

find_package(KF5Wayland CONFIG)
add_executable(myTest myTest.cpp)
target_link_libraries(myTest Qt5::Gui Qt5::Test)
kwaylandtest(myTest)

This also allows to run the same test on X11 and on Wayland. Assuming the test is meant for build.kde.org which has an Xvfb running during the test phase, one can add the test the normal way (X11) and just add the kwaylandtest in addition. So the test will run on both windowing systems.

Now this is a really new project and the test server is still rather limited. All it does is faking rendering at 60 Hz. Otherwise it’s still limited and does not provide the functionality of e.g. a window manager on X11. In that regard it’s also inspired by Xvfb which doesn’t support that. I plan to extend this as I have need in the tests I’m going to add for it.

Speaking of that: the first test case making use of this new infrastructure is already pushed.

Posted on

KWayland joined KDE Frameworks

The current release 5.22 of KDE Frameworks gained a new framework: KWayland. So far KWayland got released together with Plasma. KWayland entered as tier 1/integration and is only available on Linux (and other Linux-like systems).

For us working on the Wayland stack in Plasma and KDE this is a very important step. Now we can use KWayland also in other frameworks. Also with KWayland in frameworks we expose it to a larger audience. We hope that it is a useful framework for anyone using Wayland with Qt. It’s not a replacement for QtWayland, rather an addition and way more flexible by being closer to the Wayland API.

This change is also important for distributions. Please note that this is only a logical move in the project structure. KWayland 5.22 is fully ABI compatible to the last release 5.6. You can just exchange the KWayland from Plasma with the one in frameworks. Plasma 5.6 of course works perfectly fine with KWayland 5.22.

Posted on

Running frameworks powered applications on Wayland

After I got KWindowSystem to no longer require X11 on Linux I dared to start some of our applications which got ported to frameworks 5 with the magic “-platform wayland” command line switch. And look there: they started and were useable. But there were some obvious problems: e.g. our platform integration plugin was not loaded. But with a small change to Qt 5.3 this problem is solved. Now if you run a Wayland compositor in a KDE session you will get the KDE integration as one would expect. But this just openend a new set of problems: our default QStyle (Oxygen) was crashing any application on startup as it was still assuming that it’s on X11 if compiled with X11 support. Easy enough to fix and now Oxygen works as one would expect.

This experience highlighted an obvious problem: our applications will crash if they are compiled with X11 support and do not perform a runtime check. So I started to hunt down possible crashers in our libraries. In the perfect world there should not be any X11 specific code in the libraries (except KWindowSystems). And luckily our libraries supported non-X11 platforms for quite some time, so all the X specific code should be in HAVE_X11 blocks. So a small reminder for everybody who thinks that we should never have supported Windows in the first place: thanks to Windows support most of our applications just work on Wayland. Have a look at this nice collection of applications which are running just fine on Wayland:

Aus Weston

Right now we have reached a state where I am no longer able to crash applications at random and most applications which I give a try just work. We had a few problems in kde4support which prevented any applications which still used K(Unique)Application to start at all on Wayland and that framework had stronger usage of HAVE_X11 than I expected. Although the framework is deprecated I fixed all the issues I could find in it, to get applications to support Wayland faster. Basically if your application compiles on frameworks it will run on Wayland out of the box. Also thanks to that work our applications will just work on any proprietary windowing system (so no need to be upset that we put more work on e.g. Windows support than on your small pet project). My personal aim is to have Wayland support at least on par with Windows support in our first release of frameworks. Later on we will improve it to get it on the same level as X11 support.

Of course it’s possible that I haven’t spotten all crashes in the libraries yet. And I encourage our application developers to test their applications on Wayland. That’s quite simple in fact: just start Weston (can be nested in the X session) and prepare the setup:

source kf5_env.sh # your kf5 environment variables setup script
unset DISPLAY # to make sure that any XOpenDisplay call will fail
export WAYLAND_DISPLAY=wayland-0 # adjust to whatever you used in Weston

Now all you need is to pass “-platform wayland” to the command line args to start your application on Weston. In case you are using a KApplication and KCmdLineArgs you need to use “--platform wayland” instead. Update: as an alternative one can also export the environment variable “QT_QPA_PLATFORM” and set it to “wayland”. If you run into any problems with it, feel free to ping me on IRC. In case you get your application to crash in one of the frameworks and it’s a crash due to using X11, please report a bug and set me on CC. In case you hit a crash in your application there is a very easy pattern to solve the problem:

#if HAVE_X11
if (QX11Info::isPlatformX11()) {
    // do your X specific calls here
}
#endif

If you are not using QX11Info you can also do:

#if HAVE_X11
if (QGuiApplication::platformName() == QStringLiteral("xcb")) {
    // do your X specific calls here
}
#endif

As you can see it’s performing a string comparison so you don’t want to have that in a code path which gets called often. Recommendation: move it into a member variable which gets initialized only once in app life cycle and also ifdef the variable – no need to do these checks on e.g. Windows. If you have any questions with it, feel free to ask me.

In the workspace module I hit a few crashers in modules which make absolutely no sense on non-X11. The code is too X specific and most likely needs a complete rewrite if we want to have it on non-X11. Of course we don’t want to have modules which just crash in systemsettings. So I introduced a new method to KService to check whether the plugin makes sense on the current Qt platform. This is honored by ::noDisplay() so systemsettings (and also kcmshell5) won’t pick them. To specify one can use e.g.

X-KDE-OnlyShowOnQtPlatforms=xcb

in the plugin’s desktop file. There’s also a “X-KDE-NotShowOnQtPlatforms”.

Posted on

KWindowSystem in Frameworks 5

KWindowSystem is a tier 1 framework which allows to interact with the windowing system. Historically it provided an implementation of NETWM on X11. It provides a NETRootInfo for accessing the global state (all that’s set on the root window) and NETWinInfo for all information about a specific window. The classes have a window manager and client perspective. This is the foundation which powers our window manager and various parts of the desktop shell such as the taskmanager.

On top of those X11-specific classes we have a convenient API KWindowInfo and KWindowSystem which provides a windowing system independent API for our applications. Thus we have different implementations depending of the platform it’s compiled on. On X11 the implementation depends on named NET* classes, on Windows and Mac what makes sense is implemented using the platform specific API.

In the good old days of Qt 4 this was a sufficient solution. If it’s build on unix-like systems we have X11 and we know it’s X11, on Windows it’s Windows and so on. With Qt 5 this no longer works. Just because we built with X11 support doesn’t mean the software will run on X11. Due to the introduction of the QPA it’s possible that another platform is used – most obvious Wayland. But there are more platforms for Linux like Android. With the solution from Qt 4 our applications would just crash as soon as they access KWindowSystem as that tries to interact with XLib/xcb unconditionally.

Over the last weeks I spent quite some time on making sure that KWindowSystem works as expected (that is doing nothing at the moment) when run on Wayland. Just adding a new implementation as in the Qt 4 days is no solution as we want our framework to support both X11 and Wayland at the same time. Otherwise our distributions would have a hard time packaging our software. The approach was to introduce an internal abstraction in KWindowInfo and KWindowSystem and have a platform implementation. This is now done for X11 together with a dummy implementation which is used as a fallback if we do not have an implementation for the currently used windowing system (e.g. Wayland). Unfortunately this has a side-effect: it broke the backend for Windows and MacOS. I don’t feel very happy about it as I don’t like to break the work of others, but I cannot fix it. Windows and MacOS are proprietary systems for which either a license or even specific hardware is required. I do hope that the specific teams will re-add the support till the release of frameworks 5. Please note: at the time of writing this blog post not all patches are merged yet.

A nice side-effect for this work was that I started to write unit tests for KWindowInfo on X11. This is far from trivial as it interacts with X11 and the running window manager. And the test kind of depends on the used window manager. Obviously given that it’s KDE it would make sense to write the test against KWin, but that’s not sufficient for our CI system as kwindowsystem is a dependency of KWin and thus kwindowsystem cannot depend on KWin (not even on runtime). Thus the tests are now performed against openbox on the CI system, but also succeed when running against KWin. They are quite a stress test for a window manager and found one very unlikely crash condition in KWin (of course already fixed).

The framework provides more functionality which is kind of X11 specific. For example there is the KSelectionOwner and KSelectionWatcher which implements a manager selection as described in ICCCM, section 2.8. Again a very important building block for our window manager. While it’s clearly X11 specific code which only gets built if X11 is available, there is no reason to crash if it’s not run on X11. So I went through all of our sources and tried to make sure that it correctly checks whether the runtime platform is xcb. Thus we don’t have to change all applications using it, but can rely on the library not to crash. Still if your application is using these X11 specific functionality I highly recommend to check for the platform as you might run into runtime errors. E.g. claiming a manager selection will fail, don’t rely on it.

As all of this is kind of a requirement to running frameworks based applications on Wayland, I have to do the obligatory screenshot of Kate on Weston:

Aus Weston
Posted on

Generating test coverage for a framework

Over the last week I was trying to add unit tests to some rather old piece of code in frameworks. Of course I wanted to know how good this test is and looked into how one can generate test coverage for our tests. As I consider this as rather useful I thought to share the steps.

For generating the test coverage I used gcov which is part of gcc. So nothing to do there. As a frontend I decided for lcov as that can generate some nice html views. On debian based systems it is proved by package lcov.

Let’s assume that we have a standard framework with:

  • framework/autotests
  • framework/src
  • framework/tests

The first step to enable test coverage is to modify the CMakeLists.txt. There is the possibility to switch to CMAKE_BUILD_TYPE “Coverage”, but that would require building all of frameworks with it. Interesting for the CI system, but maybe not for just developing one unit test.

In your framework toplevel CMakeLists.txt add the following definition:

add_definitions(-fprofile-arcs -ftest-coverage)

And also adjust the linking of each of your targets:

target_link_libraries(targetName -fprofile-arcs -ftest-coverage)

Remember to not commit those changes 😉

Now recompile the framework, go the build directory of your framework and run:

make test

This generates the basic coverage data which you can now process with lcov run from your build directory:

lcov --capture --directory ./ --output-file coverage.info

And last step is to generate the html output:

genhtml coverage.info --output-directory /path/to/generated/pages

Open your favorite web browser and load index.html in the specified path and enjoy.