Home

Awesome

Pinnacle banner

<div align="center">

Discord Matrix

</div>

image

Table of Contents

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.

Pinnacle comes integrated with Snowcap, a very, very WIP widget system. Currently it's only being used for the builtin quit prompt and keybind overlay. In the future, Snowcap will be used for everything Awesome uses its widget system for: a taskbar, system tray, etc.

Features

Roadmap

Dependencies

You will need:

The following are optional dependencies:

TODO: other distros

Building

Clone this repository and, if building with Snowcap integration, update the snowcap submodule:

git clone https://github.com/pinnacle-comp/pinnacle
git submodule update --init

[!NOTE] For all following cargo/just commands, if you would like to build without Snowcap integration, run with --no-default-features.

Build the project with:

cargo build [--release]

To additionally install the default configs, protobuf definitions, and Lua API, run:

just install build [--release] # Order matters, put build/run/test last to pass through arguments

Running

[!TIP] Before running, read the information in Configuration.

[!IMPORTANT] If you are going to use a Lua config, you must run just install to install the protobuf definitions and Lua library.

After building, run the executable located in either:

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

[!IMPORTANT] When compiling with Snowcap integration, if you do not have Vulkan set up properly, Pinnacle will crash on startup.

For those using Nix outside of NixOS, you will need to run the built binary with nixGL using both GL and Vulkan wrappers, nested inside one another:

nix run --impure github:nix-community/nixGL -- nix run --impure github:nix-community/nixGL#nixVulkanIntel -- ./target/debug/pinnacle

Or, run the project directly with

cargo run [--release]

# With installation:
just install run [--release]

See flags Pinnacle accepts by running cargo run -- --help (or -h).

Configuration

Pinnacle is configured in your choice of Lua or Rust.

Out-of-the-box configurations

Pinnacle embeds the default Rust config into the binary. If you would like to use the Lua or Rust default configs standalone, run one of the following in the crate root:

# For a Lua configuration
just install run -- -c ./api/lua/examples/default

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

When running a Rust config without compiled Snowcap integration, use the following directory instead (Lua users can use the same directory):

cargo run -- -c ./api/rust/examples/default_config_no_snowcap

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:

just install-configs 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.

Note that this currently copies default configs with Snowcap integration.

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

More on configuration

Pinnacle is configured mostly at runtime through IPC using gRPC. This is done through configuration clients that use the Lua and Rust APIs.

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 embedded Rust config.

Additionally, if your config crashes, Pinnacle will also start the embedded Rust config.

[!NOTE] If you are using a Lua config and have not run eval $(luarocks path --lua-version <your-lua-version>), Pinnacle will fallback to the embedded Rust config.

The metaconfig.toml file

A metaconfig.toml file must contain the following entries:

It also has the following optional entries:

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

<b>Lua: https://pinnacle-comp.github.io/lua-reference/.<br> Rust: https://pinnacle-comp.github.io/rust-reference/main.</b>

Documentation for the Rust API can be reached by replacing main with the branch you want. Other branches for Lua soon<sup>tm</sup>

Controls

The following are the default controls, mirroring Awesome's defaults.

<kbd>Mod</kbd> is <kbd>Super</kbd> when running in a tty and <kbd>Alt</kbd> when running as a nested window.

BindingAction
<kbd>Mod</kbd> + <kbd>s</kbd>Show the keybind overlay
<kbd>Mod</kbd> + <kbd>Mouse left drag</kbd>Move window
<kbd>Mod</kbd> + <kbd>Mouse right drag</kbd>Resize window
<kbd>Mod</kbd><kbd>Shift</kbd> + <kbd>q</kbd>Quit Pinnacle
<kbd>Mod</kbd><kbd>Ctrl</kbd> + <kbd>r</kbd>Reload the config
<kbd>Mod</kbd><kbd>Shift</kbd> + <kbd>c</kbd>Close window
<kbd>Mod</kbd> + <kbd>Return</kbd>Spawn Alacritty (you can change this in the config)
<kbd>Mod</kbd><kbd>Ctrl</kbd> + <kbd>Space</kbd>Toggle floating
<kbd>Mod</kbd> + <kbd>f</kbd>Toggle fullscreen
<kbd>Mod</kbd> + <kbd>m</kbd>Toggle maximized
<kbd>Mod</kbd> + <kbd>Space</kbd>Cycle to the next layout
<kbd>Mod</kbd><kbd>Shift</kbd> + <kbd>Space</kbd>Cycle to the previous layout
<kbd>Mod</kbd> + <kbd>1</kbd> to <kbd>5</kbd>Switch to tag 1 to 5
<kbd>Mod</kbd><kbd>Ctrl</kbd> + <kbd>1</kbd> to <kbd>5</kbd>Toggle tag 1 to 5
<kbd>Mod</kbd><kbd>Shift</kbd> + <kbd>1</kbd> to <kbd>5</kbd>Move a window to tag 1 to 5
<kbd>Mod</kbd><kbd>Ctrl</kbd><kbd>Shift</kbd> + <kbd>1</kbd> to <kbd>5</kbd>Toggle tag 1 to 5 on a window

Feature Requests, Bug Reports, Contributions, and Questions

See CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

With Special Thanks To