Vaxry's blog

weeb codes, :tm:

What is the wlroots rewrite, why, and how's it going?

14 V 2024


My endeavors at rewriting wlroots have become quite a common topic in many parts of the Hyprland spaces online, and I've noticed that a lot of people do not actually understand what it entails, or what it is, and what it's not.

Because of that, I've decided to write a small blogpost detailing the reason, details, and current status of the rewrite.

What are we doing?

Firstly, let's talk about what is actually happening. Clearing the #1 misconception, no, I am not making a library to compete with wlroots. There is no point, and not enough benefit to warrant the issues that come with having a big library.

What I am doing, is effectively rewriting the wlroots modules that Hyprland would rely on, in Hyprland. That is why, so far, there has been no new dependencies, and yet, a lot of the wlroots modules have already been rewritten and are live.

There likely will be a new library for the very low-level abstractions (like drm, kms, libinput) because I'd prefer to keep that away from Hyprland, plus, it might come in handy elsweyr in the future. More on that later.

Why are we doing?

There are many reasons as to why one might want to not use wlroots. Personally, I've always had the thought back in my head about stopping using the library for a few reasons, like for example the multiple times I've spent dozens of hours debugging a single issue only for it to turn out a small typo or a careless mistake that any language would catch at compile time, except for C. Memory safety issues arising from the absolute lack of any documentation whatsoever of wlroots have also been quite the annoyance. Many of the modules are written in C, which makes them prone to memory safety issues, but have a round zero documentation on how to properly use them, and not enough asserts to let the developer know something went wrong.

The development of a display server is very complicated, as they are very broad and complex pieces of software. Mixing a C library with 0 documentation is basically asking for trouble.

I do understand that the developers may not have enough time to write proper docs, (even Simon Ser recently said he'll have to tone down his contributions due to the termination of his contract with SourceHut - I wish you all the best wherever you end up, Simon) but this doesn't change the actual state of the library.

Further reasons could include slow development pace - new wayland features that require changes in wlroots tend to take ages to get merged into wlroots, like for example tearing, where a basically ready MR took 9 months to merge because of 100 "style nits" and 2 actually important remarks, or explicit sync still not being a thing, despite KDE and Gnome having implementations already.

Obviously, the fact that I am banned from contributing to Freedesktop - and by extension wlroots, is another big factor, and probably the one that finally tipped the scales, because I am no longer allowed to participate in discussion or contribute code to wlroots.

I want to emphasize - wlroots is a massive library and a feat unto itself, but it isn't without its flaws, that I believe I can reduce by writing my own implementations. So far, it seems so. New implementations are fixing old, long-standing bugs, introducing two minor oopsies fixed in 20 mins, and we live on.

What's the current status?

First, I need to introduce a bit about how Wayland compositors actually work:

when it comes to the compositor, the first layer is of course the kernel. From the kernel, we get stuff like access to the display via drm, input via libinput, etc.

Using these, we can render onto the display and listen to input devices like mice or keyboards. We'll call this the low-level backend.

Then, we have the "wayland" part, using libwayland, which is the implementation of the protocol. (the "how apps send messages to the server and vice versa") This is the protocol.

Using the protocol, we can write implementations for various protocol specifications that allow us to create a functioning desktop.

Wlroots in general provides modules to all of the above and some more abstractions, (e.g. scene) but Hyprland would only use the above three.

The current status looks as follows:


About 85% of implementations have been rewritten and are in Hyprland. The ones left right now (after #5999 is merged) are parts of the core wayland protocol (like wl_surface, wl_shm or wl_buffer) and wlr_xwayland (for communicating with xwl). After this, no wayland will be handled by wlroots.

The protocol

The protocol implementation does not need to be rewritten. There is no point - it's only the protocol "language". In fact, it's better not to, to keep compatibility with other apps as good as possible.

The Backend

The backend rewrite has not started yet, and is queued for once I am done with all implementations. It will likely end up as a new library in C++.

What are the implications?

For an end-user, there is not much. Basically, you will have a few bugs fixed, and a few new added, like with everything. In the long run, this should lessen the amount of bugs in general, and lead to a much cleaner codebase. (some parts of Hyprland are notoriously convoluted mostly because of wlroots' C and lack of docs)

There should be no fears of "fragmentation", as nothing is becoming fragmented here. Wlroots' wayland protocols are still supported, so apps designed for wlroots compositors will still work (just like most do work on e.g. KDE too) so you can sleep safe with regards to that.

Additionally, I'm aiming for much faster support of important stuff like explicit sync or HDR in Hyprland once the backend library is done - as I am no longer bound to wlroots' mercy for deciding to support these.

How can I help?

The best thing you can do as an end user is test the changes - I often post the MR links on twitter or discord. Running them and reporting any new issues is helpful as we can squash them before the merge or next release. Special thanks to Agent00Ming for doing just that more than anyone else has ever done. They have some patience :D

Another thing is obviously contributing patches and fixes to issues you find - it takes some burden off my shoulders while I spend tons of time writing code. Recently, I've been coding for up to 10-14h a day, and I don't think that's healthy to be honest. I have started taking short gaming breaks recently because I just had to. Brain gets fried. (before you say "haha but your github shows little activity", Github doesn't count activity in MRs, which is most of my activity right now)

Closing thoughts

Although the wlroots rewrite is not necessary by any means - I believe it will ultimately lead to a better product. After all the implementations are rewritten, I also would like to take a week or two cleaning up the codebase of any old, ugly solutions to work around wlroots' limitations or quirky design. Another round of this will probably be made after the new backend library is done.

Ad meliora, finis coronat opus.

Questions, comments, mistakes? Ping me a mail at vaxry [at] and I'll get back to ya.