███████╗██╗    ██╗███╗   ███╗

     ██╔════╝██║    ██║████╗ ████║

     ███████╗██║ █╗ ██║██╔████╔██║

     ╚════██║██║███╗██║██║╚██╔╝██║

     ███████║╚███╔███╔╝██║ ╚═╝ ██║

     ╚══════╝ ╚══╝╚══╝ ╚═╝     ╚═╝

          simple window manager

swm is a dynamic tiling Wayland compositor based on wlroots. It began as a

fork of dwl[0], replacing dwl's dwm-style window-management policy with one

inspired by spectrwm[1].

swm is configured in C and aims to remain small enough to understand, modify,

and extend. It supports native Wayland clients, X11 clients through Xwayland,

multiple outputs, global workspaces, server-side decorations, layer-shell

panels and launchers, session locking, idle inhibition, input methods, and

the standard wlroots output-management, screencopy, data-control,

foreign-toplevel, and toplevel image-capture protocols.

# REQUIREMENTS

Building swm requires:

* C compiler that supports C23, and lld

* GNU or BSD make

* pkg-config

* asciidoctor (man page)

* wlroots 0.20

* wayland and wayland-protocols

* libinput and xkbcommon

* libxcb and xcb-icccm

Xwayland is optional at runtime. Without it, swm continues to run but cannot

manage X11 applications. The default configuration uses these runtime commands:

* `foot` for the terminal, also started when swm starts

* `fuzzel` for the application launcher

* `swaylock` for screen locking

* `wpctl` for audio volume and mute controls

* `brightnessctl` for display and keyboard backlight controls

* `playerctl` for media playback controls

Install the commands for the features you use, or change them in `config.h`

and rebuild swm. The corresponding bindings require these commands to work.

# BUILD AND CONFIGURATION

    make

On the first build, `config.def.h` is copied to `config.h`. Subsequent builds,

including forced builds, preserve `config.h`. Edit that file to configure

appearance, input, monitor rules, application rules, layouts, commands,

autostart programs, and bindings, then rebuild swm.

There is no runtime configuration file. To return to the distributed defaults,

remove `config.h` and rebuild; save any local configuration first.

The compiler, installation prefix, version, and wlroots include/library flags

can be overridden in `config.mk` or on the make command line. In particular,

`WLR_INCS` and `WLR_LIBS` can point at a separately built wlroots tree.

# INSTALL

The default prefix is `/usr/local`:

    sudo make install

This installs the executable, `swm(1)` manual page, and Wayland session entry.

Use `PREFIX` and `DESTDIR` to change or stage the installation, for example:

    make PREFIX=/usr DESTDIR="$pkgdir" install

To remove the same installed files:

    sudo make uninstall

# RUN

Start `swm` from a TTY, select it in a display manager, or run it nested inside

another Wayland session. `XDG_RUNTIME_DIR` must be set.

    swm [--socket name] [-s command]

The `--socket` option selects the Wayland display socket name. swm creates the

socket after the display backend starts. Without this option, swm selects an

available socket name. The `-s` flag starts a command through `/bin/sh`; when

swm exits it terminates that command's process group. Programs listed in the

`autostart` array in `config.h` are started independently. Set

`SWM_NO_AUTOSTART=1` to suppress that array, which is useful for testing or a

minimal session.

swm sets `WAYLAND_DISPLAY`, `DISPLAY` when Xwayland is available, and

`XDG_CURRENT_DESKTOP=swm` for programs it starts.

# USAGE

The defaults use Super as Mod and provide ten global workspaces. A workspace can

appear on only one output; selecting one already visible elsewhere swaps the

two outputs' workspaces. Each workspace keeps its own layout state. Available

layouts place the master area on the left, top, right, or bottom, plus a max

layout. Floating and fullscreen are independent of the selected layout.

See `man swm` for the full set of key bindings.

# BARS AND STATUS

swm has no built-in bar. A layer-shell bar such as Waybar[2] can use the

`ext/workspaces` module, backed by swm's ext-workspace-v1 implementation. Each

output has its own workspace group, so the active button identifies the

workspace shown on that output. Empty inactive workspaces are advertised as

hidden; occupied workspaces remain visible. See `swmctl(1)` for workspace

metadata and Waybar integration.

On each state change swm also writes line-oriented status records to standard

output. When `-s` is used, that output is connected to the startup command's

standard input. Workspace metadata uses `workspace N title VALUE` and

`workspace N color #RRGGBBAA` records; empty values mean unset. Use

`swmctl events --filter=active-window` to receive the active window title for

a custom bar module.

`swmctl window regions` prints visible window rectangles in the format accepted

by `slurp -r`.

# TESTING AND DEVELOPMENT

Run the complete test suite with:

    make test

Make builds one focused C unit-test binary and a test compositor, then the

Python runner executes them alongside native Wayland and XWayland clients,

including a two-output run. Unchanged binaries are reused; use the narrower

targets while developing:

    make test-unit

    make test-integration

Coverage is informational and has its own target:

    make coverage

Generated test files live under `test/.build/`; remove them with

`make test-clean`. All targets require Python 3 and the normal build

dependencies. Integration tests additionally require PyWayland and its protocol

scanner, xcffib, wlr-randr, and Xwayland; coverage requires LLVM's coverage

tools.

Other development targets are:

    make man       # build swm.1 from swm.1.adoc

    make fmt       # format tracked C sources with clang-format

    make analyze   # rebuild under scan-build

    make clean

# LICENSE

swm inherits code and design from dwl, dwm, spectrwm, sway, and TinyWL. See

`LICENSE` and the `LICENSE.*` files for the applicable terms and attribution.

[0]: https://codeberg.org/dwl/dwl

[1]: https://github.com/conformal/spectrwm

[2]: https://github.com/Alexays/Waybar