2023-06-20 23:18:53 +02:00
# <div align="center">Pinnacle</div>
2023-06-20 23:16:14 +02:00
< div align = "center" >
< picture >
< source media = "(prefers-color-scheme: dark)" srcset = "/assets/cool_logo_dark_theme.png" >
< source media = "(prefers-color-scheme: light)" srcset = "/assets/cool_logo_light_theme.png" >
< img alt = "Cool logo" src = "/assets/cool_logo_dark_theme.png" >
< / picture >
< / div >
2023-06-20 20:52:50 +02:00
2023-06-20 23:16:14 +02:00
< div align = "center" >
A very, VERY WIP Smithay-based wayland compositor
< / div >
2023-08-14 21:47:27 +02:00
## Changelog
See [`CHANGELOG.md` ](CHANGELOG.md ).
2023-07-22 04:48:56 +02:00
2023-08-16 04:58:03 +02:00
## Info
### 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.
It sports high configurability through a (soon to be) extensive Lua API, with plans for a Rust API in the future.
Showcase soon:tm: (don't expect anything mind-blowing)
### Features
> This is a non-exhaustive list.
- [x] Winit backend (so you can run Pinnacle in your graphical environment)
- [x] Udev backend (so you can run Pinnacle in a tty)
- [x] Tag system
2023-07-03 01:31:41 +02:00
- [ ] Layout system
2023-07-18 17:41:55 +02:00
- [x] Left master stack, corner, dwindle, spiral layouts
- [ ] Other three master stack directions, floating, magnifier, maximized, and fullscreen layouts
- [ ] Resizable layouts
2023-08-03 02:45:56 +02:00
- [x] XWayland support
2023-08-16 04:58:03 +02:00
- This is currently somewhat buggy. If you find a problem, please submit an issue!
2023-08-08 01:25:22 +02:00
- [x] Layer-shell support
- [ ] wlr-screencopy support
- [ ] wlr-output-management support
2023-07-03 01:31:41 +02:00
- [ ] Server-side decorations
2023-07-13 04:48:47 +02:00
- [ ] Animations and blur and all that pizazz
2023-07-18 17:41:55 +02:00
- [ ] Widget system
2023-07-03 01:31:41 +02:00
- [ ] The other stuff Awesome has
- [x] Is very cool :thumbsup:
2023-06-20 23:16:14 +02:00
## Dependencies
2023-08-16 04:58:03 +02:00
> I have not tested these. If Pinnacle doesn't work properly with these packages installed, please submit an issue.
2023-06-20 23:16:14 +02:00
You'll need the following packages, as specified by [Smithay ](https://github.com/Smithay/smithay ):
2023-08-08 19:53:04 +02:00
`libwayland libxkbcommon libudev libinput libgdm libseat` , as well as `xwayland` .
2023-07-13 04:48:47 +02:00
- Arch:
```
2023-08-16 04:58:03 +02:00
sudo pacman -S wayland wayland-protocols libxkbcommon systemd-libs libinput mesa seatd xwayland
2023-07-13 04:48:47 +02:00
```
- Debian:
```
2023-08-08 19:53:04 +02:00
sudo apt install libwayland-dev libxkbcommon-dev libudev-dev libinput-dev libgdm-dev libseat-dev xwayland
2023-07-13 04:48:47 +02:00
```
2023-08-08 01:25:22 +02:00
- NixOS: Use the provided [`shell.nix` ](shell.nix ).
2023-07-13 04:48:47 +02:00
- TODO: other distros.
2023-08-08 01:25:22 +02:00
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.
2023-06-20 23:16:14 +02:00
## Building
Build the project with:
```
cargo build [--release]
```
2023-08-08 01:25:22 +02:00
For NixOS users, there is a provided [`shell.nix` ](shell.nix ) file that you can use for `nix-shell` .
2023-08-16 04:58:03 +02:00
< sup > flake soon:tm:< / sup >
2023-08-08 01:25:22 +02:00
2023-06-20 23:16:14 +02:00
## Running
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
```
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]
2023-06-20 23:16:14 +02:00
```
2023-08-16 04:58:03 +02:00
Pinnacle will automatically initialize the correct backend for your environment.
However, there is an additional flag you can pass in: `--<backend>` . You most likely do not need to use it.
2023-08-08 20:30:52 +02:00
2023-06-20 23:16:14 +02:00
`backend` can be one of two values:
2023-07-03 01:31:41 +02:00
- `winit` : run Pinnacle as a window in your graphical environment
2023-08-16 04:58:03 +02:00
- `udev` : run Pinnacle in a tty.
2023-06-20 23:16:14 +02:00
2023-08-08 20:30:52 +02:00
If you try to run either in environments where you shouldn't be, you will get a warning requiring you to
pass in the `--force` flag to continue. *You probably shouldn't be doing that.*
2023-08-16 04:58:03 +02:00
> #### :information_source: Make sure `command` in your `metaconfig.toml` is set to the right file.
> If it isn't, the compositor will open, but your config will not apply. In that case, kill the compositor using the keybind defined in `kill_keybind` and set `command` properly.
2023-08-08 01:25:22 +02:00
2023-08-08 01:31:06 +02:00
> #### :information_source: Pinnacle will open a socket in the `/tmp` directory.
2023-08-08 01:25:22 +02:00
> If for whatever reason you need the socket to be in a different place, run Pinnacle with
> the `SOCKET_DIR` environment variable:
> ```sh
2023-08-08 20:32:47 +02:00
> SOCKET_DIR=/path/to/new/dir/ cargo run
2023-08-08 01:25:22 +02:00
> ```
2023-08-16 04:58:03 +02:00
> #### :warning: Do not run Pinnacle as root.
2023-08-08 01:25:22 +02:00
> This will open the socket with root-only permissions, and future non-root invocations
of Pinnacle will fail when trying to remove the socket until it is removed manually.
2023-06-20 23:16:14 +02:00
## Configuration
2023-08-16 04:58:03 +02:00
Pinnacle is configured in Lua. Rust support is planned.
2023-06-20 23:16:14 +02:00
2023-08-16 04:58:03 +02:00
Pinnacle will search for a `metaconfig.toml` file in the following directories, from top to bottom:
2023-08-08 01:25:22 +02:00
```sh
2023-08-16 04:58:03 +02:00
$PINNACLE_CONFIG_DIR
$XDG_CONFIG_HOME/pinnacle/
~/.config/pinnacle
2023-06-20 23:16:14 +02:00
```
2023-08-16 04:58:03 +02:00
The `metaconfig.toml` file provides information on what config to run, kill and reload keybinds,
and any environment variables you want set.
To use the provided Lua config, run the following:
2023-08-08 01:25:22 +02:00
```sh
2023-08-16 04:58:03 +02:00
PINNACLE_CONFIG_DIR="./api/lua" cargo run
2023-06-20 23:16:14 +02:00
```
2023-08-16 04:58:03 +02:00
To run without the above environment variable, copy [`metaconfig.toml` ](api/lua/metaconfig.toml ) and
[`example_config.lua` ](api/lua/example_config.lua ) to `$XDG_CONFIG_HOME/pinnacle/`
(this will probably be `~/.config/pinnacle` ).
2023-08-03 02:45:56 +02:00
2023-08-16 04:58:03 +02:00
> If you rename `example_config.lua` to something like `init.lua`, you will need to change `command` in `metaconfig.toml` to reflect that.
2023-08-03 02:45:56 +02:00
2023-08-16 04:58:03 +02:00
### :information_source: Using the Lua Language Server
It is ** *highly*** recommended to use the [Lua language server ](https://github.com/LuaLS/lua-language-server )
and set it up to have the [`api/lua` ](api/lua ) directory as a library.
This will provide documentation, autocomplete, and error checking.
2023-06-20 23:16:14 +02:00
#### For VS Code:
2023-08-08 01:25:22 +02:00
Install the [Lua ](https://marketplace.visualstudio.com/items?itemName=sumneko.lua ) plugin, then go into
its settings and add the path to the [`api/lua` ](api/lua ) directory to `Workspace: Library` .
2023-06-20 23:16:14 +02:00
#### For Neovim:
2023-06-22 00:36:51 +02:00
Pass this table into your Lua language server settings:
2023-06-20 23:16:14 +02:00
```lua
Lua = {
workspace = {
library = {
2023-08-08 01:25:22 +02:00
"/path/to/pinnacle/api/lua" -- Your path here
2023-06-20 23:16:14 +02:00
}
}
}
```
2023-08-16 04:58:03 +02:00
### API Documentation
You can find online documentation for the Lua API [here ](https://ottatop.github.io/pinnacle/main ).
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://ottatop.github.io/pinnacle/<branch name>` .
2023-06-20 23:16:14 +02:00
## Controls
The following controls are currently hardcoded:
2023-07-03 01:31:41 +02:00
- `Ctrl + Left Mouse` : Move a window
- `Ctrl + Right Mouse` : Resize a window
2023-06-20 23:16:14 +02:00
2023-06-22 00:36:51 +02:00
You can find the rest of the controls in the [`example_config` ](api/lua/example_config.lua ).
2023-08-04 03:54:22 +02:00
## Feature Requests, Bug Reports, Contributions, and Questions
2023-08-14 21:47:27 +02:00
See [`CONTRIBUTING.md` ](CONTRIBUTING.md ).