update README
it's time
This commit is contained in:
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
|
||||
aims to implement a Wayland compositor in the fewest lines of code possible,
|
||||
while still supporting a reasonable set of features. Reading this code is the
|
||||
best starting point for anyone looking to build their own Wayland compositor
|
||||
based on wlroots.
|
||||
dwl is a compact, hackable compositor for Wayland based on
|
||||
[wlroots](https://github.com/swaywm/wlroots). It is intended to fill the same
|
||||
space in the Wayland world that dwm does in X11, primarily in terms of
|
||||
philosophy, and secondarily in terms of functionality. 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`
|
||||
- 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
|
||||
|
||||
dwl is disconnected from the main wlroots build system, in order to make it
|
||||
easier to understand the build requirements for your own Wayland compositors.
|
||||
Simply install the dependencies:
|
||||
dwl has only two dependencies: wlroots and wayland-protocols. Simply install
|
||||
these and run `make`.
|
||||
|
||||
- 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
|
||||
|
||||
You can run dwl with `./dwl`. In an existing Wayland or X11 session,
|
||||
dwl will open a Wayland or X11 window respectively to act as a virtual
|
||||
display. You can then open Wayland windows by setting `WAYLAND_DISPLAY` to the
|
||||
value shown in the logs. You can also run `./dwl` from a TTY.
|
||||
dwl can be run as-is, with no arguments. In an existing Wayland or X11 session,
|
||||
this will open a window to act as a virtual display. When run from a TTY, the
|
||||
Wayland server will take over the entire virtual terminal. Clients started by
|
||||
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
|
||||
startup, such as a terminal emulator. This will be necessary to start any new
|
||||
programs from within the compositor, as dwl does not support any custom
|
||||
keybindings. dwl supports the following keybindings:
|
||||
|
||||
- `Alt+Escape`: Terminate the compositor
|
||||
- `Alt+F1`: Cycle between windows
|
||||
You can also specify a startup program using the `-s` option. The argument to
|
||||
this option will be run at startup as a shell command (using `sh -c`) and can
|
||||
serve a similar function to `.xinitrc`: starting a service manager or other
|
||||
startup applications. Unlike `.xinitrc`, the display server will not shut down
|
||||
when this process terminates. Instead, as dwl is shutting down, it will send
|
||||
this process a SIGTERM and wait for it to terminate (if it hasn't already).
|
||||
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
|
||||
- Any kind of configuration, e.g. output layout
|
||||
- Any protocol other than xdg-shell (e.g. layer-shell, for
|
||||
panels/taskbars/etc; or Xwayland, for proxied X11 windows)
|
||||
- Optional protocols, e.g. screen capture, primary selection, virtual
|
||||
keyboard, etc. Most of these are plug-and-play with wlroots, but they're
|
||||
omitted for brevity.
|
||||
- Damage tracking, which tracks which parts of the screen are changing and
|
||||
minimizes redraws accordingly.
|
||||
- Urgent/attention/focus-request not yet implemented
|
||||
- Borders and selected/normal/urgent colors not implemented
|
||||
- No support for layer-shell yet
|
||||
- HiDPI works, but multi-DPI is not as nice as sway, depending on the scale
|
||||
factors involved. Perhaps scaling filters are needed?
|
||||
- Monitor rotation/transform is not working yet
|
||||
- Mouse resize is not precise
|
||||
- No statusbar
|
||||
- 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 New Issue
Block a user