diff options
| -rw-r--r-- | doc/manual/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/manual/conf-file.xml | 2 | ||||
| -rw-r--r-- | doc/manual/env-common.xml | 9 | ||||
| -rw-r--r-- | doc/manual/manual.xml | 4 | ||||
| -rw-r--r-- | doc/manual/nix-channel.xml | 83 | ||||
| -rw-r--r-- | doc/manual/nix-store.xml | 14 | ||||
| -rw-r--r-- | doc/manual/package-management.xml | 9 |
7 files changed, 108 insertions, 17 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index f5a93cf30..81367fd14 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -5,12 +5,12 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \ --param section.autolabel 1 \ --param section.label.includes.component.label 1 \ --param html.stylesheet \'style.css\' \ - --param xref.with.number.and.title 0 \ + --param xref.with.number.and.title 1 \ --param toc.section.depth 3 man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \ nix-collect-garbage.1 nix-push.1 nix-pull.1 \ - nix-prefetch-url.1 + nix-prefetch-url.1 nix-channel.1 FIGURES = figures/user-environments.png diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml index 13fac5335..629dd3bac 100644 --- a/doc/manual/conf-file.xml +++ b/doc/manual/conf-file.xml @@ -7,7 +7,7 @@ This file is a list of <literal><replaceable>name</replaceable> = Comments start with a <literal>#</literal> character. An example configuration file is shown in <xref linkend="ex-nix-conf" />.</para> -<example id='ex-nix-conf'><title>Nix expression for GNU Hello</title> +<example id='ex-nix-conf'><title>Nix configuration file</title> <programlisting> gc-keep-outputs = true # Nice for developers diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml index ec468eba1..2d25d3b28 100644 --- a/doc/manual/env-common.xml +++ b/doc/manual/env-common.xml @@ -246,11 +246,10 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen> <varlistentry><term><filename>references</filename></term> <listitem><para>The reference graph of the inputs, in the format - accepted by the command <link - linkend="rsec-nix-store-reg-val"><command>nix-store - --register-validity</command></link>. It is necessary to run - this command on the remote machine after copying the inputs to - inform Nix on the remote machine that the inputs are valid + accepted by the command <command>nix-store + --register-validity</command>. It is necessary to run this + command on the remote machine after copying the inputs to inform + Nix on the remote machine that the inputs are valid paths.</para></listitem> </varlistentry> diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index f1dd0430a..a9e4473e0 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -56,6 +56,10 @@ <title>nix-collect-garbage</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-collect-garbage.xml" /> </sect1> + <sect1 id="sec-nix-channel"> + <title>nix-channel</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-channel.xml" /> + </sect1> <sect1> <title>nix-push</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-push.xml" /> diff --git a/doc/manual/nix-channel.xml b/doc/manual/nix-channel.xml new file mode 100644 index 000000000..059832a86 --- /dev/null +++ b/doc/manual/nix-channel.xml @@ -0,0 +1,83 @@ +<refentry> + +<refnamediv> + <refname>nix-channel</refname> + <refpurpose>manage Nix channels</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>nix-channel</command> + <group choice='req'> + <arg choice='plain'><option>--add</option> <replaceable>url</replaceable></arg> + <arg choice='plain'><option>--remove</option> <replaceable>url</replaceable></arg> + <arg choice='plain'><option>--list</option></arg> + <arg choice='plain'><option>--update</option></arg> + </group> + </cmdsynopsis> +</refsynopsisdiv> + +<refsection><title>Description</title> + +<para>A Nix channel is mechanism that allows you to automatically stay +up-to-date with a set of pre-built Nix expressions. A Nix channel is +just a URL that points to a place that contains a set of Nix +expressions, as well as a <command>nix-push</command> manifest. See +also <xref linkend="sec-channels" />.</para> + +<para>This command has the following operations: + +<variablelist> + + <varlistentry><term><option>--add</option> <replaceable>url</replaceable></term> + + <listitem><para>Adds <replaceable>url</replaceable> to the list of + subscribed channels.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--remove</option> <replaceable>url</replaceable></term> + + <listitem><para>Removes <replaceable>url</replaceable> from the + list of subscribed channels.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--list</option></term> + + <listitem><para>Prints the URLs of all subscribed channels on + standard output.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--update</option></term> + + <listitem><para>Downloads the Nix expressions of all subscribed + channels, makes the conjunction of these the default for + <command>nix-env</command> operations (by calling <command>nix-env + -I</command>), and performs a <command>nix-pull</command> on the + manifests of all channels to make pre-built binaries + available.</para></listitem> + + </varlistentry> + +</variablelist> + +</para> + +<para>Note that <option>--add</option> and <option>--remove</option> +do not automatically perform an update.</para> + +<para>The list of subscribed channels is stored in +<filename>~/.nix-channels</filename>.</para> + +<para>A channel consists of two elements: a bzipped Tar archive +containing the Nix expressions, and a manifest created by +<command>nix-push</command>. These must be stored under +<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal> and +<literal><replaceable>url</replaceable>/MANIFEST</literal>, +respectively.</para> + +</refsection> + +</refentry> diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml index 614d30b6a..eead48397 100644 --- a/doc/manual/nix-store.xml +++ b/doc/manual/nix-store.xml @@ -571,13 +571,14 @@ $ gv graph.ps</screen> <!--######################################################################--> -<refsection id="rsec-nix-store-reg-val"><title>Operation <option>--register-validity</option></title> +<!-- +<refsection id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title> <refsection><title>Synopsis</title> <cmdsynopsis> <command>nix-store</command> - <arg choice='plain'><option>--register-validity</option></arg> + <arg choice='plain'><option>-XXX-register-validity</option></arg> </cmdsynopsis> </refsection> @@ -588,18 +589,20 @@ $ gv graph.ps</screen> </refsection> </refsection> +--> <!--######################################################################--> -<refsection><title>Operation <option>--substitute</option></title> +<!-- +<refsection><title>Operation <option>-XXX-substitute</option></title> <refsection><title>Synopsis</title> <cmdsynopsis> <command>nix-store</command> - <arg choice='plain'><option>--substitute</option></arg> + <arg choice='plain'><option>-XXX-substitute</option></arg> <arg choice='plain' rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg> </cmdsynopsis> @@ -607,7 +610,7 @@ $ gv graph.ps</screen> <refsection><title>Description</title> -<para>The operation <option>--substitute</option> registers that the +<para>The operation <option>-XXX-substitute</option> registers that the store path <replaceable>srcpath</replaceable> can be built by realising the derivation expression in <replaceable>subpath</replaceable>. This is used to implement binary @@ -616,6 +619,7 @@ deployment.</para> </refsection> </refsection> +--> diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml index b827ae75b..450353337 100644 --- a/doc/manual/package-management.xml +++ b/doc/manual/package-management.xml @@ -408,7 +408,7 @@ followed to prevent infinite recursion.</para> </sect1> -<sect1><title>Channels</title> +<sect1 id="sec-channels"><title>Channels</title> <para>If you want to stay up to date with a set of packages, it’s not very convenient to manually download the latest set of Nix expressions @@ -418,9 +418,10 @@ pre-built binaries (if available), and upgrade using <emphasis>Nix channels</emphasis>.</para> <para>A Nix channel is just a URL that points to a place that contains -a set of Nix expressions and a manifest. Using the command -<command>nix-channel</command> you can automatically stay up to date -with whatever is available at that URL.</para> +a set of Nix expressions and a manifest. Using the command <link +linkend="sec-nix-channel"><command>nix-channel</command></link> you +can automatically stay up to date with whatever is available at that +URL.</para> <para>You can <quote>subscribe</quote> to a channel using <command>nix-channel --add</command>, e.g., |