pinnacle/README.md

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

Table of Contents

• Info
  • What is Pinnacle?
  • Features
  • Roadmap
• Dependencies
• Building
• Running
• Configuration
  • Out-of-the-box configurations
  • Custom configuration
    • Lua
      • Lua Language Server completion
    • Rust
    • API Documentation
• Controls
• Feature Requests, Bug Reports, Contributions, and Questions
• Changelog

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 extensive configurability through either Lua or Rust, with the ability to add more languages 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

• Tag system
• Left master stack, corner, dwindle, and spiral layouts from Awesome
• (Really scuffed) XWayland support
• Layer-shell support
• Configurable in Lua or Rust
• Is very cool 👍

Roadmap

• TODO

Dependencies

You will need:

• Rust 1.72 or newer, to build the project and use the Rust API
• Lua 5.4 or newer, to use the Lua API
• Packages for Smithay: libwayland libxkbcommon libudev libinput libgdm libseat, as well as xwayland
  • Arch:

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

  • Debian:

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

  • NixOS: There is a really old shell.nix that may or may not work 💀
• protoc, the Protocol Buffer Compiler, for configuration
  • Arch:

    sudo pacman -S protobuf
    

• LuaRocks, the Lua package manager, to use the Lua API
  • Arch:

    sudo pacman -S luarocks
    

  • You must run eval $(luarocks path --lua-version 5.4) so that your config can find the API library files. It is recommended to place this command in your shell's startup script.

TODO: other distros

Building

Build the project with:

cargo build [--release]

Note

On build, build.rs will:

• Copy Protobuf definition files to $XDG_DATA_HOME/pinnacle/protobuf
• Copy the default config to $XDG_DATA_HOME/pinnacle/default_config
• cd into api/lua and run luarocks make to install the Lua library to ~/.luarocks/share/lua/5.4

Running

Important

Before running, read the information in Configuration.

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).

Configuration

Pinnacle is configured in your choice of Lua or Rust.

Note

Pinnacle is currently in the process of migrating the configuration backend from MessagePack to gRPC. The Lua library has already been rewritten, and the Rust API will be rewritten soon.

Out-of-the-box configurations

If you just want to test Pinnacle out without copying stuff to your config directory, run one of the following in the crate root:

# For a Lua configuration
PINNACLE_CONFIG_DIR="./api/lua/examples/default" cargo run
# This should also have been copied to the directory below, so below will do the same
PINNACLE_CONFIG_DIR="~/.local/share/pinnacle/default_config" cargo run

# For a Rust configuration
PINNACLE_CONFIG_DIR="./api/rust" cargo run

Custom configuration

Important

Pinnacle is under heavy development, and there will be major breaking changes to these APIs until I release version 0.1, at which point there will be an API stability spec in place.

Until then, I recommend you either use the out-of-the-box configs above or prepare for your config to break every now and then.

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 Lua config will be loaded.

Lua

For custom configuration in Lua, copy the contents of ~/.local/share/pinnacle/default_config to ~/.config/pinnacle (or $XDG_CONFIG_HOME/pinnacle):

mkdir ~/.config/pinnacle
cp -r ~/.local/share/pinnacle/default_config/. ~/.config/pinnacle

Note: there is a .luarc.json file that may not get copied if you do cp <path>/* ~/.config/pinnacle. The above command takes that into account.

If you rename default_config.lua, make sure command in your metaconfig.toml is updated to reflect that. If it isn't, the compositor will load the default config instead.

Lua Language Server completion

A .luarc.json file is included with the default Lua config and will set the correct workspace library files for use with the Lua language server.

Rust

If you want to use Rust to configure Pinnacle, follow these steps:

1. In ~/.config/pinnacle, run cargo init.
2. In the Cargo.toml file, add the following under [dependencies]:

pinnacle_api = { git = "http://github.com/pinnacle-comp/pinnacle" }

3. Create the file metaconfig.toml at the root. Add the following to the file:

command = ["cargo", "run"]
reload_keybind = { modifiers = ["Ctrl", "Alt"], key = "r" }
kill_keybind = { modifiers = ["Ctrl", "Alt", "Shift"], key = "escape" }

4. Copy the contents from example_config.rs to src/main.rs.
5. Run Pinnacle! (You may want to run cargo build beforehand so you don't have to wait for your config to compile.)

API Documentation

Lua: https://pinnacle-comp.github.io/pinnacle/main/lua.
Rust: https://pinnacle-comp.github.io/pinnacle/main/rust.

Documentation for other branches can be reached by replacing main with the branch you want.

Controls

The following are the default controls in the default_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.