README.md (8031B)
1 # dwl - dwm for Wayland 2 3 Join us on our IRC channel: [#dwl on Libera Chat] 4 Or on our [Discord server]. 5 6 dwl is a compact, hackable compositor for [Wayland] based on [wlroots]. It is 7 intended to fill the same space in the Wayland world that dwm does in X11, 8 primarily in terms of functionality, and secondarily in terms of philosophy. 9 Like dwm, dwl is: 10 11 - Easy to understand, hack on, and extend with patches 12 - One C source file (or a very small number) configurable via `config.h` 13 - Tied to as few external dependencies as possible 14 15 dwl is not meant to provide every feature under the sun. Instead, like dwm, it 16 sticks to features which are necessary, simple, and straightforward to implement 17 given the base on which it is built. Implemented default features are: 18 19 - Any features provided by dwm/Xlib: simple window borders, tags, keybindings, 20 client rules, mouse move/resize. Providing a built-in status bar is an 21 exception to this goal, to avoid dependencies on font rendering and/or 22 drawing libraries when an external bar could work well. 23 - Configurable multi-monitor layout support, including position and rotation 24 - Configurable HiDPI/multi-DPI support 25 - Idle-inhibit protocol which lets applications such as mpv disable idle 26 monitoring 27 - Provide information to external status bars via stdout/stdin 28 - Urgency hints via xdg-activate protocol 29 - Support screen lockers via ext-session-lock-v1 protocol 30 - Various Wayland protocols 31 - XWayland support as provided by wlroots (can be enabled in `config.mk`) 32 - Zero flickering - Wayland users naturally expect that "every frame is perfect" 33 - Layer shell popups (used by Waybar) 34 - Damage tracking provided by scenegraph API 35 36 Given the Wayland architecture, dwl has to implement features from dwm **and** 37 the xorg-server. Because of this, it is impossible to maintain the original 38 project goal of 2000 SLOC and have a reasonably complete compositor with 39 features comparable to dwm. However, this does not mean that the code will grow 40 indiscriminately. We will try to keep the code as small as possible. 41 42 Features under consideration (possibly as patches) are: 43 44 - Protocols made trivial by wlroots 45 - Implement the text-input and input-method protocols to support IME once ibus 46 implements input-method v2 (see https://github.com/ibus/ibus/pull/2256 and 47 https://codeberg.org/dwl/dwl/pulls/235) 48 49 Feature *non-goals* for the main codebase include: 50 51 - Client-side decoration (any more than is necessary to tell the clients not to) 52 - Client-initiated window management, such as move, resize, and close, which can 53 be done through the compositor 54 - Animations and visual effects 55 56 ## Building dwl 57 58 dwl has the following dependencies: 59 ``` 60 libinput 61 wayland 62 wlroots (compiled with the libinput backend) 63 xkbcommon 64 wayland-protocols (compile-time only) 65 pkg-config (compile-time only) 66 ``` 67 If you enable X11 support: 68 ``` 69 libxcb 70 libxcb-wm 71 wlroots (compiled with X11 support) 72 Xwayland (runtime only) 73 ``` 74 75 Simply install these (and their `-devel` versions if your distro has separate 76 development packages) and run `make`. If you wish to build against a Git 77 version of wlroots, check out the [wlroots-next branch]. 78 79 To enable XWayland, you should uncomment its flags in `config.mk`. 80 81 ## Configuration 82 83 All configuration is done by editing `config.h` and recompiling, in the same 84 manner as dwm. There is no way to separately restart the window manager in 85 Wayland without restarting the entire display server, so any changes will take 86 effect the next time dwl is executed. 87 88 As in the dwm community, we encourage users to share patches they have created. 89 Check out the dwl [patches repository] and [patches wiki]! 90 91 ## Running dwl 92 93 dwl can be run on any of the backends supported by wlroots. This means you can 94 run it as a separate window inside either an X11 or Wayland session, as well 95 as directly from a VT console. Depending on your distro's setup, you may need 96 to add your user to the `video` and `input` groups before you can run dwl on 97 a VT. If you are using `elogind` or `systemd-logind` you need to install 98 polkit; otherwise you need to add yourself in the `seat` group and 99 enable/start the seatd daemon. 100 101 When dwl is run with no arguments, it will launch the server and begin handling 102 any shortcuts configured in `config.h`. There is no status bar or other 103 decoration initially; these are instead clients that can be run within 104 the Wayland session. 105 Do note that the background color is black. 106 107 If you would like to run a script or command automatically at startup, you can 108 specify the command using the `-s` option. This command will be executed as a 109 shell command using `/bin/sh -c`. It serves a similar function to `.xinitrc`, 110 but differs in that the display server will not shut down when this process 111 terminates. Instead, dwl will send this process a SIGTERM at shutdown and wait 112 for it to terminate (if it hasn't already). This makes it ideal for execing into 113 a user service manager like [s6], [anopa], [runit], [dinit], or [`systemd --user`]. 114 115 Note: The `-s` command is run as a *child process* of dwl, which means that it 116 does not have the ability to affect the environment of dwl or of any processes 117 that it spawns. If you need to set environment variables that affect the entire 118 dwl session, these must be set prior to running dwl. For example, Wayland 119 requires a valid `XDG_RUNTIME_DIR`, which is usually set up by a session manager 120 such as `elogind` or `systemd-logind`. If your system doesn't do this 121 automatically, you will need to configure it prior to launching `dwl`, e.g.: 122 123 export XDG_RUNTIME_DIR=/tmp/xdg-runtime-$(id -u) 124 mkdir -p $XDG_RUNTIME_DIR 125 dwl 126 127 ### Status information 128 129 Information about selected layouts, current window title, app-id, and 130 selected/occupied/urgent tags is written to the stdin of the `-s` command (see 131 the `printstatus()` function for details). This information can be used to 132 populate an external status bar with a script that parses the information. 133 Failing to read this information will cause dwl to block, so if you do want to 134 run a startup command that does not consume the status information, you can 135 close standard input with the `<&-` shell redirection, for example: 136 137 dwl -s 'foot --server <&-' 138 139 If your startup command is a shell script, you can achieve the same inside the 140 script with the line 141 142 exec <&- 143 144 To get a list of status bars that work with dwl consult our [wiki]. 145 146 ## Replacements for X applications 147 148 You can find a [list of useful resources on our wiki]. 149 150 ## Acknowledgements 151 152 dwl began by extending the TinyWL example provided (CC0) by the sway/wlroots 153 developers. This was made possible in many cases by looking at how sway 154 accomplished something, then trying to do the same in as suckless a way as 155 possible. 156 157 Many thanks to suckless.org and the dwm developers and community for the 158 inspiration, and to the various contributors to the project, including: 159 160 - **Devin J. Pohly for creating and nurturing the fledgling project** 161 - Alexander Courtis for the XWayland implementation 162 - Guido Cella for the layer-shell protocol implementation, patch maintenance, 163 and for helping to keep the project running 164 - Stivvo for output management and fullscreen support, and patch maintenance 165 166 167 [Discord server]: https://discord.gg/jJxZnrGPWN 168 [#dwl on Libera Chat]: https://web.libera.chat/?channels=#dwl 169 [Wayland]: https://wayland.freedesktop.org/ 170 [wlroots]: https://gitlab.freedesktop.org/wlroots/wlroots/ 171 [wlroots-next branch]: https://codeberg.org/dwl/dwl/src/branch/wlroots-next 172 [patches repository]: https://codeberg.org/dwl/dwl-patches 173 [patches wiki]: https://codeberg.org/dwl/dwl-patches/wiki 174 [s6]: https://skarnet.org/software/s6/ 175 [anopa]: https://jjacky.com/anopa/ 176 [runit]: http://smarden.org/runit/faq.html#userservices 177 [dinit]: https://davmac.org/projects/dinit/ 178 [`systemd --user`]: https://wiki.archlinux.org/title/Systemd/User 179 [wiki]: https://codeberg.org/dwl/dwl/wiki/Home#compatible-status-bars 180 [list of useful resources on our wiki]: 181 https://codeberg.org/dwl/dwl/wiki/Home#migrating-from-x