hyprwm/hyprland-wiki
1
0
Fork 0
mirror of https://github.com/hyprwm/hyprland-wiki.git synced 2024-11-15 01:35:58 +01:00
Code Issues Projects Releases Packages Wiki Activity

add hyprpm docs

Browse source
This commit is contained in:
Vaxry 2023-12-06 20:09:54 +00:00
parent 24e278d8a5
commit fc11217823
2 changed files with 62 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

46
pages/Plugins/Development/Plugin-Guidelines.md
View file

@ -2,6 +2,50 @@ This page documents the recommended guidelines for making a stable and neat plug
{{< toc >}} {{< 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 ## Formatting
Although Hyprland plugins obviously are not _required_ to follow Hyprland's formatting, naming conventions, etc. 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. 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 ## Threads
The Wayland event loop is strictly single-threaded. It is not recommended to create threads in your code, unless 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) they are fully detached from the Hyprland process. (e.g. saving a file)

100
pages/Plugins/Using-Plugins.md
View file

@ -24,111 +24,45 @@ to use you will have to find yourself.
## Installing / Using plugins ## 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 >}} ### hyprpm
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.
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 ```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 >}} once it finishes, you can list your installed plugins with
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:
```sh ```sh
git clone https://github.com/hyprwm/hyprland-plugins && cd hyprland-plugins hyprpm list
```
{{< 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
``` ```
If you are using a release version of Hyprland, checkout it: (in this example it's `v0.24.1`, adjust to your release ver) and enable or disable them via `hyprpm enable name` and `hyprpm disable name`.
```sh
git checkout tags/v0.24.1
```
Prepare Hyprland sources: In order for the plugins to be loaded into hyprland, run `hyprpm reload`.
```sh
make all
sudo make installheaders
```
{{< hint type=note >}} You can add `exec-once = hyprpm reload` to your hyprland config to have plugins loaded at startup.
If you are using hyprland-git, make _sure_ the commit you use matches the cloned sources.
You can check the commit you are running with `hyprctl version`, and change the commit in the sources In order update your plugins, run `hyprpm update`.
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 >}}
### Building ### Manual
Now, enter your plugin of choice's directory, for example: Different plugins may have different build methods, refer to their instructions.
```sh
cd ../borders-plus-plus
```
Compile it: If you don't have hyprland headers installed, clone hyprland, checkout to your version,
```sh build hyprland, and run `sudo make installheaders`. Then build your plugin(s).
make all
```
Congratulations! A file called `plugin_name.so` should now be in your current directory. To load plugins manually, use `hyprctl plugin load path` !NOTE: Path HAS TO BE ABSOLUTE!
Copy it wherever you please to keep it organized and load with `hyprctl plugin load <path>`.
You can unload plugins with `hyprctl plugin unload path`.
## FAQ About Plugins ## 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? ### How do I list my loaded plugins?
`hyprctl plugin list` `hyprctl plugin list`
### Can I unload a plugin?
Yes. `hyprctl plugin unload /path/to/plugin.so`
### How do I make my own plugin? ### How do I make my own plugin?
See [here](../Development/Getting-Started). See [here](../Development/Getting-Started).