home-manager/docs/nix-flakes.adoc
mtths 9da6c0232e
docs: explain how to enable flakes on NixOS
Since `nix.conf` is generated when using NixOS, it cannot be edited.

Instead we add the instructions described by Xe in
https://xeiaso.net/blog/nix-flakes-1-2022-02-21
2022-09-29 12:15:38 +02:00

242 lines
7 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[[ch-nix-flakes]]
== Nix Flakes
:nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes
Home Manager includes a `flake.nix` file for compatibility with {nixos-wiki-flakes}[Nix Flakes].
The support is still experimental and may change in backwards incompatible ways.
[[sec-flakes-prerequisties]]
=== Prerequisties
* Install Nix 2.4 or later, or have it in `nix-shell`.
* Enable experimental features `nix-command` and `flakes`.
+
** When using NixOS, add the following to your `configuration.nix` and rebuild your system.
+
[source,nix]
nix = {
package = pkgs.nixFlakes;
extraOptions = ''
experimental-features = nix-command flakes
'';
};
+
** If you are not using NixOS, add the following to `nix.conf` (located at `~/.config/nix/` or `/etc/nix/nix.conf`).
+
[source,bash]
experimental-features = nix-command flakes
+
You may need to restart the Nix daemon with, for example, `sudo systemctl restart nix-daemon.service`.
+
** Alternatively, you can enable flakes on a per-command basis with the following additional flags to `nix` and `home-manager`:
+
[source,console]
----
$ nix --extra-experimental-features "nix-command flakes" <sub-commands>
$ home-manager --extra-experimental-features "nix-command flakes" <sub-commands>
----
* Prepare your Home Manager configuration (`home.nix`).
+
Unlike the channel-based setup,
`home.nix` will be evaluated when the flake is built,
so it must be present before bootstrap of Home Manager from the flake.
See <<sec-usage-configuration>> for introduction about
writing a Home Manager configuration.
[[sec-flakes-standalone]]
=== Standalone setup
1. Set up a flake with a `flake.nix` as follows:
+
[source,nix]
----
{
description = "Home Manager configuration of Jane Doe";
inputs = {
# Specify the source of Home Manager and Nixpkgs.
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
home-manager = {
url = "github:nix-community/home-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
};
outputs = { nixpkgs, home-manager, ... }:
let
system = "x86_64-linux";
pkgs = nixpkgs.legacyPackages.${system};
in {
homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration {
inherit pkgs;
# Specify your home configuration modules here, for example,
# the path to your home.nix.
modules = [
./home.nix
];
# Optionally use extraSpecialArgs
# to pass through arguments to home.nix
};
};
}
----
+
[NOTE]
====
* The above example tracks the master branch of Home Manager
and nixos-unstable branch of Nixpkgs.
If you would like to use the `release-22.05` branch,
change the `home-manager` input url to `github:nix-community/home-manager/release-22.05`
and `nixpkgs` url to `github:NixOS/nixpkgs/nixos-22.05`.
* The Home Manager library is exported by the flake under
`lib.hm`.
* You can use the above `flake.nix` as a template in `~/.config/nixpkgs` by
[source,console]
$ nix flake new ~/.config/nixpkgs -t github:nix-community/home-manager
====
2. Install Home Manager and apply the configuration by
+
[source,console]
----
$ nix build --no-link <flake-uri>#homeConfigurations.jdoe.activationPackage
$ "$(nix path-info <flake-uri>#homeConfigurations.jdoe.activationPackage)"/activate
----
+
Substitute `<flake-uri>` with the flake URI of the configuration flake.
If `flake.nix` resides in `~/.config/nixpkgs`,
`<flake-uri>` may be `~/.config/nixpkgs`
as a Git tree or `path:~/.config/nixpkgs` if not.
3. Since the release `21.05`,
building a flake-based configuration is as simple as
+
[source,console]
$ home-manager switch --flake '<flake-uri>#jdoe'
+
once home-manager is installed.
+
Here, `jdoe` is a configuration specified in the flake file,
and `<flake-uri>#jdoe` will be expanded to
`<flake-uri>#homeConfigurations.jdoe.activationPackage`
and be built by Nix.
[NOTE]
====
The flake inputs are not upgraded automatically when switching.
The analogy to the command `home-manager --update ...` is `nix flake update`.
If updating more than one input is undesirable,
the command `nix flake lock --update-input <input-name>` can be used.
You can also pass flake-related options
such as `--recreate-lock-file` or `--update-input [input]`
to `home-manager` when building/switching,
and these options will be forwarded to `nix build`.
See the {nixos-wiki-flakes}[NixOS Wiki page] for detail.
====
[[sec-flakes-nixos-module]]
=== NixOS module
To use Home Manager as a NixOS module,
a bare-minimum `flake.nix` would be as follows:
[source,nix]
----
{
description = "NixOS configuration";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
home-manager.url = "github:nix-community/home-manager";
home-manager.inputs.nixpkgs.follows = "nixpkgs";
};
outputs = inputs@{ nixpkgs, home-manager, ... }: {
nixosConfigurations = {
hostname = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
home-manager.nixosModules.home-manager
{
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
home-manager.users.jdoe = import ./home.nix;
# Optionally, use home-manager.extraSpecialArgs to pass
# arguments to home.nix
}
];
};
};
};
}
----
The Home Manager configuration is then part of the NixOS configuration
and is automatically rebuilt with the system when using the appropriate command
for the system, such as `nixos-rebuild switch --flake <flake-uri>`.
You can use the above `flake.nix` as a template in `/etc/nixos` by
[source,console]
$ nix flake new /etc/nixos -t github:nix-community/home-manager#nixos
[[sec-flakes-nix-darwin-module]]
=== nix-darwin module
The flake-based setup of the Home Manager nix-darwin module
is similar to that of NixOS. The `flake.nix` would be:
[source,nix]
----
{
description = "NixOS configuration";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
darwin.url = "github:lnl7/nix-darwin";
darwin.inputs.nixpkgs.follows = "nixpkgs";
home-manager.url = "github:nix-community/home-manager";
home-manager.inputs.nixpkgs.follows = "nixpkgs";
};
outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: {
darwinConfigurations = {
hostname = darwin.lib.darwinSystem {
system = "x86_64-darwin";
modules = [
./configuration.nix
home-manager.darwinModules.home-manager
{
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
home-manager.users.jdoe = import ./home.nix;
# Optionally, use home-manager.extraSpecialArgs to pass
# arguments to home.nix
}
];
};
};
};
}
----
and it is also rebuilt with the nix-darwin generations.
The rebuild command here may be `darwin-rebuild switch --flake <flake-uri>`.
You can use the above `flake.nix` as a template in `~/.config/darwin` by
[source,console]
$ nix flake new ~/.config/darwin -t github:nix-community/home-manager#nix-darwin