From 524bef5b93ce2733244f0b3e7aed2d1a03ad735a Mon Sep 17 00:00:00 2001 From: Mihai Fufezan Date: Thu, 7 Dec 2023 00:25:03 +0200 Subject: [PATCH] reword, format --- .../Plugins/Development/Plugin-Guidelines.md | 75 ++++++++++++------- 1 file changed, 50 insertions(+), 25 deletions(-) diff --git a/pages/Plugins/Development/Plugin-Guidelines.md b/pages/Plugins/Development/Plugin-Guidelines.md index 29e0e38..bcbc3ba 100644 --- a/pages/Plugins/Development/Plugin-Guidelines.md +++ b/pages/Plugins/Development/Plugin-Guidelines.md @@ -1,17 +1,21 @@ -This page documents the recommended guidelines for making a stable and neat plugin. +This page documents the recommended guidelines for making a stable and neat +plugin. {{< toc >}} ## Making your plugin compatible with hyprpm -In order for your plugin to be installable by hyprpm, you need a manifest. -hyprpm will parse hyprload manifests just fine, but it's recommended to use the more -powerful hyprpm manifest. +In order for your plugin to be installable by `hyprpm`, you need a manifest. + +`hyprpm` will parse `hyprload` manifests just fine, but it's recommended to use +the more powerful hyprpm 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" @@ -21,10 +25,14 @@ commit_pins = [ ["d74607e414dcd16911089a6d4b6aeb661c880923", "efee74a7404495dbda70205824d6e9fc923ccdae"] ] ``` -`name` and `authors` are required. `commit_pins` are optional. See a bit below for what commit pins are. + +`name` and `authors` are required. `commit_pins` are optional. See +[commit pins](#commit-pins) for more info. ### Plugins + For each plugin, make a category like this: + ```toml [plugin-name] description = "An epic plugin that will change the world!" @@ -34,42 +42,59 @@ 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. + +`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 +Commit pins allow you to manage versioning of your plugin. they are pairs of +`hash,hash`, where the first hash is the Hyprland commit hash, and the second is +your plugin's corresponding commit 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. +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. + +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`](https://github.com/hyprwm/Hyprland/blob/main/.clang-format) in +the Hyprland repo. ## Usage of the API -It's always advised to use the API entries whenever possible, as they are guaranteed stability as long as the version -matches. -It is, of course, possible to use the internal methods by just including the proper headers, -but it should not be treated as the default way of doing things. +It's always advised to use the API entries whenever possible, as they are +guaranteed stability as long as the version matches. -Hyprland's internal methods may be changed, removed or added without any prior notice. It is worth nothing though -that methods that "seem" fundamental, like e.g. `focusWindow` or `mouseMoveUnified` probably are, and are -unlikely to change their general method of functioning. +It is, of course, possible to use the internal methods by just including the +proper headers, but it should not be treated as the default way of doing things. + +Hyprland's internal methods may be changed, removed or added without any prior +notice. It is worth nothing though that methods that "seem" fundamental, like +e.g. `focusWindow` or `mouseMoveUnified` probably are, and are unlikely to +change their general method of functioning. ## Function Hooks -Function hooks allow your plugin to intercept all calls to a function of your choice. They are to be treated as -a last resort, as they are the easiest thing to break between updates. + +Function hooks allow your plugin to intercept all calls to a function of your +choice. They are to be treated as a last resort, as they are the easiest thing +to break between updates. 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) + +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)