Nix: add Plugins, Contributing and Debugging, update files

pages/Nix/Contributing and Debugging.md

@@ -0,0 +1,53 @@
+---
+title: Contributing and Debugging
+---
+
+Everything needed to build and debug Hyprland is included inside the provided
+`devShell`.
+
+To use it in the cloned repo, simply run `nix develop`.
+
+## Build in debug mode
+
+A debug build is already provided through
+`hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland-debug`.
+
+## Bisecting an issue
+
+Follow the
+[Bisecting an issue](https://wiki.hyprland.org/Crashes-and-Bugs/#bisecting-an-issue)
+guide. To build, run `nix build '.?submodules=1'`.
+
+To view logs, pass the `--print-build-logs` (`-L`) flag.
+
+To keep a failed build directory, pass the `--keep-failed` flag.
+
+## Building the Wayland stack with ASan
+
+Run `nix develop` first, then follow the
+[Building with ASan](https://wiki.hyprland.org/Crashes-and-Bugs/#bisecting-an-issue)
+guide.
+
+## Manual building
+
+Nix works differently than other build systems, so it has its own abstractions
+over popular build systems such as Meson, CMake and Ninja.
+
+In order to manually build Hyprland, you can run the following commands, while
+in the `nix develop` shell.
+
+For CMake:
+
+```bash
+$ cmakeConfigurePhase # to run the CMake configure phase
+$ ninjaBuildPhase     # to run the Ninja build phase
+$ ninjaInstallPhase   # to run the Ninja install phase
+```
+
+For Meson:
+
+```bash
+$ mesonConfigurePhase # to run the Meson configure phase
+$ ninjaBuildPhase     # to run the Ninja build phase
+$ mesonInstallPhase   # to run the Meson install phase
+```

pages/Nix/Hyprland on Home Manager.md

@@ -8,9 +8,11 @@ For a list of available options, check the
 {{< callout >}}
 
 - _(Required) NixOS Module_: enables critical components needed to run Hyprland
-  properly
+  properly. Without this, you may have issues with XDG Portals, or missing
-- _(Optional) Home-manager module_: lets you declaratively configure Hyprland
+  session files in your Display Manager.
-  {{< /callout >}}
+- _(Optional) Home Manager module_: lets you declaratively configure Hyprland
+
+{{< /callout >}}
 
 ## Installation
 
@@ -18,9 +20,6 @@ For a list of available options, check the
 
 {{< tab "Home Manager" >}}
 
-Home Manager has options for Hyprland without needing to import the Flake
-module.
-
 ```nix
 {
   wayland.windowManager.hyprland.enable = true;
@@ -66,7 +65,9 @@ Don't forget to replace `user@hostname` with your username and hostname!
 
       modules = [
         hyprland.homeManagerModules.default
-        {wayland.windowManager.hyprland.enable = true;}
+        {
+          wayland.windowManager.hyprland.enable = true;
+        }
         # ...
       ];
     };
@@ -107,7 +108,7 @@ in {
   wayland.windowManager.hyprland = {
     enable = true;
 
-    package = hyprland-flake.packages.${pkgs.system}.hyprland;
+    package = hyprland-flake.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
   }
 }
 ```
@@ -119,11 +120,11 @@ in {
 ## Usage
 
 Once the module is enabled, you can use it to declaratively configure Hyprland.
-Here is an example config, made to work with either the upstream Home Manager
+Here is an example config:
-module, or the flake-based Home Manager module.
 
 ```nix
 # home.nix
+
 {
   wayland.windowManager.hyprland.settings = {
     "$mod" = "SUPER";
@@ -157,16 +158,20 @@ module, or the flake-based Home Manager module.
 Hyprland plugins can be added through the `plugins` option:
 
 ```nix
-wayland.windowManager.hyprland.plugins = [
+{
-  inputs.hyprland-plugins.packages.${pkgs.system}.hyprbars
+  wayland.windowManager.hyprland.plugins = [
-  "/absolute/path/to/plugin.so"
+    inputs.hyprland-plugins.packages.${pkgs.stdenv.hostPlatform.system}.hyprbars
-];
+    "/absolute/path/to/plugin.so"
+  ];
+}
 ```
 
 For examples on how to build Hyprland plugins using Nix, see the
-[official plugins](https://github.com/hyprwm/hyprland-plugins).
+[Nix/Plugins](../Plugins) page.
 
-## Fixing problems with themes
+## FAQ
+
+### Fixing problems with themes
 
 If your themes for mouse cursors, icons or windows don't load correctly, try
 setting them with `home.pointerCursor` and `gtk.theme`, which enable a bunch of
@@ -175,34 +180,37 @@ compatibility options that should make the themes load in all situations.
 Example configuration:
 
 ```nix
-home.pointerCursor = {
+{
-  gtk.enable = true;
+  home.pointerCursor = {
-  # x11.enable = true;
+    gtk.enable = true;
-  package = pkgs.bibata-cursors;
+    # x11.enable = true;
-  name = "Bibata-Modern-Classic";
+    package = pkgs.bibata-cursors;
-  size = 16;
+    name = "Bibata-Modern-Classic";
-};
+    size = 16;
-
-gtk = {
-  enable = true;
-  theme = {
-    package = pkgs.flat-remix-gtk;
-    name = "Flat-Remix-GTK-Grey-Darkest";
   };
 
-  iconTheme = {
+  gtk = {
-    package = pkgs.gnome.adwaita-icon-theme;
+    enable = true;
-    name = "Adwaita";
-  };
 
-  font = {
+    theme = {
-    name = "Sans";
+      package = pkgs.flat-remix-gtk;
-    size = 11;
+      name = "Flat-Remix-GTK-Grey-Darkest";
+    };
+
+    iconTheme = {
+      package = pkgs.gnome.adwaita-icon-theme;
+      name = "Adwaita";
+    };
+
+    font = {
+      name = "Sans";
+      size = 11;
+    };
   };
-};
+}
 ```
 
-## Programs don't work in systemd services, but do on the terminal
+### Programs don't work in systemd services, but do on the terminal
 
 This problem is related to systemd not importing the environment by default. It
 will not have knowledge of `PATH`, so it cannot run the commands in the

pages/Nix/Hyprland on NixOS.md

@@ -3,7 +3,7 @@ title: Hyprland on NixOS
 ---
 
 The NixOS module enables critical components needed to run Hyprland properly,
-such as: polkit,
+such as polkit,
 [xdg-desktop-portal-hyprland](https://github.com/hyprwm/xdg-desktop-portal-hyprland),
 graphics drivers, fonts, dconf, xwayland, and adding a proper Desktop Entry to
 your Display Manager.
@@ -14,8 +14,9 @@ Make sure to check out the options of the
 {{< callout >}}
 
 - _(Required) NixOS Module_: enables critical components needed to run Hyprland
-  properly
+  properly. Without this, you may have issues with XDG Portals, or missing
-- _(Optional) Home-manager module_: lets you declaratively configure Hyprland
+  session files in your Display Manager.
+- _(Optional) Home Manager Module_: lets you declaratively configure Hyprland
 
 {{< /callout >}}
 
@@ -26,12 +27,12 @@ Make sure to check out the options of the
 ```nix
 # configuration.nix
 
-{pkgs, ...}: {
+{
   programs.hyprland.enable = true;
 }
 ```
 
-This will use the Hyprland version that Nixpkgs has.
+This will use the Hyprland version included in the Nixpkgs release you're using.
 
 {{< /tab >}}
 
@@ -69,7 +70,7 @@ this:
 {inputs, pkgs, ...}: {
   programs.hyprland = {
     enable = true;
-    package = inputs.hyprland.packages.${pkgs.system}.hyprland;
+    package = inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
   };
 }
 ```
@@ -77,7 +78,7 @@ this:
 Don't forget to change the `HOSTNAME` to your actual hostname!
 
 If you start experiencing lag and FPS drops in games or programs like Blender on
-**stable** NixOS when using the Hyprland flake, it most likely is a `mesa`
+**stable** NixOS when using the Hyprland flake, it is most likely a `mesa`
 version mismatch between your system and Hyprland.
 
 You can fix this issue by using `mesa` from Hyprland's `nixpkgs` input:
@@ -126,7 +127,7 @@ have to compile Hyprland yourself.
 in {
   programs.hyprland = {
     enable = true;
-    package = hyprland.packages.${pkgs.system}.hyprland;
+    package = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
   };
 }
 ```

pages/Nix/Hyprland on other distros.md

@@ -6,7 +6,8 @@ If you use Nix on distros other than NixOS, you can still use Hyprland.
 
 The best option would be through [Home Manager](../Hyprland-on-Home-Manager).
 
-However, if Home Manager is not for you, you can use it as a normal package.
+However, if Home Manager is not for you, Hyprland can be installed as a normal
+package.
 
 First, [enable flakes](https://nixos.wiki/wiki/Flakes#Enable_flakes). Once you
 have flakes working, install Hyprland through `nix profile`:

pages/Nix/Options & Overrides.md

@@ -2,8 +2,8 @@
 title: Options & Overrides
 ---
 
-You can override the package through `.override` or `.overrideAttrs`. This is
+You can override the package through the `.override` or `.overrideAttrs`
-easily achievable on [NixOS](../Hyprland-on-NixOS) or
+mechanisms. This is easily achievable on [NixOS](../Hyprland-on-NixOS) or
 [Home Manager](../Hyprland-on-Home-Manager).
 
 ## Package options
@@ -14,7 +14,7 @@ be changed by setting the appropriate option to `true`/`false`.
 ### Package
 
 ```nix
-(pkgs.hyprland.override { # or inputs.hyprland.packages.${pkgs.system}.hyprland
+(pkgs.hyprland.override { # or inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland
   enableXWayland = true;  # whether to enable XWayland
   legacyRenderer = false; # whether to use the legacy renderer (for old GPUs)
   withSystemd = true;     # whether to build with systemd support
@@ -24,10 +24,12 @@ be changed by setting the appropriate option to `true`/`false`.
 ### NixOS & HM modules
 
 ```nix
-programs.hyprland = { # or wayland.windowManager.hyprland
+{
-  enable = true;
+  programs.hyprland = { # or wayland.windowManager.hyprland
-  xwayland.enable = true;
+    enable = true;
-};
+    xwayland.enable = true;
+  };
+}
 ```
 
 ## Options descriptions
@@ -37,10 +39,6 @@ programs.hyprland = { # or wayland.windowManager.hyprland
 XWayland is enabled by default in the Nix package. You can disable it either in
 the package itself, or through the module options.
 
-### XWayland HiDPI
-
-See [XWayland](../../Configuring/XWayland).
-
 ## Using Nix repl
 
 If you're using Nix (and not NixOS or Home Manager) and you want to override,

pages/Nix/Plugins.md

@@ -0,0 +1,121 @@
+---
+title: Plugins
+---
+
+Hyprland plugins are managed differently on Nix than on other distros. The most
+notable change is that `hyprpm` is unsupported, but we have our own way of
+building plugins.
+
+## Using plugins from Nixpkgs
+
+In Nixpkgs, there are Hyprland plugins packaged for the Hyprland version in
+Nixpkgs. You can use them like this:
+
+```nix
+{pkgs, ...}: {
+  wayland.windowManager.hyprland.plugins = [
+    pkgs.hyprlandPlugins.<plugin>
+  ];
+}
+```
+
+You can find which plugins are included using
+`nix search nixpkgs#hyprlandPlugins`.
+
+## hyprland-plugins
+
+Official plugins made/maintained by vaxry.
+
+To use these plugins, it is recommended that you are already using the Hyprland
+flake, and **not** the Nixpkgs version.
+
+First, add the flake to your flake inputs:
+
+```nix
+{
+  inputs = {
+    hyprland.url = "git+https://github.com/hyprwm/Hyprland?submodules=1";
+
+    hyprland-plugins = {
+      url = "github:hyprwm/hyprland-plugins";
+      inputs.hyprland.follows = "hyprland";
+    };
+
+    # ...
+  }
+}
+```
+
+The `inputs.hyprland.follows` line makes hyprland-plugins use the exact Hyprland
+revision you have locked. This means there aren't any version mismatches, as
+long as you update both inputs at once.
+
+The next step is adding the plugins to Hyprland:
+
+```nix
+{inputs, pkgs, ...}: {
+  wayland.windowManager.hyprland = {
+    enable = true;
+
+    plugins = [
+      inputs.hyprland-plugins.packages.${pkgs.stdenv.hostPlatform.system}.<plugin>
+    ];
+  };
+}
+```
+
+## Building plugins with Nix
+
+The plugins inside Nixpkgs, as well as the ones in `hyprland-plugins`, are built
+using a general function, `mkHyprlandPlugin`. Any plugin can be made to work
+with it. The general usage is presented below, exemplified through hy3's
+derivation:
+
+```nix
+{pkgs, ...}: {
+  hy3 = pkgs.callPackage ({
+    lib,
+    fetchFromGitHub,
+    cmake,
+    hyprland,
+    hyprlandPlugins,
+  }:
+    hyprlandPlugins.mkHyprlandPlugin pkgs.hyprland {
+      pluginName = "hy3";
+      version = "0.39.1";
+
+      src = fetchFromGitHub {
+        owner = "outfoxxed";
+        repo = "hy3";
+        rev = "hl0.39.1";
+        hash = "sha256-PqVld+oFziSt7VZTNBomPyboaMEAIkerPQFwNJL/Wjw=";
+      };
+
+      # any nativeBuildInputs required for the plugin
+      nativeBuildInputs = [cmake];
+
+      # set any buildInputs that are not already included in Hyprland
+      # by default, Hyprland and its dependencies are included
+      buildInputs = [];
+
+      meta = {
+        homepage = "https://github.com/outfoxxed/hy3";
+        description = "Hyprland plugin for an i3 / sway like manual tiling layout";
+        license = lib.licenses.gpl3;
+        platforms = lib.platforms.linux;
+        maintainers = with lib.maintainers; [aacebedo];
+      };
+    });
+}
+```
+
+In a similar manner to `stdenv.mkDerivation`, `mkHyprlandPlugin` takes an
+attrset with mostly the same options as `mkDerivation`, as it is essentially a
+wrapper around it.
+
+The exception is that it also takes a `hyprland` package before the attrset, in
+case you want to build with a different package than the one in Nixpkgs.
+
+This is not always the best way to build for a different version, and it is
+recommended that you use an overlay to apply your desired Hyprland package in
+Nixpkgs instead.

pages/Nix/_index.md

@@ -8,27 +8,22 @@ To install Hyprland on NixOS, we provide a NixOS and a Home Manager module.
 {{< callout title=Note >}}
 
 - _(Required) NixOS Module_: enables critical components needed to run Hyprland
-  properly
+  properly. Without this, you may have issues with XDG Portals, or missing
-- _(Optional) Home-manager module_: lets you declaratively configure Hyprland
+  session files in your Display Manager.
+- _(Optional) Home Manager Module_: lets you declaratively configure Hyprland
 
 {{< /callout >}}
 
 ## NixOS module
 
-The module is now upstreamed into Nixpkgs, which means all you need in your
-configuration is:
-
 ```nix
-{config, pkgs, ...}: {
+{
   programs.hyprland.enable = true;
   # Optional, hint electron apps to use wayland:
   # environment.sessionVariables.NIXOS_OZONE_WL = "1";
 }
 ```
 
-Note that the command to run hyprland is `Hyprland` (with a capital `H`) and not
-`hyprland`.
-
 For more options, see
 [module options](https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=hyprland).