Nix: improve docs and split page

This commit is contained in:
Mihai Fufezan 2022-12-18 15:20:19 +02:00
parent 85d7d17e46
commit 211f9a808d
No known key found for this signature in database
GPG key ID: 5899325F2F120900
7 changed files with 308 additions and 274 deletions

28
pages/Nix/Cachix.md Normal file
View file

@ -0,0 +1,28 @@
Hyprland often needs dependencies which aren't yet cached in `cache.nixos.org`.
Instead of requiring you to build those dependencies (which may include `mesa`,
`ffmpeg`, etc), we provide a Cachix cache that you can add to your Nix
substituters.
The [Hyprland Cachix](https://app.cachix.org/cache/hyprland) exists to cache the
`hyprland` packages and any dependencies not found in `cache.nixos.org`.
{{< hint >}}
In order for Nix to take advantage of the cache, it has to be enabled **before**
enabling the Hyprland module(s) or adding the package.
{{< /hint >}}
{{< hint type=important >}}
Overriding Hyprland's `nixpkgs` input
(`inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";`) will make the cache
useless, since you're building from a different Nixpkgs commit.
{{< /hint >}}
```nix
# configuration.nix
{
nix.settings = {
substituters = ["https://hyprland.cachix.org"];
trusted-public-keys = ["hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="];
};
}
```

View file

@ -0,0 +1,55 @@
You can use the Home Manager module by adding it to your configuration:
For a list of available options, check the
[module file](https://github.com/hyprwm/Hyprland/blob/main/nix/hm-module.nix).
## With flakes
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager = {
url = "github:nix-community/home-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
hyprland.url = "github:hyprwm/Hyprland";
};
outputs = {nixpkgs, home-manager, hyprland, ...}: {
homeConfigurations."user@hostname" = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
hyprland.homeManagerModules.default
{wayland.windowManager.hyprland.enable = true;}
# ...
];
};
};
```
Don't forget to replace `user@hostname` with your username and hostname!
## Without flakes
```nix
# home config
{config, pkgs, inputs, ...}: let
flake-compat = builtins.fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz";
hyprland = (import flake-compat {
src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/master.tar.gz";
}).defaultNix;
in {
imports = [
hyprland.homeManagerModules.default
];
wayland.windowManager.hyprland.enable = true;
# ...
}
```

View file

@ -0,0 +1,62 @@
The NixOS module enables critical components needed to run Hyprland properly,
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.
Make sure to check out the options of the
[Nix module](https://github.com/hyprwm/Hyprland/blob/main/nix/module.nix).
Do note that the Nixpkgs Hyprland package is not actively maintained, and may be outdated.
As such, installation using the Flake is recommended.
## With flakes
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
hyprland.url = "github:hyprwm/Hyprland";
};
outputs = {nixpkgs, hyprland, ...}: {
nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
# ...
modules = [
hyprland.nixosModules.default
{programs.hyprland.enable = true;}
# ...
];
};
};
```
Don't forget to replace `HOSTNAME` with your hostname!
## Without flakes
{{< hint >}}
If you're using Hyprland through an overlay, set
`programs.hyprland.package = pkgs.hyprland;`. This also means the `xwayland`
and `nvidiaPatches` options no longer apply.
{{< /hint >}}
```nix
# configuration.nix
{config, pkgs, ...}: let
flake-compat = builtins.fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz";
hyprland = (import flake-compat {
src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/master.tar.gz";
}).defaultNix;
in {
imports = [
hyprland.nixosModules.default
];
programs.hyprland = {
enable = true;
package = hyprland.packages.${pkgs.system}.default;
};
}
```

View file

