From e2be63155007fa0e3559e49fa666be7a58ccfc89 Mon Sep 17 00:00:00 2001 From: rycee Date: Thu, 10 Feb 2022 21:42:14 +0000 Subject: [PATCH] deploy: 85bbc6cc12071c840cf3998e5d8f757fd00c1542 --- index.html | 167 +++++++++++++++++++++++++++++++++++++++++++++++------ tools.html | 14 ++--- 2 files changed, 157 insertions(+), 24 deletions(-) diff --git a/index.html b/index.html index 5e40e060..34ee70e9 100644 --- a/index.html +++ b/index.html @@ -1,6 +1,6 @@ -Home Manager Manual
Home Manager Manual
   Next

Home Manager Manual

Preface
1. Installing Home Manager
1.1. Standalone installation
1.2. NixOS module
1.3. nix-darwin module
2. Using Home Manager
2.1. Configuration Example
2.2. Rollbacks
2.3. Keeping your ~ safe from harm
2.4. Graphical services
3. Writing Home Manager Modules
3.1. Option Types
4. Contributing
4.1. Getting started
4.2. Guidelines
4.2.1. Maintain backward compatibility
4.2.2. Keep forward compatibility in mind
4.2.3. Add only valuable options
4.2.4. Add relevant tests
4.2.5. Add relevant documentation
4.2.6. Add yourself as a module maintainer
4.2.7. Format your code
4.2.8. Format your commit messages
4.2.9. Format your news entries
4.2.10. Use conditional modules and news
4.2.11. Mind the license
4.3. Commits
4.4. Code Style
4.5. News
4.6. Tests
5. Frequently Asked Questions (FAQ)
5.1. Why is there a collision error when switching generation?
5.2. Why are the session variables not set?
5.3. How to set up a configuration for multiple users/machines?
5.4. Why do I get an error message about ca.desrt.dconf?
5.5. How do I install packages from Nixpkgs unstable?
5.6. How do I override the package used by a module?
A. Configuration Options
B. NixOS Module Options
C. nix-darwin Module Options
D. Tools
home-manager - — reconfigure a user environment
E. Release Notes
E.1. Release 22.05
E.1.1. Highlights
E.1.2. State Version Changes
E.2. Release 21.11
E.2.1. Highlights
E.2.2. State Version Changes
E.3. Release 21.05
E.3.1. Highlights
E.3.2. State Version Changes
E.4. Release 20.09
E.4.1. Highlights
E.4.2. State Version Changes
E.5. Release 20.03
E.5.1. Highlights
E.5.2. State Version Changes
E.6. Release 19.09
E.6.1. Highlights
E.6.2. State Version Changes
E.7. Release 19.03
E.7.1. Highlights
E.7.2. State Version Changes
E.8. Release 18.09

Preface

+Home Manager Manual

Home Manager Manual
   Next

Home Manager Manual

Preface
1. Installing Home Manager
1.1. Standalone installation
1.2. NixOS module
1.3. nix-darwin module
2. Using Home Manager
2.1. Configuration Example
2.2. Rollbacks
2.3. Keeping your ~ safe from harm
2.4. Graphical services
3. Nix Flakes
3.1. Prerequisties
3.2. Standalone setup
3.3. NixOS module
3.4. nix-darwin module
4. Writing Home Manager Modules
4.1. Option Types
5. Contributing
5.1. Getting started
5.2. Guidelines
5.2.1. Maintain backward compatibility
5.2.2. Keep forward compatibility in mind
5.2.3. Add only valuable options
5.2.4. Add relevant tests
5.2.5. Add relevant documentation
5.2.6. Add yourself as a module maintainer
5.2.7. Format your code
5.2.8. Format your commit messages
5.2.9. Format your news entries
5.2.10. Use conditional modules and news
5.2.11. Mind the license
5.3. Commits
5.4. Code Style
5.5. News
5.6. Tests
6. Frequently Asked Questions (FAQ)
6.1. Why is there a collision error when switching generation?
6.2. Why are the session variables not set?
6.3. How to set up a configuration for multiple users/machines?
6.4. Why do I get an error message about ca.desrt.dconf?
6.5. How do I install packages from Nixpkgs unstable?
6.6. How do I override the package used by a module?
A. Configuration Options
B. NixOS Module Options
C. nix-darwin Module Options
D. Tools
home-manager + — reconfigure a user environment
E. Release Notes
E.1. Release 22.05
E.1.1. Highlights
E.1.2. State Version Changes
E.2. Release 21.11
E.2.1. Highlights
E.2.2. State Version Changes
E.3. Release 21.05
E.3.1. Highlights
E.3.2. State Version Changes
E.4. Release 20.09
E.4.1. Highlights
E.4.2. State Version Changes
E.5. Release 20.03
E.5.1. Highlights
E.5.2. State Version Changes
E.6. Release 19.09
E.6.1. Highlights
E.6.2. State Version Changes
E.7. Release 19.03
E.7.1. Highlights
E.7.2. State Version Changes
E.8. Release 18.09

