Installation

hyprpm

hyprpm is the primary non-Nix installation path.

hyprpm add https://github.com/sandwichfarm/hyprexpo
hyprpm enable hyprexpo
hyprpm reload

The plugin repository is named hyprexpo in hyprpm.toml, and the built output is hyprexpo.so.

When registering from a source checkout, use the guarded wrapper:

./scripts/hyprpm-add.sh https://github.com/sandwichfarm/hyprexpo

It also accepts a revision argument for the development track. Before invoking hyprpm, an explicit revision is checked in a fresh clone against maintained branch or release-tag history. A temporary PR branch or a PR-only commit is rejected. A locally available commit is not sufficient: squash merges can leave it unavailable to a future normal clone.

Build From Source

Build dependencies are a C++23 compiler, pkg-config, Hyprland development headers, and these pkg-config packages:

hyprland pixman-1 libdrm pangocairo libinput libudev wayland-server xkbcommon lua5.4

The build prefers the lua5.4 pkg-config module and falls back to lua for distributions such as Fedora where lua-devel exposes the generic module name.

Build with the Makefile:

git clone https://github.com/sandwichfarm/hyprexpo
cd hyprexpo
make all

Alternative build entry points are available:

meson setup build
meson compile -C build

cmake -S . -B build
cmake --build build

Install a Local Build

For development, do not replace the hyprpm-managed copy first. Hyprland's plugin development docs recommend testing in a nested debug session and loading the built plugin by absolute path with hyprctl plugin load.

Launch a disposable nested session that builds and loads a user-owned local plugin artifact:

./scripts/run-nested.sh

If you already have a disposable Hyprland session running, build to ${XDG_CACHE_HOME:-$HOME/.cache}/hyprexpo/hyprexpo.so and load or reload it:

make dev-load
make dev-reload

Only replace the hyprpm-managed copy when you intentionally want the installed plugin to point at this checkout's build:

make install
hyprpm reload

make install and scripts/dev-link.sh check the saved repository.rev before changing a managed destination. The preflight uses Git and Python 3.11+ and requires network access only for an explicit revision. Run it independently with make check-hyprpm-state (INSTALL_USER and INSTALL_DIR select the same destination as make install). Failed or unreadable state stops replacement; see saved-revision recovery. These commands never persist a test revision. Use the development load commands above for PR testing.

If the hyprpm artifact path is root-owned, keep the privilege at the command line and preserve the target user explicitly:

sudo make install INSTALL_USER="$USER"
hyprpm reload

Equivalent manual install:

make check-hyprpm-state &&
install -Dm755 hyprexpo.so \
    "/var/cache/hyprpm/$USER/hyprexpo/hyprexpo.so"
hyprpm reload

Use sudo install ... only if that destination is intentionally root-owned.

WARNING

Use install, not plain cp, when replacing a loaded .so. Hyprland maps the plugin into the running process. Overwriting that file in place can corrupt the live mapping and crash the session.

Nix

Nix users should build HyprExpo through the Nix Hyprland plugin path instead of mixing a hyprpm artifact into a Nix-managed Hyprland session. The repository contains default.nix, which uses hyprlandPlugins.mkHyprlandPlugin so the plugin follows the Hyprland input supplied by the caller.

Hyprland plugins are ABI-sensitive. Keep the plugin build and running Hyprland revision aligned. If Hyprland is updated, rebuild HyprExpo from the same Hyprland input before loading it.