From 96467b414f9f3962e85c5be63655a36ce823d909 Mon Sep 17 00:00:00 2001 From: rycee Date: Thu, 5 Nov 2020 22:01:29 +0000 Subject: [PATCH] deploy: faca77d77d58e39b21dec6bc19c0adb199b3dfb8 --- index.html | 292 +++++++++++++++++------------------------------------ tools.html | 14 +-- 2 files changed, 97 insertions(+), 209 deletions(-) diff --git a/index.html b/index.html index 6a69fe0f..12d3fd21 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. Writing Home Manager Modules
2.1. Option Types
3. Contributing
3.1. Getting started
3.2. Guidelines
3.2.1. Maintain backward compatibility
3.2.2. Keep forward compatibility in mind
3.2.3. Add only valuable options
3.2.4. Add relevant tests
3.2.5. Add relevant documentation
3.2.6. Add yourself as a module maintainer
3.2.7. Format your code
3.2.8. Format your commit messages
3.2.9. Format your news entries
3.2.10. Use conditional modules and news
3.2.11. Mind the license
3.3. Commits
3.4. Code Style
3.5. News
3.6. Tests
4. Frequently Asked Questions (FAQ)
4.1. Why is there a collision error when switching generation?
4.2. Why are the session variables not set?
4.3. How do set up a configuration for multiple users/machines?
4.4. Why do I get an error message about ca.desrt.dconf?
4.5. How do I install packages from Nixpkgs unstable?
4.6. How do I override the package used by a module?
A. Configuration Options
B. Tools
home-manager - — reconfigure a user environment
C. Release Notes
C.1. Release 21.03
C.1.1. Highlights
C.1.2. State Version Changes
C.2. Release 20.09
C.2.1. Highlights
C.2.2. State Version Changes
C.3. Release 20.03
C.3.1. Highlights
C.3.2. State Version Changes
C.4. Release 19.09
C.4.1. Highlights
C.4.2. State Version Changes
C.5. Release 19.03
C.5.1. Highlights
C.5.2. State Version Changes
C.6. 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. Writing Home Manager Modules
2.1. Option Types
3. Contributing
3.1. Getting started
3.2. Guidelines
3.2.1. Maintain backward compatibility
3.2.2. Keep forward compatibility in mind
3.2.3. Add only valuable options
3.2.4. Add relevant tests
3.2.5. Add relevant documentation
3.2.6. Add yourself as a module maintainer
3.2.7. Format your code
3.2.8. Format your commit messages
3.2.9. Format your news entries
3.2.10. Use conditional modules and news
3.2.11. Mind the license
3.3. Commits
3.4. Code Style
3.5. News
3.6. Tests
4. Frequently Asked Questions (FAQ)
4.1. Why is there a collision error when switching generation?
4.2. Why are the session variables not set?
4.3. How do set up a configuration for multiple users/machines?
4.4. Why do I get an error message about ca.desrt.dconf?
4.5. How do I install packages from Nixpkgs unstable?
4.6. How do I override the package used by a module?
A. Configuration Options
B. Tools
home-manager + — reconfigure a user environment
C. Release Notes
C.1. Release 21.03
C.1.1. Highlights
C.1.2. State Version Changes
C.2. Release 20.09
C.2.1. Highlights
C.2.2. State Version Changes
C.3. Release 20.03
C.3.1. Highlights
C.3.2. State Version Changes
C.4. Release 19.09
C.4.1. Highlights
C.4.2. State Version Changes
C.5. Release 19.03
C.5.1. Highlights
C.5.2. State Version Changes
C.6. Release 18.09

Preface

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

@@ -16,211 +16,99 @@ Commands prefixed with # have to be run as root, either requiring to login as root user or temporarily switching to it using sudo for example. -

Chapter 1. Installing Home Manager

