From 3b2c4e767c742cbfaaf3db89d505389422ebd55c Mon Sep 17 00:00:00 2001 From: rycee Date: Wed, 1 Mar 2023 21:49:01 +0000 Subject: [PATCH] deploy: f8077880359b72bbd290ee216b105f200a6f7cc7 --- index.html | 19 +++++++++++++------ tools.html | 14 +++++++------- 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/index.html b/index.html index 2098e3ab4..f81a7bc20 100644 --- a/index.html +++ b/index.html @@ -1,5 +1,5 @@ -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
2.5. Updating
3. Nix Flakes
3.1. Prerequisites
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 or dconf.service?
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 +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
2.5. Updating
3. Nix Flakes
3.1. Prerequisites
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. Third-Party Tools and Extensions
6.1. Module Collections
7. Frequently Asked Questions (FAQ)
7.1. Why is there a collision error when switching generation?
7.2. Why are the session variables not set?
7.3. How to set up a configuration for multiple users/machines?
7.4. Why do I get an error message about ca.desrt.dconf or dconf.service?
7.5. How do I install packages from Nixpkgs unstable?
7.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 23.05
E.1.1. Highlights
E.1.2. State Version Changes
E.2. Release 22.11
E.2.1. Highlights
E.2.2. State Version Changes
E.3. Release 22.05
E.3.1. Highlights
E.3.2. State Version Changes
E.4. Release 21.11
E.4.1. Highlights
E.4.2. State Version Changes
E.5. Release 21.05
E.5.1. Highlights
E.5.2. State Version Changes
E.6. Release 20.09
E.6.1. Highlights
E.6.2. State Version Changes
E.7. Release 20.03
E.7.1. Highlights
E.7.2. State Version Changes
E.8. Release 19.09
E.8.1. Highlights
E.8.2. State Version Changes
E.9. Release 19.03
E.9.1. Highlights
E.9.2. State Version Changes
E.10. Release 18.09

Preface

This manual will eventually describe how to install, use, and extend Home Manager. @@ -578,7 +578,14 @@ 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.

    • 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

    However, those invocations will impurely source the system’s nixpkgs, and may cause failures. To run against the nixpkgs from the flake.lock, use instead e.g.

    $ nix develop --ignore-environment .#tests.all

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

    However, those invocations will impurely source the system’s nixpkgs, and may cause failures. To run against the nixpkgs from the flake.lock, use instead e.g.

    $ nix develop --ignore-environment .#tests.all

    Chapter 6. Third-Party Tools and Extensions

    Here is a collection of tools and extensions that relate to Home +Manager. Note, these are maintained outside the regular Home Manager +flow so quality and support may vary wildly. If you encounter problems +then please raise them in the corresponding project, not as issues in +the Home Manager tracker.

    If you have made something interesting related to Home Manager then +you are encouraged to create a PR that expands this chapter.

    6.1. Module Collections

    Chapter 7. Frequently Asked Questions (FAQ)

    7.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
@@ -590,7 +597,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 '*'.

    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. To enable such management you use programs.bash.enable, programs.zsh.enable, or programs.fish.enable.

    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

    • +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 '*'.

    7.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. To enable such management you use programs.bash.enable, programs.zsh.enable, or programs.fish.enable.

    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

    7.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 @@ -602,9 +609,9 @@ 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.

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

    You are most likely trying to configure something that uses dconf +}

    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.

    7.4. Why do I get an error message about ca.desrt.dconf or dconf.service?

    You are most likely trying to configure something that uses dconf 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

    or

    error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.

    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, ... }:
+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
    or
    error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.
    The solution on NixOS is to add
    programs.dconf.enable = true;
    to your system configuration.

    7.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
 
@@ -619,7 +626,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.

    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. +$ nix-channel --update

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

    7.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 23a656745..dc5c2155e 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 | @@ -92,7 +92,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.

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

    -

    Options

    +

    Options

    The tool accepts the options

    -A attrPath @@ -284,15 +284,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