From fc11217823b1ab76f205738ae93542f8d7f9c89f Mon Sep 17 00:00:00 2001 From: Vaxry Date: Wed, 6 Dec 2023 20:09:54 +0000 Subject: [PATCH] add hyprpm docs --- .../Plugins/Development/Plugin-Guidelines.md | 46 +++++++- pages/Plugins/Using-Plugins.md | 100 +++--------------- 2 files changed, 62 insertions(+), 84 deletions(-) diff --git a/pages/Plugins/Development/Plugin-Guidelines.md b/pages/Plugins/Development/Plugin-Guidelines.md index 9fd0e4d..519f131 100644 --- a/pages/Plugins/Development/Plugin-Guidelines.md +++ b/pages/Plugins/Development/Plugin-Guidelines.md @@ -2,6 +2,50 @@ This page documents the recommended guidelines for making a stable and neat plug {{< toc >}} +## Making your plugin compatible with hyprpm +In order for your plugin to be installable by hyprpm, you need a manifest. + +Make a file in the root of your repository called `hyprpm.toml`. + +### Repository metadata +At the beginning, put some metadata about your plugin: +```toml +[repository] +name = "MyPlugin" +authors = ["Me"] +commit_pins = [ + ["3bb9c7c5cf4f2ee30bf821501499f2308d616f94", "efee74a7404495dbda70205824d6e9fc923ccdae"], + ["d74607e414dcd16911089a6d4b6aeb661c880923", "efee74a7404495dbda70205824d6e9fc923ccdae"] +] +``` +`name` and `authors` are required. `commit_pins` are optional. See a bit below for what commit pins are. + +### Plugins +For each plugin, make a category like this: +```toml +[plugin-name] +description = "An epic plugin that will change the world!" +authors = ["Me"] +output = "plugin.so" +build = [ + "make all" +] +``` +`description`, `authors` are optional. `output` and `build` are required. +`build` are the commands that hyprpm will run in the root of the repo to build the plugin. +Every command will reset the cwd to the repo root. +`output` is the path to the output `.so` file from the root of the repo. + +### Commit pins +Commit pins allow you to manage versioning of your plugin. they are pairs of `hash,hash`, where the first +hash is the hyprland hash, and the second is your plugin's hash. + +For example, in the manifest above, `d74607e414dcd16911089a6d4b6aeb661c880923` corresponds to hyprland's `0.33.1` +release, which means that if someone is running `0.33.1`, hyprpm will reset your plugin to commit hash +`efee74a7404495dbda70205824d6e9fc923ccdae`. + +It's recommended you add a pin for each hyprland release. If no pin matches, latest git will be used. + ## Formatting Although Hyprland plugins obviously are not _required_ to follow Hyprland's formatting, naming conventions, etc. it might be a good idea to keep your code consistent. See `.clang-format` in the Hyprland repo. @@ -25,4 +69,4 @@ Always prefer using Event Hooks. ## Threads The Wayland event loop is strictly single-threaded. It is not recommended to create threads in your code, unless -they are fully detached from the Hyprland process. (e.g. saving a file) \ No newline at end of file +they are fully detached from the Hyprland process. (e.g. saving a file) diff --git a/pages/Plugins/Using-Plugins.md b/pages/Plugins/Using-Plugins.md index 916ce0c..c68c3ff 100644 --- a/pages/Plugins/Using-Plugins.md +++ b/pages/Plugins/Using-Plugins.md @@ -24,111 +24,45 @@ to use you will have to find yourself. ## Installing / Using plugins -Clone and compile plugin(s) of your choice. +It is _highly_ recommended you use the Hyprland Plugin Manager, `hyprpm`. For manual instructions, see a bit below. -{{< hint type=tip >}} -Due to the fact that plugins share C++ objects, your plugins must be -compiled with the same compiler as Hyprland, and on the same architecture. +### hyprpm -In rare cases, they might even need to be compiled on the same machine. +Find a repository you want to install plugins from. As an example, we will use [hyprland-plugins](https://github.com/hyprwm/hyprland-plugins). -Official releases are always compiled with `gcc`. -{{< /hint >}} - -Place them somewhere on your system. - -In hyprland, run in a terminal: ```sh -hyprctl plugin load /path/to/the/plugin.so +hyprpm add https://github.com/hyprwm/hyprland-plugins ``` -You can also use a plugin entry in your configuration file. -```ini -plugin = /my/epic/plugin.so -``` -Plugins added to your configuration file will be unloaded if you remove their entries. -{{< hint type=important >}} -The plugin path has to be absolute. (starting from the root of the filesystem) -{{< /hint >}} - -## Compiling official plugins - -Official plugins can be found at [hyprwm/hyprland-plugins](https://github.com/hyprwm/hyprland-plugins). - -Clone the repo and enter it: +once it finishes, you can list your installed plugins with ```sh -git clone https://github.com/hyprwm/hyprland-plugins && cd hyprland-plugins -``` -{{< hint type=tip >}} -If you build Hyprland manually and install using `sudo make install` (NOT meson) you can completely skip -this next step of getting the sources and checking them out. -{{< /hint >}} - -### Preparing Hyprland sources for plugins - -{{< hint type=note >}} - -This step is not required if any of those apply to you: - - You use the Arch official `hyprland` package - - You install manually with `sudo make install` - -{{< /hint >}} - -Inside the repo, clone Hyprland and enter it: -```sh -git clone --recursive https://github.com/hyprwm/Hyprland && cd Hyprland +hyprpm list ``` -If you are using a release version of Hyprland, checkout it: (in this example it's `v0.24.1`, adjust to your release ver) -```sh -git checkout tags/v0.24.1 -``` +and enable or disable them via `hyprpm enable name` and `hyprpm disable name`. -Prepare Hyprland sources: -```sh -make all -sudo make installheaders -``` +In order for the plugins to be loaded into hyprland, run `hyprpm reload`. -{{< hint type=note >}} -If you are using hyprland-git, make _sure_ the commit you use matches the cloned sources. +You can add `exec-once = hyprpm reload` to your hyprland config to have plugins loaded at startup. -You can check the commit you are running with `hyprctl version`, and change the commit in the sources -with `git reset --hard `. Make sure to remove the `dirty` at the end of the hash from `hyprctl version` -or else git will reject it. -{{< /hint >}} +In order update your plugins, run `hyprpm update`. -### Building +### Manual -Now, enter your plugin of choice's directory, for example: -```sh -cd ../borders-plus-plus -``` +Different plugins may have different build methods, refer to their instructions. -Compile it: -```sh -make all -``` +If you don't have hyprland headers installed, clone hyprland, checkout to your version, +build hyprland, and run `sudo make installheaders`. Then build your plugin(s). -Congratulations! A file called `plugin_name.so` should now be in your current directory. -Copy it wherever you please to keep it organized and load with `hyprctl plugin load `. +To load plugins manually, use `hyprctl plugin load path` !NOTE: Path HAS TO BE ABSOLUTE! + +You can unload plugins with `hyprctl plugin unload path`. ## FAQ About Plugins -### My plugin crashes Hyprland! -Oops. Make sure your plugin is compiled on the same machine as Hyprland. If that doesn't help, -ask the plugin's maintainer to fix it. - -### My plugin no longer works after updating Hyprland! -Make sure to re-compile the plugin after each Hyprland update. -Every hyprland version change (even from one commit to another) requires plugins to be re-compiled. - ### How do I list my loaded plugins? `hyprctl plugin list` -### Can I unload a plugin? -Yes. `hyprctl plugin unload /path/to/plugin.so` - ### How do I make my own plugin? See [here](../Development/Getting-Started).