mirror of
https://git.allpurposem.at/mat/WiggleWobble.git
synced 2025-12-23 21:11:29 +01:00
101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# Hyprland Plugin Template
|
|
|
|
This is a fork of [hyprland-community/hyprland-plugin-template](https://github.com/hyprland-community/hyprland-plugin-template/fork),
|
|
with more opinionated build tools (meson and optionally nix).
|
|
|
|
The goal of this repository is to create a robust `Hyprland` plugin template, with
|
|
- nix
|
|
- A working, extensible `meson.build`
|
|
- [`hyprload`](https://github.com/Duckonaut/hyprload) support out of the box
|
|
- Environment set up guide
|
|
- Clangd flags set up for autocomplete and error checking
|
|
|
|
It is highly recommended to read the [Plugin development](https://wiki.hyprland.org/Plugins/Development/Getting-Started/)
|
|
section of the Hyprland Wiki first. Some stuff will be different in this template, but it gives
|
|
you a general idea about what's going on
|
|
|
|
## Support
|
|
If you have any issues setting this up, open an issue in this repository. I will try to help.
|
|
|
|
## Setup
|
|
This is a github template repository. To use it, use the green **Use this template** button
|
|
at the top of the repository file view.
|
|
|
|
### Setting up a development environment
|
|
|
|
**With nix**:
|
|
|
|
Run `nix develop` before opening your editor, or use [direnv](https://github.com/direnv/direnv).
|
|
|
|
> `nix develop` will:
|
|
> 1. Create a shell with all dependencies installed
|
|
> 2. Run `meson setup build`
|
|
> 3. Create a **clangd** compatible `compile_commands.json`
|
|
|
|
**Without nix**:
|
|
|
|
Run this command to setup the build directory and generate a **clangd** compatible
|
|
`compile_commands.json`
|
|
|
|
```bash
|
|
meson setup build && sed -e 's/c++23/c++2b/g' ./build/compile_commands.json > ./compile_commands.json
|
|
```
|
|
|
|
#### Making it Your Own
|
|
To change your plugin name, version, and author (that's you!) there are a few things that need
|
|
changing (I would like to streamline it somehow, but it's manageable for now)
|
|
- `main.cpp`: The `PLUGIN_INIT` function returns a struct with the plugin name, description,
|
|
author and version. Change those.
|
|
- `meson.build`: At the top of the file, the project name `example` should be changed.
|
|
- `src/meson.build`: The name of the `shared_library` (first argument) should be changed. The
|
|
resulting library will be changed to `build/src/libYOUR_PLUGIN.so` so you should change the
|
|
`[examplePlugin.build.output]` entry as well
|
|
- `hyprload.toml`: The `[examplePlugin]` and `[examplePlugin.build]` should be changed to match
|
|
the name of your plugin. `hyprload` will look at these dictionaries for info about the plugin.
|
|
For more info, see [hyprload docs](https://github.com/Duckonaut/hyprload#format)
|
|
- `plugin.nix`: Change `pname` and the `meta` section.
|
|
|
|
## Building and testing
|
|
|
|
After `nix develop`, the steps to build are simple
|
|
|
|
### Manually
|
|
|
|
This is how you'll build the plugin during development
|
|
|
|
- `meson setup build`: This will create the `build` directory. You don't always need to run this
|
|
after the first time, but sometimes things get borked (don't know why) and you need to `rm -rf
|
|
build` and re-setup
|
|
- `meson compile -Cbuild`: This will build the `PLUGIN_NAME.so` file.
|
|
- `hyprctl plugin unload $PWD/build/src/PLUGIN_NAME.so`: If you have an old version loaded, unload it
|
|
- `hyprctl plugin load $PWD/build/src/PLUGIN_NAME.so`: Load the plugin
|
|
|
|
Do note that if you only load/unload from the same path, Hyprland can ignore your changes.
|
|
|
|
### Via nix
|
|
|
|
You don't need this that often for development but you can build directly without `nix develop`
|
|
with `nix build`.
|
|
|
|
### Using `hyprload`
|
|
|
|
TODO: update
|
|
|
|
This works rather well in nested Hyprland sessions, since `hyprload` keeps sessions separate.
|
|
- `make install`: This will build and copy the plugin to the `hyprload` plugin directory.
|
|
- Reload `hyprload` for the changes to take effect
|
|
|
|
This doesn't have the issue of ignoring changes, because of how `hyprload` handles its loaded
|
|
plugins.
|
|
|
|
### Nested Hyprland
|
|
Developing a plugin may be tough. You might crash Hyprland a couple times. For this reason,
|
|
it's a good idea to develop them in a nested Hyprland session. If you run `Hyprland` from an
|
|
existing Hyprland session, it'll open in a window. If this window crashes, it's pretty much fine!
|
|
Refer to the [Hyprland wiki](http://wiki.hyprland.org/Plugins/Development/Getting-Started/#setting-up-a-development-environment)
|
|
for more info.
|
|
|
|
## ""Publishing""
|
|
If you haven't messed up your `hyprload.toml` manifest too badly, anyone should be able to use
|
|
your plugin by just adding `'YOUR_GITHUB_NAME/YOUR_PLUGIN'` to their own `hyprload.toml` config!
|