- Home Manager can be used in three primary ways: -

  1. - Using the standalone home-manager tool. For platforms - other than NixOS and Darwin, this is the only available choice. It is also - recommended for people on NixOS or Darwin that want to manage their home - directory independent of the system as a whole. See - Section 1.1, “Standalone installation” for instructions on how to - perform this installation. -

  2. - As a module within a NixOS system configuration. This allows the user - profiles to be built together with the system when running - nixos-rebuild. See - Section 1.2, “NixOS module” for a description of this - setup. -

  3. - As a module within a - nix-darwin - system configuration. This allows the user profiles to be built together - with the system when running darwin-rebuild. See - Section 1.3, “nix-darwin module” for a description of this - setup. -

-

1.1. Standalone installation

  1. - Make sure you have a working Nix installation. Specifically, make - sure that your user is able to build and install Nix packages. - For example, you should be able to successfully run a command - like nix-instantiate '<nixpkgs>' -A hello - without having to switch to the root user. For a multi-user - install of Nix this means that your user must be covered by the - allowed-users - Nix option. On NixOS you can control this option using the - nix.allowedUsers - system option. -

  2. - Add the Home Manager channel that you wish to follow. This is done by - running - 

    -$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
-$ nix-channel --update
-

    - if you are following Nixpkgs master or an unstable channel and - 

    -$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager
-$ nix-channel --update
-

    - if you follow a Nixpkgs version 20.09 channel. -

    - On NixOS you may need to log out and back in for the channel to become - available. On non-NixOS you may have to add -

    -export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH
-

    - to your shell (see - nix#2033). -

  3. - Run the Home Manager installation command and create the first Home - Manager generation: - 

    -$ nix-shell '<home-manager>' -A install
-

    - Once finished, Home Manager should be active and available in your user - environment. -

  4. - If you do not plan on having Home Manager manage your shell configuration - then you must source the - 

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

    - file in your shell configuration. Unfortunately, we currently only support - POSIX.2-like shells such as - Bash or - Z shell. -

    - For example, if you use Bash then add - 

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

    - to your ~/.profile file. -

- If instead of using channels you want to run Home Manager from a Git - checkout of the repository then you can use the - programs.home-manager.path option to specify the absolute - path to the repository. -

1.2. NixOS module

- Home Manager provides a NixOS module that allows you to prepare user - environments directly from the system configuration file, which often is - more convenient than using the home-manager tool. It also - opens up additional possibilities, for example, to automatically configure - user environments in NixOS declarative containers or on systems deployed - through NixOps. -

- To make the NixOS module available for use you must import - it into your system configuration. This is most conveniently done by adding - a Home Manager channel, for example - 

-# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
-# nix-channel --update
-

- if you are following Nixpkgs master or an unstable channel and - 

-# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager
-# nix-channel --update
-

- if you follow a Nixpkgs version 20.09 channel. -

- It is then possible to add - 

-imports = [ <home-manager/nixos> ];
-

- to your system configuration.nix file, which will - introduce a new NixOS option called home-manager.users - whose type is an attribute set that maps user names to Home Manager - configurations. -

- For example, a NixOS configuration may include the lines - 

-users.users.eve.isNormalUser = true;
+

Chapter 1. Installing Home Manager

Home Manager can be used in three primary ways:

  1. +Using the standalone home-manager tool. For platforms other than +NixOS and Darwin, this is the only available choice. It is also +recommended for people on NixOS or Darwin that want to manage their +home directory independent of the system as a whole. See +Section 1.1, “Standalone installation” for instructions on how to perform this +installation. +
  2. +As a module within a NixOS system configuration. This allows the +user profiles to be built together with the system when running +nixos-rebuild. See Section 1.2, “NixOS module” for a description of +this setup. +
  3. +As a module within a nix-darwin system configuration. +This allows the user profiles to be built together with the system +when running darwin-rebuild. See Section 1.3, “nix-darwin module” +for a description of this setup. +

1.1. Standalone installation

  1. +Make sure you have a working Nix installation. Specifically, make +sure that your user is able to build and install Nix packages. For +example, you should be able to successfully run a command like +nix-instantiate '<nixpkgs>' -A hello without having to switch to the +root user. For a multi-user install of Nix this means that your user +must be covered by the allowed-users Nix +option. On NixOS you can control this option using the +nix.allowedUsers system option. +

  2. +Add the Home Manager channel that you wish to follow. This is done +by running +

    $ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
+$ nix-channel --update

    if you are following Nixpkgs master or an unstable channel and

    $ nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager
+$ nix-channel --update

    if you follow a Nixpkgs version 20.09 channel.

    On NixOS you may need to log out and back in for the channel to become +available. On non-NixOS you may have to add

    export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH

    to your shell (see +nix#2033).

  3. +Run the Home Manager installation command and create the first Home +Manager generation: +

    $ nix-shell '<home-manager>' -A install

    Once finished, Home Manager should be active and available in your +user environment.

  4. +If you do not plan on having Home Manager manage your shell +configuration then you must source the +

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

    file in your shell configuration. Unfortunately, we currently only +support POSIX.2-like shells such as +Bash or +Z shell.

    For example, if you use Bash then add

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

    to your ~/.profile file.

If instead of using channels you want to run Home Manager from a Git +checkout of the repository then you can use the +programs.home-manager.path option to specify the absolute path +to the repository.

1.2. NixOS module

Home Manager provides a NixOS module that allows you to prepare user +environments directly from the system configuration file, which often +is more convenient than using the home-manager tool. It also opens +up additional possibilities, for example, to automatically configure +user environments in NixOS declarative containers or on systems +deployed through NixOps.

To make the NixOS module available for use you must import it into +your system configuration. This is most conveniently done by adding a +Home Manager channel, for example

# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
+# nix-channel --update

if you are following Nixpkgs master or an unstable channel and

# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager
+# nix-channel --update

if you follow a Nixpkgs version 20.09 channel.

It is then possible to add

imports = [ <home-manager/nixos> ];

to your system configuration.nix file, which will introduce a new +NixOS option called home-manager.users whose type is an attribute +set that maps user names to Home Manager configurations.

For example, a NixOS configuration may include the lines

users.users.eve.isNormalUser = true;
 home-manager.users.eve = { pkgs, ... }: {
   home.packages = [ pkgs.atool pkgs.httpie ];
   programs.bash.enable = true;
-};
-

- and after a nixos-rebuild switch the user eve's - environment should include a basic Bash configuration and the packages atool - and httpie. -

Note

- By default packages will be installed to - $HOME/.nix-profile but they can be installed to - /etc/profiles if - 

-home-manager.useUserPackages = true;
-

- is added to the system configuration. This is necessary if, for example, - you wish to use nixos-rebuild build-vm. This option may - become the default value in the future. -

Note

- By default, Home Manager uses a private pkgs instance - that is configured via the home-manager.users.<name>.nixpkgs options. - To instead use the global pkgs that is configured via - the system level nixpkgs options, set - 

-home-manager.useGlobalPkgs = true;
-

- This saves an extra Nixpkgs evaluation, adds consistency, and removes the - dependency on NIX_PATH, which is otherwise used for - importing Nixpkgs. -

1.3. nix-darwin module

- Home Manager provides a module that allows you to prepare user - environments directly from the nix-darwin configuration file, which often is - more convenient than using the home-manager tool. -

- To make the NixOS module available for use you must import - it into your system configuration. This is most conveniently done by adding - a Home Manager channel, for example - 

-# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
-# nix-channel --update
-

- if you are following Nixpkgs master or an unstable channel and - 

-# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager
-# nix-channel --update
-

- if you follow a Nixpkgs version 20.09 channel. -

- It is then possible to add - 

-imports = [ <home-manager/nix-darwin> ];
-

- to your nix-darwin configuration.nix file, which will - introduce a new NixOS option called home-manager whose type - is an attribute set that maps user names to Home Manager configurations. -

- For example, a nix-darwin configuration may include the lines - 

-home-manager.users.eve = { pkgs, ... }: {
+};

and after a nixos-rebuild switch the user eve’s environment should +include a basic Bash configuration and the packages atool and httpie.

Note

By default packages will be installed to $HOME/.nix-profile but they +can be installed to /etc/profiles if

home-manager.useUserPackages = true;

is added to the system configuration. This is necessary if, for +example, you wish to use nixos-rebuild build-vm. This option may +become the default value in the future.

Note

By default, Home Manager uses a private pkgs instance that is +configured via the home-manager.users.<name>.nixpkgs options. To +instead use the global pkgs that is configured via the system level +nixpkgs options, set

home-manager.useGlobalPkgs = true;

This saves an extra Nixpkgs evaluation, adds consistency, and removes +the dependency on NIX_PATH, which is otherwise used for importing +Nixpkgs.

1.3. nix-darwin module

Home Manager provides a module that allows you to prepare user +environments directly from the nix-darwin configuration +file, which often is more convenient than using the home-manager +tool.

To make the NixOS module available for use you must import it into +your system configuration. This is most conveniently done by adding a +Home Manager channel, for example

# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
+# nix-channel --update

if you are following Nixpkgs master or an unstable channel and

# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager
+# nix-channel --update

if you follow a Nixpkgs version 20.09 channel.

It is then possible to add

imports = [ <home-manager/nix-darwin> ];

to your nix-darwin configuration.nix file, which will introduce a +new NixOS option called home-manager whose type is an attribute set +that maps user names to Home Manager configurations.

For example, a nix-darwin configuration may include the lines

home-manager.users.eve = { pkgs, ... }: {
   home.packages = [ pkgs.atool pkgs.httpie ];
   programs.bash.enable = true;
-};
-

- and after a darwin-rebuild --switch the user eve's - environment should include a basic Bash configuration and the packages atool - and httpie. -

Note

- By default user packages will not be ignored in favor of - environment.systemPackages, but they will be intalled to - /etc/profiles/per-user/$USERNAME if - 

-home-manager.useUserPackages = true;
-

- is added to the nix-darwin configuration. This option may become the default - value in the future. -

Note

- By default, Home Manager uses a private pkgs instance - that is configured via the home-manager.users.<name>.nixpkgs options. - To instead use the global pkgs that is configured via - the system level nixpkgs options, set - 

-home-manager.useGlobalPkgs = true;
-

- This saves an extra Nixpkgs evaluation, adds consistency, and removes the - dependency on NIX_PATH, which is otherwise used for - importing Nixpkgs. -

Chapter 2. 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.

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

+};

and after a darwin-rebuild --switch the user eve’s environment +should include a basic Bash configuration and the packages atool and +httpie.

Note

By default user packages will not be ignored in favor of +environment.systemPackages, but they will be intalled to +/etc/profiles/per-user/$USERNAME if

home-manager.useUserPackages = true;

is added to the nix-darwin configuration. This option may become the +default value in the future.

Note

By default, Home Manager uses a private pkgs instance that is +configured via the home-manager.users.<name>.nixpkgs options. To +instead use the global pkgs that is configured via the system level +nixpkgs options, set

home-manager.useGlobalPkgs = true;

This saves an extra Nixpkgs evaluation, adds consistency, and removes +the dependency on NIX_PATH, which is otherwise used for importing +Nixpkgs.

Chapter 2. 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.

2.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. diff --git a/tools.html b/tools.html index eacd14fa..13ffddf7 100644 --- a/tools.html +++ b/tools.html @@ -1,6 +1,6 @@ -Appendix B. Tools

Appendix B. Tools
Prev   Next

Appendix B. Tools

home-manager - — reconfigure a user environment

Name

home-manager +Appendix B. Tools

Appendix B. Tools
Prev   Next

Appendix B. Tools

home-manager + — reconfigure a user environment

Name

home-manager — reconfigure a user environment

Synopsis

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

Description

+ ]

Description

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

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

-

Options

+

Options

The tool accepts the options

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

Activates verbose output. -

Files

+

Files

~/.local/share/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 A. Configuration Options Home Appendix C. Release Notes
\ No newline at end of file