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

Add hyprpm docs (#410)

Browse source 
---------

Co-authored-by: Mihai Fufezan <fufexan@protonmail.com>
This commit is contained in:
Vaxry 2023-12-07 10:41:25 +00:00 committed by GitHub
parent 24e278d8a5
commit 093b835fbd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 106 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -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 >}} {{< 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 ## 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 ## 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, It's always advised to use the API entries whenever possible, as they are
but it should not be treated as the default way of doing things. 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 It is, of course, possible to use the internal methods by just including the
that methods that "seem" fundamental, like e.g. `focusWindow` or `mouseMoveUnified` probably are, and are proper headers, but it should not be treated as the default way of doing things.
unlikely to change their general method of functioning.
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
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. 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
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)

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

@ -24,111 +24,48 @@ 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 -n` 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. `-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 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 For all options of `hyprpm`, run `hyprpm -h`.
Now, enter your plugin of choice's directory, for example: ### Manual
```sh
cd ../borders-plus-plus
```
Compile it: Different plugins may have different build methods, refer to their instructions.
```sh
make all
```
Congratulations! A file called `plugin_name.so` should now be in your current directory. If you don't have hyprland headers installed, clone hyprland, checkout to your version,
Copy it wherever you please to keep it organized and load with `hyprctl plugin load <path>`. 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 ## 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).