mirror of
https://github.com/nix-community/home-manager
synced 2024-11-23 11:39:46 +01:00
docs: move Nix Flakes documentation to manual
In the manual: * Add chapter Nix Flakes * Add links to sections of chapter "Using Home Manager" In README.md: * Remove section "Nix Flakes" * Add manual reference at the buttom of section "Installation"
This commit is contained in:
Shamrock Lee
Robert Helgesson
parent
e2aa1f5986
commit
85bbc6cc12
4 changed files with 228 additions and 93 deletions
97
README.md
97
README.md
|
|
@ -77,6 +77,9 @@ Home Manager can be used in three primary ways:
|
||||||
installation][manual nix-darwin install] in the manual for a
|
installation][manual nix-darwin install] in the manual for a
|
||||||
description of this setup.
|
description of this setup.
|
||||||
|
|
||||||
|
Home Manager provides both the channel-based setup and the flake-based one.
|
||||||
|
See [Nix Flakes][manual nix flakes] for a description of the flake-based setup.
|
||||||
|
|
||||||
Translations
|
Translations
|
||||||
------------
|
------------
|
||||||
|
|
||||||
|
|
@ -90,99 +93,6 @@ contribute to the translation effort then start by going to the
|
||||||
<img src="https://hosted.weblate.org/widgets/home-manager/-/multi-auto.svg" alt="Translation status" />
|
<img src="https://hosted.weblate.org/widgets/home-manager/-/multi-auto.svg" alt="Translation status" />
|
||||||
</a>
|
</a>
|
||||||
|
|
||||||
Nix Flakes
|
|
||||||
----------
|
|
||||||
|
|
||||||
Home Manager includes a `flake.nix` file for compatibility with [Nix Flakes][]
|
|
||||||
for those that wish to use it as a module. A bare-minimum `flake.nix` would be
|
|
||||||
as follows:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
description = "NixOS configuration";
|
|
||||||
|
|
||||||
inputs = {
|
|
||||||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
|
||||||
home-manager.url = "github:nix-community/home-manager";
|
|
||||||
# nix-darwin.url = "github:lnl7/nix-darwin";
|
|
||||||
};
|
|
||||||
|
|
||||||
outputs = inputs@{ home-manager, nixpkgs, ... }: {
|
|
||||||
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
|
|
||||||
}
|
|
||||||
];
|
|
||||||
};
|
|
||||||
};
|
|
||||||
|
|
||||||
# You do not need this unless you are using the nix-darwin project
|
|
||||||
darwinConfigurations = {
|
|
||||||
hostname = inputs.nix-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;
|
|
||||||
}
|
|
||||||
];
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
The Home Manager configuration is then part of the NixOS/Darwin configuration
|
|
||||||
and is automatically rebuilt with the system when using the appropriate command
|
|
||||||
for the system, such as `nixos-rebuild switch --flake <path>` for NixOS,
|
|
||||||
and `darwin-rebuild switch --flake <path>` with nix-darwin.
|
|
||||||
|
|
||||||
If you are not using NixOS you can place the following flake in
|
|
||||||
`~/.config/nixpkgs/flake.nix` to load your standard Home Manager
|
|
||||||
configuration:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
description = "A Home Manager flake";
|
|
||||||
|
|
||||||
inputs = {
|
|
||||||
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
|
|
||||||
home-manager.url = "github:nix-community/home-manager";
|
|
||||||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
|
||||||
};
|
|
||||||
|
|
||||||
outputs = inputs: {
|
|
||||||
homeConfigurations = {
|
|
||||||
jdoe = inputs.home-manager.lib.homeManagerConfiguration {
|
|
||||||
system = "x86_64-linux";
|
|
||||||
homeDirectory = "/home/jdoe";
|
|
||||||
username = "jdoe";
|
|
||||||
configuration.imports = [ ./home.nix ];
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Note, the Home Manager library is exported by the flake under
|
|
||||||
`lib.hm`.
|
|
||||||
|
|
||||||
When using flakes, switch to new configurations with
|
|
||||||
`home-manager switch --flake <path>`.
|
|
||||||
|
|
||||||
Releases
|
Releases
|
||||||
--------
|
--------
|
||||||
|
|
||||||
|
|
@ -214,3 +124,4 @@ This project is licensed under the terms of the [MIT license](LICENSE).
|
||||||
[manual standalone install]: https://nix-community.github.io/home-manager/index.html#sec-install-standalone
|
[manual standalone install]: https://nix-community.github.io/home-manager/index.html#sec-install-standalone
|
||||||
[manual nixos install]: https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module
|
[manual nixos install]: https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module
|
||||||
[manual nix-darwin install]: https://nix-community.github.io/home-manager/index.html#sec-install-nix-darwin-module
|
[manual nix-darwin install]: https://nix-community.github.io/home-manager/index.html#sec-install-nix-darwin-module
|
||||||
|
[manual nix flakes]: https://nix-community.github.io/home-manager/index.html#ch-nix-flakes
|
||||||
|
|
|
||||||
|
|
@ -32,6 +32,7 @@
|
||||||
</preface>
|
</preface>
|
||||||
<xi:include href="installation.xml" />
|
<xi:include href="installation.xml" />
|
||||||
<xi:include href="usage.xml" />
|
<xi:include href="usage.xml" />
|
||||||
|
<xi:include href="nix-flakes.xml" />
|
||||||
<xi:include href="writing-modules.xml" />
|
<xi:include href="writing-modules.xml" />
|
||||||
<xi:include href="contributing.xml" />
|
<xi:include href="contributing.xml" />
|
||||||
<xi:include href="faq.xml" />
|
<xi:include href="faq.xml" />
|
||||||
|
|
|
||||||
219
docs/nix-flakes.adoc
Normal file
219
docs/nix-flakes.adoc
Normal file
|
|
@ -0,0 +1,219 @@
|
||||||
|
[[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 have it in `nix-shell`.
|
||||||
|
|
||||||
|
* Enable experimental features `nix-command` and `flakes`.
|
||||||
|
+
|
||||||
|
Either set in `nix.conf`
|
||||||
|
+
|
||||||
|
[source,bash]
|
||||||
|
experimental-features = nix-command flakes
|
||||||
|
+
|
||||||
|
or pass them to `nix` by
|
||||||
|
+
|
||||||
|
[source,console]
|
||||||
|
nix --experimental-features "nix-command flakes" your command
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
+
|
||||||
|
[NOTE]
|
||||||
|
====
|
||||||
|
The `stateVersion` will be specified in the flake instead of in the configuration file.
|
||||||
|
|
||||||
|
Remove the line containing `home.stateVersion` in the example.
|
||||||
|
====
|
||||||
|
|
||||||
|
[[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
|
||||||
|
home-manager.url = "github:nix-community/home-manager";
|
||||||
|
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||||
|
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||||
|
};
|
||||||
|
|
||||||
|
outputs = { home-manager, ... }:
|
||||||
|
let
|
||||||
|
system = "x86_64-linux";
|
||||||
|
username = "jdoe";
|
||||||
|
in {
|
||||||
|
homeConfigurations.${username} = home-manager.lib.homeManagerConfiguration {
|
||||||
|
# Specify the path to your home configuration here
|
||||||
|
configuration = import ./home.nix;
|
||||||
|
|
||||||
|
inherit system username;
|
||||||
|
homeDirectory = "/home/${username}";
|
||||||
|
# Update the state version as needed.
|
||||||
|
# See the changelog here:
|
||||||
|
# https://nix-community.github.io/home-manager/release-notes.html#sec-release-21.05
|
||||||
|
stateVersion = "21.11";
|
||||||
|
|
||||||
|
# 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-21.11` branch,
|
||||||
|
change the `home-manager` input url to `github:nix-community/home-manager/release-21.11`
|
||||||
|
and `nixpkgs` url to `github:NixOS/nixpkgs/nixos-21.11`.
|
||||||
|
Make sure to also update to the `stateVersion` option accordingly.
|
||||||
|
|
||||||
|
* The Home Manager library is exported by the flake under
|
||||||
|
`lib.hm`.
|
||||||
|
====
|
||||||
|
|
||||||
|
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)"/bin/activate
|
||||||
|
----
|
||||||
|
+
|
||||||
|
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>`.
|
||||||
|
|
||||||
|
[[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";
|
||||||
|
nix-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, nix-darwin, ... }: {
|
||||||
|
darwinConfigurations = {
|
||||||
|
hostname = nix-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>`.
|
||||||
|
|
@ -29,6 +29,7 @@ man home-configuration.nix
|
||||||
|
|
||||||
Once a configuration is successfully built, it can be activated. The activation performs the steps necessary to make the files, programs, and services available in your user environment. The `home-manager switch` command performs a combined build and activation.
|
Once a configuration is successfully built, it can be activated. The activation performs the steps necessary to make the files, programs, and services available in your user environment. The `home-manager switch` command performs a combined build and activation.
|
||||||
|
|
||||||
|
[[sec-usage-configuration]]
|
||||||
=== Configuration Example
|
=== Configuration Example
|
||||||
|
|
||||||
A fresh install of Home Manager will generate a minimal `~/.config/nixpkgs/home.nix` file containing something like
|
A fresh install of Home Manager will generate a minimal `~/.config/nixpkgs/home.nix` file containing something like
|
||||||
|
|
@ -128,6 +129,7 @@ home-manager build
|
||||||
which will create a `result` link to a directory containing an
|
which will create a `result` link to a directory containing an
|
||||||
activation script and the generated home directory files.
|
activation script and the generated home directory files.
|
||||||
|
|
||||||
|
[[sec-usage-rollbacks]]
|
||||||
=== Rollbacks
|
=== Rollbacks
|
||||||
|
|
||||||
While the `home-manager` tool does not explicitly support rollbacks at the moment it is relatively easy to perform one manually. The steps to do so are
|
While the `home-manager` tool does not explicitly support rollbacks at the moment it is relatively easy to perform one manually. The steps to do so are
|
||||||
|
|
@ -162,6 +164,7 @@ Starting home manager activation
|
||||||
…
|
…
|
||||||
----
|
----
|
||||||
|
|
||||||
|
[[sec-usage-dotfiles]]
|
||||||
=== Keeping your ~ safe from harm
|
=== Keeping your ~ safe from harm
|
||||||
|
|
||||||
To configure programs and services Home Manager must write various things to your home directory. To prevent overwriting any existing files when switching to a new generation, Home Manager will attempt to detect collisions between existing files and generated files. If any such collision is detected the activation will terminate before changing anything on your computer.
|
To configure programs and services Home Manager must write various things to your home directory. To prevent overwriting any existing files when switching to a new generation, Home Manager will attempt to detect collisions between existing files and generated files. If any such collision is detected the activation will terminate before changing anything on your computer.
|
||||||
|
|
@ -194,6 +197,7 @@ Existing file '/home/jdoe/.config/git/config' is in the way
|
||||||
Please move the above files and try again
|
Please move the above files and try again
|
||||||
----
|
----
|
||||||
|
|
||||||
|
[[sec-usage-graphical]]
|
||||||
=== Graphical services
|
=== Graphical services
|
||||||
|
|
||||||
Home Manager includes a number of services intended to run in a graphical session, for example `xscreensaver` and `dunst`. Unfortunately, such services will not be started automatically unless you let Home Manager start your X session. That is, you have something like
|
Home Manager includes a number of services intended to run in a graphical session, for example `xscreensaver` and `dunst`. Unfortunately, such services will not be started automatically unless you let Home Manager start your X session. That is, you have something like
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue