Build WebKit/WPE on Linux/X11

There’s a lot of documentation online about building Webkit/WPE on Linux. But as most instructions are targetting embedded platforms developers, the focus is on building Webkit with Wayland using the flatpak-sdk to automate and speed up the building process. As the steps I’ve followed to build it on my X11 system and run the Webkit/WPE MiniBrowser on a nested Weston were a bit different from the recommended ones I thought that a blog post about them might be useful to people trying to build WPE/Webkit in platforms lacking Wayland, flatpak, systemd, and modern Desktop Environments like the latest KDE and GNOME.

Be careful though: this is not the recommended way to build WebKit/WPE, only the alternative steps I’ve followed in my personal computer until I have access to a building machine! If you are not sure about what you want to do with WebKit/WPE please take a look at the recommended wiki instructions before you follow mine!

My system

I am using Debian without systemd (but I use systemd-shim for the apps that strongly require systemd). I also use X11 and the openbox window manager for the graphics apps. This means that many broadly used Gnome or KDE libraries are missing from my system which also lacks support for Wayland.

Fortunatelly WPE supports many backends, and Weston, the Wayland compositing window manager, can run on top of X (like Xephyr, XNest) allowing hardware accelerated rendering too, and so I can still use the OpenGL drivers I am using under X11 if I run it nested. 😀

Also, systemd is not a strong requirement to build WebKit. CMake has an option to disable it (although if you use systemd-shim you don’t need to do so), and only when you build WebKit/WPE using flatpak-sdk and its default options ENABLE_SYSTEMD might be set by default.

Below are the steps I’ve followed to build Webkit/WPE and some prerequisites libraries and tools on this Debian/X11/NestedWeston system I’ve just described.

Environment setup:

This is a step I’ve followed to be able to debug the WebKit/WPE low level graphics code. It can be skipped if you don’t use mesa drivers and don’t need to debug EGL and OpenGL (ES) code.

My setup: I tend to install the mesa drivers in a custom directory /home/eleni/igalia/install, whose tree is something like that:

As most libraries are part of mesa, maintaining this tree isn’t hard, and I can link any program I need to debug with my compiled version of EGL, GLES, etc to have a better picture of GPU-code related errors.

I’ve used the following script to setup my debug environment before building WebKit/WPE, and made sure that everytime I build a prerequisite library that requires a graphics API from mesa, I replace the system include and library paths with my $HOME/igalia/install include and library paths.

You can ignore the last comments unless if you need to use WebKit with Vulkan (I don’t know if it has a working Vulkan backend yet): in that case radeon_icd.x86_64.json should be replaced with your vendor’s.

Other useful tips to debug graphics are to set the OpenGL ES version to the one you need to debug or change the GLSL with mesa environment variables from here: https://docs.mesa3d.org/envvars.html. This might be handy if you need to debug the WebGL implementation for example.

Requirement #1: libwpe

I cloned libwpe from github:

Things I’ve changed:

I’ve set the CMAKE_BUILD_TYPE to Debug, the CMAKE_INSTALL_PREFIX to my local installation directory (where I’ve also built mesa because I want to be able to fully debug OpenGL) and is /home/eleni/igalia/install.

Then I left CMake autodetect LIBXKBCOMMON_LIBRARY that was installed system wide.

Because I prefer to use my own custom mesa debug build when I am debugging OpenGL (see environment setup) I’ve also changed the EGL paths to point to my local mesa installation paths (that can be done from ccmake in Advanced Mode but it’s definitely not required).

I’ve built libwpe running make -j8 install inside the build directory (I could have used Ninja too if I had used the -G Ninja option in CMake).

About the backend: according to the wiki instructions it doesn’t need to be set as WPEBackend-default will be dynamically loaded. I left it empty and I didn’t have any problem.

Requirement #2: WPEBackend-fdo

I cloned WPEBackend-fdo from Igalia‘s repository:
git clone git@github.com:Igalia/WPEBackend-fdo.git

Before building it I’ve set the PKG_CONFIG_PATH to point at the pkgconfig directory that contains the libwpe .pc file. If you have installed it in some of the default system directories you can ignore this step, for me it was something like:

export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/home/eleni/igalia/install/lib/pkgconfig.

Then I called:

and ran ninja -C build (-j8) install to compile it and install it in my custom installation path ( /home/eleni/igalia/install).

Requirement #3: Weston

In order to run Webkit/WPE under X11, Weston needs to be installed in the system. Weston can run nested and use X11 for compositing. On Debian-based systems you only need to run apt-get install weston on a terminal.

If you don’t use systemd, you might need to add your user in weston-launch group to have permissions to launch Weston apps.

I launched weston-terminal to check if hardware acceleration and the OpenGL and Vulkan drivers I’ve build myself are enabled by running glxinfo and vulkaninfo respectively.

Note that everytime you start weston or a Weston client you must set the XDG_RUNTIME_DIR (it’s the directory where Weston stores its socket files).

I set it to /tmp.

Build WebKit/WPE

After having installed the prerequisite libraries (I believe building them under Wayland would be quite similar), it was time to build WebKit itself. I didn’t follow the exact steps described here because I realized that some errors caused by my system missing many standard packages were bypassed when I was building WebKit with flatpak and so I prefered to use CMake to be able to debug the installation myself. I don’t recommend to use CMake over flatpak but to use CMake in case you face problems when you build it in a non-standard system!

The first time I’ve built Webkit/WPE, I used the flatpak-sdk for the Tools dependencies but this is not absolutely necessary if you use CMake. You will be warned if something is missing anyway!

I checked out the code:

Then I installed the dependencies:

I had to make a few changes for this script to run without errors on Debian Unstable, which I describe in this bug report: https://bugs.webkit.org/show_bug.cgi?id=221254:

• Renamed python-psutil to python3-psutil
• Added libegl-mesa0 to dependencies as it’s required by libegl1-mesa-dev.

(This complex bug fix was my first WebKit patch! :’D, thanks Adrian for the review!).

After that I’ve also ran:

following the recommended instructions.

What I had to do differently was this step for the reason I explained:

so I’ve replaced this step with my next:

Build WebKit using CMake:

Before I started my CMake build, I made a small change in one of my CMakeLists.txt files. It was necessary because I’ve built the FDO backend myself and the version wasn’t set properly (version string was empty). I don’t know if I could have done something differently to fix it as I’ve followed the recommended steps from WPE wiki to build WPEBackend-fdo. Maybe version is set in Release builds only. In any case, it looks more like a local configuration problem than a CMake one and I didn’t investigate it further.

In Webkit/Tools/wpe/backends/CMakeLists.txt I replaced:

then I created a build directory, entered it and ran ccmake ...

I’ve changed:
the CMAKE_BUILD_TYPE to DEBUG
the CMAKE_INSTALL_PREFIX to $HOME/igalia/install
all include and library paths I considered necessary (for example the paths of libEGL.so, and EGL include directory) to my local ones in $HOME/igalia/install

and!
The include directories of the dependencies! It seems that $HOME/igalia/install/include is not the correct path for libwpe and WPEBackend-fdo and I had to set the following paths:

I also enabled -DCMAKE_EXPORT_COMPILE_COMMANDS=YES to be able to use ccls with vim and navigate the huge codebase until I become more familiar with it… 😀

Then I ran ninja -j <as many as I had> -C build install waited about one day and was ready! 😀 (Ok, that sounded scary but it was my first time. Now I’m using tricks to speed up WebKit/WPE build, thanks to my colleagues help, and there are more tips to speed it up when building it using the flatpak-sdk. Also I am going to use a more powerful machine in the future…)

Run WPE MiniBrowser on Weston

Next step was again from WebKit/WPE wiki. I’ve used the recommended script to run MiniBrowser to test WebKit/WPE on top of X11, after I’ve set the XDG_RUNTIME_DIR to /tmp:

The command was:

One can also run:

to run the mini browser with another website.

And finally, this is how WebKit/WPE MiniBrowser looks like when it’s running on top of my nested Weston:

I’ve opened a terminal next to it and ran glxinfo to check which OpenGL drivers are used by MiniBrowser. That git part in the OpenGL version string indicates that the drivers used are the ones I’ve built myself in my custom installation directory.

Run WPE MiniBrowser on X11

If you don’t need to debug any wayland-specific code you can also run MiniBrowser under X11 using:

and the result will be the same. Have fun! 🙂

Links

[1]: Official WebKit website
[2]: WebKit/WPE wiki
[3]: Igalia’s browsers team
[4]: Freedesktop.org (for more info about Weston and graphics APIs).