Hyprland Plugin Template

This is a fork of hyprland-community/hyprland-plugin-template, 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 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 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.

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

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
• 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 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!