|
|
|
@@ -5,21 +5,134 @@ Or on our [Discord server].
|
|
|
|
|
|
|
|
|
|
dwl is a compact, hackable compositor for [Wayland] based on [wlroots]. It is
|
|
|
|
|
intended to fill the same space in the Wayland world that dwm does in X11,
|
|
|
|
|
primarily in terms of functionality, and secondarily in terms of philosophy.
|
|
|
|
|
Like dwm, dwl is:
|
|
|
|
|
primarily in terms of functionality, and secondarily in terms of
|
|
|
|
|
philosophy. Like dwm, dwl is:
|
|
|
|
|
|
|
|
|
|
- Easy to understand, hack on, and extend with patches
|
|
|
|
|
- One C source file (or a very small number) configurable via `config.h`
|
|
|
|
|
- Tied to as few external dependencies as possible
|
|
|
|
|
|
|
|
|
|
## Getting Started:
|
|
|
|
|
|
|
|
|
|
### **dwl branch 0.7 and releases based upon 0.7 build against [wlroots] 0.18**
|
|
|
|
|
|
|
|
|
|
### Latest semi-stable [release]
|
|
|
|
|
This is probably where you want to start. This builds against the dependent
|
|
|
|
|
packages' versions currently shipping in major distributions. If your
|
|
|
|
|
distribution's wlroots version is older, use an earlier dwl [release] or [0.x
|
|
|
|
|
branch].
|
|
|
|
|
|
|
|
|
|
### Development branch [main]
|
|
|
|
|
Active development progresses on the `main` branch. The `main` branch is built
|
|
|
|
|
against a late (and often changing) git commit of wlroots. While the adventurous
|
|
|
|
|
are welcome to use `main`, it is a rocky road. Using `main` requires that the
|
|
|
|
|
user be willing to chase git commits of wlroots. Testing development pull
|
|
|
|
|
requests may involve merging unmerged pull requests in [wlroots]' git repository
|
|
|
|
|
and/or git commits of wayland.
|
|
|
|
|
|
|
|
|
|
### Building dwl
|
|
|
|
|
dwl has the following dependencies:
|
|
|
|
|
- libinput
|
|
|
|
|
- wayland
|
|
|
|
|
- wlroots (compiled with the libinput backend)
|
|
|
|
|
- xkbcommon
|
|
|
|
|
- wayland-protocols (compile-time only)
|
|
|
|
|
- pkg-config (compile-time only)
|
|
|
|
|
|
|
|
|
|
dwl has the following additional dependencies if XWayland support is enabled:
|
|
|
|
|
- libxcb
|
|
|
|
|
- libxcb-wm
|
|
|
|
|
- wlroots (compiled with X11 support)
|
|
|
|
|
- Xwayland (runtime only)
|
|
|
|
|
|
|
|
|
|
Install these (and their `-devel` versions if your distro has separate
|
|
|
|
|
development packages) and run `make`. If you wish to build against a released
|
|
|
|
|
version of wlroots (*you probably do*), use a [release] or a [0.x branch]. If
|
|
|
|
|
you want to use the unstable development `main` branch, you need to use the git
|
|
|
|
|
version of [wlroots].
|
|
|
|
|
|
|
|
|
|
To enable XWayland, you should uncomment its flags in `config.mk`.
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
All configuration is done by editing `config.h` and recompiling, in the same
|
|
|
|
|
manner as dwm. There is no way to separately restart the window manager in
|
|
|
|
|
Wayland without restarting the entire display server, so any changes will take
|
|
|
|
|
effect the next time dwl is executed.
|
|
|
|
|
|
|
|
|
|
As in the dwm community, we encourage users to share patches they have
|
|
|
|
|
created. Check out the [dwl-patches] repository!
|
|
|
|
|
|
|
|
|
|
## Running dwl
|
|
|
|
|
|
|
|
|
|
dwl can be run on any of the backends supported by wlroots. This means you can
|
|
|
|
|
run it as a separate window inside either an X11 or Wayland session, as well as
|
|
|
|
|
directly from a VT console. Depending on your distro's setup, you may need to
|
|
|
|
|
add your user to the `video` and `input` groups before you can run dwl on a
|
|
|
|
|
VT. If you are using `elogind` or `systemd-logind` you need to install polkit;
|
|
|
|
|
otherwise you need to add yourself in the `seat` group and enable/start the
|
|
|
|
|
seatd daemon.
|
|
|
|
|
|
|
|
|
|
When dwl is run with no arguments, it will launch the server and begin handling
|
|
|
|
|
any shortcuts configured in `config.h`. There is no status bar or other
|
|
|
|
|
decoration initially; these are instead clients that can be run within the
|
|
|
|
|
Wayland session. Do note that the default background color is black. This can be
|
|
|
|
|
modified in `config.h`.
|
|
|
|
|
|
|
|
|
|
If you would like to run a script or command automatically at startup, you can
|
|
|
|
|
specify the command using the `-s` option. This command will be executed as a
|
|
|
|
|
shell command using `/bin/sh -c`. It serves a similar function to `.xinitrc`,
|
|
|
|
|
but differs in that the display server will not shut down when this process
|
|
|
|
|
terminates. Instead, dwl will send this process a SIGTERM at shutdown and wait
|
|
|
|
|
for it to terminate (if it hasn't already). This makes it ideal for execing into
|
|
|
|
|
a user service manager like [s6], [anopa], [runit], [dinit], or [`systemd
|
|
|
|
|
--user`].
|
|
|
|
|
|
|
|
|
|
Note: The `-s` command is run as a *child process* of dwl, which means that it
|
|
|
|
|
does not have the ability to affect the environment of dwl or of any processes
|
|
|
|
|
that it spawns. If you need to set environment variables that affect the entire
|
|
|
|
|
dwl session, these must be set prior to running dwl. For example, Wayland
|
|
|
|
|
requires a valid `XDG_RUNTIME_DIR`, which is usually set up by a session manager
|
|
|
|
|
such as `elogind` or `systemd-logind`. If your system doesn't do this
|
|
|
|
|
automatically, you will need to configure it prior to launching `dwl`, e.g.:
|
|
|
|
|
|
|
|
|
|
export XDG_RUNTIME_DIR=/tmp/xdg-runtime-$(id -u)
|
|
|
|
|
mkdir -p $XDG_RUNTIME_DIR
|
|
|
|
|
dwl
|
|
|
|
|
|
|
|
|
|
### Status information
|
|
|
|
|
|
|
|
|
|
Information about selected layouts, current window title, app-id, and
|
|
|
|
|
selected/occupied/urgent tags is written to the stdin of the `-s` command (see
|
|
|
|
|
the `printstatus()` function for details). This information can be used to
|
|
|
|
|
populate an external status bar with a script that parses the
|
|
|
|
|
information. Failing to read this information will cause dwl to block, so if you
|
|
|
|
|
do want to run a startup command that does not consume the status information,
|
|
|
|
|
you can close standard input with the `<&-` shell redirection, for example:
|
|
|
|
|
|
|
|
|
|
dwl -s 'foot --server <&-'
|
|
|
|
|
|
|
|
|
|
If your startup command is a shell script, you can achieve the same inside the
|
|
|
|
|
script with the line
|
|
|
|
|
|
|
|
|
|
exec <&-
|
|
|
|
|
|
|
|
|
|
To get a list of status bars that work with dwl consult our [wiki].
|
|
|
|
|
|
|
|
|
|
## Replacements for X applications
|
|
|
|
|
|
|
|
|
|
You can find a [list of useful resources on our wiki].
|
|
|
|
|
|
|
|
|
|
## Background
|
|
|
|
|
|
|
|
|
|
dwl is not meant to provide every feature under the sun. Instead, like dwm, it
|
|
|
|
|
sticks to features which are necessary, simple, and straightforward to implement
|
|
|
|
|
given the base on which it is built. Implemented default features are:
|
|
|
|
|
|
|
|
|
|
- Any features provided by dwm/Xlib: simple window borders, tags, keybindings,
|
|
|
|
|
client rules, mouse move/resize. Providing a built-in status bar is an
|
|
|
|
|
exception to this goal, to avoid dependencies on font rendering and/or
|
|
|
|
|
drawing libraries when an external bar could work well.
|
|
|
|
|
exception to this goal, to avoid dependencies on font rendering and/or drawing
|
|
|
|
|
libraries when an external bar could work well.
|
|
|
|
|
- Configurable multi-monitor layout support, including position and rotation
|
|
|
|
|
- Configurable HiDPI/multi-DPI support
|
|
|
|
|
- Idle-inhibit protocol which lets applications such as mpv disable idle
|
|
|
|
@@ -53,100 +166,6 @@ Feature *non-goals* for the main codebase include:
|
|
|
|
|
be done through the compositor
|
|
|
|
|
- Animations and visual effects
|
|
|
|
|
|
|
|
|
|
## Building dwl
|
|
|
|
|
|
|
|
|
|
dwl has the following dependencies:
|
|
|
|
|
```
|
|
|
|
|
libinput
|
|
|
|
|
wayland
|
|
|
|
|
wlroots (compiled with the libinput backend)
|
|
|
|
|
xkbcommon
|
|
|
|
|
wayland-protocols (compile-time only)
|
|
|
|
|
pkg-config (compile-time only)
|
|
|
|
|
```
|
|
|
|
|
If you enable X11 support:
|
|
|
|
|
```
|
|
|
|
|
libxcb
|
|
|
|
|
libxcb-wm
|
|
|
|
|
wlroots (compiled with X11 support)
|
|
|
|
|
Xwayland (runtime only)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Simply install these (and their `-devel` versions if your distro has separate
|
|
|
|
|
development packages) and run `make`. If you wish to build against a Git
|
|
|
|
|
version of wlroots, check out the [wlroots-next branch].
|
|
|
|
|
|
|
|
|
|
To enable XWayland, you should uncomment its flags in `config.mk`.
|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
All configuration is done by editing `config.h` and recompiling, in the same
|
|
|
|
|
manner as dwm. There is no way to separately restart the window manager in
|
|
|
|
|
Wayland without restarting the entire display server, so any changes will take
|
|
|
|
|
effect the next time dwl is executed.
|
|
|
|
|
|
|
|
|
|
As in the dwm community, we encourage users to share patches they have created.
|
|
|
|
|
Check out the dwl [patches repository]!
|
|
|
|
|
|
|
|
|
|
## Running dwl
|
|
|
|
|
|
|
|
|
|
dwl can be run on any of the backends supported by wlroots. This means you can
|
|
|
|
|
run it as a separate window inside either an X11 or Wayland session, as well
|
|
|
|
|
as directly from a VT console. Depending on your distro's setup, you may need
|
|
|
|
|
to add your user to the `video` and `input` groups before you can run dwl on
|
|
|
|
|
a VT. If you are using `elogind` or `systemd-logind` you need to install
|
|
|
|
|
polkit; otherwise you need to add yourself in the `seat` group and
|
|
|
|
|
enable/start the seatd daemon.
|
|
|
|
|
|
|
|
|
|
When dwl is run with no arguments, it will launch the server and begin handling
|
|
|
|
|
any shortcuts configured in `config.h`. There is no status bar or other
|
|
|
|
|
decoration initially; these are instead clients that can be run within
|
|
|
|
|
the Wayland session.
|
|
|
|
|
Do note that the background color is black.
|
|
|
|
|
|
|
|
|
|
If you would like to run a script or command automatically at startup, you can
|
|
|
|
|
specify the command using the `-s` option. This command will be executed as a
|
|
|
|
|
shell command using `/bin/sh -c`. It serves a similar function to `.xinitrc`,
|
|
|
|
|
but differs in that the display server will not shut down when this process
|
|
|
|
|
terminates. Instead, dwl will send this process a SIGTERM at shutdown and wait
|
|
|
|
|
for it to terminate (if it hasn't already). This makes it ideal for execing into
|
|
|
|
|
a user service manager like [s6], [anopa], [runit], [dinit], or [`systemd --user`].
|
|
|
|
|
|
|
|
|
|
Note: The `-s` command is run as a *child process* of dwl, which means that it
|
|
|
|
|
does not have the ability to affect the environment of dwl or of any processes
|
|
|
|
|
that it spawns. If you need to set environment variables that affect the entire
|
|
|
|
|
dwl session, these must be set prior to running dwl. For example, Wayland
|
|
|
|
|
requires a valid `XDG_RUNTIME_DIR`, which is usually set up by a session manager
|
|
|
|
|
such as `elogind` or `systemd-logind`. If your system doesn't do this
|
|
|
|
|
automatically, you will need to configure it prior to launching `dwl`, e.g.:
|
|
|
|
|
|
|
|
|
|
export XDG_RUNTIME_DIR=/tmp/xdg-runtime-$(id -u)
|
|
|
|
|
mkdir -p $XDG_RUNTIME_DIR
|
|
|
|
|
dwl
|
|
|
|
|
|
|
|
|
|
### Status information
|
|
|
|
|
|
|
|
|
|
Information about selected layouts, current window title, app-id, and
|
|
|
|
|
selected/occupied/urgent tags is written to the stdin of the `-s` command (see
|
|
|
|
|
the `printstatus()` function for details). This information can be used to
|
|
|
|
|
populate an external status bar with a script that parses the information.
|
|
|
|
|
Failing to read this information will cause dwl to block, so if you do want to
|
|
|
|
|
run a startup command that does not consume the status information, you can
|
|
|
|
|
close standard input with the `<&-` shell redirection, for example:
|
|
|
|
|
|
|
|
|
|
dwl -s 'foot --server <&-'
|
|
|
|
|
|
|
|
|
|
If your startup command is a shell script, you can achieve the same inside the
|
|
|
|
|
script with the line
|
|
|
|
|
|
|
|
|
|
exec <&-
|
|
|
|
|
|
|
|
|
|
To get a list of status bars that work with dwl consult our [wiki].
|
|
|
|
|
|
|
|
|
|
## Replacements for X applications
|
|
|
|
|
|
|
|
|
|
You can find a [list of useful resources on our wiki].
|
|
|
|
|
|
|
|
|
|
## Acknowledgements
|
|
|
|
|
|
|
|
|
|
dwl began by extending the TinyWL example provided (CC0) by the sway/wlroots
|
|
|
|
@@ -164,17 +183,19 @@ inspiration, and to the various contributors to the project, including:
|
|
|
|
|
- Stivvo for output management and fullscreen support, and patch maintenance
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[Discord server]: https://discord.gg/jJxZnrGPWN
|
|
|
|
|
[#dwl on Libera Chat]: https://web.libera.chat/?channels=#dwl
|
|
|
|
|
[Wayland]: https://wayland.freedesktop.org/
|
|
|
|
|
[wlroots]: https://gitlab.freedesktop.org/wlroots/wlroots/
|
|
|
|
|
[wlroots-next branch]: https://codeberg.org/dwl/dwl/src/branch/wlroots-next
|
|
|
|
|
[patches repository]: https://codeberg.org/dwl/dwl-patches
|
|
|
|
|
[s6]: https://skarnet.org/software/s6/
|
|
|
|
|
[anopa]: https://jjacky.com/anopa/
|
|
|
|
|
[runit]: http://smarden.org/runit/faq.html#userservices
|
|
|
|
|
[dinit]: https://davmac.org/projects/dinit/
|
|
|
|
|
[`systemd --user`]: https://wiki.archlinux.org/title/Systemd/User
|
|
|
|
|
[#dwl on Libera Chat]: https://web.libera.chat/?channels=#dwl
|
|
|
|
|
[0.7-rc1]: https://codeberg.org/dwl/dwl/releases/tag/v0.7-rc1
|
|
|
|
|
[0.x branch]: https://codeberg.org/dwl/dwl/branches
|
|
|
|
|
[anopa]: https://jjacky.com/anopa/
|
|
|
|
|
[dinit]: https://davmac.org/projects/dinit/
|
|
|
|
|
[dwl-patches]: https://codeberg.org/dwl/dwl-patches
|
|
|
|
|
[list of useful resources on our wiki]: https://codeberg.org/dwl/dwl/wiki/Home#migrating-from-x
|
|
|
|
|
[main]: https://codeberg.org/dwl/dwl/src/branch/main
|
|
|
|
|
[release]: https://codeberg.org/dwl/dwl/releases
|
|
|
|
|
[runit]: http://smarden.org/runit/faq.html#userservices
|
|
|
|
|
[s6]: https://skarnet.org/software/s6/
|
|
|
|
|
[wlroots]: https://gitlab.freedesktop.org/wlroots/wlroots/
|
|
|
|
|
[wiki]: https://codeberg.org/dwl/dwl/wiki/Home#compatible-status-bars
|
|
|
|
|
[list of useful resources on our wiki]:
|
|
|
|
|
https://codeberg.org/dwl/dwl/wiki/Home#migrating-from-x
|
|
|
|
|
[Discord server]: https://discord.gg/jJxZnrGPWN
|
|
|
|
|
[Wayland]: https://wayland.freedesktop.org/
|
|
|
|
|
Nikita Ivanov