diff options
author | Katharina Fey <kookie@spacekookie.de> | 2019-10-05 12:06:29 +0000 |
---|---|---|
committer | Katharina Fey <kookie@spacekookie.de> | 2019-10-05 12:42:50 +0000 |
commit | 1148b1d122bc03e9a3665856c9b7bb96bd4e3994 (patch) | |
tree | 1a9586de593790e236349d5caa0abdff7f3f6856 /home-manager/doc | |
parent | 919d4e75699aa4ba456fd2d3d416a0522c9c7294 (diff) | |
parent | 8bddc1adab0f7a51476f819fa2197353e8e1d136 (diff) |
Add 'home-manager/' from commit '8bddc1adab0f7a51476f819fa2197353e8e1d136'
git-subtree-dir: home-manager
git-subtree-mainline: 919d4e75699aa4ba456fd2d3d416a0522c9c7294
git-subtree-split: 8bddc1adab0f7a51476f819fa2197353e8e1d136
Diffstat (limited to 'home-manager/doc')
-rw-r--r-- | home-manager/doc/default.nix | 72 | ||||
-rw-r--r-- | home-manager/doc/installation.xml | 310 | ||||
-rw-r--r-- | home-manager/doc/man-configuration.xml | 40 | ||||
-rw-r--r-- | home-manager/doc/man-home-manager.xml | 497 | ||||
-rw-r--r-- | home-manager/doc/man-pages.xml | 12 | ||||
-rw-r--r-- | home-manager/doc/manual.xml | 38 | ||||
-rw-r--r-- | home-manager/doc/release-notes/release-notes.xml | 14 | ||||
-rw-r--r-- | home-manager/doc/release-notes/rl-1809.adoc | 4 | ||||
-rw-r--r-- | home-manager/doc/release-notes/rl-1903.adoc | 59 | ||||
-rw-r--r-- | home-manager/doc/release-notes/rl-1909.adoc | 19 |
10 files changed, 1065 insertions, 0 deletions
diff --git a/home-manager/doc/default.nix b/home-manager/doc/default.nix new file mode 100644 index 00000000000..acfa1f1e49c --- /dev/null +++ b/home-manager/doc/default.nix @@ -0,0 +1,72 @@ +{ pkgs }: + +let + + lib = pkgs.lib; + + nmdSrc = pkgs.fetchFromGitLab { + name = "nmd"; + owner = "rycee"; + repo = "nmd"; + rev = "9751ca5ef6eb2ef27470010208d4c0a20e89443d"; + sha256 = "0rbx10n8kk0bvp1nl5c8q79lz1w0p1b8103asbvwps3gmqd070hi"; + }; + + nmd = import nmdSrc { inherit pkgs; }; + + # Make sure the used package is scrubbed to avoid actually + # instantiating derivations. + scrubbedPkgsModule = { + imports = [ + { + _module.args = { + pkgs = lib.mkForce (nmd.scrubDerivations "pkgs" pkgs); + pkgs_i686 = lib.mkForce { }; + }; + } + ]; + }; + + hmModulesDocs = nmd.buildModulesDocs { + modules = + import ../modules/modules.nix { inherit lib pkgs; } + ++ [ scrubbedPkgsModule ]; + moduleRootPaths = [ ./.. ]; + mkModuleUrl = path: + "https://github.com/rycee/home-manager/blob/master/${path}#blob-path"; + channelName = "home-manager"; + docBook.id = "home-manager-options"; + }; + + docs = nmd.buildDocBookDocs { + pathName = "home-manager"; + modulesDocs = [ hmModulesDocs ]; + documentsDirectory = ./.; + chunkToc = '' + <toc> + <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-home-manager-manual"><?dbhtml filename="index.html"?> + <d:tocentry linkend="ch-options"><?dbhtml filename="options.html"?></d:tocentry> + <d:tocentry linkend="ch-tools"><?dbhtml filename="tools.html"?></d:tocentry> + <d:tocentry linkend="ch-release-notes"><?dbhtml filename="release-notes.html"?></d:tocentry> + </d:tocentry> + </toc> + ''; + }; + +in + +{ + inherit nmdSrc; + + options = { + json = hmModulesDocs.json.override { + path = "share/doc/home-manager/options.json"; + }; + }; + + manPages = docs.manPages; + + manual = { + inherit (docs) html htmlOpenTool; + }; +} diff --git a/home-manager/doc/installation.xml b/home-manager/doc/installation.xml new file mode 100644 index 00000000000..0e4c904e570 --- /dev/null +++ b/home-manager/doc/installation.xml @@ -0,0 +1,310 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-installation"> + <title>Installing Home Manager</title> + <para> + Home Manager can be used in three primary ways: + <orderedlist> + <listitem> + <para> + Using the standalone <command>home-manager</command> 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 + <xref linkend="sec-install-standalone"/> for instructions on how to + perform this installation. + </para> + </listitem> + <listitem> + <para> + As a module within a NixOS system configuration. This allows the user + profiles to be built together with the system when running + <command>nixos-rebuild</command>. See + <xref linkend="sec-install-nixos-module"/> for a description of this + setup. + </para> + </listitem> + <listitem> + <para> + As a module within a + <link xlink:href="https://github.com/LnL7/nix-darwin/">nix-darwin</link> + system configuration. This allows the user profiles to be built together + with the system when running <command>darwin-rebuild</command>. See + <xref linkend="sec-install-nix-darwin-module"/> for a description of this + setup. + </para> + </listitem> + </orderedlist> + </para> + <section xml:id="sec-install-standalone"> + <title>Standalone installation</title> + + <orderedlist> + <listitem> + <para> + Make sure you have a working Nix installation. If you are not using NixOS + then it may be necessary to run + </para> +<screen> +<prompt>$</prompt> <userinput>mkdir -m 0755 -p /nix/var/nix/{profiles,gcroots}/per-user/$USER</userinput> +</screen> + <para> + since Home Manager uses these directories to manage your profile + generations. On NixOS these should already be available. + </para> + <para> + Also 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 + <literal>nix-instantiate '<nixpkgs>' -A hello</literal> 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 + <link xlink:href="https://nixos.org/nix/manual/#conf-allowed-users"><literal>allowed-users</literal></link> + Nix option. On NixOS you can control this option using the + <link xlink:href="https://nixos.org/nixos/manual/options.html#opt-nix.allowedUsers"><literal>nix.allowedUsers</literal></link> + system option. + </para> + </listitem> + <listitem> + <para> + Add the Home Manager channel that you wish to follow. This is done by + running + </para> +<screen> +<prompt>$</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager</userinput> +<prompt>$</prompt> <userinput>nix-channel --update</userinput> +</screen> + <para> + if you are following Nixpkgs master or an unstable channel and + </para> +<screen> +<prompt>$</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/release-19.03.tar.gz home-manager</userinput> +<prompt>$</prompt> <userinput>nix-channel --update</userinput> +</screen> + <para> + if you follow a Nixpkgs version 19.03 channel. + </para> + <para> + 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 +<programlisting language="bash"> +export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH +</programlisting> + to your shell (see + <link xlink:href="https://github.com/NixOS/nix/issues/2033">nix#2033</link>). + </para> + </listitem> + <listitem> + <para> + Run the Home Manager installation command and create the first Home + Manager generation: + </para> +<screen> +<prompt>$</prompt> <userinput>nix-shell '<home-manager>' -A install</userinput> +</screen> + <para> + Once finished, Home Manager should be active and available in your user + environment. + </para> + </listitem> + <listitem> + <para> + If you do not plan on having Home Manager manage your shell configuration + then you must source the + </para> +<programlisting language="bash"> +$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh +</programlisting> + <para> + file in your shell configuration. Unfortunately, we currently only support + POSIX.2-like shells such as + <link xlink:href="https://www.gnu.org/software/bash/">Bash</link> or + <link xlink:href="http://zsh.sourceforge.net/">Z shell</link>. + </para> + <para> + For example, if you use Bash then add + </para> +<programlisting language="bash"> +. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" +</programlisting> + <para> + to your <literal>~/.profile</literal> file. + </para> + </listitem> + </orderedlist> + + <para> + If instead of using channels you want to run Home Manager from a Git + checkout of the repository then you can use the + <literal>programs.home-manager.path</literal> option to specify the absolute + path to the repository. + </para> + </section> + <section xml:id="sec-install-nixos-module"> + <title>NixOS module</title> + + <para> + 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 <command>home-manager</command> tool. It also + opens up additional possibilities, for example, to automatically configure + user environments in NixOS declarative containers or on systems deployed + through NixOps. + </para> + + <para> + To make the NixOS module available for use you must <option>import</option> + it into your system configuration. This is most conveniently done by adding + a Home Manager channel, for example + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you are following Nixpkgs master or an unstable channel and + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/release-19.03.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you follow a Nixpkgs version 19.03 channel. + </para> + + <para> + It is then possible to add + </para> + +<programlisting language="nix"> +imports = [ <home-manager/nixos> ]; +</programlisting> + + <para> + to your system <filename>configuration.nix</filename> file, which will + introduce a new NixOS option called <option>home-manager.users</option> + whose type is an attribute set that maps user names to Home Manager + configurations. + </para> + + <para> + For example, a NixOS configuration may include the lines + </para> + +<programlisting language="nix"> +users.users.eve.isNormalUser = true; +home-manager.users.eve = { pkgs, ... }: { + home.packages = [ pkgs.atool pkgs.httpie ]; + programs.bash.enable = true; +}; +</programlisting> + + <para> + and after a <command>nixos-rebuild switch</command> the user eve's + environment should include a basic Bash configuration and the packages atool + and httpie. + </para> + + <note> + <para> + By default packages will be installed to + <filename>$HOME/.nix-profile</filename> but they can be installed to + <filename>/etc/profiles</filename> if + </para> +<programlisting language="nix"> +home-manager.useUserPackages = true; +</programlisting> + <para> + is added to the system configuration. This is necessary if, for example, + you wish to use <command>nixos-rebuild build-vm</command>. This option may + become the default value in the future. + </para> + </note> + </section> + <section xml:id="sec-install-nix-darwin-module"> + <title>nix-darwin module</title> + + <para> + 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 <command>home-manager</command> tool. + </para> + + <para> + To make the NixOS module available for use you must <option>import</option> + it into your system configuration. This is most conveniently done by adding + a Home Manager channel, for example + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you are following Nixpkgs master or an unstable channel and + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/release-19.03.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you follow a Nixpkgs version 19.03 channel. + </para> + + <para> + It is then possible to add + </para> + +<programlisting language="nix"> +imports = [ <home-manager/nix-darwin> ]; +</programlisting> + + <para> + to your nix-darwin <filename>configuration.nix</filename> file, which will + introduce a new NixOS option called <option>home-manager</option> whose type + is an attribute set that maps user names to Home Manager configurations. + </para> + + <para> + For example, a nix-darwin configuration may include the lines + </para> + +<programlisting language="nix"> +home-manager.users.eve = { pkgs, ... }: { + home.packages = [ pkgs.atool pkgs.httpie ]; + programs.bash.enable = true; +}; +</programlisting> + + <para> + and after a <command>darwin-rebuild --switch</command> the user eve's + environment should include a basic Bash configuration and the packages atool + and httpie. + </para> + + <note> + <para> + By default user packages will not be ignored in favor of + <option>environment.systemPackages</option>, but they will be intalled to + <option>/etc/profiles/per-user/$USERNAME</option> if + </para> + +<programlisting language="nix"> +home-manager.useUserPackages = true; +</programlisting> + + <para> + is added to the nix-darwin configuration. This option may become the default + value in the future. + </para> + </note> + </section> +</chapter> diff --git a/home-manager/doc/man-configuration.xml b/home-manager/doc/man-configuration.xml new file mode 100644 index 00000000000..42962a75f3c --- /dev/null +++ b/home-manager/doc/man-configuration.xml @@ -0,0 +1,40 @@ +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refmeta> + <refentrytitle><filename>home-configuration.nix</filename></refentrytitle> + <manvolnum>5</manvolnum> + <refmiscinfo class="source">Home Manager</refmiscinfo> +<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> + </refmeta> + <refnamediv> + <refname><filename>home-configuration.nix</filename></refname> + <refpurpose>Home Manager configuration specification</refpurpose> + </refnamediv> + <refsection> + <title>Description</title> + <para> + The file <filename>~/.config/nixpkgs/home.nix</filename> contains the + declarative specification of your Home Manager configuration. The command + <command>home-manager</command> takes this file and realises the user + environment configuration specified therein. + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + You can use the following options in + <filename>home-configuration.nix</filename>: + </para> + <xi:include href="./nmd-result/home-manager-options.xml" /> + </refsection> + <refsection> + <title>See also</title> + <para> + <citerefentry> + <refentrytitle>home-manager</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry> + </para> + </refsection> +</refentry> diff --git a/home-manager/doc/man-home-manager.xml b/home-manager/doc/man-home-manager.xml new file mode 100644 index 00000000000..a0f55d1106a --- /dev/null +++ b/home-manager/doc/man-home-manager.xml @@ -0,0 +1,497 @@ +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refmeta> + <refentrytitle><command>home-manager</command> + </refentrytitle><manvolnum>1</manvolnum> + <refmiscinfo class="source">Home Manager</refmiscinfo> + </refmeta> + <refnamediv> + <refname><command>home-manager</command> + </refname><refpurpose>reconfigure a user environment</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + <command>home-manager</command> <group choice="req"> + <arg choice="plain"> + build + </arg> + + <arg choice="plain"> + edit + </arg> + + <arg choice="plain"> + expire-generations <replaceable>timestamp</replaceable> + </arg> + + <arg choice="plain"> + generations + </arg> + + <arg choice="plain"> + help + </arg> + + <arg choice="plain"> + news + </arg> + + <arg choice="plain"> + packages + </arg> + + <arg choice="plain"> + remove-generations <replaceable>ID …</replaceable> + </arg> + + <arg choice="plain"> + switch + </arg> + + <arg choice="plain"> + uninstall + </arg> + </group> + <sbr /> + <arg> + -A <replaceable>attrPath</replaceable> + </arg> + + <arg> + -I <replaceable>path</replaceable> + </arg> + + <arg> + -b <replaceable>ext</replaceable> + </arg> + + <arg> + <group choice="req"> + <arg choice="plain"> + -f + </arg> + + <arg choice="plain"> + --file + </arg> + </group> <replaceable>path</replaceable> + </arg> + + <arg> + <group choice="req"> + <arg choice="plain"> + -h + </arg> + + <arg choice="plain"> + --help + </arg> + </group> + </arg> + + <arg> + <group choice="req"> + <arg choice="plain"> + -n + </arg> + + <arg choice="plain"> + --dry-run + </arg> + </group> + </arg> + + <arg> + --option <replaceable>name</replaceable> <replaceable>value</replaceable> + </arg> + + <arg> + --cores <replaceable>number</replaceable> + </arg> + + <arg> + --max-jobs <replaceable>number</replaceable> + </arg> + + <arg> + --keep-failed + </arg> + + <arg> + --keep-going + </arg> + + <arg> + --show-trace + </arg> + + <arg> + <group choice="req"> + <arg choice="plain"> + -v + </arg> + + <arg choice="plain"> + --verbose + </arg> + </group> + </arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsection> + <title>Description</title> + <para> + This command updates the user environment so that it corresponds to the + configuration specified in <filename>~/.config/nixpkgs/home.nix</filename>. + </para> + <para> + All operations using this tool expects a sub-command that indicates the + operation to perform. It must be one of + <variablelist> + <varlistentry> + <term> + <option>build</option> + </term> + <listitem> + <para> + Build configuration into a <filename>result</filename> directory. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>edit</option> + </term> + <listitem> + <para> + Open the home configuration using the editor indicated by + <envar>EDITOR</envar>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>expire-generations <replaceable>timestamp</replaceable></option> + </term> + <listitem> + <para> + Remove generations older than <replaceable>timestamp</replaceable> where + <replaceable>timestamp</replaceable> is interpreted as in the + <option>-d</option> argument of the <citerefentry> + <refentrytitle>date</refentrytitle> + <manvolnum>1</manvolnum> </citerefentry> tool. For example <literal>-30 + days</literal> or <literal>2018-01-01</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>generations</option> + </term> + <listitem> + <para> + List all home environment generations. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>help</option> + </term> + <listitem> + <para> + Print tool help. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>news</option> + </term> + <listitem> + <para> + Show news entries in a pager. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>packages</option> + </term> + <listitem> + <para> + List all packages installed in <varname>home-manager-path</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>remove-generations <replaceable>ID …</replaceable></option> + </term> + <listitem> + <para> + Remove indicated generations. Use the <option>generations</option> + sub-command to find suitable generation numbers. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>switch</option> + </term> + <listitem> + <para> + Build and activate the configuration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>uninstall</option> + </term> + <listitem> + <para> + Remove Home Manager from the user environment. This will + <itemizedlist> + <listitem> + <para> + remove all managed files from the home directory, + </para> + </listitem> + <listitem> + <para> + remove packages installed through Home Manager from the user profile, + and + </para> + </listitem> + <listitem> + <para> + optionally remove all Home Manager generations and make them + available for immediate garbage collection. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsection> + <refsection> + <title>Options</title> + <para> + The tool accepts the options + </para> + <variablelist> + <varlistentry> + <term> + <option>-A <replaceable>attrPath</replaceable></option> + </term> + <listitem> + <para> + Optional attribute that selects a configuration expression in the + configuration file. That is, if <filename>home.nix</filename> contains +<programlisting language="nix"> +{ + joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; }; + joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; }; +} +</programlisting> + then the command <command>home-manager switch -A joe-at-work</command> + will activate the profile containing the fortune program. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-I <replaceable>path</replaceable></option> + </term> + <listitem> + <para> + Add a path to the Nix expression search path. For example, to build a + Home Manager profile using a specific Nixpkgs run <command>home-manager + -I nixpkgs=/absolute/path/to/nixpkgs build</command>. By default + <literal><nixpkgs></literal> is used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-b <replaceable>extension</replaceable></option> + </term> + <listitem> + <para> + Enable automatic resolution of collisions between unmanaged and managed + files. The name of the original file will be suffixed by the given + extension. For example, +<screen> +<prompt>$</prompt> <userinput>home-manager -b bck switch</userinput> +</screen> + will cause a colliding file <filename>~/.config/foo.conf</filename> to be + moved to <filename>~/.config/foo.conf.bck</filename>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-f <replaceable>path</replaceable></option> + </term> + <term> + <option>--file <replaceable>path</replaceable></option> + </term> + <listitem> + <para> + Indicates the path to the Home Manager configuration file. If not given, + <filename>~/.config/nixpkgs/home.nix</filename> is used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-h</option> + </term> + <term> + <option>--help</option> + </term> + <listitem> + <para> + Prints usage information for the <command>home-manager</command> tool. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-n</option> + </term> + <term> + <option>--dry-run</option> + </term> + <listitem> + <para> + Perform a dry-run of the given operation, only prints what actions would + be taken. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--option <replaceable>name</replaceable> <replaceable>value</replaceable></option> + </term> + <listitem> + <para> + Passed on to <citerefentry> + <refentrytitle>nix-build</refentrytitle> + <manvolnum>1</manvolnum> </citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--cores <replaceable>number</replaceable></option> + </term> + <listitem> + <para> + Passed on to <citerefentry> + <refentrytitle>nix-build</refentrytitle> + <manvolnum>1</manvolnum> </citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--max-jobs <replaceable>number</replaceable></option> + </term> + <listitem> + <para> + Passed on to <citerefentry> + <refentrytitle>nix-build</refentrytitle> + <manvolnum>1</manvolnum> </citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--keep-failed</option> + </term> + <listitem> + <para> + Passed on to <citerefentry> + <refentrytitle>nix-build</refentrytitle> + <manvolnum>1</manvolnum> </citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--keep-going</option> + </term> + <listitem> + <para> + Passed on to <citerefentry> + <refentrytitle>nix-build</refentrytitle> + <manvolnum>1</manvolnum> </citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>--show-trace</option> + </term> + <listitem> + <para> + Passed on to <citerefentry> + <refentrytitle>nix-build</refentrytitle> + <manvolnum>1</manvolnum> </citerefentry>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <option>-v</option> + </term> + <term> + <option>--verbose</option> + </term> + <listitem> + <para> + Activates verbose output. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Files</title> + <variablelist> + <varlistentry> + <term> + <filename>~/.local/share/home-manager/news-read-ids</filename> + </term> + <listitem> + <para> + Identifiers of news items that have been shown. Can be deleted to reset + the read news indicator. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsection> + <refsection> + <title>Bugs</title> + <para> + Please report any bugs on the + <link + xlink:href="https://github.com/rycee/home-manager/issues">project + issue tracker</link>. + </para> + </refsection> + <refsection> + <title>See also</title> + <para> + <citerefentry> + <refentrytitle>home-configuration.nix</refentrytitle> + <manvolnum>5</manvolnum> </citerefentry> + </para> + </refsection> +</refentry> diff --git a/home-manager/doc/man-pages.xml b/home-manager/doc/man-pages.xml new file mode 100644 index 00000000000..616c2ef291b --- /dev/null +++ b/home-manager/doc/man-pages.xml @@ -0,0 +1,12 @@ +<reference xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude"> + <title>Home Manager Reference Pages</title> + <info> + <author><personname>Home Manager contributors</personname></author> + <copyright><year>2017–2019</year><holder>Home Manager contributors</holder> + </copyright> + </info> + <xi:include href="man-configuration.xml" /> + <xi:include href="man-home-manager.xml" /> +</reference> diff --git a/home-manager/doc/manual.xml b/home-manager/doc/manual.xml new file mode 100644 index 00000000000..8ff81308b2c --- /dev/null +++ b/home-manager/doc/manual.xml @@ -0,0 +1,38 @@ +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="book-home-manager-manual"> + <info> + <title>Home Manager Manual</title> + </info> + <preface> + <title>Preface</title> + <para> + This manual will eventually describes how to install, use, and extend Home + Manager. + </para> + <para> + If you encounter problems or bugs then please report them on the + <link xlink:href="https://github.com/rycee/home-manager/issues">Home Manager + issue tracker</link>. + </para> + <note> + <para> + Commands prefixed with <literal>#</literal> have to be run as root, either + requiring to login as root user or temporarily switching to it using + <literal>sudo</literal> for example. + </para> + </note> + </preface> + <xi:include href="installation.xml" /> + <appendix xml:id="ch-options"> + <title>Configuration Options</title> + <xi:include href="./nmd-result/home-manager-options.xml" /> + </appendix> + <appendix xml:id="ch-tools"> + <title>Tools</title> + <xi:include href="./man-home-manager.xml" /> + </appendix> + <xi:include href="./release-notes/release-notes.xml" /> +</book> diff --git a/home-manager/doc/release-notes/release-notes.xml b/home-manager/doc/release-notes/release-notes.xml new file mode 100644 index 00000000000..4675f0bfa5c --- /dev/null +++ b/home-manager/doc/release-notes/release-notes.xml @@ -0,0 +1,14 @@ +<appendix xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-release-notes"> + <title>Release Notes</title> + <para> + This section lists the release notes for stable versions of Home Manager and + the current unstable version. + </para> + <xi:include href="rl-1909.xml" /> + <xi:include href="rl-1903.xml" /> + <xi:include href="rl-1809.xml" /> +</appendix> diff --git a/home-manager/doc/release-notes/rl-1809.adoc b/home-manager/doc/release-notes/rl-1809.adoc new file mode 100644 index 00000000000..b363704e241 --- /dev/null +++ b/home-manager/doc/release-notes/rl-1809.adoc @@ -0,0 +1,4 @@ +[[sec-release-18.09]] +== Release 18.09 + +The 18.09 release branch became the stable branch in September, 2018. diff --git a/home-manager/doc/release-notes/rl-1903.adoc b/home-manager/doc/release-notes/rl-1903.adoc new file mode 100644 index 00000000000..6dfdc67f5bf --- /dev/null +++ b/home-manager/doc/release-notes/rl-1903.adoc @@ -0,0 +1,59 @@ +[[sec-release-19.03]] +== Release 19.03 + +The 19.03 release branch became the stable branch in April, 2019. + +[[sec-release-19.03-highlights]] +=== Highlights +:opt-home-file-source: opt-home.file._name__.source + +This release has the following notable changes: + +* The <<{opt-home-file-source}>> option now allows source files to be +hidden, that is, having a name starting with the `.` character. It +also allows the source file name to contain characters not typically +allowed for Nix store paths. For example, your configuration can now +contain things such as ++ +[source,nix] +---- +home.file."my file".source = ./. + "/file with spaces!"; +---- + +* The type used for the systemd unit options under +<<opt-systemd.user.services>>, <<opt-systemd.user.sockets>>, etc. has +been changed to offer more robust merging of configurations. If you +don't override values within systemd units then you are not affected +by this change. Unfortunately, if you do override unit values you may +encounter errors. ++ +In particular, if you get an error saying that a ``unique option'' is +``defined multiple times'' then you need to use the +https://nixos.org/nixos/manual/#sec-option-definitions-setting-priorities[`mkForce`] +function. For example, ++ +[source,nix] +---- +systemd.user.services.foo.Service.ExecStart = "/foo/bar"; +---- ++ +becomes ++ +[source,nix] +---- +systemd.user.services.foo.Service.ExecStart = lib.mkForce "/foo/bar"; +---- ++ +We had to make this change because the old merging was causing too +many confusing situations for people. + +[[sec-release-19.03-state-version-changes]] +=== State Version Changes + +The state version in this release includes the changes below. These +changes are only active if the <<opt-home.stateVersion>> option is set +to ``19.03'' or later. + +* There is now an option <<opt-programs.beets.enable>> that defaults +to `false`. Before the module would be active if the +<<opt-programs.beets.settings>> option was non-empty. diff --git a/home-manager/doc/release-notes/rl-1909.adoc b/home-manager/doc/release-notes/rl-1909.adoc new file mode 100644 index 00000000000..a33d629767e --- /dev/null +++ b/home-manager/doc/release-notes/rl-1909.adoc @@ -0,0 +1,19 @@ +[[sec-release-19.09]] +== Release 19.09 (unreleased) + +This is the current unstable branch and the information in this +section is therefore not final. + +[[sec-release-19.09-state-version-changes]] +=== State Version Changes + +The state version in this release includes the changes below. These +changes are only active if the `home.stateVersion` option is set to +"19.09" or later. + +* The <<opt-programs.firefox.package>> option now expects a wrapped + Firefox package and defaults to `pkgs.firefox`. + +* The options <<opt-home.keyboard.layout>> and + <<opt-home.keyboard.variant>> now default to `null`, which indicates + that the system value should be used. |