migueldeoleiros' wiki

Recent notes

See 81 more →

turtile wiki

5 min read

Links: turtile

Build

Dependencies

  • wayland
  • wayland-protocols
  • wlroots-0.18
  • meson
  • ninja
  • gcc
  • cmake
  • pkg-config
  • libxkbcommon
  • libconfig
  • json-c
  • uuid

Steps

1. Clone the Repository

Start by cloning the project repository:

git clone https://github.com/migueldeoleiros/turtile.git
cd turtile

2. Install Dependencies

  • On Arch Linux:

    Arch Linux typically provides the latest versions directly from its repositories:

    sudo pacman -Syu
sudo pacman -S meson ninja gcc cmake pkgconf libxkbcommon libconfig json-c wayland wayland-protocols wlroots

  • On Ubuntu:

    Ubuntu’s repositories may not provide the latest versions of certain libraries. To ensure compatibility, we build some dependencies from source. If you use ubuntu or other debian based distro you can check out the commands in the CI build

3. Configure the Project with Meson

Once dependencies are installed, configure the turtile project:

meson setup build

4. Build the Project

Compile the project:

meson compile -C build

You’ll be left with a turtile and ttcli binaries inside the build directory

Configuration

turtile uses a configuration file written in the libconfig format , which must be explicitly passed to the compositor with the -c [path/to/config.cfg] option. This guide explains each configuration option available and provides examples for customization.

Loading the Configuration

To load a configuration file, start the compositor with the -c flag, followed by the path to the configuration file:

turtile -c path/to/config.cfg

Sample Configuration

The configuration file has several sections that control application behavior, workspace setup, keyboard shortcuts, and appearance.

autostart = (
  "kitty",
  "nautilus",
);
 
workspaces = (
  "main",
  "work",
  "fun",
);
 
keybinds = (
  {mod = [], key = "Escape", cmd = "./build/ttcli exit"},
  {mod = ["alt"], key = "Return", cmd = "kitty"},
 
  {mod = ["alt"], key = "Tab", cmd = "./build/ttcli window cycle"},
  {mod = ["alt"], key = "q", cmd = "./build/ttcli window kill"},
 
  {mod = ["alt"], key = "1", cmd = "./build/ttcli workspace switch main"},
  {mod = ["alt"], key = "2", cmd = "./build/ttcli workspace switch work"},
  {mod = ["alt"], key = "2", cmd = "./build/ttcli workspace switch fun"},
  {mod = ["alt", "shift"], key = "1", cmd = "./build/ttcli window move-to main"},
  {mod = ["alt", "shift"], key = "2", cmd = "./build/ttcli window move-to work"},
  {mod = ["alt", "shift"], key = "3", cmd = "./build/ttcli window move-to fun"},
);
 
background_color = (0.2, 0.2, 0.3);

Configuration Options

autostart

Defines a list of applications to start automatically when the compositor launches.

Format: A list of strings, where each string is the command to launch an application.

autostart = (
  "kitty",
  "nautilus",
);

workspaces

Specifies the names of workspaces that will be available in the compositor. Each name in the list represents a workspace that can be switched to or configured independently.

Format: A list of strings, each representing a workspace name.

workspaces = (
  "main",
  "work",
  "fun",
);

keybinds

Defines keybindings for actions within the compositor, such as switching workspaces or launching applications. Each keybinding specifies a modifier (optional), a key, and a command to execute.

Format: A list of objects, each containing:

  • mod: A list of modifier keys (e.g., mod4 for the “Super” key). Leave empty for no modifier.
  • key: The key to bind (e.g., “1”). It’s important to capitalize the first letter of keys like “Escape”
  • cmd: The command to execute when the key combination is pressed, this can be any shell command.
keybinds = (
  {mod = [], key = "Escape", cmd = "./build/ttcli exit"},
  {mod = ["alt"], key = "Return", cmd = "kitty"},
  {mod = ["alt"], key = "Tab", cmd = "./build/ttcli window cycle"},
);

background_color

Sets the background color of the compositor in RGB format, with values between 0 and 1.

Format: A list of three floating-point numbers, representing the RGB color channels.

background_color = (0.2, 0.2, 0.3);  # A muted dark blue

CLI usage

This page provides a comprehensive guide to turtile’s Command Line Interface (CLI) commands.
The CLI lets you interact with and control turtile by issuing commands through a Unix socket.

exit

Description: Terminates the turtile compositor.

Usage: ttcli exit

window

window list

Description: Lists all active windows with information on their ID, class, title, and associated workspace.

Usage: ttcli window list

Output format:

[
  {
    "id": "window_id",
    "class": "app_id",
    "title": "window_title",
    "workspace": "workspace_name"
  }
]

window switch

Description: Switches focus to the specified window by its ID.

Usage: ttcli window switch <window_id>

Arguments:
<window_id> ID of the window to focus.

window cycle

Description: Cycles focus to the next window within the current workspace.

Usage: ttcli window cycle

window kill

Description: Closes a window. Can close a specified window by ID or the currently focused window if no ID is given.

Usage: ttcli window kill [<window_id>]

Arguments:
[<window_id>] (optional) ID of the window to close.

window move-to

Description: Moves a window to a specified workspace. Can target a specific window by ID or the currently focused window.

Usage: ttcli window move-to <workspace_name> [<window_id>]

Arguments:
<workspace_name> Name of the destination workspace.
[<window_id>] (optional) ID of the window to move.

window mtoggle

Description: Sets a window as the master in the current workspace. Can target a specific window by ID or otherwise the currently focused window.
If no window is specified and the current window is the next window in the stack will be set as the master instead.

Usage: ttcli window mtoggle [<window_id>]

Arguments:
[<window_id>] (optional) ID of the window to set as master.

workspace

workspace list

Description: Lists all available workspaces and their status (active/inactive).

Usage: workspace list

Output sample:

[
  {
    "name": "workspace_name",
    "active": true
  }
]

workspace switch

Description: Switches focus to a specified workspace.

Usage: workspace switch <workspace_name>

Arguments:
<workspace_name> Name of the workspace to switch to.

Graph View