pinnacle/README.md

https://github.com/Ottatop/pinnacle/assets/120758733/c175ba80-9796-4759-92c3-1d7a6639b0c9

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.

More video examples below!

Click me

All videos were recorded using Screenkey and the Winit backend.

https://github.com/Ottatop/pinnacle/assets/120758733/5b6b224b-3031-4a1c-9375-1143f1bfc0e3

https://github.com/Ottatop/pinnacle/assets/120758733/7a465983-2560-412e-9154-40b3dfd20488

(This video is very crunchy in my attempts to get under the 10mb limit)

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™️}

Note

On build, install_libs.sh will run to copy the Lua API library to $XDG_DATA_HOME/pinnacle (or ~/.local/share/pinnacle).

Running

Important

Before running, read the information in Configuration.

Also, ensure you have installed the Lua API library to its correct location, as noted in Building.

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]

See flags you can pass in by running cargo run -- --help (or -h).

Important

Make sure command in your metaconfig.toml is set to the right file. If it isn't, the compositor will load the default config instead.

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 # Only if $XDG_CONFIG_HOME is not defined

The metaconfig.toml file provides information on what config to run, kill and reload keybinds, and any environment variables you want set. For more details, see the provided metaconfig.toml file.

If no metaconfig.toml file is found, the default config will be loaded.

For custom configuration, you can 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.

This documentation is auto-generated from the provided LuaLS annotation through ldoc_gen, so there may be some errors as I work the kinks out.

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://pinnacle-comp.github.io/pinnacle/<branch name>.

Controls

The following are the default controls in the example_config.

Binding	Action
Ctrl + Mouse left drag	Move window
Ctrl + Mouse right drag	Resize window
CtrlAlt + q	Quit Pinnacle
CtrlAlt + c	Close window
Ctrl + Return	Spawn Alacritty (you can change this in the config)
CtrlAlt + Space	Toggle between floating and tiled
Ctrl + f	Toggle fullscreen
Ctrl + m	Toggle maximized
Ctrl + Space	Cycle to the next layout
CtrlShift + Space	Cycle to the previous layout
Ctrl + 1 to 5	Switch to tag 1 to 5
CtrlShift + 1 to 5	Toggle tag 1 to 5
CtrlAlt + 1 to 5	Move a window to tag 1 to 5
CtrlAltShift + 1 to 5	Toggle tag 1 to 5 on a window

Feature Requests, Bug Reports, Contributions, and Questions

See CONTRIBUTING.md.

Changelog

See CHANGELOG.md.