pinnacle/README.md

Table of Contents

• Info
  • What is Pinnacle?
  • Features
  • Roadmap
• Dependencies
• Building
• Running
• Configuration
  • Out-of-the-box configurations
  • Custom configuration
    • Generating a config
  • More on configuration
    • The metaconfig.toml file
  • Lua Language Server completion
  • API references
• 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.

Features

• Tag system
• Customizable layouts, including most of the ones from Awesome
• (Scuffed) XWayland support
• wlr-layer-shell support
• Configurable in Lua or Rust
• wlr-screencopy support
• Is very cool 👍

Roadmap

• See #142

Dependencies

You will need:

• Rust 1.74 or newer
  • If you want to use the Rust API, you will need Rust 1.75 or newer
• 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/Ubuntu:

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

  • NixOS: There is flake flake.nix with a devShell. It also includes the other tools needed for the build and sets up the LD_LIBRARY_PATH so the dynamically loaded libraries are found.

    Note

    Luarocks currently doesn't install the Lua library and its dependencies due to openssh directory shenanigans. Fix soon, hopefully. In the meantime you can use the Rust API.

• protoc, the Protocol Buffer Compiler, for configuration
  • Arch:

    sudo pacman -S protobuf
    

  • Debian/Ubuntu:

    sudo apt install protobuf-compiler
    

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

    sudo pacman -S luarocks
    

  • Debian/Ubuntu:

    sudo apt install 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 Lua default config and Rust default config to $XDG_DATA_HOME/pinnacle/default_config/{lua,rust}
• 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.

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
cargo run -- -c "./api/lua/examples/default"

# For a Rust configuration
cargo run -- -c "./api/rust/examples/default_config"

Custom configuration

Important

Pinnacle is under 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.

Generating a config

Run the following command to open up the interactive config generator:

cargo run -- config gen

This will prompt you to choose a language (Lua or Rust) and directory to put the config in. It will then generate a config at that directory. If Lua is chosen and there are conflicting files in the directory, the generator will prompt to rename them to a backup before continuing. If Rust is chosen, the directory must be manually emptied to continue.

Run cargo run -- config gen --help for information on the command.

More on configuration

Pinnacle is configured purely through IPC using gRPC. This is done through configuration clients that use the Lua and Rust interface libraries.

As the compositor has no direct integration with these clients, it must know what it needs to run through a separate file, aptly called the metaconfig.toml file.

To start a config, Pinnacle will search for a metaconfig.toml file in the first directory that exists from the following:

1. The directory passed in through --config-dir/-c
2. $PINNACLE_CONFIG_DIR
3. $XDG_CONFIG_HOME/pinnacle
4. ~/.config/pinnacle if $XDG_CONFIG_HOME is not defined

If there is no metaconfig.toml file in that directory, Pinnacle will start the default Lua config at $XDG_DATA_HOME/pinnacle/default_config/lua (typically ~/.local/share/pinnacle/default_config/lua).

Additionally, if your config crashes, Pinnacle will also start the default Lua config.

Note

If you have not run eval $(luarocks path --lua-version 5.4), Pinnacle will go into an endless loop of starting the default Lua config only for it to crash because it can't find the Lua library.

The metaconfig.toml file

A metaconfig.toml file must contain the following entries:

• command: An array denoting the program and arguments Pinnacle will run to start a config.
• reload_keybind: A table denoting a keybind that Pinnacle will hardcode to restart your config.
• kill_keybind: A table denoting a keybind that Pinnacle will hardcode to quit the compositor.
  • The two keybinds above prevent you from getting locked in the compositor if the default config fails to start.

It also has the following optional entries:

• socket_dir: A directory that Pinnacle will place its IPC socket in (this defaults to $XDG_RUNTIME_DIR, falling back to /tmp if that doesn't exist).
• [envs]: A table of environment variables that Pinnacle will start the config with.

For the specifics, see the default metaconfig.toml file.

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.

API references

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

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.