diff --git a/README.md b/README.md index e67a71b..e9c90fd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ # 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 -- A working, extensible `Makefile` +- 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 @@ -18,62 +22,65 @@ This is a github template repository. To use it, use the green **Use this templa 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](https://github.com/rizsotto/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. +**With nix**: -#### 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. +Run `nix develop` before opening your editor, or use [direnv](https://github.com/direnv/direnv). -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`. +> `nix develop` will: +> 1. Create a shell with all dependencies installed +> 2. Run `meson setup build` +> 3. Create a **clangd** compatible `compile_commands.json` -#### 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. +**Without nix**: -When users install your plugin via `hyprload`, it will also automatically set up everything -to ensure maximum compatibility. +Run this command to setup the build directory and generate a **clangd** compatible +`compile_commands.json` -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`) +```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 3 variables that need +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. -- `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. +- `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 having the headers available, the steps to build are simple + +After `nix develop`, 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 + +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