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