From e41ea7354e6a527673d5dee51fcf7bd40da4b82e Mon Sep 17 00:00:00 2001 From: rycee Date: Mon, 15 Nov 2021 19:58:45 +0000 Subject: [PATCH] deploy: 2dcd9eb021bab3ac51995099aec16b7354851c9c --- index.html | 48 +++++++++++++++++++++++++++++------------------- tools.html | 14 +++++++------- 2 files changed, 36 insertions(+), 26 deletions(-) diff --git a/index.html b/index.html index 66dadd34..851baf8e 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 21.11
E.1.1. Highlights
E.1.2. State Version Changes
E.2. Release 21.05
E.2.1. Highlights
E.2.2. State Version Changes
E.3. Release 20.09
E.3.1. Highlights
E.3.2. State Version Changes
E.4. Release 20.03
E.4.1. Highlights
E.4.2. State Version Changes
E.5. Release 19.09
E.5.1. Highlights
E.5.2. State Version Changes
E.6. Release 19.03
E.6.1. Highlights
E.6.2. State Version Changes
E.7. 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. 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 21.11
E.1.1. Highlights
E.1.2. State Version Changes
E.2. Release 21.05
E.2.1. Highlights
E.2.2. State Version Changes
E.3. Release 20.09
E.3.1. Highlights
E.3.2. State Version Changes
E.4. Release 20.03
E.4.1. Highlights
E.4.2. State Version Changes
E.5. Release 19.09
E.5.1. Highlights
E.5.2. State Version Changes
E.6. Release 19.03
E.6.1. Highlights
E.6.2. State Version Changes
E.7. Release 18.09

Preface

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

@@ -18,7 +18,7 @@ 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 +home directory independently of the system as a whole. See Section 1.1, “Standalone installation” for instructions on how to perform this installation.

  • @@ -31,7 +31,7 @@ As a module within a darwin-rebuild. See Section 1.3, “nix-darwin module” for a description of this setup. -

    • 1.1. Standalone installation

    1. +

    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 @@ -40,12 +40,12 @@ 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. If you are -following Nixpkgs master or an unstable channel then this is done by -running +

      Note that Nix 2.4 is not yet fully supported. Most significantly, Home +Manager is incompatible with the new nix profile.

    3. +Add the appropriate Home Manager channel. If you are following +Nixpkgs master or an unstable channel you can run 

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

      and if you follow a Nixpkgs version 21.05 channel, you can run

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

      and if you follow a Nixpkgs version 21.05 channel you can run

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

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

    4. @@ -56,14 +56,12 @@ user environment.

    5. 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. Alternatively source

      /etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh

      when managing home configuration together with system configuration.

      This file can be sourced directly by POSIX.2-like shells such as -Bash or -Z shell. Fish -users can use utilities such as -foreign-env or -babelfish.

      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 +Bash or Z shell. Fish users can use utilities +such as foreign-env or babelfish.

    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 +to the repository.

    Once installed you can see Chapter 2, Using Home Manager for a more detailed +description of Home Manager and how to use it.

    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 @@ -80,7 +78,12 @@ 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 +include a basic Bash configuration and the packages atool and httpie.

    If you do not plan on having Home Manager manage your shell +configuration then you must add either

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

    or

    . "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"

    to your shell configuration, depending on whether +home-manager.useUserPackages is enabled. This file can +be sourced directly by POSIX.2-like shells such as Bash or +Z shell. Fish users can use utilities such as +foreign-env or babelfish.

    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 @@ -88,7 +91,8 @@ configured via the home-manager.users.<name>.nixpkgs 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 +Nixpkgs.

    Once installed you can see Chapter 2, Using Home Manager for a more detailed +description of Home Manager and how to use it.

    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 @@ -107,7 +111,12 @@ home-manager.users.eve = { pkgs, ... }: { 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 +httpie.

    If you do not plan on having Home Manager manage your shell +configuration then you must add either

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

    or

    . "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"

    to your shell configuration, depending on whether +home-manager.useUserPackages is enabled. This file +can be sourced directly by POSIX.2-like shells such as Bash or +Z shell. Fish users can use utilities such as +foreign-env or babelfish.

    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 @@ -115,7 +124,8 @@ configured via the home-manager.users.<name>.nixpkgs 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. 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 containing 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
+Nixpkgs.

    Once installed you can see Chapter 2, Using Home Manager for a more detailed +description of Home Manager and how to use it.

    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, ... }:
diff --git a/tools.html b/tools.html
index 78902f08..59aae896 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
      |   
@@ -82,7 +82,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.
   
    
@@ -151,7 +151,7 @@
           available for immediate garbage collection.
          
    
       
    
-  
    Options
    
+  
    Options
    
    The tool accepts the options
   
    
      -A attrPath
@@ -259,15 +259,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 C. nix-darwin Module Options Home Appendix E. Release Notes
    \ No newline at end of file