Add hyprpm docs (#410)
--------- Co-authored-by: Mihai Fufezan <fufexan@protonmail.com>
This commit is contained in:
Vaxry
GitHub
parent
24e278d8a5
commit
093b835fbd
|
|
@ -1,28 +1,100 @@
|
|||
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.
|
||||
|
||||
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
|
||||
[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!"
|
||||
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 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.
|
||||
|
||||
## 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)
|
||||
|
|
|
|||
|
|
@ -24,111 +24,48 @@ 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 -n` to your hyprland config to have plugins loaded at startup.
|
||||
`-n` will make hyprpm send a notification if anything goes wrong (e.g. update needed)
|
||||
|
||||
You can check the commit you are running with `hyprctl version`, and change the commit in the sources
|
||||
with `git reset --hard <hash>`. 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
|
||||
For all options of `hyprpm`, run `hyprpm -h`.
|
||||
|
||||
Now, enter your plugin of choice's directory, for example:
|
||||
```sh
|
||||
cd ../borders-plus-plus
|
||||
```
|
||||
### Manual
|
||||
|
||||
Compile it:
|
||||
```sh
|
||||
make all
|
||||
```
|
||||
Different plugins may have different build methods, refer to their instructions.
|
||||
|
||||
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 <path>`.
|
||||
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).
|
||||
|
||||
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).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue