pinnacle/README.md

Pinnacle

A very, VERY WIP Smithay-based wayland compositor

Changelog

See CHANGELOG.md.

Features

• Winit backend
• Udev backend
  • This is currently just a copy of Anvil's udev backend.
• Basic tags
• 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 that's not already listed in GitHub issues, feel free to submit it!
• 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 👍

Info

What is Pinnacle?

Pinnacle is a Wayland compositor built in Rust using Smithay.

In short, this is my attempt at creating something like AwesomeWM for Wayland.

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

Why Pinnacle?

Well, I currently use Awesome. And I really like it! Unfortunately, Awesome doesn't exist for Wayland (anymore). There doesn't seem to be any Wayland compositor out there that has all of the following:

• Tags for window management
• Configurable in Lua (or any other programming language for that matter)
• Has a bunch of batteries included (widget system, systray, etc)

So, this is my attempt at making an Awesome-esque Wayland compositor.

Dependencies

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 seatda 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. It should work, but if it doesn't, please raise an issue. ^{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]

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. NOTE: I tried running udev in Awesome and some things broke so uh, don't do that

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.

ℹ️ When running in debug mode, the compositor will drastically slow down if there are too many windows on screen. If you don't want this to happen, use release mode.

❗ IMPORTANT: Read the following before you launch the udev backend:

If you successfully enter the udev backend but none of the controls work, this means either Pinnacle failed to find your config, or the config process crashed.

You can either switch ttys or press Ctrl + Alt + Shift + Escape, which has been hardcoded in to kill the compositor.

ℹ️ 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

⚠️ Don't 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

Please note: this is WIP and has few options.

Pinnacle supports configuration through Lua (and hopefully more languages if it's not too unwieldy 🦀).

Run Pinnacle with the PINNACLE_CONFIG environment variable set to the path of your config file. If not specified, Pinnacle will look for the following:

$XDG_CONFIG_HOME/pinnacle/init.lua
~/.config/pinnacle/init.lua         # if XDG_CONFIG_HOME isn't set

The following will use the example config file in api/lua:

PINNACLE_CONFIG="./api/lua/example_config.lua" cargo run

ℹ️ The config is an external process.

If it crashes for whatever reason, all of your keybinds will stop working. Again, you can switch ttys or exit the compositor with Ctrl + Alt + Shift + Escape.

Config reloading soon™️

API Documentation

There is a preliminary doc website generated with LDoc. 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>.

ℹ️ 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, as I'll be using its doc comments to 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
        }
    }
}

Controls

The following controls are currently hardcoded:

• Ctrl + Left Mouse: Move a window
• Ctrl + Right Mouse: Resize a window
• Ctrl + Alt + Shift + Esc: Kill Pinnacle. This is for when the compositor inevitably locks up because I did a dumb thing 👍

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

Feature Requests, Bug Reports, Contributions, and Questions

See CONTRIBUTING.md.