Hyprland Plugin Template

The goal of this repository is to create a robust Hyprland plugin template, with

• A working, extensible Makefile
• 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

Text editor and autocompletion

For a code editor, I recommend VS Code or Neovim, but anything that can use Clangd will work If you use Clangd, make clangd will generate a simple compile_flags.txt file with the proper include paths and flags, which will make Clangd recognize the includes etc. Alternatively, use bear to generate compile_commands.json which is a bit more granular.

Warning: Compiling the plugin should still be done using GCC 12+. Clang does not properly build Hyprland, and is very fussy about the hook system. You will most likely encounter errors like cannot cast from type 'void (CCompositor::*)(CWindow *, wlr_surface *)' to pointer type 'void *' This won't happen when building with GCC and can be ignored.

Hyprland headers

The most important part of setting up plugin builds is getting access to Hyprland headers Plugins can hook directly into Hyprland's C++ code, which is what makes them so powerful. Because of that, they need to be able to see the Hyprland source.

When building your own plugins for testing, make sure you have the pkg-config path set up correctly and that your installation of Hyprland has the headers in /usr/local/include/hyprland. This requires running make pluginenv.

Hyprload, and why it's useful for plugin development

If you use hyprload, it makes sure that the pkg-config path and headers are always available. By design it keeps a copy of Hyprland source code up to date with the Hyprland version you're running in $HOME/.local/share/hyprload/hyprland, and builds pluginenv whenever needed.

When users install your plugin via hyprload, it will also automatically set up everything to ensure maximum compatibility.

When developing plugins and frequently changing them, the make install command will automatically place your plugin build in the directory hyprload automatically loads. You can reload plugins when testing using the hyprload reload dispatcher (bind it in your hyprland.conf, or execute via hyprctl dispatch hyprload reload)

Making it Your Own

To change your plugin name, version, and author (that's you!) there are 3 variables 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.
• Makefile: At the top of the file, the variable PLUGIN_NAME contains the name of the plugin .so that will be built. This should generally match your plugin name.
• 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

Building and testing

After having the headers available, the steps to build are simple

Manually

• make: This will build the PLUGIN_NAME.so file.
• hyprctl plugin unload $PWD/PLUGIN_NAME.so: If you have an old version loaded, unload it
• hyprctl plugin load $PWD/PLUGIN_NAME.so: Load the plugin

Do note that if you only load/unload from the same path, Hyprland can ignore your changes.

Using hyprload

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!