pinnacle/README.md

282 lines
12 KiB
Markdown
Raw Normal View History

![Pinnacle banner](/assets/pinnacle_banner_dark.png)
2023-06-20 20:52:50 +02:00
2024-03-30 03:28:08 +01:00
<div align="center">
[![Discord](https://img.shields.io/discord/1223351743522537565?style=for-the-badge&logo=discord&logoColor=white&label=Discord&labelColor=%235865F2&color=%231825A2)](https://discord.gg/JhpKtU2aMA)
[![Matrix](https://img.shields.io/matrix/pinnacle%3Amatrix.org?style=for-the-badge&logo=matrix&logoColor=white&label=Matrix&labelColor=black&color=gray)](https://matrix.to/#/#pinnacle:matrix.org)
</div>
![image](https://github.com/pinnacle-comp/pinnacle/assets/120758733/a0e9ce93-30bb-4359-9b61-78ad4c4134d9)
2023-09-08 05:52:45 +02:00
2023-10-25 11:23:20 +02:00
# Table of Contents
- [Info](#info)
- [What is Pinnacle?](#what-is-pinnacle)
- [Features](#features)
- [Roadmap](#roadmap)
- [Dependencies](#dependencies)
- [Building](#building)
- [Running](#running)
- [Configuration](#configuration)
- [Out-of-the-box configurations](#out-of-the-box-configurations)
- [Custom configuration](#custom-configuration)
2024-03-03 10:50:04 +01:00
- [Generating a config](#generating-a-config)
2024-04-07 09:20:07 +02:00
- [More on configuration](#more-on-configuration)
2024-03-13 00:15:42 +01:00
- [The `metaconfig.toml` file](#the-metaconfigtoml-file)
2024-03-03 10:50:04 +01:00
- [Lua Language Server completion](#lua-language-server-completion)
- [API references](#api-references)
2023-10-25 11:23:20 +02:00
- [Controls](#controls)
- [Feature Requests, Bug Reports, Contributions, and Questions](#feature-requests-bug-reports-contributions-and-questions)
- [Changelog](#changelog)
2023-08-17 04:23:17 +02:00
# Info
2023-08-16 04:58:03 +02:00
### What is Pinnacle?
Pinnacle is a Wayland compositor built in Rust using [Smithay](https://github.com/Smithay/smithay).
It's my attempt at creating something like [AwesomeWM](https://github.com/awesomeWM/awesome)
for Wayland.
### What is Snowcap?
You will see references to Snowcap throughout this README. [Snowcap](https://github.com/pinnacle-comp/snowcap) is the
very, *very* WIP widget system for Pinnacle. 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.
> [!NOTE]
> Only the Rust API has implemented Snowcap integration currently. Lua support soon™
2023-08-16 04:58:03 +02:00
### Features
2023-10-21 04:11:16 +02:00
- Tag system
2024-04-07 09:20:07 +02:00
- Customizable layouts, including most of the ones from Awesome
- (Scuffed) XWayland support
- wlr-layer-shell support
2023-10-21 04:11:16 +02:00
- Configurable in Lua or Rust
2024-04-07 09:20:07 +02:00
- wlr-screencopy support
- A really *really* WIP widget system
2023-10-21 04:11:16 +02:00
- Is very cool :thumbsup:
2023-07-03 01:31:41 +02:00
2023-10-21 04:11:16 +02:00
### Roadmap
- See [#142](https://github.com/pinnacle-comp/pinnacle/issues/142)
2023-06-20 23:16:14 +02:00
2023-08-17 04:23:17 +02:00
# Dependencies
2024-01-16 23:54:25 +01:00
You will need:
- [Rust](https://www.rust-lang.org/) 1.75 or newer
- The following external dependencies:
- `libwayland`
- `libxkbcommon`
- `libudev`
- `libinput`
- `libgbm`
- `libseat`
- `libEGL`
- `libsystemd`
- `libdisplay-info` for monitor display information
- `xwayland` for Xwayland support
- [`protoc`](https://grpc.io/docs/protoc-installation/) for the API
The following are optional dependencies:
- [`just`](https://github.com/casey/just) to automate installation of libraries and files
- The following are required to use the Lua API:
- `just` as mentioned above
- [`lua`](https://www.lua.org/) 5.2 or newer
- [`luarocks`](https://luarocks.org/) for API installation
- You must run `eval $(luarocks path --lua-version <your-lua-version>)` so that your config can find the API
library files. It is recommended to place this command in your shell's startup script.
- Arch and derivatives:
```sh
sudo pacman -S wayland libxkbcommon libinput mesa seatd systemd-libs libdisplay-info xorg-xwayland protobuf
# And optionally
sudo pacman -S just lua luarocks
```
- Debian and derivatives:
```sh
sudo apt install libwayland-dev libxkbcommon-dev libudev-dev libinput-dev libgbm-dev libseat-dev libsystemd-dev protobuf-compiler xwayland libegl-dev libdisplay-info-dev
# And optionally
sudo apt install just lua5.4 luarocks
```
- Note: `just` is only available in apt from Debian 13.
- Nix and NixOS:
- Use the provided [`flake.nix`](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.
2024-04-14 21:12:57 +02:00
> 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.
2024-01-16 23:54:25 +01:00
TODO: other distros
2023-08-17 04:23:17 +02:00
# Building
Clone this repository and, if building with Snowcap integration, update the `snowcap` submodule:
```sh
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`.
2023-06-20 23:16:14 +02:00
Build the project with:
```sh
2023-06-20 23:16:14 +02:00
cargo build [--release]
```
2024-04-23 23:32:26 +02:00
To additionally install the default configs, protobuf definitions, and Lua API, run:
```sh
just install build [--release] # Order matters, put build/run/test last to pass through arguments
```
2023-09-22 00:34:02 +02:00
2023-08-17 04:23:17 +02:00
# Running
> [!TIP]
2023-09-08 07:23:19 +02:00
> Before running, read the information in [Configuration](#configuration).
2023-08-16 20:57:47 +02:00
> [!IMPORTANT]
2024-04-23 23:32:26 +02:00
> If you are going to use a Lua config, you must run `just install` to install the protobuf definitions
> and Lua library.
2023-06-20 23:16:14 +02:00
After building, run the executable located in either:
2023-08-08 01:25:22 +02:00
```sh
2023-08-08 20:30:52 +02:00
./target/debug/pinnacle # without --release
./target/release/pinnacle # with --release
2023-06-20 23:16:14 +02:00
```
> [!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](https://github.com/nix-community/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
> ```
2023-06-20 23:16:14 +02:00
Or, run the project directly with
2023-08-08 01:25:22 +02:00
```sh
2023-08-08 20:30:52 +02:00
cargo run [--release]
2024-04-23 23:32:26 +02:00
# With installation:
just install run [--release]
2023-06-20 23:16:14 +02:00
```
2024-04-23 23:32:26 +02:00
See flags Pinnacle accepts by running `cargo run -- --help` (or `-h`).
2023-08-08 20:30:52 +02:00
2023-08-17 04:23:17 +02:00
# Configuration
2023-10-21 04:11:16 +02:00
Pinnacle is configured in your choice of Lua or Rust.
2023-06-20 23:16:14 +02:00
2023-10-21 04:11:16 +02:00
## 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:
2024-03-03 10:21:54 +01:00
2023-10-21 04:11:16 +02:00
```sh
# For a Lua configuration
2024-04-23 23:32:26 +02:00
just install run -- -c "./api/lua/examples/default"
2023-10-21 04:11:16 +02:00
# For a Rust configuration
2024-03-03 10:21:54 +01:00
cargo run -- -c "./api/rust/examples/default_config"
```
When running the default Rust config standalone without compiled Snowcap integration,
run the one in the following directory:
```sh
cargo run -- -c "./api/rust/examples/default_config_no_snowcap"
2023-10-21 04:11:16 +02:00
```
## Custom configuration
> [!IMPORTANT]
2024-01-22 07:03:55 +01:00
> 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.
2024-03-03 10:21:54 +01:00
### Generating a config
Run the following command to open up the interactive config generator:
2023-08-08 01:25:22 +02:00
```sh
just install-configs run -- config gen
2023-06-20 23:16:14 +02:00
```
2023-08-16 04:58:03 +02:00
2024-03-03 10:21:54 +01:00
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.
2023-08-16 04:58:03 +02:00
2024-03-03 10:21:54 +01:00
Run `cargo run -- config gen --help` for information on the command.
2023-09-22 03:08:02 +02:00
2024-04-07 09:20:07 +02:00
## More on configuration
2024-03-03 10:21:54 +01:00
Pinnacle is configured purely through IPC using [gRPC](https://grpc.io/). This is done through
configuration clients that use the [Lua](api/lua) and [Rust](api/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`
2024-04-23 23:32:26 +02:00
4. `~/.config/pinnacle` if `$XDG_CONFIG_HOME` is not defined
2023-08-03 02:45:56 +02:00
2024-04-23 08:02:30 +02:00
If there is no `metaconfig.toml` file in that directory, Pinnacle will start the embedded
Rust config.
2023-08-03 02:45:56 +02:00
2024-04-23 08:02:30 +02:00
Additionally, if your config crashes, Pinnacle will also start the embedded Rust config.
2024-03-03 10:21:54 +01:00
> [!NOTE]
2024-05-04 20:36:04 +02:00
> If you have not run `eval $(luarocks path --lua-version <your-lua-version>)`, Pinnacle will fallback to the
2024-04-23 04:20:05 +02:00
> embedded Rust config.
2024-03-03 10:21:54 +01:00
### 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`](api/lua/examples/default/metaconfig.toml) file.
## Lua Language Server completion
2024-01-16 23:54:25 +01:00
A [`.luarc.json`](api/lua/examples/default/.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](https://github.com/LuaLS/lua-language-server).
2023-06-20 23:16:14 +02:00
2024-03-03 10:50:04 +01:00
## API references
<b>Lua: https://pinnacle-comp.github.io/lua-reference/main.<br>
Rust: https://pinnacle-comp.github.io/rust-reference/main.</b>
2023-08-16 04:58:03 +02:00
2023-10-21 04:11:16 +02:00
> Documentation for other branches can be reached by replacing `main` with the branch you want.
2023-08-16 04:58:03 +02:00
2023-08-17 04:23:17 +02:00
# Controls
The following are the default controls in the [`default_config`](api/rust/examples/default_config/main.rs).
2023-09-11 05:25:18 +02:00
| Binding | Action |
|----------------------------------------------|------------------------------------|
| <kbd>Ctrl</kbd> + <kbd>s</kbd> | Show the keybind overlay |
2023-09-11 05:25:18 +02:00
| <kbd>Ctrl</kbd> + <kbd>Mouse left drag</kbd> | Move window |
| <kbd>Ctrl</kbd> + <kbd>Mouse right drag</kbd>| Resize window |
| <kbd>Ctrl</kbd><kbd>Alt</kbd> + <kbd>q</kbd> | Quit Pinnacle |
| <kbd>Ctrl</kbd><kbd>Alt</kbd> + <kbd>c</kbd> | Close window |
| <kbd>Ctrl</kbd> + <kbd>Return</kbd> | Spawn [Alacritty](https://github.com/alacritty/alacritty) (you can change this in the config)|
| <kbd>Ctrl</kbd><kbd>Alt</kbd> + <kbd>Space</kbd> | Toggle between floating and tiled |
| <kbd>Ctrl</kbd> + <kbd>f</kbd> | Toggle fullscreen |
| <kbd>Ctrl</kbd> + <kbd>m</kbd> | Toggle maximized |
| <kbd>Ctrl</kbd> + <kbd>Space</kbd> | Cycle to the next layout |
| <kbd>Ctrl</kbd><kbd>Shift</kbd> + <kbd>Space</kbd> | Cycle to the previous layout |
| <kbd>Ctrl</kbd> + <kbd>1</kbd> to <kbd>5</kbd> | Switch to tag `1` to `5` |
| <kbd>Ctrl</kbd><kbd>Shift</kbd> + <kbd>1</kbd> to <kbd>5</kbd> | Toggle tag `1` to `5` |
| <kbd>Ctrl</kbd><kbd>Alt</kbd> + <kbd>1</kbd> to <kbd>5</kbd> | Move a window to tag `1` to `5` |
| <kbd>Ctrl</kbd><kbd>Alt</kbd><kbd>Shift</kbd> + <kbd>1</kbd> to <kbd>5</kbd> | Toggle tag `1` to `5` on a window |
2023-08-04 03:54:22 +02:00
2023-08-17 04:23:17 +02:00
# Feature Requests, Bug Reports, Contributions, and Questions
2023-08-14 21:47:27 +02:00
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
2023-08-16 20:57:47 +02:00
2023-08-17 04:23:17 +02:00
# Changelog
2023-08-16 20:57:47 +02:00
See [`CHANGELOG.md`](CHANGELOG.md).
2024-05-27 23:43:26 +02:00
# With Special Thanks To
- [Niri](https://github.com/YaLTeR/niri): For all that rendering and protocol stuff I, ahem, *took inspiration* from