# Cagebreak

From ArchWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Related articles

- Wayland#Compositors
- Window manager

Cagebreak is a tiling compositor for wayland, based on cage and inspired by ratpoison, which is easily controlled through the keyboard and a unix domain socket.

## Installation

Install cagebreakAUR or cagebreak-binAUR. Alternatively, download a release tarball or clone the repository.

### Optional dependencies

- wl-clipboard for copy/paste capabilities
- xorg-xwayland for allowing Xorg applications to run under cagebreak

## Configuration

The general configuration for cagebreak is located in `$XDG_CONFIG_PATH/cagebreak/config`. This defaults to `~/.config/cagebreak/config`.

Read the configuration man page for detailed information. Note that you can also add configuration by using #Interaction through socket.

An example configuration file may be found on Github.

## Usage

Start cagebreak like any other binary.

### Getting started

The following is an example of how to install and use cagebreak with the configuration file provided on Github.

1. Install `cagebreak` as per #Installation. You should use cagebreak-binAUR unless you have reasons to do otherwise.
2. Copy the example configuration from Github to `$XDG_CONFIG_PATH/cagebreak/config`. Documentation is provided in the configuration man page.
3. Install `xterm` or replace `xterm` with your preferred terminal emulator in the configuration file.
4. Run the following command or add it to `~/.bash_profile` to run cagebreak on login (see #Keyboard layout for explanation):
   - `XKB_DEFAULT_LAYOUT=us cagebreak`
5. Cagebreak should start up and display the terminal emulator you specified above. Press `C-t` `t` to open a new terminal or `C-t` `S` to split the screen. You can also use `Alt-<number>` to switch to the workspace `<number>`. For a full list of available keybindings, read the configuration file and the documentation.
6. If you wish, you may also interact with cagebreak using the unix domain socket. See #Interaction through socket for further information.
7. Also, please file any bugs you may find:
   - Github issue tracker or via email as per the readme for cagebreak
   - AUR comments for the cagebreak-binAUR and cagebreakAUR PKGBUILDs

### Keyboard layout

Set the environment variable `XKB_DEFAULT_LAYOUT` to the desired keyboard layout. See the man page for further information.

### Interaction through socket

On startup, cagebreak opens a unix domain socket through which interaction with the compositor is possible at run-time. The path to this socket is stored in the `CAGEBREAK_SOCKET` environment variable. For example, openbsd-netcat may be invoked with:

    $ nc -U $CAGEBREAK_SOCKET

to send cagebreak any configuration while it is running. The syntax is identical to the syntax of the configuration file.

## See also

1. github
2. github wiki
3. pkgbuild on github

Category:

- Wayland compositors