update README
it's time
This commit is contained in:
Devin J. Pohly
parent
275badc707
commit
b7a21478d6
117
README.md
117
README.md
|
|
@ -1,50 +1,99 @@
|
||||||
# dwl
|
# dwl - dwm for Wayland
|
||||||
|
|
||||||
This is the "minimum viable product" Wayland compositor based on wlroots. It
|
dwl is a compact, hackable compositor for Wayland based on
|
||||||
aims to implement a Wayland compositor in the fewest lines of code possible,
|
[wlroots](https://github.com/swaywm/wlroots). It is intended to fill the same
|
||||||
while still supporting a reasonable set of features. Reading this code is the
|
space in the Wayland world that dwm does in X11, primarily in terms of
|
||||||
best starting point for anyone looking to build their own Wayland compositor
|
philosophy, and secondarily in terms of functionality. Like dwm, dwl is:
|
||||||
based on wlroots.
|
|
||||||
|
- Easy to understand, hack on, and extend with patches
|
||||||
|
- One C source file (or a very small number) configurable via `config.h`
|
||||||
|
- Limited to a maximum number of SLOC (to be determined)
|
||||||
|
- Tied to as few external dependencies as possible
|
||||||
|
|
||||||
|
|
||||||
|
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. Since wlroots provides a number
|
||||||
|
of features that are more complicated to accomplish with Xlib and select
|
||||||
|
extensions, dwl can be in some ways more featureful than dwm *while remaining
|
||||||
|
just as simple.* Intended default features are:
|
||||||
|
|
||||||
|
- Any features provided by dwm/Xlib: simple window borders, tags, keybindings,
|
||||||
|
client rules, mouse move/resize (see below for why the built-in status bar is
|
||||||
|
a possible exception)
|
||||||
|
- Configurable multi-monitor layout support, including position and rotation
|
||||||
|
- Configurable HiDPI/multi-DPI support
|
||||||
|
- Wayland protocols needed for daily life in the tiling world: at a minimum,
|
||||||
|
xdg-shell and layer-shell (for bars/menus). Protocols trivially provided by
|
||||||
|
wlroots may also be added.
|
||||||
|
- Basic yes/no damage tracking to avoid needless redraws (if it can be done
|
||||||
|
simply and has an impact on power consumption)
|
||||||
|
|
||||||
|
|
||||||
|
Other features under consideration are:
|
||||||
|
|
||||||
|
- Additional Wayland compositor protocols which are trivially provided by
|
||||||
|
wlroots or can be conditionally included via `config.h` settings: xwayland,
|
||||||
|
xdg-portal, etc.
|
||||||
|
- External bar support instead of a built-in status bar, to avoid taking a
|
||||||
|
dependency on FreeType or Pango
|
||||||
|
- More in-depth damage region tracking
|
||||||
|
|
||||||
|
|
||||||
## Building dwl
|
## Building dwl
|
||||||
|
|
||||||
dwl is disconnected from the main wlroots build system, in order to make it
|
dwl has only two dependencies: wlroots and wayland-protocols. Simply install
|
||||||
easier to understand the build requirements for your own Wayland compositors.
|
these and run `make`.
|
||||||
Simply install the dependencies:
|
|
||||||
|
|
||||||
- wlroots
|
|
||||||
- wayland-protocols
|
|
||||||
|
|
||||||
And run `make`.
|
## 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.
|
||||||
|
|
||||||
|
|
||||||
## Running dwl
|
## Running dwl
|
||||||
|
|
||||||
You can run dwl with `./dwl`. In an existing Wayland or X11 session,
|
dwl can be run as-is, with no arguments. In an existing Wayland or X11 session,
|
||||||
dwl will open a Wayland or X11 window respectively to act as a virtual
|
this will open a window to act as a virtual display. When run from a TTY, the
|
||||||
display. You can then open Wayland windows by setting `WAYLAND_DISPLAY` to the
|
Wayland server will take over the entire virtual terminal. Clients started by
|
||||||
value shown in the logs. You can also run `./dwl` from a TTY.
|
dwl will have `WAYLAND_DISPLAY` set in their environment, and other clients can be
|
||||||
|
started from outside the session by setting this variable accordingly.
|
||||||
|
|
||||||
In either case, you will likely want to specify `-s [cmd]` to run a command at
|
You can also specify a startup program using the `-s` option. The argument to
|
||||||
startup, such as a terminal emulator. This will be necessary to start any new
|
this option will be run at startup as a shell command (using `sh -c`) and can
|
||||||
programs from within the compositor, as dwl does not support any custom
|
serve a similar function to `.xinitrc`: starting a service manager or other
|
||||||
keybindings. dwl supports the following keybindings:
|
startup applications. Unlike `.xinitrc`, the display server will not shut down
|
||||||
|
when this process terminates. Instead, as dwl is shutting down, it will send
|
||||||
- `Alt+Escape`: Terminate the compositor
|
this process a SIGTERM and wait for it to terminate (if it hasn't already).
|
||||||
- `Alt+F1`: Cycle between windows
|
This make it ideal not only for initialization but also for execing into a
|
||||||
|
user-level service manager like s6 or `systemd --user`.
|
||||||
|
|
||||||
|
|
||||||
## Limitations
|
## Known limitations and issues
|
||||||
|
|
||||||
Notable omissions from dwl:
|
dwl is a work in progress, and it has not yet reached its feature goals in a
|
||||||
|
number of ways:
|
||||||
|
|
||||||
- HiDPI support
|
- Urgent/attention/focus-request not yet implemented
|
||||||
- Any kind of configuration, e.g. output layout
|
- Borders and selected/normal/urgent colors not implemented
|
||||||
- Any protocol other than xdg-shell (e.g. layer-shell, for
|
- No support for layer-shell yet
|
||||||
panels/taskbars/etc; or Xwayland, for proxied X11 windows)
|
- HiDPI works, but multi-DPI is not as nice as sway, depending on the scale
|
||||||
- Optional protocols, e.g. screen capture, primary selection, virtual
|
factors involved. Perhaps scaling filters are needed?
|
||||||
keyboard, etc. Most of these are plug-and-play with wlroots, but they're
|
- Monitor rotation/transform is not working yet
|
||||||
omitted for brevity.
|
- Mouse resize is not precise
|
||||||
- Damage tracking, which tracks which parts of the screen are changing and
|
- No statusbar
|
||||||
minimizes redraws accordingly.
|
- No damage tracking
|
||||||
|
- No handling of fullscreen/fixed windows (or whatever the Wayland analogues
|
||||||
|
are)
|
||||||
|
|
||||||
|
|
||||||
|
## Acknowledgements
|
||||||
|
|
||||||
|
dwl began by extending the TinyWL example provided (CC0) by the sway/wlroots
|
||||||
|
developers. This was made possible in many cases by looking at how sway
|
||||||
|
accomplished something, then trying to do the same in as suckless a way as
|
||||||
|
possible. Speaking of which, many thanks to suckless.org and the dwm
|
||||||
|
developers and community for the inspiration.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue