Contributing and Debugging
PR, code styling and code FAQs are here
For issues, please see the guidelines
xcb stuff, check with your local package provider.
wayland - of course.
yay -S gdb ninja gcc cmake libxcb xcb-proto xcb-util xcb-util-keysyms libxfixes libx11 libxcomposite xorg-xinput libxrender pixman wayland-protocols cairo pango seatd
(If any are missing hmu)
Install the VSCode C/C++ and CMake Tools extensions and use that.
I’ve attached a example/launch.json that you can copy to your .vscode/ folder in the repo root.
With that, you can build in debug, go to the debugging tab and hit
attach and profile in your preferred way.
For all ways, make sure to
sudo make clearto clear any root-owned files. Also, before the first build (or after some updates, possibly)
sudo make config. (If you get any
missing header file "...-protocol.h", you need to
make configwill overwrite wlroots headers in
/usr/, meaning you’ll be unable to build any other wlroots compositor without a wlroots reinstall.
when running Hyprland in Debug mode, the config is
~/.config/hypr/hyprlandd.conf and the logs can be found at
You can use the logs and the GDB debugger, but running Hyprland in debug compile as a driver and using it for a while might give more insight to the more random bugs.
When Hyprland crashes, use
coredumpctl and then
coredumpctl info PID to see
the dump. See the instructions below for more info about
You can also use the amazing command
watch -n 0.1 "cat /tmp/hypr/$(echo HYPRLAND_INSTANCE_SIGNATURE)/hyprland.log | grep -v \"arranged\" | tail -n 40"
for live logs. (replace
hyprlandd for debug builds)
Hyprland can run nested in a window. For that, make sure you did the following:
- built in debug
- removed ALL
exec-once=keywords from your debug config (
- set a resolution and are not using
- made sure no keybinds overlap (use a different mod for your keybinds altogether)
Once you launch, the display will probably be completely garbled. To fix that,
in the parent, do a
hyprctl clients and note the size of the window. Make sure
while opening the terminal to not resize the nested window. Note that resolution
and use it down to the pixel in your
If you segfault in
shadowKeybinds, you probably either are using the same mod
as your parent or resized the window.