Work in progress: Developing Wayland extension protocols for Mir servers

Developing Wayland extension protocols for Mir servers

With the Mir 1.2 release I promised:

we have made it possible for a shell developed with Mir to add its own extensions… I’ll be following up with a worked example of this process."

In the course of developing the example I came across a number of “bumps in the road” where it was unnecessarily difficult and have been fixing them in Mir. Most of the fixes have landed on Mir “master”, but while working on this I found that it was possible to extend the mirtest-dev package to make it very easy to test the extensions in a downstream shell. The last piece of that work has just been merged.

I’ll be looking towards releasing an update to Mir that contains these improvements. (There’s some other work near completion we may want to include, but there won’t be a long delay.)

The worked example

The first thing I needed was a downstream shell that plausibly needed an extension writing. I’m sure it will come as no surprise that I chose egmde as the example server. For the extension protocol I chose “primary selection”. While a protocol that allows every application to “spy” on the clipboard may not meet the security criteria we use for Mir in IoT, for a desktop environment like egmde it is a great convenience.

The changes to egmde can be seen in this pull request. I’ll discuss these in more detail below, but for those that want to follow along the following setup is needed to build the code.

The following Mir packages are needed:

sudo apt install libmiral-dev mir-graphics-drivers-desktop
sudo apt install libmirwayland-dev mirtest-dev wlcs

The libmirwayland-dev provides the tooling needed to implement the protocol in Mir while mirtest-dev and wlcs provide the testing framework.

At the time of writing, the version of Mir I’m using is not yet in any of the Mir PPAs but it will be uploaded to “Latest Integration Build” and available in a couple of hours. To add that PPA:

sudo add-apt-repository --update ppa:mir-team/dev

wlcs tests for primary selection

In parallel with this work I’ve proposed adding some “primary selection” tests to wlcs. These too are currently only available when built from source. Here’s an example of what the tests look like:

TEST_F(PrimarySelection, source_sees_request)
    MockPrimarySelectionSourceListener  source_listener{source_app.source};
    PrimarySelectionOfferListener       offer_listener;
    StubPrimarySelectionDeviceListener  device_listener{sink_app.device, offer_listener};
    ASSERT_THAT(device_listener.selected, NotNull());

    EXPECT_CALL(source_listener, send(_, _, _))
        .WillRepeatedly(Invoke([&](auto*, auto*, int fd) { close(fd); }));

    Pipe pipe;
    zwp_primary_selection_offer_v1_receive(device_listener.selected, any_mime_type, pipe.source);

Implementing a protocol extension

The first step in implementing a protocol extension is to use the protocol generator from the libmirwayland-dev package, I’ve added two directories to egmde: wayland-protocols and wayland-generated. The first of these contains a copy of the protocol definition, the second the generated files and the cmake script to generate them. Only the latter is worth reproducing here:

set(PROTOCOL "primary-selection-unstable-v1")
set(PROTOCOL_FILE "${CMAKE_CURRENT_SOURCE_DIR}/../wayland-protocols/${PROTOCOL}.xml")
set(GENERATE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/primary-selection-unstable-v1_wrapper")

    COMMAND "sh" "-c" "mir_wayland_generator zwp_ ${PROTOCOL_FILE} header >${GENERATE_FILE}.h"
    COMMAND "sh" "-c" "mir_wayland_generator zwp_ ${PROTOCOL_FILE} source >${GENERATE_FILE}.cpp"


The generator cannot implement the semantics of the protocol: it just provides the “hooks” into which to write the code. The latter can be found in a couple of files egprimary_selection_device_controller.cpp and primary_selection.cpp (this is only split this way as a lot of logic can be shared with gtk_primary_selection.)

All these generated and and-written files are combined into a static library that is used both by egmde and by a new module that provides the wlcs test fixture for egmde.

wlcs test fixture

To run wlcs tests requires a “test fixture” that allows the test executable to load and control the compositor. Mir makes it very easy to implement a fixture: here is the entire “fixture” code for egmde:

#include "primary_selection.h"
#include "gtk_primary_selection.h"

#include <miral/wayland_extensions.h>
#include <miral/test_wlcs_display_server.h>

struct TestWlcsDisplayServer : miral::TestWlcsDisplayServer
    miral::WaylandExtensions wayland_extensions;

    TestWlcsDisplayServer(int argc, char const** argv) :
        miral::TestWlcsDisplayServer{argc, argv}

WlcsExtensionDescriptor const extensions[] = {
    {"wl_compositor",               4},
    {"wl_shm",                      1},
    {"wl_data_device_manager",      3},
    {"wl_shell",                    1},
    {"wl_seat",                     6},
    {"wl_output",                   3},
    {"wl_subcompositor",            1},
    {"xdg_wm_base",                 1},
    {"zxdg_shell_unstable_v6",      1},
    {"wlr_layer_shell_unstable_v1", 1},
    {"zwp_primary_selection_device_manager_v1", 1},
    {"gtk_primary_selection_device_manager", 1},

WlcsIntegrationDescriptor const descriptor{
    sizeof(extensions) / sizeof(extensions[0]),

WlcsIntegrationDescriptor const* get_descriptor(WlcsDisplayServer const* /*server*/)
    return &descriptor;

WlcsDisplayServer* wlcs_create_server(int argc, char const** argv)
    auto server = new TestWlcsDisplayServer(argc, argv);

    server->get_descriptor = &get_descriptor;
    return server;

void wlcs_destroy_server(WlcsDisplayServer* server)
    delete static_cast<TestWlcsDisplayServer*>(server);

extern WlcsServerIntegration const wlcs_server_integration {

Running the tests

With all this in place, we just need to run our updated wlcs with the egmde test fixture:

$ cmake-build-debug/wlcs ../egmde/cmake-build-debug/ --gtest_filter=Prim*
Note: Google Test filter = Prim*
[==========] Running 5 tests from 1 test case.
[----------] Global test environment set-up.
[----------] 5 tests from PrimarySelection
[ RUN      ] PrimarySelection.source_can_offer
[       OK ] PrimarySelection.source_can_offer (9 ms)
[ RUN      ] PrimarySelection.sink_can_listen
[       OK ] PrimarySelection.sink_can_listen (8 ms)
[ RUN      ] PrimarySelection.sink_can_request
[       OK ] PrimarySelection.sink_can_request (11 ms)
[ RUN      ] PrimarySelection.source_sees_request
[       OK ] PrimarySelection.source_sees_request (9 ms)
[ RUN      ] PrimarySelection.source_can_supply_request
[       OK ] PrimarySelection.source_can_supply_request (8 ms)
[----------] 5 tests from PrimarySelection (45 ms total)

[----------] Global test environment tear-down
[==========] 5 tests from 1 test cases run. (45ms total elapsed)
[  PASSED  ] 5 tests

The real world

I’ve not (yet) found a client toolkit that uses “zwp_primary_selection_device_manager_v1”, so I’ve yet to check whether this works with real applications. But the principle steps of this article remain valid even if there are errors in the implementation of this protocol.