protocols/
test/
.clang-format
571 B
.clangd
365 B
.gitignore
82 B
.gitsigners
91 B
LICENSE
32.3 KiB
LICENSE.dwl
34.9 KiB
LICENSE.dwm
2.0 KiB
LICENSE.spectrwm
1.3 KiB
LICENSE.sway
1.0 KiB
LICENSE.tinywl
7.0 KiB
Makefile
7.8 KiB
PKGBUILD
952 B
README
5.6 KiB
config.def.h
15.7 KiB
config.mk
269 B
swm.1.adoc
3.3 KiB
swm.c
246.5 KiB
swm.desktop
81 B
swm.h
3.5 KiB
swmctl.1.adoc
2.5 KiB
swmctl.c
19.6 KiB
util.c
2.2 KiB
util.h
399 B
README
raw
| 1 | |
| 2 | |
| 3 | |
| 4 | ███████╗██╗ ██╗███╗ ███╗ |
| 5 | ██╔════╝██║ ██║████╗ ████║ |
| 6 | ███████╗██║ █╗ ██║██╔████╔██║ |
| 7 | ╚════██║██║███╗██║██║╚██╔╝██║ |
| 8 | ███████║╚███╔███╔╝██║ ╚═╝ ██║ |
| 9 | ╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝ |
| 10 | simple window manager |
| 11 | |
| 12 | |
| 13 | swm is a dynamic tiling Wayland compositor based on wlroots. It began as a |
| 14 | fork of dwl[0], replacing dwl's dwm-style window-management policy with one |
| 15 | inspired by spectrwm[1]. |
| 16 | |
| 17 | swm is configured in C and aims to remain small enough to understand, modify, |
| 18 | and extend. It supports native Wayland clients, X11 clients through Xwayland, |
| 19 | multiple outputs, global workspaces, server-side decorations, layer-shell |
| 20 | panels and launchers, session locking, idle inhibition, input methods, and |
| 21 | the standard wlroots output-management, screencopy, data-control, |
| 22 | foreign-toplevel, and toplevel image-capture protocols. |
| 23 | |
| 24 | |
| 25 | # REQUIREMENTS |
| 26 | |
| 27 | Building swm requires: |
| 28 | |
| 29 | * C compiler that supports C23, and lld |
| 30 | * GNU or BSD make |
| 31 | * pkg-config |
| 32 | * asciidoctor (man page) |
| 33 | * wlroots 0.20 |
| 34 | * wayland and wayland-protocols |
| 35 | * libinput and xkbcommon |
| 36 | * libxcb and xcb-icccm |
| 37 | |
| 38 | Xwayland is optional at runtime. Without it, swm continues to run but cannot |
| 39 | manage X11 applications. The default configuration also expects `foot` and |
| 40 | `wmenu-run`; change these commands in `config.h` if they are not installed. |
| 41 | |
| 42 | |
| 43 | # BUILD AND CONFIGURATION |
| 44 | |
| 45 | make |
| 46 | |
| 47 | On the first build, `config.def.h` is copied to `config.h`. Subsequent builds, |
| 48 | including forced builds, preserve `config.h`. Edit that file to configure |
| 49 | appearance, input, monitor rules, application rules, layouts, commands, |
| 50 | autostart programs, and bindings, then rebuild swm. |
| 51 | |
| 52 | There is no runtime configuration file. To return to the distributed defaults, |
| 53 | remove `config.h` and rebuild; save any local configuration first. |
| 54 | |
| 55 | The compiler, installation prefix, version, and wlroots include/library flags |
| 56 | can be overridden in `config.mk` or on the make command line. In particular, |
| 57 | `WLR_INCS` and `WLR_LIBS` can point at a separately built wlroots tree. |
| 58 | |
| 59 | |
| 60 | # INSTALL |
| 61 | |
| 62 | The default prefix is `/usr/local`: |
| 63 | |
| 64 | sudo make install |
| 65 | |
| 66 | This installs the executable, `swm(1)` manual page, and Wayland session entry. |
| 67 | Use `PREFIX` and `DESTDIR` to change or stage the installation, for example: |
| 68 | |
| 69 | make PREFIX=/usr DESTDIR="$pkgdir" install |
| 70 | |
| 71 | To remove the same installed files: |
| 72 | |
| 73 | sudo make uninstall |
| 74 | |
| 75 | |
| 76 | # RUN |
| 77 | |
| 78 | Start `swm` from a TTY, select it in a display manager, or run it nested inside |
| 79 | another Wayland session. `XDG_RUNTIME_DIR` must be set. |
| 80 | |
| 81 | swm [-s command] |
| 82 | |
| 83 | The `-s` flag starts a command through `/bin/sh`; when swm exits it terminates |
| 84 | that command's process group. Programs listed in the `autostart` array in |
| 85 | `config.h` are started independently. Set `SWM_NO_AUTOSTART=1` to suppress that |
| 86 | array, which is useful for testing or a minimal session. |
| 87 | |
| 88 | swm sets `WAYLAND_DISPLAY`, `DISPLAY` when Xwayland is available, and |
| 89 | `XDG_CURRENT_DESKTOP=swm` for programs it starts. |
| 90 | |
| 91 | |
| 92 | # USAGE |
| 93 | |
| 94 | The defaults use Alt as Mod and provide ten global workspaces. A workspace can |
| 95 | appear on only one output; selecting one already visible elsewhere swaps the |
| 96 | two outputs' workspaces. Each workspace keeps its own layout state. Available |
| 97 | layouts place the master area on the left, top, right, or bottom, plus a max |
| 98 | layout. Floating and fullscreen are independent of the selected layout. |
| 99 | |
| 100 | See `man swm` for the full set of key bindings. |
| 101 | |
| 102 | |
| 103 | # BARS AND STATUS |
| 104 | |
| 105 | swm has no built-in bar. A layer-shell bar such as Waybar[2] can use the |
| 106 | `ext/workspaces` module, backed by swm's ext-workspace-v1 implementation. |
| 107 | Empty inactive workspaces are advertised as hidden; occupied and selected |
| 108 | workspaces remain visible. See `swmctl(1)` for workspace metadata and Waybar |
| 109 | integration. |
| 110 | |
| 111 | On each state change swm also writes line-oriented status records to standard |
| 112 | output. When `-s` is used, that output is connected to the startup command's |
| 113 | standard input. Workspace metadata uses `workspace N title VALUE` and |
| 114 | `workspace N color #RRGGBBAA` records; empty values mean unset. The active window |
| 115 | title is published atomically to |
| 116 | `$XDG_RUNTIME_DIR/swm-title`, which can be consumed by a custom bar module. |
| 117 | Visible window rectangles are published atomically to |
| 118 | `$XDG_RUNTIME_DIR/swm-windows` in the format accepted by `slurp -r`. |
| 119 | |
| 120 | |
| 121 | # TESTING AND DEVELOPMENT |
| 122 | |
| 123 | Run the complete test suite with: |
| 124 | |
| 125 | make test |
| 126 | |
| 127 | Make builds one focused C unit-test binary and a test compositor, then the |
| 128 | Python runner executes them alongside native Wayland and XWayland clients, |
| 129 | including a two-output run. Unchanged binaries are reused; use the narrower |
| 130 | targets while developing: |
| 131 | |
| 132 | make test-unit |
| 133 | make test-integration |
| 134 | |
| 135 | Coverage is informational and has its own target: |
| 136 | |
| 137 | make coverage |
| 138 | |
| 139 | Generated test files live under `test/.build/`; remove them with |
| 140 | `make test-clean`. All targets require Python 3 and the normal build |
| 141 | dependencies. Integration tests additionally require PyWayland and its protocol |
| 142 | scanner, xcffib, wlr-randr, and Xwayland; coverage requires LLVM's coverage |
| 143 | tools. |
| 144 | |
| 145 | Other development targets are: |
| 146 | |
| 147 | make man # build swm.1 from swm.1.adoc |
| 148 | make fmt # format tracked C sources with clang-format |
| 149 | make analyze # rebuild under scan-build |
| 150 | make clean |
| 151 | |
| 152 | |
| 153 | # LICENSE |
| 154 | |
| 155 | swm inherits code and design from dwl, dwm, spectrwm, sway, and TinyWL. See |
| 156 | `LICENSE` and the `LICENSE.*` files for the applicable terms and attribution. |
| 157 | |
| 158 | [0]: https://codeberg.org/dwl/dwl |
| 159 | [1]: https://github.com/conformal/spectrwm |
| 160 | [2]: https://github.com/Alexays/Waybar |