diff options
Diffstat (limited to 'doc')
33 files changed, 579 insertions, 341 deletions
diff --git a/doc/manual/advanced-topics/advanced-topics.xml b/doc/manual/advanced-topics/advanced-topics.xml new file mode 100644 index 000000000000..338aa6f3a238 --- /dev/null +++ b/doc/manual/advanced-topics/advanced-topics.xml @@ -0,0 +1,10 @@ +<part 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"> + +<title>Advanced Topics</title> + +<xi:include href="distributed-builds.xml" /> + +</part> diff --git a/doc/manual/builds/enabling-builds.xml b/doc/manual/advanced-topics/distributed-builds.xml index 4b45812ee918..70f396f81cdb 100644 --- a/doc/manual/builds/enabling-builds.xml +++ b/doc/manual/advanced-topics/distributed-builds.xml @@ -2,9 +2,18 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" - xml:id="ch-enabling-builds"> + xml:id='chap-distributed-builds'> -<title>Enabling Distributed Builds</title> +<title>Distributed Builds</title> + +<para>Nix supports distributed builds, where a local Nix installation can +forward Nix builds to other machines over the network. This allows +multiple builds to be performed in parallel (thus improving +performance) and allows Nix to perform multi-platform builds in a +semi-transparent way. For instance, if you perform a build for a +<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal> +machine, Nix can automatically forward the build to a +<literal>powerpc-darwin</literal> machine, if available.</para> <para>You can enable distributed builds by setting the environment variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix @@ -41,7 +50,7 @@ example configuration is shown in <xref linkend='ex-remote-systems' bits of information: <orderedlist> - + <listitem><para>The name of the remote machine, with optionally the user under which the remote build should be performed. This is actually passed as an argument to <command>ssh</command>, so it can @@ -73,9 +82,9 @@ bits of information: <filename>build-remote.pl</filename> will only perform the derivation on a machine that has the specified features. For instance, the attribute - + <programlisting> -requiredSystemFeatures = [ "kvm" ]; +requiredSystemFeatures = [ "kvm" ]; </programlisting> will cause the build to be performed on a machine that has the @@ -103,4 +112,4 @@ running, they should use the same <envar>NIX_CURRENT_LOAD</envar> file. Maybe in the future <filename>build-remote.pl</filename> will look at the actual remote load.</para> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/builds/build-farm.xml b/doc/manual/builds/build-farm.xml deleted file mode 100644 index e0e9f10f1173..000000000000 --- a/doc/manual/builds/build-farm.xml +++ /dev/null @@ -1,22 +0,0 @@ -<part 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='chap-distributed-builds'> - -<title>Distributed Builds</title> - -<partintro> -<para>Nix supports distributed builds, where a local Nix installation can -forward Nix builds to other machines over the network. This allows -multiple builds to be performed in parallel (thus improving -performance) and allows Nix to perform multi-platform builds in a -semi-transparent way. For instance, if you perform a build for a -<literal>powerpc-darwin</literal> on an <literal>i686-linux</literal> -machine, Nix can automatically forward the build to a -<literal>powerpc-darwin</literal> machine, if available.</para> -</partintro> - -<xi:include href="enabling-builds.xml" /> - -</part> diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml index 053f4d43cb0c..1728abfd9c59 100644 --- a/doc/manual/command-ref/conf-file.xml +++ b/doc/manual/command-ref/conf-file.xml @@ -243,7 +243,8 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para> users” feature</link> to perform the actual builds under different users than root). Currently, chroot builds only work on Linux because Nix uses “bind mounts” to make the Nix store and other - directories available inside the chroot.</para> + directories available inside the chroot. Kernel version 3.13 or later + is needed.</para> </listitem> diff --git a/doc/manual/command-ref/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml index 195b209f9523..a6f4a27203ac 100644 --- a/doc/manual/command-ref/nix-channel.xml +++ b/doc/manual/command-ref/nix-channel.xml @@ -21,7 +21,7 @@ <command>nix-channel</command> <group choice='req'> <arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></arg> - <arg choice='plain'><option>--remove</option> <replaceable>url</replaceable></arg> + <arg choice='plain'><option>--remove</option> <replaceable>name</replaceable></arg> <arg choice='plain'><option>--list</option></arg> <arg choice='plain'><option>--update</option> <arg rep='repeat'><replaceable>names</replaceable></arg></arg> <arg choice='plain'><option>--rollback</option> <arg choice='opt'><replaceable>generation</replaceable></arg></arg> @@ -33,8 +33,8 @@ <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 containing a set of Nix expressions -and a <command>nix-push</command> manifest. <phrase +just a URL that points to a place containing both a set of Nix +expressions and a pointer to a binary cache. <phrase condition="manual">See also <xref linkend="sec-channels" />.</phrase></para> @@ -99,13 +99,6 @@ 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> <refsection><title>Examples</title> @@ -163,4 +156,49 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.nixpkgsVersion' </refsection> +<refsection><title>Channel format</title> + +<para>A channel URL should point to a directory containing the +following files:</para> + +<variablelist> + + <varlistentry><term><filename>nixexprs.tar.xz</filename></term> + + <listitem><para>A tarball containing Nix expressions and files + referenced by them (such as build scripts and patches). At + top-level, the tarball should contain a single directory. That + directory must contain a file <filename>default.nix</filename> + that serves as the channel’s “entry point”.</para></listitem> + + </varlistentry> + + <varlistentry><term><filename>binary-cache-url</filename></term> + + <listitem><para>A file containing the URL to a binary cache (such + as <uri>https://cache.nixos.org</uri>. Nix will automatically + check this cache for pre-built binaries, if the user has + sufficient rights to add binary caches. For instance, in a + multi-user Nix setup, the binary caches provided by the channels + of the root user are used automatically, but caches corresponding + to the channels of non-root users are ignored. Binary caches can + be created and maintained using + <command>nix-push</command>.</para></listitem> + + </varlistentry> + + <varlistentry><term><filename>MANIFEST.bz2</filename></term> + + <listitem><para>(Deprecated in favour of binary caches.) A + manifest as created by <command>nix-push</command>. Only used if + <filename>binary-cache-url</filename> is not present or if the + <filename>nix.conf</filename> option + <option>force-manifest</option> is set.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + </refentry> diff --git a/doc/manual/command-ref/nix-install-package.xml b/doc/manual/command-ref/nix-install-package.xml index 7d5cd996e44a..f7802a95d55e 100644 --- a/doc/manual/command-ref/nix-install-package.xml +++ b/doc/manual/command-ref/nix-install-package.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-nix-install-package"> - + <refmeta> <refentrytitle>nix-install-package</refentrytitle> <manvolnum>1</manvolnum> @@ -47,8 +47,7 @@ <para>The command <command>nix-install-package</command> interactively installs a Nix Package file (<filename>*.nixpkg</filename>), which is a small file that contains a store path to be installed along with the -URL of a <link linkend="sec-nix-push"><command>nix-push</command> -manifest</link>. The Nix Package file is either +URL of a binary cache. The Nix Package file is either <replaceable>file</replaceable>, or automatically downloaded from <replaceable>url</replaceable> if the <option>--url</option> switch is used.</para> @@ -76,7 +75,7 @@ to restart itself with <command>xterm</command>, <refsection><title>Options</title> <variablelist> - + <varlistentry><term><option>--non-interactive</option></term> <listitem><para>Do not open a new terminal window and do not ask @@ -139,14 +138,14 @@ The elements are as follows: <variablelist> <varlistentry><term><literal>NIXPKG1</literal></term> - + <listitem><para>The version of the Nix Package file.</para></listitem> </varlistentry> <varlistentry><term><replaceable>manifestURL</replaceable></term> - + <listitem><para>The manifest to be pulled by <command>nix-pull</command>. The manifest must contain <replaceable>outPath</replaceable>.</para></listitem> @@ -154,21 +153,21 @@ The elements are as follows: </varlistentry> <varlistentry><term><replaceable>name</replaceable></term> - + <listitem><para>The symbolic name and version of the package.</para></listitem> </varlistentry> <varlistentry><term><replaceable>system</replaceable></term> - + <listitem><para>The platform identifier of the platform for which this binary package is intended.</para></listitem> </varlistentry> <varlistentry><term><replaceable>drvPath</replaceable></term> - + <listitem><para>The path in the Nix store of the derivation from which <replaceable>outPath</replaceable> was built. Not currently used.</para></listitem> @@ -176,17 +175,21 @@ The elements are as follows: </varlistentry> <varlistentry><term><replaceable>outPath</replaceable></term> - - <listitem><para>The path in the Nix store of the package. After - <command>nix-install-package</command> has obtained the manifest - from <replaceable>manifestURL</replaceable>, it performs a - <literal>nix-env -i</literal> <replaceable>outPath</replaceable> - to install the binary package.</para></listitem> + + <listitem><para>The path in the Nix store of the + package.</para></listitem> + + </varlistentry> + + <varlistentry><term><replaceable>binaryCacheURL</replaceable></term> + + <listitem><para>The URL of a binary cache containing the closure + of <replaceable>outPath</replaceable>.</para></listitem> </varlistentry> </variablelist> - + </para> <para>An example follows: diff --git a/doc/manual/command-ref/nix-pull.xml b/doc/manual/command-ref/nix-pull.xml index 598c651b5091..eb471677b63f 100644 --- a/doc/manual/command-ref/nix-pull.xml +++ b/doc/manual/command-ref/nix-pull.xml @@ -13,7 +13,7 @@ <refnamediv> <refname>nix-pull</refname> - <refpurpose>pull substitutes from a network cache</refpurpose> + <refpurpose>register availability of pre-built binaries (deprecated)</refpurpose> </refnamediv> <refsynopsisdiv> @@ -26,6 +26,9 @@ <refsection><title>Description</title> +<note><para>This command and the use of manifests is deprecated. It is +better to use binary caches.</para></note> + <para>The command <command>nix-pull</command> obtains a list of pre-built store paths from the URL <replaceable>url</replaceable>, and for each of these store paths, registers a substitute derivation that @@ -43,7 +46,7 @@ with the files created by <replaceable>nix-push</replaceable>.</para> <refsection><title>Examples</title> <screen> -$ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST</screen> +$ nix-pull https://nixos.org/releases/nixpkgs/nixpkgs-15.05pre54468.69858d7/MANIFEST</screen> </refsection> diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml index 1f03117636c9..c1b172b70380 100644 --- a/doc/manual/command-ref/nix-shell.xml +++ b/doc/manual/command-ref/nix-shell.xml @@ -29,6 +29,7 @@ <replaceable>attrPath</replaceable> </arg> <arg><option>--command</option> <replaceable>cmd</replaceable></arg> + <arg><option>--run</option> <replaceable>cmd</replaceable></arg> <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg> <arg><option>--pure</option></arg> <group choice='req'> @@ -92,11 +93,24 @@ also <xref linkend="sec-common-options" />.</phrase></para> <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term> <listitem><para>In the environment of the derivation, run the - shell command <replaceable>cmd</replaceable> instead of starting - an interactive shell. However, if you end the shell command with - <literal>return</literal>, you still get an interactive shell. - This can be useful for doing any additional - initialisation.</para></listitem> + shell command <replaceable>cmd</replaceable>. This command is + executed in an interactive shell. (Use <option>--run</option> to + use a non-interactive shell instead.) However, a call to + <literal>exit</literal> is implicitly added to the command, so the + shell will exit after running the command. To prevent this, add + <literal>return</literal> at the end; e.g. <literal>--command + "echo Hello; return"</literal> will print <literal>Hello</literal> + and then drop you into the interactive shell. This can be useful + for doing any additional initialisation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--run</option> <replaceable>cmd</replaceable></term> + + <listitem><para>Like <option>--command</option>, but executes the + command in a non-interactive shell. This means (among other + things) that if you hit Ctrl-C while the command is running, the + shell exits.</para></listitem> </varlistentry> diff --git a/doc/manual/command-ref/utilities.xml b/doc/manual/command-ref/utilities.xml index d5650fd38f43..be2fe6e2d235 100644 --- a/doc/manual/command-ref/utilities.xml +++ b/doc/manual/command-ref/utilities.xml @@ -13,7 +13,9 @@ work with Nix.</para> <xi:include href="nix-collect-garbage.xml" /> <xi:include href="nix-copy-closure.xml" /> <xi:include href="nix-daemon.xml" /> +<!-- <xi:include href="nix-generate-patches.xml" /> +--> <xi:include href="nix-hash.xml" /> <xi:include href="nix-install-package.xml" /> <xi:include href="nix-instantiate.xml" /> @@ -21,4 +23,4 @@ work with Nix.</para> <xi:include href="nix-pull.xml" /> <xi:include href="nix-push.xml" /> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/expressions/advanced-attributes.xml b/doc/manual/expressions/advanced-attributes.xml index f8b84b98cb82..83ad6eefc8b1 100644 --- a/doc/manual/expressions/advanced-attributes.xml +++ b/doc/manual/expressions/advanced-attributes.xml @@ -40,7 +40,7 @@ allowedReferences = []; recursively. For example, <programlisting> -allowedReferences = [ foobar ]; +allowedRequisites = [ foobar ]; </programlisting> enforces that the output of a derivation cannot have any other @@ -90,6 +90,33 @@ derivation { </varlistentry> + <varlistentry><term><varname>impureEnvVars</varname></term> + + <listitem><para>This attribute allows you to specify a list of + environment variables that should be passed from the environment + of the calling user to the builder. Usually, the environment is + cleared completely when the builder is executed, but with this + attribute you can allow specific environment variables to be + passed unmodified. For example, <function>fetchurl</function> in + Nixpkgs has the line + +<programlisting> +impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; +</programlisting> + + to make it use the proxy server configuration specified by the + user in the environment variables <envar>http_proxy</envar> and + friends.</para> + + <para>This attribute is only allowed in <link + linkend="fixed-output-drvs">fixed-output derivations</link>, where + impurities such as these are okay since (the hash of) the output + is known in advance. It is ignored for all other + derivations.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="fixed-output-drvs"> <term><varname>outputHash</varname></term> <term><varname>outputHashAlgo</varname></term> @@ -215,29 +242,29 @@ stdenv.mkDerivation { </varlistentry> - <varlistentry><term><varname>impureEnvVars</varname></term> - - <listitem><para>This attribute allows you to specify a list of - environment variables that should be passed from the environment - of the calling user to the builder. Usually, the environment is - cleared completely when the builder is executed, but with this - attribute you can allow specific environment variables to be - passed unmodified. For example, <function>fetchurl</function> in - Nixpkgs has the line - -<programlisting> -impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; -</programlisting> - - to make it use the proxy server configuration specified by the - user in the environment variables <envar>http_proxy</envar> and - friends.</para> - - <para>This attribute is only allowed in <link - linkend="fixed-output-drvs">fixed-output derivations</link>, where - impurities such as these are okay since (the hash of) the output - is known in advance. It is ignored for all other - derivations.</para></listitem> + <varlistentry><term><varname>passAsFile</varname></term> + + <listitem><para>A list of names of attributes that should be + passed via files rather than environment variables. For example, + if you have + + <programlisting> +passAsFile = ["big"]; +big = "a very long string"; + </programlisting> + + then when the builder runs, the environment variable + <envar>bigPath</envar> will contain the absolute path to a + temporary file containing <literal>a very long + string</literal>. That is, for any attribute + <replaceable>x</replaceable> listed in + <varname>passAsFile</varname>, Nix will pass an environment + variable <envar><replaceable>x</replaceable>Path</envar> holding + the path of the file containing the value of attribute + <replaceable>x</replaceable>. This is useful when you need to pass + large strings to a builder, since most operating systems impose a + limit on the size of the environment (typically, a few hundred + kilobyte).</para></listitem> </varlistentry> diff --git a/doc/manual/expressions/custom-builder.xml b/doc/manual/expressions/custom-builder.xml deleted file mode 100644 index c26deac40f4a..000000000000 --- a/doc/manual/expressions/custom-builder.xml +++ /dev/null @@ -1,26 +0,0 @@ -<section 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="sec-custom-builder"> - -<title>Customizing the Generic Builder</title> - -<para>The operation of the generic builder can be modified in many -places by setting certain variables. These <emphasis>hook -variables</emphasis> are typically set to the name of some shell -function defined by you. For instance, to perform some additional -steps after <command>make install</command> you would set the -<varname>postInstall</varname> variable: - -<programlisting> -postInstall=myPostInstall - -myPostInstall() { - mkdir $out/share/extra - cp extrafiles/* $out/share/extra -}</programlisting> - -</para> - -</section> \ No newline at end of file diff --git a/doc/manual/expressions/debug-build.xml b/doc/manual/expressions/debug-build.xml index 508cb2c1930e..0c1f4e6719b2 100644 --- a/doc/manual/expressions/debug-build.xml +++ b/doc/manual/expressions/debug-build.xml @@ -6,13 +6,14 @@ <title>Debugging Build Failures</title> -<para>At the beginning of each phase, the set of all shell variables -is written to the file <filename>env-vars</filename> at the top-level -build directory. This is useful for debugging: it allows you to -recreate the environment in which a build was performed. For -instance, if a build fails, then assuming you used the -<option>-K</option> flag, you can go to the output directory and -<quote>switch</quote> to the environment of the builder: +<para>At the beginning of each phase of the build (such as unpacking, +building or installing), the set of all shell variables is written to +the file <filename>env-vars</filename> at the top-level build +directory. This is useful for debugging: it allows you to recreate +the environment in which a build was performed. For instance, if a +build fails, then assuming you used the <option>-K</option> flag, you +can go to the output directory and <quote>switch</quote> to the +environment of the builder: <screen> $ nix-build -K ./foo.nix @@ -30,4 +31,4 @@ $ make </para> -</section> \ No newline at end of file +</section> diff --git a/doc/manual/expressions/derivations.xml b/doc/manual/expressions/derivations.xml index b57c33f4e3a9..90e2786faaab 100644 --- a/doc/manual/expressions/derivations.xml +++ b/doc/manual/expressions/derivations.xml @@ -110,12 +110,12 @@ buildInputs = [ pkg pkg.headers ]; </itemizedlist> -<para>The function <function>mkDerivation</function> in the standard -environment is a wrapper around <function>derivation</function> that -adds a default value for <varname>system</varname> and always uses -Bash as the builder, to which the supplied builder is passed as a -command-line argument. See <xref linkend='sec-standard-environment' -/>.</para> +<para>The function <function>mkDerivation</function> in the Nixpkgs +standard environment is a wrapper around +<function>derivation</function> that adds a default value for +<varname>system</varname> and always uses Bash as the builder, to +which the supplied builder is passed as a command-line argument. See +the Nixpkgs manual for details.</para> <para>The builder is executed as follows: @@ -208,4 +208,4 @@ command-line argument. See <xref linkend='sec-standard-environment' <xi:include href="advanced-attributes.xml" /> -</section> \ No newline at end of file +</section> diff --git a/doc/manual/expressions/generic-builder.xml b/doc/manual/expressions/generic-builder.xml index f8567a042d47..db7ff405d8b1 100644 --- a/doc/manual/expressions/generic-builder.xml +++ b/doc/manual/expressions/generic-builder.xml @@ -71,7 +71,7 @@ genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> generic builder is smart enough to figure out whether to unpack the sources using <command>gzip</command>, <command>bzip2</command>, etc. It can be customised in many ways; - see <xref linkend='sec-standard-environment' />.</para> + see the Nixpkgs manual for details.</para> </callout> @@ -95,4 +95,4 @@ In fact, <varname>mkDerivation</varname> provides a default builder that looks exactly like that, so it is actually possible to omit the builder for Hello entirely.</para> -</section> \ No newline at end of file +</section> diff --git a/doc/manual/expressions/language-values.xml b/doc/manual/expressions/language-values.xml index c3514e58f0de..0bf6632d6e3a 100644 --- a/doc/manual/expressions/language-values.xml +++ b/doc/manual/expressions/language-values.xml @@ -155,7 +155,14 @@ stdenv.mkDerivation { expression that contained it. For instance, if a Nix expression in <filename>/foo/bar/bla.nix</filename> refers to <filename>../xyzzy/fnord.nix</filename>, the absolute path is - <filename>/foo/xyzzy/fnord.nix</filename>.</para></listitem> + <filename>/foo/xyzzy/fnord.nix</filename>.</para> + + <para>If the first component of a path is a <literal>~</literal>, + it is interpreted as if the rest of the path were relative to the + user's home directory. e.g. <filename>~/foo</filename> would be + equivalent to <filename>/home/edolstra/foo</filename> for a user + whose home directory is <filename>/home/edolstra</filename>. + </para></listitem> <listitem><para><emphasis>Booleans</emphasis> with values <literal>true</literal> and diff --git a/doc/manual/expressions/simple-building-testing.xml b/doc/manual/expressions/simple-building-testing.xml index cc90409b5e93..e0dd98b7e67e 100644 --- a/doc/manual/expressions/simple-building-testing.xml +++ b/doc/manual/expressions/simple-building-testing.xml @@ -83,4 +83,6 @@ Just pass the option <link linkend='opt-max-jobs'><option>-j in parallel, or set. Typically this should be the number of CPUs.</para> -</section> \ No newline at end of file +<xi:include href="debug-build.xml" /> + +</section> diff --git a/doc/manual/expressions/simple-expression.xml b/doc/manual/expressions/simple-expression.xml index a8eb96f5a8e2..29fd872eea19 100644 --- a/doc/manual/expressions/simple-expression.xml +++ b/doc/manual/expressions/simple-expression.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ch-simple-expression"> -<title>Simple Nix Expression Use-Case</title> +<title>A Simple Nix Expression</title> <para>This section shows how to add and test the <link xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello @@ -44,4 +44,4 @@ need to do three things: <xi:include href="simple-building-testing.xml" /> <xi:include href="generic-builder.xml" /> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/expressions/standard-env.xml b/doc/manual/expressions/standard-env.xml deleted file mode 100644 index 2571f43fccba..000000000000 --- a/doc/manual/expressions/standard-env.xml +++ /dev/null @@ -1,60 +0,0 @@ -<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='sec-standard-environment'> - -<title>The Standard Environment</title> - - -<para>The standard environment is used by passing it as an input -called <envar>stdenv</envar> to the derivation, and then doing - -<programlisting> -source $stdenv/setup</programlisting> - -at the top of the builder.</para> - -<para>Apart from adding the aforementioned commands to the -<envar>PATH</envar>, <filename>setup</filename> also does the -following: - -<itemizedlist> - - <listitem><para>All input packages specified in the - <envar>buildInputs</envar> environment variable have their - <filename>/bin</filename> subdirectory added to <envar>PATH</envar>, - their <filename>/include</filename> subdirectory added to the C/C++ - header file search path, and their <filename>/lib</filename> - subdirectory added to the linker search path. This can be extended. - For instance, when the <command>pkgconfig</command> package is - used, the subdirectory <filename>/lib/pkgconfig</filename> of each - input is added to the <envar>PKG_CONFIG_PATH</envar> environment - variable.</para></listitem> - - <listitem><para>The environment variable - <envar>NIX_CFLAGS_STRIP</envar> is set so that the compiler strips - debug information from object files. This can be disabled by - setting <envar>NIX_STRIP_DEBUG</envar> to - <literal>0</literal>.</para></listitem> - -</itemizedlist> - -</para> - -<para>The <filename>setup</filename> script also exports a function -called <function>genericBuild</function> that knows how to build -typical Autoconf-style packages. It can be customised to perform -builds for any type of package. It is advisable to use -<function>genericBuild</function> since it provides facilities that -are almost always useful such as unpacking of sources, patching of -sources, nested logging, etc.</para> - -<para>The definitive, up-to-date documentation of the generic builder -is the source itself, which resides in -<filename>pkgs/stdenv/generic/setup.sh</filename>.</para> - -<xi:include href="custom-builder.xml" /> -<xi:include href="debug-build.xml" /> - -</chapter> \ No newline at end of file diff --git a/doc/manual/expressions/writing-nix-expressions.xml b/doc/manual/expressions/writing-nix-expressions.xml index 6b797c200992..6646dddf0842 100644 --- a/doc/manual/expressions/writing-nix-expressions.xml +++ b/doc/manual/expressions/writing-nix-expressions.xml @@ -22,6 +22,5 @@ manual</link>.</para></note> <xi:include href="simple-expression.xml" /> <xi:include href="expression-language.xml" /> -<xi:include href="standard-env.xml" /> </part> diff --git a/doc/manual/installation/multi-user.xml b/doc/manual/installation/multi-user.xml index 312f5966452d..49c4f723597e 100644 --- a/doc/manual/installation/multi-user.xml +++ b/doc/manual/installation/multi-user.xml @@ -23,11 +23,11 @@ daemon</emphasis> running under the owner of the Nix store/database that performs the operation.</para> <note><para>Multi-user mode has one important limitation: only -<systemitem class="username">root</systemitem> can run <command -linkend="sec-nix-pull">nix-pull</command> to register the availability -of pre-built binaries. However, those registrations are shared by all -users, so they still get the benefit from <command>nix-pull</command>s -done by <systemitem class="username">root</systemitem>.</para></note> +<systemitem class="username">root</systemitem> and a set of trusted +users specified in <filename>nix.conf</filename> can specify arbitrary +binary caches. So while unprivileged users may install packages from +arbitrary Nix expressions, they may not get pre-built +binaries.</para></note> <simplesect> @@ -52,6 +52,34 @@ This creates 10 build users. There can never be more concurrent builds than the number of build users, so you may want to increase this if you expect to do many builds at the same time.</para> +<para>On Mac OS X, you can create the required group and users by +running the following script: + +<programlisting> +#! /bin/bash -e + +dseditgroup -o create nixbld -q + +gid=$(dscl . -read /Groups/nixbld | awk '($1 == "PrimaryGroupID:") {print $2 }') + +echo "created nixbld group with gid $gid" + +for i in $(seq 1 10); do + user=/Users/nixbld$i + uid="$((30000 + $i))" + dscl . create $user + dscl . create $user RealName "Nix build user $i" + dscl . create $user PrimaryGroupID "$gid" + dscl . create $user UserShell /usr/bin/false + dscl . create $user NFSHomeDirectory /var/empty + dscl . create $user UniqueID "$uid" + dseditgroup -o edit -a nixbld$i -t user nixbld + echo "created nixbld$i user with uid $uid" +done +</programlisting> + +</para> + </simplesect> diff --git a/doc/manual/local.mk b/doc/manual/local.mk index 8511e83599cd..3d7e7fed9631 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -7,7 +7,8 @@ XSLTPROC = $(xsltproc) --nonet $(xmlflags) \ --param admon.style \'\' \ --param callout.graphics.extension \'.gif\' \ --param contrib.inline.enabled 0 \ - --stringparam generate.toc "book toc" + --stringparam generate.toc "book toc" \ + --param keep.relative.image.uris 0 docbookxsl = http://docbook.sourceforge.net/release/xsl-ns/1.78.1 docbookrng = http://docbook.org/xml/5.0/rng/docbook.rng @@ -39,7 +40,7 @@ dist-files += $(d)/manual.xmli $(d)/version.txt $(d)/manual.is-valid man-pages := $(foreach n, \ nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \ nix-collect-garbage.1 nix-push.1 nix-pull.1 \ - nix-prefetch-url.1 nix-channel.1 nix-generate-patches.1 \ + nix-prefetch-url.1 nix-channel.1 \ nix-install-package.1 nix-hash.1 nix-copy-closure.1 \ nix.conf.5 nix-daemon.8, \ $(d)/$(n)) diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 5c46f303a11c..61205d916993 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -4,10 +4,8 @@ version="5.0"> <info> - <title>Nix Package Manager Guide</title> - - <edition>Version <xi:include href="version.txt" parse="text" /></edition> + <subtitle>Version <xi:include href="version.txt" parse="text" /></subtitle> <author> <personname> @@ -41,7 +39,7 @@ <xi:include href="installation/installation.xml" /> <xi:include href="packages/package-management.xml" /> <xi:include href="expressions/writing-nix-expressions.xml" /> - <xi:include href="builds/build-farm.xml" /> + <xi:include href="advanced-topics/advanced-topics.xml" /> <xi:include href="command-ref/command-ref.xml" /> <xi:include href="troubleshooting/troubleshooting.xml" /> <xi:include href="glossary/glossary.xml" /> diff --git a/doc/manual/packages/basic-package-mgmt.xml b/doc/manual/packages/basic-package-mgmt.xml index 69c955c1dd11..e8d1419da093 100644 --- a/doc/manual/packages/basic-package-mgmt.xml +++ b/doc/manual/packages/basic-package-mgmt.xml @@ -28,40 +28,71 @@ Nix expressions called the Nix Package collection that contains packages ranging from basic development stuff such as GCC and Glibc, to end-user applications like Mozilla Firefox. (Nix is however not tied to the Nix Package collection; you could write your own Nix -expressions based on it, or completely new ones.) You can download -the latest version from <link -xlink:href='http://nixos.org/nixpkgs/download.html' />.</para> +expressions based on it, or completely new ones.)</para> + +<para>You can manually download the latest version of Nixpkgs from +<link xlink:href='http://nixos.org/nixpkgs/download.html'/>. However, +it’s much more convenient to use the Nixpkgs +<emphasis>channel</emphasis>, since it makes it easy to stay up to +date with new versions of Nixpkgs. (Channels are described in more +detail in <xref linkend="sec-channels"/>.) Nixpkgs is automatically +added to your list of “subscribed” channels when you install +Nix. If this is not the case for some reason, you can add it as +follows: -<para>Assuming that you have downloaded and unpacked a release of Nix -Packages, you can view the set of available packages in the release: +<screen> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable +$ nix-channel --update +</screen> + +</para> + +<note><para>On NixOS, you’re automatically subscribed to a NixOS +channel corresponding to your NixOS major release +(e.g. <uri>http://nixos.org/channels/nixos-14.12</uri>). A NixOS +channel is identical to the Nixpkgs channel, except that it contains +only Linux binaries and is updated only if a set of regression tests +succeed.</para></note> + +<para>You can view the set of available packages in Nixpkgs: <screen> -$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*' -ant-blackdown-1.4.2 +$ nix-env -qa aterm-2.2 bash-3.0 binutils-2.15 bison-1.875d blackdown-1.4.2 bzip2-1.0.2 -...</screen> - -where <literal>nixpkgs-<replaceable>version</replaceable></literal> is -where you’ve unpacked the release. The flag <option>-q</option> -specifies a query operation; <option>-a</option> means that you want -to show the “available” (i.e., installable) packages, as opposed to -the installed packages; and <option>-f</option> -<filename>nixpkgs-<replaceable>version</replaceable></filename> -specifies the source of the packages. The argument -<literal>'*'</literal> shows all installable packages. (The quotes are -necessary to prevent shell expansion.) You can also select specific -packages by name: +…</screen> + +The flag <option>-q</option> specifies a query operation, and +<option>-a</option> means that you want to show the “available” (i.e., +installable) packages, as opposed to the installed packages. If you +downloaded Nixpkgs yourself, or if you checked it out from GitHub, +then you need to pass the path to your Nixpkgs tree using the +<option>-f</option> flag: + +<screen> +$ nix-env -qaf <replaceable>/path/to/nixpkgs</replaceable> +</screen> + +where <replaceable>/path/to/nixpkgs</replaceable> is where you’ve +unpacked or checked out Nixpkgs.</para> + +<para>You can select specific packages by name: + +<screen> +$ nix-env -qa firefox +firefox-34.0.5 +firefox-with-plugins-34.0.5 +</screen> + +and using regular expressions: <screen> -$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> gcc -gcc-3.4.6 -gcc-4.0.3 -gcc-4.1.1</screen> +$ nix-env -qa 'firefox.*' +</screen> </para> @@ -70,12 +101,12 @@ available packages, i.e., whether they are installed into the user environment and/or present in the system: <screen> -$ nix-env -qasf nixpkgs-<replaceable>version</replaceable> '*' -... +$ nix-env -qas +… -PS bash-3.0 --S binutils-2.15 IPS bison-1.875d -...</screen> +…</screen> The first character (<literal>I</literal>) indicates whether the package is installed in your current user environment. The second @@ -88,40 +119,33 @@ just means that Nix knows that it can fetch a pre-built package from somewhere (typically a network server) instead of building it locally.</para> -<para>So now that we have a set of Nix expressions we can build the -packages contained in them. This is done using <literal>nix-env --i</literal>. For instance, +<para>You can install a package using <literal>nix-env -i</literal>. +For instance, <screen> -$ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen> +$ nix-env -i subversion</screen> will install the package called <literal>subversion</literal> (which is, of course, the <link xlink:href='http://subversion.tigris.org/'>Subversion version management system</link>).</para> -<para>When you do this for the first time, Nix will start building -Subversion and all its dependencies. This will take quite a while — -typically an hour or two on modern machines. Fortunately, there is a -faster way (so do a Ctrl-C on that install operation!): you just need -to tell Nix that pre-built binaries of all those packages are -available somewhere. This is done using the -<command>nix-pull</command> command, which must be supplied with a URL -containing a <emphasis>manifest</emphasis> describing what binaries -are available. This URL should correspond to the Nix Packages release -that you’re using. For instance, if you obtained a release from <link -xlink:href='http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x' -/>, then you should do: - -<screen> -$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST</screen> - -If you then issue the installation command, it should start -downloading binaries from <systemitem -class='fqdomainname'>nixos.org</systemitem>, instead of building -them from source. This might still take a while since all -dependencies must be downloaded, but on a reasonably fast connection -such as a DSL line it’s on the order of a few minutes.</para> +<note><para>When you ask Nix to install a package, it will first try +to get it in pre-compiled form from a <emphasis>binary +cache</emphasis>. By default, Nix will use the binary cache +<uri>https://cache.nixos.org</uri>; it contains binaries for most +packages in Nixpkgs. Only if no binary is available in the binary +cache, Nix will build the package from source. So if <literal>nix-env +-i subversion</literal> results in Nix building stuff from source, +then either the package is not built for your platform by the Nixpkgs +build servers, or your version of Nixpkgs is too old or too new. For +instance, if you have a very recent checkout of Nixpkgs, then the +Nixpkgs build servers may not have had a chance to build everything +and upload the resulting binaries to +<uri>https://cache.nixos.org</uri>. The Nixpkgs channel is only +updated after all binaries have been uploaded to the cache, so if you +stick to the Nixpkgs channel (rather than using a Git checkout of the +Nixpkgs tree), you will get binaries for most packages.</para></note> <para>Naturally, packages can also be uninstalled: @@ -134,7 +158,7 @@ $ nix-env -e subversion</screen> release of Nix Packages, you can do: <screen> -$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen> +$ nix-env -u subversion</screen> This will <emphasis>only</emphasis> upgrade Subversion if there is a “newer” version in the new set of Nix expressions, as @@ -149,17 +173,17 @@ whatever version is already installed.</para> versions: <screen> -$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen> +$ nix-env -u</screen> </para> <para>Sometimes it’s useful to be able to ask what <command>nix-env</command> would do, without actually doing it. For instance, to find out what packages would be upgraded by -<literal>nix-env -u '*'</literal>, you can do +<literal>nix-env -u</literal>, you can do <screen> -$ nix-env ... -u '*' --dry-run +$ nix-env -u --dry-run (dry run; not doing anything) upgrading `libxslt-1.1.0' to `libxslt-1.1.10' upgrading `graphviz-1.10' to `graphviz-1.12' @@ -167,4 +191,4 @@ upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen> </para> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/packages/binary-cache-substituter.xml b/doc/manual/packages/binary-cache-substituter.xml new file mode 100644 index 000000000000..c6ceb9c80610 --- /dev/null +++ b/doc/manual/packages/binary-cache-substituter.xml @@ -0,0 +1,70 @@ +<section 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="ssec-binary-cache-substituter"> + +<title>Serving a Nix store via HTTP</title> + +<para>You can easily share the Nix store of a machine via HTTP. This +allows other machines to fetch store paths from that machine to speed +up installations. It uses the same <emphasis>binary cache</emphasis> +mechanism that Nix usually uses to fetch pre-built binaries from +<uri>https://cache.nixos.org</uri>.</para> + +<para>The daemon that handles binary cache requests via HTTP, +<command>nix-serve</command>, is not part of the Nix distribution, but +you can install it from Nixpkgs: + +<screen> +$ nix-env -i nix-serve +</screen> + +You can then start the server, listening for HTTP connections on +whatever port you like: + +<screen> +$ nix-serve -p 8080 +</screen> + +To check whether it works, try the following on the client: + +<screen> +$ curl http://avalon:8080/nix-cache-info +</screen> + +which should print something like: + +<screen> +StoreDir: /nix/store +WantMassQuery: 1 +Priority: 30 +</screen> + +</para> + +<para>On the client side, you can tell Nix to use your binary cache +using <option>--option extra-binary-caches</option>, e.g.: + +<screen> +$ nix-env -i firefox --option extra-binary-caches http://avalon:8080/ +</screen> + +The option <option>extra-binary-caches</option> tells Nix to use this +binary cache in addition to your default caches, such as +<uri>https://cache.nixos.org</uri>. Thus, for any path in the closure +of Firefox, Nix will first check if the path is available on the +server <literal>avalon</literal> or another binary caches. If not, it +will fall back to building from source.</para> + +<para>You can also tell Nix to always use your binary cache by adding +a line to the <filename linkend="sec-conf-file">nix.conf</filename> +configuration file like this: + +<programlisting> +binary-caches = http://avalon:8080/ https://cache.nixos.org/ +</programlisting> + +</para> + +</section> diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml index 094e11fe3b15..15c119fcb1f9 100644 --- a/doc/manual/packages/channels.xml +++ b/doc/manual/packages/channels.xml @@ -8,10 +8,9 @@ <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 -for those packages, use <command>nix-pull</command> to register -pre-built binaries (if available), and upgrade using -<command>nix-env</command>. Fortunately, there’s a better way: -<emphasis>Nix channels</emphasis>.</para> +for those packages and upgrade using <command>nix-env</command>. +Fortunately, there’s a better way: <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 <link @@ -23,35 +22,36 @@ URL.</para> <command>nix-channel --add</command>, e.g., <screen> -$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable</screen> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable</screen> subscribes you to a channel that always contains that latest version -of the Nix Packages collection. (Instead of -<literal>nixpkgs-unstable</literal> you could also subscribe to -<literal>nixpkgs-stable</literal>, which should have a higher level of -stability, but right now is just outdated.) Subscribing really just -means that the URL is added to the file -<filename>~/.nix-channels</filename>. Right now there is no command -to “unsubscribe”; you should just edit that file manually -and delete the offending URL.</para> +of the Nix Packages collection. (Subscribing really just means that +the URL is added to the file <filename>~/.nix-channels</filename>, +where it is read by subsequent calls to <command>nix-channel +--update</command>.) You can “unsubscribe” using <command>nix-channel +--remove</command>: + +<screen> +$ nix-channel --remove nixpkgs +</screen> +</para> <para>To obtain the latest Nix expressions available in a channel, do <screen> $ nix-channel --update</screen> -This downloads the Nix expressions in every channel (downloaded from -<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>) -and registers any available pre-built binaries in every channel -(by <command>nix-pull</command>ing -<literal><replaceable>url</replaceable>/MANIFEST</literal>). It also -makes the union of each channel’s Nix expressions the default for -<command>nix-env</command> operations. Consequently, you can then say +This downloads and unpacks the Nix expressions in every channel +(downloaded from <literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>). +It also makes the union of each channel’s Nix expressions available by +default to <command>nix-env</command> operations (via the symlink +<filename>~/.nix-defexpr/channels</filename>). Consequently, you can +then say <screen> -$ nix-env -u '*'</screen> +$ nix-env -u</screen> to upgrade all packages in your profile to the latest versions available in the subscribed channels.</para> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/packages/copy-closure.xml b/doc/manual/packages/copy-closure.xml new file mode 100644 index 000000000000..012030e3eb67 --- /dev/null +++ b/doc/manual/packages/copy-closure.xml @@ -0,0 +1,50 @@ +<section 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="ssec-copy-closure"> + +<title>Copying Closures Via SSH</title> + +<para>The command <command +linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix +store path along with all its dependencies to or from another machine +via the SSH protocol. It doesn’t copy store paths that are already +present on the target machine. For example, the following command +copies Firefox with all its dependencies: + +<screen> +$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen> + +See <xref linkend='sec-nix-copy-closure' /> for details.</para> + +<para>With <command linkend='refsec-nix-store-export'>nix-store +--export</command> and <command +linkend='refsec-nix-store-import'>nix-store --import</command> you can +write the closure of a store path (that is, the path and all its +dependencies) to a file, and then unpack that file into another Nix +store. For example, + +<screen> +$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen> + +writes the closure of Firefox to a file. You can then copy this file +to another machine and install the closure: + +<screen> +$ nix-store --import < firefox.closure</screen> + +Any store paths in the closure that are already present in the target +store are ignored. It is also possible to pipe the export into +another command, e.g. to copy and install a closure directly to/on +another machine: + +<screen> +$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \ + ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen> + +However, <command>nix-copy-closure</command> is generally more +efficient because it only copies paths that are not already present in +the target Nix store.</para> + +</section> diff --git a/doc/manual/packages/garbage-collection.xml b/doc/manual/packages/garbage-collection.xml index ae28c485f076..03b8e4c976c1 100644 --- a/doc/manual/packages/garbage-collection.xml +++ b/doc/manual/packages/garbage-collection.xml @@ -37,7 +37,14 @@ generations, e.g., <screen> $ nix-env --delete-generations 10 11 14</screen> -</para> +To delete all generations older than a specified number of days +(except the current generation), use the <literal>d</literal> +suffix. For example, + +<screen> +$ nix-env --delete-generations 14d</screen> + +deletes all generations older than two weeks.</para> <para>After removing appropriate old generations you can run the garbage collector as follows: @@ -67,4 +74,4 @@ is a quick and easy way to clean up your system.</para> <xi:include href="garbage-collector-roots.xml" /> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml index ad5e92aeb64b..4d10319abe1c 100644 --- a/doc/manual/packages/profiles.xml +++ b/doc/manual/packages/profiles.xml @@ -30,7 +30,7 @@ store.</para> <figure xml:id='fig-user-environments'><title>User environments</title> <mediaobject> <imageobject> - <imagedata fileref='figures/user-environments.png' format='PNG' /> + <imagedata fileref='../figures/user-environments.png' format='PNG' /> </imageobject> </mediaobject> </figure> @@ -73,9 +73,9 @@ generated based on the current one. For instance, generation 43 was created from generation 42 when we did <screen> -$ nix-env -i subversion mozilla</screen> +$ nix-env -i subversion firefox</screen> -on a set of Nix expressions that contained Mozilla and a new version +on a set of Nix expressions that contained Firefox and a new version of Subversion.</para> <para>Generations are grouped together into @@ -120,8 +120,7 @@ can also see all available generations: <screen> $ nix-env --list-generations</screen></para> -<para>Actually, there is another level of indirection not shown in the -figure above. You generally wouldn’t have +<para>You generally wouldn’t have <filename>/nix/var/nix/profiles/<replaceable>some-profile</replaceable>/bin</filename> in your <envar>PATH</envar>. Rather, there is a symlink <filename>~/.nix-profile</filename> that points to your current @@ -156,4 +155,4 @@ $ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen> This will <emphasis>not</emphasis> change the <command>~/.nix-profile</command> symlink.</para> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/packages/sharing-packages.xml b/doc/manual/packages/sharing-packages.xml index 8fab15f7ef2d..8465c182ee72 100644 --- a/doc/manual/packages/sharing-packages.xml +++ b/doc/manual/packages/sharing-packages.xml @@ -12,46 +12,8 @@ another machine already has some or all of those packages or their dependencies. In that case there are mechanisms to quickly copy packages between machines.</para> -<para>The command <command -linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix -store path along with all its dependencies to or from another machine -via the SSH protocol. It doesn’t copy store paths that are already -present on the target machine. For example, the following command -copies Firefox with all its dependencies: - -<screen> -$ nix-copy-closure --to alice@itchy.example.org $(type -p firefox)</screen> - -See <xref linkend='sec-nix-copy-closure' /> for details.</para> - -<para>With <command linkend='refsec-nix-store-export'>nix-store ---export</command> and <command -linkend='refsec-nix-store-import'>nix-store --import</command> you can -write the closure of a store path (that is, the path and all its -dependencies) to a file, and then unpack that file into another Nix -store. For example, - -<screen> -$ nix-store --export $(nix-store -qR $(type -p firefox)) > firefox.closure</screen> - -writes the closure of Firefox to a file. You can then copy this file -to another machine and install the closure: - -<screen> -$ nix-store --import < firefox.closure</screen> - -Any store paths in the closure that are already present in the target -store are ignored. It is also possible to pipe the export into -another command, e.g. to copy and install a closure directly to/on -another machine: - -<screen> -$ nix-store --export $(nix-store -qR $(type -p firefox)) | bzip2 | \ - ssh alice@itchy.example.org "bunzip2 | nix-store --import"</screen> - -But note that <command>nix-copy-closure</command> is generally more -efficient in this example because it only copies paths that are not -already present in the target Nix store.</para> - +<xi:include href="binary-cache-substituter.xml" /> +<xi:include href="copy-closure.xml" /> +<xi:include href="ssh-substituter.xml" /> </chapter> diff --git a/doc/manual/packages/ssh-substituter.xml b/doc/manual/packages/ssh-substituter.xml new file mode 100644 index 000000000000..f24f354c4c39 --- /dev/null +++ b/doc/manual/packages/ssh-substituter.xml @@ -0,0 +1,73 @@ +<section 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="ssec-ssh-substituter"> + +<title>Serving a Nix store via SSH</title> + +<para>You can tell Nix to automatically fetch needed binaries from a +remote Nix store via SSH. For example, the following installs Firefox, +automatically fetching any store paths in Firefox’s closure if they +are available on the server <literal>avalon</literal>: + +<screen> +$ nix-env -i firefox --option ssh-substituter-hosts alice@avalon +</screen> + +This works similar to the binary cache substituter that Nix usually +uses, only using SSH instead of HTTP: if a store path +<literal>P</literal> is needed, Nix will first check if it’s available +in the Nix store on <literal>avalon</literal>. If not, it will fall +back to using the binary cache substituter, and then to building from +source.</para> + +<note><para>The SSH substituter currently does not allow you to enter +an SSH passphrase interactively. Therefore, you should use +<command>ssh-add</command> to load the decrypted private key into +<command>ssh-agent</command>.</para></note> + +<para>You can also copy the closure of some store path, without +installing it into your profile, e.g. + +<screen> +$ nix-store -r /nix/store/m85bxg…-firefox-34.0.5 --option ssh-substituter-hosts alice@avalon +</screen> + +This is essentially equivalent to doing + +<screen> +$ nix-copy-closure --from alice@avalon /nix/store/m85bxg…-firefox-34.0.5 +</screen> + +</para> + +<para>You can use SSH’s <emphasis>forced command</emphasis> feature to +set up a restricted user account for SSH substituter access, allowing +read-only access to the local Nix store, but nothing more. For +example, add the following lines to <filename>sshd_config</filename> +to restrict the user <literal>nix-ssh</literal>: + +<programlisting> +Match User nix-ssh + AllowAgentForwarding no + AllowTcpForwarding no + PermitTTY no + PermitTunnel no + X11Forwarding no + ForceCommand nix-store --serve +Match All +</programlisting> + +On NixOS, you can accomplish the same by adding the following to your +<filename>configuration.nix</filename>: + +<programlisting> +nix.sshServe.enable = true; +nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ]; +</programlisting> + +where the latter line lists the public keys of users that are allowed +to connect.</para> + +</section> diff --git a/doc/manual/release-notes/rl-1.8.xml b/doc/manual/release-notes/rl-1.8.xml index b812915a95cd..e551ee06055f 100644 --- a/doc/manual/release-notes/rl-1.8.xml +++ b/doc/manual/release-notes/rl-1.8.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ssec-relnotes-1.8"> -<title>Release 1.8 (December 9, 2014)</title> +<title>Release 1.8 (December 14, 2014)</title> <itemizedlist> @@ -113,4 +113,11 @@ $ nix-store -l $(which xterm) </itemizedlist> +<para>This release has contributions from Adam Szkoda, Aristid +Breitkreuz, Bob van der Linden, Charles Strahan, darealshinji, Eelco +Dolstra, Gergely Risko, Joel Taylor, Ludovic Courtès, Marko Durkovic, +Mikey Ariel, Paul Colomiets, Ricardo M. Correia, Ricky Elrod, Robert +Helgesson, Rob Vermaas, Russell O'Connor, Shea Levy, Shell Turner, +Sönke Hahn, Steve Purcell, Vladimír Čunát and Wout Mertens.</para> + </section> diff --git a/doc/manual/style.css b/doc/manual/style.css index f805aeab076c..53fd9d5709c3 100644 --- a/doc/manual/style.css +++ b/doc/manual/style.css @@ -23,6 +23,11 @@ h1 /* title */ font-size: 200%; } +div.part h1 +{ + font-size: 240%; +} + h2 /* chapters, appendices, subtitle */ { font-size: 180%; @@ -30,7 +35,7 @@ h2 /* chapters, appendices, subtitle */ div.part { - margin-top: 2em; + margin-top: 4em; } /* Extra space between chapters, appendices. */ @@ -61,6 +66,12 @@ div.appendix h3 margin-top: 1.5em; } +div.refentry\.separator +{ + margin-top: 2.5em; + margin-bottom: 2em; +} + div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ { margin-top: 1.4em; diff --git a/doc/manual/troubleshooting/links-nix-store.xml b/doc/manual/troubleshooting/links-nix-store.xml index c81477bd4f27..c768889567d0 100644 --- a/doc/manual/troubleshooting/links-nix-store.xml +++ b/doc/manual/troubleshooting/links-nix-store.xml @@ -20,7 +20,7 @@ in <filename>/nix/store</filename>, as can be seen using <command>ls -l</command>: <screen> -$ ls -l /nix/store +$ ls -ld /nix/store drwxrwxrwt 32000 nix nix 4620288 Sep 8 15:08 store</screen> The <literal>ext2</literal> file system is limited to an inode link @@ -35,9 +35,9 @@ machines).</para> the <option>--max-links</option> option.</para> <para>Real solution: put the Nix store on a file system that supports -more than 32,000 subdirectories per directory, such as ReiserFS. -(This doesn’t solve the <literal>st_nlink</literal> limit, but -ReiserFS lies to the kernel by reporting a link count of 1 if it -exceeds the limit.)</para> +more than 32,000 subdirectories per directory, such as ext4. (This +doesn’t solve the <literal>st_nlink</literal> limit, but ext4 lies to +the kernel by reporting a link count of 1 if it exceeds the +limit.)</para> </section> |