Cagebreak: A Wayland Tiling Compositor Inspired by Ratpoison
Cagebreak provides a ratpoison-inspired, cage-based, tiling Wayland compositor.
$USER/.config/cagebreak/config
pacman -R cagebreak
On Arch Linux, use the AUR PKGBUILDs:
See cagebreak-pkgbuild for details.
You may check out other distros here:
There are different ways to obtain cagebreak source:
There are ways to verify that you obtained the correct source (See keys/
and CONTRIBUTING):
Cagebreak uses the meson build system.
Cagebreak is developed against the latest tag of wlroots, so as not to constantly chase breaking changes.
Execute the following commands to build Cagebreak:
$ meson setup build -Dxwayland=true -Dman-pages=true --buildtype=release
$ ninja -C build
Remove -Dman-pages=true
to disable man page generation.
To generate man pages, make sure that you have scdoc installed.
To obtain a debug build, remove --buildtype=release
.
The release build is reproducible under conditions outlined in CONTRIBUTING.
To build Cagebreak without XWayland support, remove -Dxwayland=true
.
To use XWayland make sure that your version of wlroots is compiled with XWayland support.
You'll need to have XWayland installed for XWayland support to work.
$ ./build/cagebreak
If you run Cagebreak within an existing X11 or Wayland session, it will open in a virtual output as a window in your existing session.
If you run it in a TTY, it'll run with the KMS+DRM backend.
Note that a configuration file is required. For more configuration options, see the man pages.
Please see example_scripts/
for a basis to customize from.
Cagebreak was built to suit the needs of its creators. This outlines how we intended some parts of cagebreak and might ease learning how to use cagebreak a little bit. Please note that this does not replace the man pages or the FAQ. Also, this is not intended as a guide on how cagebreak must be used but as a source of inspiration and explanation for certain particularities.
Cagebreak is keyboard-based. Everything regarding cagebreak can be done through the keyboard and it is our view that it should be. This does not mean that pointers, touchpads and such are not available for the few applications that do require them.
Cagebreak is a tiling compositor. Every view takes up as much screen space as possible. We believe this is useful, as only very few programs are typically necessary to complete a task. To manage multiple tasks concurrently, we use workspaces.
Each task deserves its own workspace. Any given task (the sort of thing you might find in your calendar or on your todo list) probably requires very few views and ideally, these take up as much of the screen as possible.
Combining 2. and 3. might look like this in practice:
- Task 1: Edit introduction section for paper on X
- Task 2: Coordinate event with person Y
- split screen vertically
- open web browser or pdf viewer to read literature
- focus next
- open editor
- change to a different workspace
- split screen vertically
- open calendar application
- focus next
- open chat application
Now each task has its own workspace and switching between tasks is possible by switching between workspaces.
Note that, for example by using the socket, more advanced setups are possible. But the user is warned that excessive tweaking eats into the work to be done.
In practice this means thinking about the applications and cagebreak commands you use and taking your keyboard layout into account when defining keybindings for your individual needs.
Example scripts can be found in the repository under
example_scripts/
.
Cagebreak plans to do or keep doing the following things in the future:
Cagebreak is managed by project-repo.
Consider project-repo a single benevolent dictator for life that happens to occupy at least two brains.
Project-repo is a pseudonym of at least two individuals acting as benevolent dictators for the project by the others mutual consent.
The individuals comprising project-repo are not otherwise associated by payment from any organisation or grant.
Use SECURITY.md to contact project-repo.
There are members of project-repo and those who are not.
There are no specific roles forced unto anyone.
The current bus factor for Cagebreak is: 1
The Bus Factor is a measure of how many people have to be incapacitated for a project to be unable to continue.
Project-repo could react to issues (even confidential e-mails) and fix easier issues if any one individual were incapacitated.
However, not all aspects of the code or release engineering are fully resilient to the loss of any one individual.
We strive to increase the bus factor to at least 2 in all aspects.
Open an issue is you find something.
See SECURITY.md for other means of contacting the Cagebreak authors and security issues.
Fixed bugs are assigned a number and summarized in Bugs.md for future reference.
Copyright (c) 2020-2024 The Cagebreak authors Copyright (c) 2018-2020 Jente Hidskes Copyright (c) 2019 The Sway authors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.