@ -0,0 +1,46 @@
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.
## With flakes
First, [enable flakes](https://nixos.wiki/wiki/Flakes#Enable_flakes).
Once you have flakes working, install Hyprland through `nix profile`:
```sh
nix profile install github:hyprwm/Hyprland
```
Since you're using Hyprland outside of NixOS, it won't be able to find graphics
drivers. To get around that, you can use [nixGL](https://github.com/guibou/nixGL).
First, install it, in the same manner you installed Hyprland:
```sh
nix profile install github:guibou/nixGL --impure
```
Impure is needed due to `nixGL`'s reliance on hardware information.
From now on, you can run Hyprland by invoking it with nixGL
```sh
nixGL Hyprland
```
or by creating a wrapper script that runs the above command inside.
## Upgrading
In order to upgrade all your packages, you can run
```sh
nix profile upgrade '.*'
```
Check the
[nix profile](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-profile.html)
command documentation for other upgrade options.

View file

@ -0,0 +1,87 @@
You can override the package through `.override` or `.overrideAttrs`. This is
easily achievable through NixOS or Home Manager.
## Package options
These are the default options that the Hyprland package is built with. These
can be changed by setting the appropriate option to `true`/`false`.
### Package
```nix
(inputs.hyprland.packages.${pkgs.default}.default.override {
enableXWayland = true;
hidpiXWayland = true;
nvidiaPatches = false;
})
```
### NixOS & HM modules
```nix
programs.hyprland = { # or wayland.windowManager.hyprland
enable = true;
xwayland = {
enable = true;
hidpi = true;
};
nvidiaPatches = false;
}
```
## Options descriptions
### XWayland
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
By default, the Nix package includes a patched wlroots that can render HiDPI
XWayland windows.
In order to enable the functionality, you have to add:
```toml
exec-once=xprop -root -f _XWAYLAND_GLOBAL_OUTPUT_SCALE 32c -set _XWAYLAND_GLOBAL_OUTPUT_SCALE 2
```
This will make XWayland programs look as if they were unscaled. To fix this, you
have to export different environment variables to make the specific toolkits
render at the proper scaling. For example
```sh
export GDK_SCALE=2
export XCURSOR_SIZE=48
```
{{< hint >}}
The GDK_SCALE variable won't conflict with wayland-native GTK programs.
{{< /hint >}}
Usually, there's no reason to disable this functionality, as it won't affect
people who don't have HiDPI screens.
If you _do_ insist on disabling it though (e.g. for adding your own patches
to wlroots), you can do so by either using the `hyprland-no-hidpi` package,
or by passing the `hidpiXWayland = false;` flag, the same way as
[disabling XWayland](#package)
### Nvidia Patches
Nvidia is notorious for not working by default with wlroots. That's why we
patch wlroots.
## Using Nix repl
If you're using Nix (and not NixOS or Home Manager) and you want to override,
you can do it like this
```sh
$ nix repl
nix-repl> :lf "github:hyprwm/Hyprland"
nix-repl> :bl outputs.packages.x86_64-linux.hyprland.override {nvidiaPatches = true;} # option = value
```
Then you can run Hyprland from the built path.

View file

@ -0,0 +1,23 @@
`xdg-desktop-portal-hyprland` (xdph) is a fork of `xdg-desktop-portal-wlr`
(xdpw), which supports window sharing and region sharing (currently broken),
apart from output (per-screen) sharing.
Due to the internal workings, `xdph` depends on the Hyrpland package for
getting the window list. However, we cannot make a cross-dependency betwen
the Hyprland flake and the `xdph` flake.
The best solution we found to make everything work properly was to override
the Hyprland package that `xdph` builds with.
In the Hyprland flake, it's done like this:
```nix
xdg-desktop-portal-hyprland = inputs.xdph.packages.${prev.system}.default.override {
hyprland-share-picker = inputs.xdph.packages.${prev.system}.hyprland-share-picker.override {inherit hyprland;};
};
```
A similar override is being done inside the NixOS module, which means you don't
have to tinker with it if you use the module.
If you don't use the module, you will want to do a similar override in your
configuration.

View file

@ -1,133 +1,19 @@
# Table of contents
{{< toc format=html >}}
## Hyprland on Nix
{{< hint type=warning >}}
Hyprland is NOT supported on NixOS stable. It may (not) compile or
work as intended. Please use the
[flake](https://github.com/hyprwm/Hyprland/blob/main/flake.nix).
{{< /hint >}}
# Install and configure Hyprland on NixOS
First of all, it is a good idea to set up [Cachix](#cachix) before continuing
with installing Hyprland.
First of all, it is a good idea to set up [Cachix](#cachix) before enabling
any of the modules/installing Hyprland.
Start off by choosing your appropriate install method on the sidebar.
Make sure to check out the options of the
[Nix module](https://github.com/hyprwm/Hyprland/blob/main/nix/module.nix).
Do note that the Nixpkgs Hyprland package is not actively maintained, and may be outdated.
As such, installation using the Flake is recommended.
## With flakes
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
hyprland.url = "github:hyprwm/Hyprland";
};
outputs = {self, nixpkgs, hyprland, ...}: {
nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
# ...
modules = [
hyprland.nixosModules.default
{programs.hyprland.enable = true;}
# ...
];
};
};
```
Don't forget to replace `HOSTNAME` with your hostname!
## Without flakes
{{< hint >}}
If you're using Hyprland through an overlay, set
`programs.hyprland.package = pkgs.hyprland;`.
{{< /hint >}}
```nix
# configuration.nix
{config, pkgs, ...}: let
flake-compat = builtins.fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz";
hyprland = (import flake-compat {
src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/master.tar.gz";
}).defaultNix;
in {
imports = [
hyprland.nixosModules.default
];
programs.hyprland = {
enable = true;
package = hyprland.packages.${pkgs.system}.default;
};
}
```
# Install and configure through Home Manager
You can use the Home Manager module by adding it to your configuration:
## With flakes
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager = {
url = "github:nix-community/home-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
hyprland.url = "github:hyprwm/Hyprland";
};
outputs = {self, nixpkgs, home-manager, hyprland, ...}: {
homeConfigurations."user@hostname" = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
hyprland.homeManagerModules.default
{wayland.windowManager.hyprland.enable = true;}
# ...
];
};
};
```
Don't forget to replace `user@hostname` with your username and hostname!
## Without flakes
```nix
# home config
{config, pkgs, inputs, ...}: let
flake-compat = builtins.fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz";
hyprland = (import flake-compat {
src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/master.tar.gz";
}).defaultNix;
in {
imports = [
hyprland.homeManagerModules.default
];
wayland.windowManager.hyprland.enable = true;
# ...
}
```
For a list of available options, check the
[module file](https://github.com/hyprwm/Hyprland/blob/main/nix/hm-module.nix).
# Modules mix'n'match
## Modules mix'n'match
- If you're on NixOS and also use HM it's a good idea to use Hyprland modules
for both. Make sure the package options are the same for both modules.
@ -137,156 +23,3 @@ For a list of available options, check the
- If you don't plan on using any module, manually enable whatever options the
modules set.
# Non-NixOS install
## With flakes
First, [enable flakes](https://nixos.wiki/wiki/Flakes#Enable_flakes).
Once you have flakes working, install Hyprland through `nix profile`:
```sh
nix profile install github:hyprwm/Hyprland
```
Since you're using Hyprland outside of NixOS, it won't be able to find graphics
drivers. To get around that, you can use [nixGL](https://github.com/guibou/nixGL).
First, install it, in the same manner you installed Hyprland:
```sh
nix profile install github:guibou/nixGL --impure
```
Impure is needed due to `nixGL`'s reliance on hardware information.
From now on, you can run Hyprland by invoking it with nixGL
```sh
nixGL Hyprland
```
or by creating a wrapper script that runs the above command inside.
## Upgrading
In order to upgrade all your packages, you can run
```sh
nix profile upgrade '.*'
```
Check the
[nix profile](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-profile.html)
command documentation for other upgrade options.
# XWayland
XWayland is enabled by default in the Nix package. You can disable it either
in the package itself, or through the module options.
## Package
```nix
(inputs.hyprland.packages.${pkgs.default}.default.override {
enableXWayland = false;
})
```
### HM module
```nix
wayland.windowManager.hyprland = {
enable = true;
xwayland.enable = false;
}
```
### NixOS module
```nix
programs.hyprland = {
enable = true;
xwayland.enable = false;
}
```
## HiDPI
By default, the Nix package includes a patched wlroots that can render HiDPI
XWayland windows.
In order to enable the functionality, you have to add:
```toml
exec-once=xprop -root -f _XWAYLAND_GLOBAL_OUTPUT_SCALE 32c -set _XWAYLAND_GLOBAL_OUTPUT_SCALE 2
```
This will make XWayland programs look as if they were unscaled. To fix this, you
have to export different environment variables to make the specific toolkits
render at the proper scaling. For example
```sh
export GDK_SCALE=2
export XCURSOR_SIZE=32
```
{{< hint >}}
The GDK_SCALE variable won't conflict with wayland-native GTK programs.
{{< /hint >}}
Usually, there's no reason to disable this functionality, as it won't affect
people who don't have HiDPI screens.
If you _do_ insist on disabling it though (e.g. for adding your own patches
to wlroots), you can do so by either using the `hyprland-no-hidpi` package,
or by passing the `hidpiXWayland = false;` flag, the same way as
[disabling XWayland](#package)
# Cachix
Hyprland often needs dependencies which aren't yet cached in `cache.nixos.org`.
Instead of requiring you to build those dependencies (which may include `mesa`,
`ffmpeg`, etc), we provide a Cachix cache that you can add to your Nix
substituters.
The [Hyprland Cachix](https://app.cachix.org/cache/hyprland) exists to cache the
`hyprland` packages and any dependencies not found in `cache.nixos.org`.
{{< hint >}}
In order for Nix to take advantage of the cache, it has to be enabled **before**
enabling the Hyprland module(s) or adding the package.
{{< /hint >}}
{{< hint type=important >}}
Overriding Hyprland's `nixpkgs` input
(`inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";`) will make the cache
useless, since you're building from a different Nixpkgs commit.
{{< /hint >}}
```nix
# configuration.nix
{
nix.settings = {
substituters = ["https://hyprland.cachix.org"];
trusted-public-keys = ["hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="];
};
}
```
# Overrides
You can override the package through `.override` or `.overrideAttrs`. This is
easily achievable through NixOS or Home Manager.
If you're using Nix (and not NixOS or Home Manager) and you want to override,
you can do it like this
```sh
$ nix repl
nix-repl> :lf "github:hyprwm/Hyprland"
nix-repl> :bl outputs.packages.x86_64-linux.hyprland.override {nvidiaPatches = true;} # option = value
```
Then you can run Hyprland from the built path.