pinnacle/README.md

Pinnacle

A very, VERY WIP Smithay-based wayland compositor

Changelog

See CHANGELOG.md.

Info

What is Pinnacle?

Pinnacle is a Wayland compositor built in Rust using Smithay. It's my attempt at creating something like AwesomeWM for Wayland.

It sports high configurability through a (soon to be) extensive Lua API, with plans for a Rust API in the future.

Showcase soon™️ (don't expect anything mind-blowing)

Features

This is a non-exhaustive list.

• Winit backend (so you can run Pinnacle in your graphical environment)
• Udev backend (so you can run Pinnacle in a tty)
• Tag system
• Layout system
  • Left master stack, corner, dwindle, spiral layouts
  • Other three master stack directions, floating, magnifier, maximized, and fullscreen layouts
  • Resizable layouts
• XWayland support
  • This is currently somewhat buggy. If you find a problem, please submit an issue!
• Layer-shell support
  • wlr-screencopy support
  • wlr-output-management support
• Server-side decorations
• Animations and blur and all that pizazz
• Widget system
• The other stuff Awesome has
• Is very cool 👍

Dependencies

I have not tested these. If Pinnacle doesn't work properly with these packages installed, please submit an issue.

You'll need the following packages, as specified by Smithay: libwayland libxkbcommon libudev libinput libgdm libseat, as well as xwayland.

• Arch:

  sudo pacman -S wayland wayland-protocols libxkbcommon systemd-libs libinput mesa seatd xwayland
  

• Debian:

  sudo apt install libwayland-dev libxkbcommon-dev libudev-dev libinput-dev libgdm-dev libseat-dev xwayland
  

• NixOS: Use the provided shell.nix.
• TODO: other distros.

You'll also need Lua 5.4 for configuration. Older versions will not work. Check with your package manager to see which version you have.

Building

Build the project with:

cargo build [--release]

For NixOS users, there is a provided shell.nix file that you can use for nix-shell. ^{flake soon™️}

Running

After building, run the executable located in either:

./target/debug/pinnacle     # without --release
./target/release/pinnacle   # with --release

Or, run the project directly with

cargo run [--release]

Pinnacle will automatically initialize the correct backend for your environment.

However, there is an additional flag you can pass in: --<backend>. You most likely do not need to use it.

backend can be one of two values:

• winit: run Pinnacle as a window in your graphical environment
• udev: run Pinnacle in a tty.

If you try to run either in environments where you shouldn't be, you will get a warning requiring you to pass in the --force flag to continue. You probably shouldn't be doing that.

ℹ️ Make sure command in your metaconfig.toml is set to the right file.

If it isn't, the compositor will open, but your config will not apply. In that case, kill the compositor using the keybind defined in kill_keybind and set command properly.

ℹ️ Pinnacle will open a socket in the /tmp directory.

If for whatever reason you need the socket to be in a different place, run Pinnacle with the SOCKET_DIR environment variable:

SOCKET_DIR=/path/to/new/dir/ cargo run

⚠️ Do not run Pinnacle as root.

This will open the socket with root-only permissions, and future non-root invocations of Pinnacle will fail when trying to remove the socket until it is removed manually.

Configuration

Pinnacle is configured in Lua. Rust support is planned.

Pinnacle will search for a metaconfig.toml file in the following directories, from top to bottom:

$PINNACLE_CONFIG_DIR
$XDG_CONFIG_HOME/pinnacle/
~/.config/pinnacle

The metaconfig.toml file provides information on what config to run, kill and reload keybinds, and any environment variables you want set.

To use the provided Lua config, run the following:

PINNACLE_CONFIG_DIR="./api/lua" cargo run

To run without the above environment variable, copy metaconfig.toml and example_config.lua to $XDG_CONFIG_HOME/pinnacle/ (this will probably be ~/.config/pinnacle).

If you rename example_config.lua to something like init.lua, you will need to change command in metaconfig.toml to reflect that.

ℹ️ Using the Lua Language Server

It is highly recommended to use the Lua language server and set it up to have the api/lua directory as a library. This will provide documentation, autocomplete, and error checking.

For VS Code:

Install the Lua plugin, then go into its settings and add the path to the api/lua directory to Workspace: Library.

For Neovim:

Pass this table into your Lua language server settings:

Lua = {
    workspace = {
        library = {
            "/path/to/pinnacle/api/lua" -- Your path here
        }
    }
}

API Documentation

You can find online documentation for the Lua API here.

Note that there are some missing things like the Keys table and Layout enum as well as any function overloads, but these should be autocompleted through the language server.

Documentation for other branches can be reached at https://ottatop.github.io/pinnacle/<branch name>.

Controls

The following controls are currently hardcoded:

• Ctrl + Left Mouse: Move a window
• Ctrl + Right Mouse: Resize a window

You can find the rest of the controls in the example_config.

Feature Requests, Bug Reports, Contributions, and Questions

See CONTRIBUTING.md.