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