Preface

This manual will eventually describe how to install, use, and extend Home Manager.

@@ -132,7 +132,7 @@ Nixpkgs.

Once installed you can see

Chapter 2. Using Home Manager

Your use of Home Manager is centered around the configuration file, which is typically found at ~/.config/nixpkgs/home.nix.

This configuration file can be built and activated.

Building a configuration produces a directory in the Nix store that contains all files and programs that should be available in your home directory and Nix user profile, respectively. The build step also checks that the configuration is valid and it will fail with an error if you, for example, assign a value to an option that does not exist or assign a value of the wrong type. Some modules also have custom assertions that perform more detailed, module specific, checks.

Concretely, if your configuration contains

programs.emacs.enable = "yes";

then building it, for example using home-manager build, will result in an error message saying something like

$ home-manager build
 error: A definition for option `programs.emacs.enable' is not of type `boolean'. Definition values:
 - In `/home/jdoe/.config/nixpkgs/home.nix': "yes"
-(use '--show-trace' to show detailed location information)

The message indicates that you must provide a Boolean value for this option, that is, either true or false. The documentation of each option will state the expected type, for programs.emacs.enable you will see “Type: boolean”. You there also find information about the default value and a description of the option. You can find the complete option documentation in Appendix A, Configuration Options or directly in the terminal by running

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.

2.1. Configuration Example

A fresh install of Home Manager will generate a minimal ~/.config/nixpkgs/home.nix file containing something like

{ config, pkgs, ... }:
+(use '--show-trace' to show detailed location information)

The message indicates that you must provide a Boolean value for this option, that is, either true or false. The documentation of each option will state the expected type, for programs.emacs.enable you will see “Type: boolean”. You there also find information about the default value and a description of the option. You can find the complete option documentation in Appendix A, Configuration Options or directly in the terminal by running

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.

2.1. Configuration Example

A fresh install of Home Manager will generate a minimal ~/.config/nixpkgs/home.nix file containing something like

{ config, pkgs, ... }:
 
 {
   # Home Manager needs a bit of information about you and the
@@ -199,7 +199,7 @@ The option names of a program module typically start with 
 
3 

 Similarly, for a service module, the names start with services.<package name>. Note in some cases a package has both programs and service options – Emacs is such an example.

To activate this configuration you can run

home-manager switch

or if you are not feeling so lucky,

home-manager build

which will create a result link to a directory containing an -activation script and the generated home directory files.

2.2. 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

  1. +activation script and the generated home directory files.

2.2. 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

  1. Run home-manager generations to determine which generation you wish to rollback to: 

    $ home-manager generations
 2018-01-04 11:56 : id 765 -> /nix/store/kahm1rxk77mnvd2l8pfvd4jkkffk5ijk-home-manager-generation
@@ -213,7 +213,7 @@ Copy the Nix store path of the generation you chose, e.g.,
 Run the activate script inside the copied store path:
 
    $ /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation/activate
 Starting home manager activation
-…

2.3. 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.

For example, suppose you have a wonderful, painstakingly created ~/.config/git/config and add

{
+…

2.3. 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.

For example, suppose you have a wonderful, painstakingly created ~/.config/git/config and add

{
   # …
 
   programs.git = {
@@ -227,7 +227,7 @@ Starting home manager activation
 …
 Activating checkLinkTargets
 Existing file '/home/jdoe/.config/git/config' is in the way
-Please move the above files and try again

2.4. 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

{
+Please move the above files and try again

2.4. 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

{
   # …
 
   services.xserver.enable = true;
@@ -240,7 +240,140 @@ Please move the above files and try again

in your Home Manager configuration.

Chapter 3. Writing Home Manager Modules

The module system in Home Manager is based entirely on the NixOS module system so we will here only highlight aspects that are specific for Home Manager. For information about the module system as such please refer to the Writing NixOS Modules chapter of the NixOS manual.

3.1. Option Types

Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types dagOf and gvariant that are used, for example, by programs.ssh.matchBlocks and dconf.settings.

+}

in your Home Manager configuration.

Chapter 3. Nix Flakes

Home Manager includes a flake.nix file for compatibility with Nix Flakes. +The support is still experimental and may change in backwards incompatible ways.

3.1. Prerequisties

  • +Install Nix 2.4 or have it in nix-shell. +

  • +Enable experimental features nix-command and flakes. +

    Either set in nix.conf

    experimental-features = nix-command flakes

    or pass them to nix by

    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 Section 2.1, “Configuration Example” 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.

3.2. Standalone setup

  1. +Set up a flake with a flake.nix as follows: +

    {
+  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 +

    $ 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 +

    $ 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 page for detail.

3.3. NixOS module

To use Home Manager as a NixOS module, +a bare-minimum flake.nix would be as follows:

{
+  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>.

3.4. 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:

{
+  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>.

Chapter 4. Writing Home Manager Modules

The module system in Home Manager is based entirely on the NixOS module system so we will here only highlight aspects that are specific for Home Manager. For information about the module system as such please refer to the Writing NixOS Modules chapter of the NixOS manual.

4.1. Option Types

Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types dagOf and gvariant that are used, for example, by programs.ssh.matchBlocks and dconf.settings.

hm.types.dagOf

Options of this type have attribute sets as values where each member is a node in a directed acyclic graph (DAG). This allows the attribute set entries to express dependency relations among themselves. This can, for example, be used to control the order of match blocks in a OpenSSH client configuration or the order of activation script blocks in home.activation. @@ -368,23 +501,23 @@ Builds a GVariant maybe value containing the given GVariant element. hm.gvariant.mkTuple elements

Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value. -

Chapter 4. Contributing

Contributions to Home Manager are very welcome. To make the process as smooth as possible for both you and the Home Manager maintainers we provide some guidelines that we ask you to follow. See Section 4.1, “Getting started” for information on how to set up a suitable development environment and Section 4.2, “Guidelines” for the actual guidelines.

This text is mainly directed at those who would like to make code contributions to Home Manager. If you just want to report a bug then first look among the already open issues, if you find one matching yours then feel free to comment on it to add any additional information you may have. If no matching issue exists then go to the new issue page and write a description of your problem. Include as much information as you can, ideally also include relevant excerpts from your Home Manager configuration.

4.1. Getting started

If you have not previously forked Home Manager then you need to do that first. Have a look at GitHub’s Fork a repo for instructions on how to do this.

Once you have a fork of Home Manager you should create a branch starting at the most recent master branch. Give your branch a reasonably descriptive name. Commit your changes to this branch and when you are happy with the result and it fulfills Section 4.2, “Guidelines” then push the branch to GitHub and create a pull request.

Assuming your clone is at $HOME/devel/home-manager then you can make the home-manager command use it by either

  1. +

Chapter 5. Contributing

Contributions to Home Manager are very welcome. To make the process as smooth as possible for both you and the Home Manager maintainers we provide some guidelines that we ask you to follow. See Section 5.1, “Getting started” for information on how to set up a suitable development environment and Section 5.2, “Guidelines” for the actual guidelines.

This text is mainly directed at those who would like to make code contributions to Home Manager. If you just want to report a bug then first look among the already open issues, if you find one matching yours then feel free to comment on it to add any additional information you may have. If no matching issue exists then go to the new issue page and write a description of your problem. Include as much information as you can, ideally also include relevant excerpts from your Home Manager configuration.

5.1. Getting started

If you have not previously forked Home Manager then you need to do that first. Have a look at GitHub’s Fork a repo for instructions on how to do this.

Once you have a fork of Home Manager you should create a branch starting at the most recent master branch. Give your branch a reasonably descriptive name. Commit your changes to this branch and when you are happy with the result and it fulfills Section 5.2, “Guidelines” then push the branch to GitHub and create a pull request.

Assuming your clone is at $HOME/devel/home-manager then you can make the home-manager command use it by either

  1. overriding the default path by using the -I command line option: 

    $ home-manager -I home-manager=$HOME/devel/home-manager

    or

  2. changing the default path by ensuring your configuration includes 

    programs.home-manager.enable = true;
-programs.home-manager.path = "$HOME/devel/home-manager";

    and running home-manager switch to activate the change. Afterwards, home-manager build and home-manager switch will use your cloned repository.

The first option is good if you only temporarily want to use your clone.

4.2. Guidelines

If your contribution satisfy the following rules then there is a good chance it will be merged without too much trouble. The rules are enforced by the Home Manager maintainers and to a lesser extent the Home Manager CI system.

If you are uncertain how these rules affect the change you would like to make then feel free to start a discussion in the #home-manager IRC channel, ideally before you start developing.

4.2.1. Maintain backward compatibility

Your contribution should not cause another user’s existing configuration to break unless there is a very good reason and the change should be announced to the user through an assertion or similar.

Remember that Home Manager is used in many different environments and you should consider how your change may effect others. For example,

  • +programs.home-manager.path = "$HOME/devel/home-manager";

    and running home-manager switch to activate the change. Afterwards, home-manager build and home-manager switch will use your cloned repository.

The first option is good if you only temporarily want to use your clone.

5.2. Guidelines

If your contribution satisfy the following rules then there is a good chance it will be merged without too much trouble. The rules are enforced by the Home Manager maintainers and to a lesser extent the Home Manager CI system.

If you are uncertain how these rules affect the change you would like to make then feel free to start a discussion in the #home-manager IRC channel, ideally before you start developing.

5.2.1. Maintain backward compatibility

Your contribution should not cause another user’s existing configuration to break unless there is a very good reason and the change should be announced to the user through an assertion or similar.

Remember that Home Manager is used in many different environments and you should consider how your change may effect others. For example,

  • Does your change work for people that do not use NixOS? Consider other GNU/Linux distributions and macOS.
  • Does your change work for people whose configuration is built on one system and deployed on another system? -

4.2.2. Keep forward compatibility in mind

The master branch of Home Manager tracks the unstable channel of Nixpkgs, which may update package versions at any time. It is therefore important to consider how a package update may affect your code and try to reduce the risk of breakage.

The most effective way to reduce this risk is to follow the advice in Section 4.2.3, “Add only valuable options”.

4.2.3. Add only valuable options

When creating a new module it is tempting to include every option supported by the software. This is strongly discouraged. Providing many options increases maintenance burden and risk of breakage considerably. This is why only the most important software options should be modeled explicitly. Less important options should be expressible through an extraConfig escape hatch.

A good rule of thumb for the first implementation of a module is to only add explicit options for those settings that absolutely must be set for the software to function correctly. It follows that a module for software that provides sensible default values for all settings would require no explicit options at all.

If the software uses a structured configuration format like a JSON, YAML, INI, TOML, or even a plain list of key/value pairs then consider using a settings option as described in Nix RFC 42.

4.2.4. Add relevant tests

If at all possible, make sure to add new tests and expand existing tests so that your change will keep working in the future. See Section 4.6, “Tests” for more information about the Home Manager test suite.

All contributed code must pass the test suite.

4.2.5. Add relevant documentation

Many code changes require changing the documentation as well. Module options should be documented with DocBook. See DocBook rocks! for a quick introduction and DocBook 5: The Definitive Guide for in-depth information of DocBook. Home Manager is itself documented using a combination of DocBook and AsciiDoc. All text is hosted in Home Manager’s Git repository.

The HTML version of the manual containing both the module option descriptions and the documentation of Home Manager can be generated and opened by typing the following in a shell within a clone of the Home Manager Git repository:

$ nix-build -A docs.html
+

5.2.2. Keep forward compatibility in mind

The master branch of Home Manager tracks the unstable channel of Nixpkgs, which may update package versions at any time. It is therefore important to consider how a package update may affect your code and try to reduce the risk of breakage.

The most effective way to reduce this risk is to follow the advice in Section 5.2.3, “Add only valuable options”.

5.2.3. Add only valuable options

When creating a new module it is tempting to include every option supported by the software. This is strongly discouraged. Providing many options increases maintenance burden and risk of breakage considerably. This is why only the most important software options should be modeled explicitly. Less important options should be expressible through an extraConfig escape hatch.

A good rule of thumb for the first implementation of a module is to only add explicit options for those settings that absolutely must be set for the software to function correctly. It follows that a module for software that provides sensible default values for all settings would require no explicit options at all.

If the software uses a structured configuration format like a JSON, YAML, INI, TOML, or even a plain list of key/value pairs then consider using a settings option as described in Nix RFC 42.

5.2.4. Add relevant tests

If at all possible, make sure to add new tests and expand existing tests so that your change will keep working in the future. See Section 5.6, “Tests” for more information about the Home Manager test suite.

All contributed code must pass the test suite.

5.2.5. Add relevant documentation

Many code changes require changing the documentation as well. Module options should be documented with DocBook. See DocBook rocks! for a quick introduction and DocBook 5: The Definitive Guide for in-depth information of DocBook. Home Manager is itself documented using a combination of DocBook and AsciiDoc. All text is hosted in Home Manager’s Git repository.

The HTML version of the manual containing both the module option descriptions and the documentation of Home Manager can be generated and opened by typing the following in a shell within a clone of the Home Manager Git repository:

$ nix-build -A docs.html
 $ xdg-open ./result/share/doc/home-manager/index.html

When you have made changes to a module, it is a good idea to check that the man page version of the module options looks good:

$ nix-build -A docs.manPages
-$ man ./result/share/man/man5/home-configuration.nix.5

4.2.6. Add yourself as a module maintainer

Every new module must include a named maintainer using the meta.maintainers attribute. If you are a user of a module that currently lacks a maintainer then please consider adopting it.

If you are present in the NixOS maintainer list then you can use that entry. If you are not then you can add yourself to modules/lib/maintainers.nix in the Home Manager project.

Also add yourself to .github/CODEOWNERS as owner of the associated module files, including the test files. You will then be automatically added as a reviewer on any new pull request that touches your files.

Maintainers are encouraged to join the IRC channel and participate when they have opportunity.

4.2.7. Format your code

Make sure your code is formatted as described in Section 4.4, “Code Style”. To maintain consistency throughout the project you are encouraged to browse through existing code and adopt its style also in new code.

4.2.8. Format your commit messages

Similar to Section 4.2.7, “Format your code” we encourage a consistent commit message format as described in Section 4.3, “Commits”.

4.2.9. Format your news entries

If your contribution includes a change that should be communicated to users of Home Manager then you can add a news entry. The entry must be formatted as described in Section 4.5, “News”.

When new modules are added a news entry should be included but you do not need to create this entry manually. The merging maintainer will create the entry for you. This is to reduce the risk of merge conflicts.

4.2.10. Use conditional modules and news

Home Manager includes a number of modules that are only usable on some of the supported platforms. The most common example of platform specific modules are those that define systemd user services, which only works on Linux systems.

If you add a module that is platform specific then make sure to include a condition in the loadModule function call. This will make the module accessible only on systems where the condition evaluates to true.

Similarly, if you are adding a news entry then it should be shown only to users that may find it relevant, see Section 4.5, “News” for a description of conditional news.

4.2.11. Mind the license

The Home Manager project is covered by the MIT license and we can only accept contributions that fall under this license, or are licensed in a compatible way. When you contribute self written code and documentation it is assumed that you are doing so under the MIT license.

A potential gotcha with respect to licensing are option descriptions. Often it is convenient to copy from the upstream software documentation. When this is done it is important to verify that the license of the upstream documentation allows redistribution under the terms of the MIT license.

4.3. Commits

The commits in your pull request should be reasonably self-contained, that is, each commit should make sense in isolation. In particular, you will be asked to amend any commit that introduces syntax errors or similar problems even if they are fixed in a later commit.

The commit messages should follow the seven rules. We also ask you to include the affected code component or module in the first line. That is, a commit message should follow the template

{component}: {description}
+$ man ./result/share/man/man5/home-configuration.nix.5

5.2.6. Add yourself as a module maintainer

Every new module must include a named maintainer using the meta.maintainers attribute. If you are a user of a module that currently lacks a maintainer then please consider adopting it.

If you are present in the NixOS maintainer list then you can use that entry. If you are not then you can add yourself to modules/lib/maintainers.nix in the Home Manager project.

Also add yourself to .github/CODEOWNERS as owner of the associated module files, including the test files. You will then be automatically added as a reviewer on any new pull request that touches your files.

Maintainers are encouraged to join the IRC channel and participate when they have opportunity.

5.2.7. Format your code

Make sure your code is formatted as described in Section 5.4, “Code Style”. To maintain consistency throughout the project you are encouraged to browse through existing code and adopt its style also in new code.

5.2.8. Format your commit messages

Similar to Section 5.2.7, “Format your code” we encourage a consistent commit message format as described in Section 5.3, “Commits”.

5.2.9. Format your news entries

If your contribution includes a change that should be communicated to users of Home Manager then you can add a news entry. The entry must be formatted as described in Section 5.5, “News”.

When new modules are added a news entry should be included but you do not need to create this entry manually. The merging maintainer will create the entry for you. This is to reduce the risk of merge conflicts.

5.2.10. Use conditional modules and news

Home Manager includes a number of modules that are only usable on some of the supported platforms. The most common example of platform specific modules are those that define systemd user services, which only works on Linux systems.

If you add a module that is platform specific then make sure to include a condition in the loadModule function call. This will make the module accessible only on systems where the condition evaluates to true.

Similarly, if you are adding a news entry then it should be shown only to users that may find it relevant, see Section 5.5, “News” for a description of conditional news.

5.2.11. Mind the license

The Home Manager project is covered by the MIT license and we can only accept contributions that fall under this license, or are licensed in a compatible way. When you contribute self written code and documentation it is assumed that you are doing so under the MIT license.

A potential gotcha with respect to licensing are option descriptions. Often it is convenient to copy from the upstream software documentation. When this is done it is important to verify that the license of the upstream documentation allows redistribution under the terms of the MIT license.

5.3. Commits

The commits in your pull request should be reasonably self-contained, that is, each commit should make sense in isolation. In particular, you will be asked to amend any commit that introduces syntax errors or similar problems even if they are fixed in a later commit.

The commit messages should follow the seven rules. We also ask you to include the affected code component or module in the first line. That is, a commit message should follow the template

{component}: {description}
 
-{long description}

where {component} refers to the code component (or module) your change affects, {description} is a very brief description of your change, and {long description} is an optional clarifying description. As a rare exception, if there is no clear component, or your change affects many components, then the {component} part is optional. See Example 4.1, “Compliant commit message” for a commit message that fulfills these requirements.

Example 4.1. Compliant commit message

The commit 69f8e47e9e74c8d3d060ca22e18246b7f7d988ef contains the commit message

starship: allow running in Emacs if vterm is used
+{long description}

where {component} refers to the code component (or module) your change affects, {description} is a very brief description of your change, and {long description} is an optional clarifying description. As a rare exception, if there is no clear component, or your change affects many components, then the {component} part is optional. See Example 5.1, “Compliant commit message” for a commit message that fulfills these requirements.

Example 5.1. Compliant commit message

The commit 69f8e47e9e74c8d3d060ca22e18246b7f7d988ef contains the commit message

starship: allow running in Emacs if vterm is used
 
 The vterm buffer is backed by libvterm and can handle Starship prompts
-without issues.

which ticks all the boxes necessary to be accepted in Home Manager.


Finally, when adding a new module, say programs/foo.nix, we use the fixed commit format foo: add module. You can, of course, still include a long description if you wish.

4.4. Code Style

The code in Home Manager is formatted by the nixfmt tool and the formatting is checked in the pull request tests. Run the format tool inside the project repository before submitting your pull request.

Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals.

We prefer lowerCamelCase for variable and attribute names with the accepted exception of variables directly referencing packages in Nixpkgs which use a hyphenated style. For example, the Home Manager option services.gpg-agent.enableSshSupport references the gpg-agent package in Nixpkgs.

4.5. News

Home Manager includes a system for presenting news to the user. When making a change you, therefore, have the option to also include an associated news entry. In general, a news entry should only be added for truly noteworthy news. For example, a bug fix or new option does generally not need a news entry.

If you do have a change worthy of a news entry then please add one in news.nix but you should follow some basic guidelines:

  • +without issues.

    which ticks all the boxes necessary to be accepted in Home Manager.


Finally, when adding a new module, say programs/foo.nix, we use the fixed commit format foo: add module. You can, of course, still include a long description if you wish.

5.4. Code Style

The code in Home Manager is formatted by the nixfmt tool and the formatting is checked in the pull request tests. Run the format tool inside the project repository before submitting your pull request.

Keep lines at a reasonable width, ideally 80 characters or less. This also applies to string literals.

We prefer lowerCamelCase for variable and attribute names with the accepted exception of variables directly referencing packages in Nixpkgs which use a hyphenated style. For example, the Home Manager option services.gpg-agent.enableSshSupport references the gpg-agent package in Nixpkgs.

5.5. News

Home Manager includes a system for presenting news to the user. When making a change you, therefore, have the option to also include an associated news entry. In general, a news entry should only be added for truly noteworthy news. For example, a bug fix or new option does generally not need a news entry.

If you do have a change worthy of a news entry then please add one in news.nix but you should follow some basic guidelines:

  • The entry timestamp should be in ISO-8601 format having "+00:00" as time zone. For example, "2017-09-13T17:10:14+00:00". A suitable timestamp can be produced by the command 

    $ date --iso-8601=second --universal
  • The entry condition should be as specific as possible. For example, if you are changing or deprecating a specific option then you could restrict the news to those users who actually use this option. @@ -397,7 +530,7 @@ If you refer to an option then write its full attribute path. That is, instead o 

    The option 'foo' has been deprecated, please use 'bar' instead.

    it should read

    The option 'services.myservice.foo' has been deprecated, please
 use 'services.myservice.bar' instead.

  • A new module, say foo.nix, should always include a news entry that has a message along the lines of -

    A new module is available: 'services.foo'.

    If the module is platform specific, e.g., a service module using systemd, then a condition like

    condition = hostPlatform.isLinux;

    should be added. If you contribute a module then you don’t need to add this entry, the merger will create an entry for you.

4.6. Tests

Home Manager includes a basic test suite and it is highly recommended to include at least one test when adding a module. Tests are typically in the form of "golden tests" where, for example, a generated configuration file is compared to a known correct file.

It is relatively easy to create tests by modeling the existing tests, found in the tests project directory.

The full Home Manager test suite can be run by executing

$ nix-shell --pure tests -A run.all

in the project root. List all test cases through

$ nix-shell --pure tests -A list

and run an individual test, for example alacritty-empty-settings, through

$ nix-shell --pure tests -A run.alacritty-empty-settings

Chapter 5. Frequently Asked Questions (FAQ)

5.1. Why is there a collision error when switching generation?

Home Manager currently installs packages into the user environment, precisely as if the packages were installed through nix-env --install. This means that you will get a collision error if your Home Manager configuration attempts to install a package that you already have installed manually, that is, packages that shows up when you run nix-env --query.

For example, imagine you have the hello package installed in your environment

$ nix-env --query
+
A new module is available: 'services.foo'.
If the module is platform specific, e.g., a service module using systemd, then a condition like
condition = hostPlatform.isLinux;
should be added. If you contribute a module then you don’t need to add this entry, the merger will create an entry for you.

5.6. Tests

Home Manager includes a basic test suite and it is highly recommended to include at least one test when adding a module. Tests are typically in the form of "golden tests" where, for example, a generated configuration file is compared to a known correct file.

It is relatively easy to create tests by modeling the existing tests, found in the tests project directory.

The full Home Manager test suite can be run by executing

$ nix-shell --pure tests -A run.all

in the project root. List all test cases through

$ nix-shell --pure tests -A list

and run an individual test, for example alacritty-empty-settings, through

$ nix-shell --pure tests -A run.alacritty-empty-settings

Chapter 6. Frequently Asked Questions (FAQ)

6.1. Why is there a collision error when switching generation?

Home Manager currently installs packages into the user environment, precisely as if the packages were installed through nix-env --install. This means that you will get a collision error if your Home Manager configuration attempts to install a package that you already have installed manually, that is, packages that shows up when you run nix-env --query.

For example, imagine you have the hello package installed in your environment

$ nix-env --query
 hello-2.10

and your Home Manager configuration contains

home.packages = [ pkgs.hello ];

Then attempting to switch to this configuration will result in an error similar to

$ home-manager switch
 these derivations will be built:
   /nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv
@@ -409,7 +542,7 @@ building path(s) ‘/nix/store/b5c0asjz9f06l52l9812w6k39ifr49jj-user-environment
 Wide character in die at /nix/store/64jc9gd2rkbgdb4yjx3nrgc91bpjj5ky-buildenv.pl line 79.
 collision between ‘/nix/store/fmwa4axzghz11cnln5absh31nbhs9lq1-home-manager-path/bin/hello’ and ‘/nix/store/c2wyl8b9p4afivpcz8jplc9kis8rj36d-hello-2.10/bin/hello’; use ‘nix-env --set-flag priority NUMBER PKGNAME’ to change the priority of one of the conflicting packages
 builder for ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed with exit code 2
-error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed

The solution is typically to uninstall the package from the environment using nix-env --uninstall and reattempt the Home Manager generation switch.

You could also opt to unistall all of the packages from your profile with nix-env --uninstall '*'.

5.2. Why are the session variables not set?

Home Manager is only able to set session variables automatically if it manages your Bash, Z shell, or fish shell configuration. If you don’t want to let Home Manager manage your shell then you will have to manually source the ~/.nix-profile/etc/profile.d/hm-session-vars.sh file in an appropriate way. In Bash and Z shell this can be done by adding

. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"

to your .profile and .zshrc files, respectively. The hm-session-vars.sh file should work in most Bourne-like shells. For fish shell, it is possible to source it using the foreign-env plugin

fenv source "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" > /dev/null

5.3. How to set up a configuration for multiple users/machines?

A typical way to prepare a repository of configurations for multiple logins and machines is to prepare one "top-level" file for each unique combination.

For example, if you have two machines, called "kronos" and "rhea" on which you want to configure your user "jane" then you could create the files

  • +error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed

    The solution is typically to uninstall the package from the environment using nix-env --uninstall and reattempt the Home Manager generation switch.

    You could also opt to unistall all of the packages from your profile with nix-env --uninstall '*'.

6.2. Why are the session variables not set?

Home Manager is only able to set session variables automatically if it manages your Bash, Z shell, or fish shell configuration. If you don’t want to let Home Manager manage your shell then you will have to manually source the ~/.nix-profile/etc/profile.d/hm-session-vars.sh file in an appropriate way. In Bash and Z shell this can be done by adding

. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"

to your .profile and .zshrc files, respectively. The hm-session-vars.sh file should work in most Bourne-like shells. For fish shell, it is possible to source it using the foreign-env plugin

fenv source "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" > /dev/null

6.3. How to set up a configuration for multiple users/machines?

A typical way to prepare a repository of configurations for multiple logins and machines is to prepare one "top-level" file for each unique combination.

For example, if you have two machines, called "kronos" and "rhea" on which you want to configure your user "jane" then you could create the files

  • kronos-jane.nix,
  • rhea-jane.nix, and @@ -421,7 +554,7 @@ error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment. imports = [ ./common.nix ]; # Various options that are specific for this machine/user. -}

    while the common.nix file contains configuration shared across the two logins. Of course, instead of just a single common.nix file you can have multiple ones, even one per program or service.

    You can get some inspiration from the Post your home-manager home.nix file! Reddit thread.

5.4. Why do I get an error message about ca.desrt.dconf?

You are most likely trying to configure the GTK or Gnome Terminal but the DBus session is not aware of the dconf service. The full error you might get is

error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files

The solution on NixOS is to add

programs.dconf.enable = true;

to your system configuration.

5.5. How do I install packages from Nixpkgs unstable?

If you are using a stable version of Nixpkgs but would like to install some particular packages from Nixpkgs unstable – or some other channel – then you can import the unstable Nixpkgs and refer to its packages within your configuration. Something like

{ pkgs, config, ... }:
+}

while the common.nix file contains configuration shared across the two logins. Of course, instead of just a single common.nix file you can have multiple ones, even one per program or service.

You can get some inspiration from the Post your home-manager home.nix file! Reddit thread.

6.4. Why do I get an error message about ca.desrt.dconf?

You are most likely trying to configure the GTK or Gnome Terminal but the DBus session is not aware of the dconf service. The full error you might get is

error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files

The solution on NixOS is to add

programs.dconf.enable = true;

to your system configuration.

6.5. How do I install packages from Nixpkgs unstable?

If you are using a stable version of Nixpkgs but would like to install some particular packages from Nixpkgs unstable – or some other channel – then you can import the unstable Nixpkgs and refer to its packages within your configuration. Something like

{ pkgs, config, ... }:
 
 let
 
@@ -436,7 +569,7 @@ in
 
   # …
 }

should work provided you have a Nix channel called nixpkgs-unstable.

You can add the nixpkgs-unstable channel by running

# nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs-unstable
-# nix-channel --update

Note, the package will not be affected by any package overrides, overlays, etc.

5.6. How do I override the package used by a module?

By default Home Manager will install the package provided by your chosen nixpkgs channel but occasionally you might end up needing to change this package. This can typically be done in two ways.

  1. +# nix-channel --update

    Note, the package will not be affected by any package overrides, overlays, etc.

6.6. How do I override the package used by a module?

By default Home Manager will install the package provided by your chosen nixpkgs channel but occasionally you might end up needing to change this package. This can typically be done in two ways.

  1. If the module provides a package option, such as programs.beets.package, then this is the recommended way to perform the override. For example, 

    programs.beets.package = pkgs.beets.override { enableCheck = true; };

  2. If no package option is available then you can typically override the relevant package using an overlay. diff --git a/tools.html b/tools.html index abecf5b1..8e6f7640 100644 --- a/tools.html +++ b/tools.html @@ -1,6 +1,6 @@ -Appendix D. Tools

    Appendix D. Tools
    Prev   Next

    Appendix D. Tools

    home-manager - — reconfigure a user environment

    Name

    home-manager +Appendix D. Tools

    Appendix D. Tools
    Prev   Next

    Appendix D. Tools

    home-manager + — reconfigure a user environment

    Name

    home-manager — reconfigure a user environment

    Synopsis

    home-manager { build | @@ -84,7 +84,7 @@ | --verbose } - ]

    Description

    + ]

    Description

    This command updates the user environment so that it corresponds to the configuration specified in ~/.config/nixpkgs/home.nix or ~/.config/nixpkgs/flake.nix.

    @@ -153,7 +153,7 @@ available for immediate garbage collection.

-

Options

+

Options

The tool accepts the options

-A attrPath @@ -265,15 +265,15 @@ --verbose

Activates verbose output. -

Files

+

Files

$XDG_DATA_HOME/home-manager/news-read-ids

Identifiers of news items that have been shown. Can be deleted to reset the read news indicator. -

Bugs

+

Bugs

Please report any bugs on the project issue tracker. -

See also

+

See also

home-configuration.nix(5)

Prev   Next
Appendix C. nix-darwin Module Options Home Appendix E. Release Notes
\ No newline at end of file