From c25d389e9e71da683149f6bc655862fbdff63814 Mon Sep 17 00:00:00 2001 From: Ottatop Date: Fri, 20 Oct 2023 21:11:16 -0500 Subject: [PATCH] Update README --- README.md | 107 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 62 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index d8910f1..1d56ced 100644 --- a/README.md +++ b/README.md @@ -26,30 +26,20 @@ It sports high configurability through a (soon to be) extensive Lua API, with pl > ### 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 -- [ ] Layout system - - [x] Left master stack, corner, dwindle, spiral layouts - - [ ] Other three master stack directions, floating, magnifier, maximized, and fullscreen layouts - - [ ] Resizable layouts -- [x] XWayland support - - This is currently somewhat buggy. If you find a problem, please submit an issue! -- [x] Layer-shell support - - [ ] wlr-screencopy support - - [ ] wlr-output-management support -- [ ] Server-side decorations -- [ ] Animations and blur and all that pizazz -- [ ] Widget system -- [ ] The other stuff Awesome has -- [x] Is very cool :thumbsup: +- Tag system +- Left master stack, corner, dwindle, spiral layouts from Awesome +- XWayland support +- Layer-shell support +- Configurable in Lua or Rust +- Is very cool :thumbsup: +### Roadmap +- TODO # Dependencies -> I have not tested these. If Pinnacle doesn't work properly with these packages installed, please submit an issue. +You will need Rust installed to compile this project and use the Rust API for configuration. -You'll need the following packages, as specified by [Smithay](https://github.com/Smithay/smithay): +You'll also need the following packages, as specified by [Smithay](https://github.com/Smithay/smithay): `libwayland libxkbcommon libudev libinput libgdm libseat`, as well as `xwayland`. - Arch: ``` @@ -62,7 +52,8 @@ You'll need the following packages, as specified by [Smithay](https://github.com - NixOS: Use the provided [`shell.nix`](shell.nix). - TODO: other distros. -You'll also need Lua 5.4 for configuration. **Older versions will not work.** +If you're configuring Pinnacle using Lua, you'll additionally need Lua 5.4 for configuration. +**Older versions will not work.** Check with your package manager to see which version you have. # Building @@ -96,8 +87,20 @@ cargo run [--release] See flags you can pass in by running `cargo run -- --help` (or `-h`). # Configuration -Pinnacle is configured in Lua. Rust support is planned. +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 either of the follow in the crate root: +```sh +# For a Lua configuration +PINNACLE_CONFIG_DIR="./api/lua" cargo run + +# For a Rust configuration +PINNACLE_CONFIG_DIR="./api/rust" cargo run +``` + +## Custom configuration Pinnacle will search for a `metaconfig.toml` file in the following directories, from top to bottom: ```sh $PINNACLE_CONFIG_DIR @@ -109,50 +112,64 @@ The `metaconfig.toml` file provides information on what config to run, kill and and any environment variables you want set. For more details, see the provided [`metaconfig.toml`](api/lua/metaconfig.toml) file. -If no `metaconfig.toml` file is found, the default config will be loaded. +If no `metaconfig.toml` file is found, the default Lua config will be loaded. - -For custom configuration, you can copy [`metaconfig.toml`](api/lua/metaconfig.toml) and +### Lua +For custom configuration in Lua, you can 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`). -> Make sure `command` in your `metaconfig.toml` is set to the right file. +> If you rename `example_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. -> -> If you rename `example_config.lua` to something like `init.lua`, -> you will need to change `command` to reflect that. -### :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. +#### :information_source: Using the Lua Language Server +It is ***highly*** recommended to setup your [Lua language server](https://github.com/LuaLS/lua-language-server) +installation to use the [`api/lua`](api/lua) directory as a library. This will provide documentation, autocomplete, and error checking. -#### For VS Code: -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`. +The Lua library should have been copied to `$XDG_DATA_HOME/pinnacle` (or `~/.local/share/pinnacle`). -#### For Neovim: +##### For VS Code: +Install the [Lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) plugin, then go into +its settings and add the path above to the [`api/lua`](api/lua) directory to `Workspace: Library`. + +##### For Neovim: Pass this table into your Lua language server settings: ```lua Lua = { workspace = { library = { - "/path/to/pinnacle/api/lua" -- Your path here + "$XDG_DATA_HOME/pinnacle/lua", -- Replace $XDG_DATA_HOME with the full path + -- OR + "$HOME/.local/share/pinnacle/lua", -- Replace $HOME with the full path } } } ``` +### 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]`: +```toml +# rev is HIGHLY recommended to prevent breaking changes +pinnacle_api = { git = "http://github.com/pinnacle-comp/pinnacle", rev = "..." } +``` +3. Create the file `metaconfig.toml` at the root. Add the following to the file: +```toml +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`](api/rust/examples/example_config.rs) to `src/main.rs`. +5. Run Pinnacle! + + ### API Documentation -You can find online documentation for the Lua API [here](https://pinnacle-comp.github.io/pinnacle/main). +Lua: https://pinnacle-comp.github.io/pinnacle/main/lua.
+Rust: https://pinnacle-comp.github.io/pinnacle/main/rust. -This documentation is auto-generated from the provided LuaLS annotation through -[ldoc_gen](https://github.com/Ottatop/ldoc_gen), so there may be some errors as I work the kinks out. - -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://pinnacle-comp.github.io/pinnacle/`. +> Documentation for other branches can be reached by replacing `main` with the branch you want. # Controls The following are the default controls in the [`example_config`](api/lua/example_config.lua).