dotfiles

my shiny new dotfiles
git clone git://git.jakekoroman.com/dotfiles
Log | Files | Refs | README

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