182/376: Merge branch 'master' of github.com:thatdocslady/nix

[Ludovic Courtès]

civodul pushed a commit to tag 1.8
in repository guix.

commit f0ef6b74b93344798e44c6dc527f88a78b75a32f
Merge: 67e5dd3 8901acc
Author: Eelco Dolstra <address@hidden>
Date:   Tue Sep 16 14:13:36 2014 +0200

    Merge branch 'master' of github.com:thatdocslady/nix
    
    Conflicts:
        doc/manual/release-notes.xml
        doc/manual/writing-nix-expressions.xml

 doc/manual/{ => bugs}/bugs.xml                     |    0
 doc/manual/builds/build-farm.xml                   |   22 +
 .../{build-farm.xml => builds/enabling-builds.xml} |   21 +-
 doc/manual/command-ref/command-ref.xml             |   20 +
 doc/manual/{ => command-ref}/conf-file.xml         |    0
 doc/manual/{ => command-ref}/env-common.xml        |   12 +-
 doc/manual/command-ref/files.xml                   |   14 +
 doc/manual/command-ref/main-commands.xml           |   17 +
 doc/manual/{ => command-ref}/nix-build.xml         |    7 +-
 doc/manual/{ => command-ref}/nix-channel.xml       |    7 +-
 .../{ => command-ref}/nix-collect-garbage.xml      |    7 +-
 doc/manual/{ => command-ref}/nix-copy-closure.xml  |    0
 doc/manual/{ => command-ref}/nix-daemon.xml        |    7 +-
 doc/manual/{ => command-ref}/nix-env.xml           |    7 +-
 doc/manual/{ => command-ref}/nix-hash.xml          |    7 +-
 .../{ => command-ref}/nix-install-package.xml      |    7 +-
 doc/manual/{ => command-ref}/nix-instantiate.xml   |    7 +-
 doc/manual/{ => command-ref}/nix-prefetch-url.xml  |    7 +-
 doc/manual/{ => command-ref}/nix-pull.xml          |    7 +-
 doc/manual/{ => command-ref}/nix-push.xml          |    7 +-
 doc/manual/{ => command-ref}/nix-shell.xml         |    7 +-
 doc/manual/{ => command-ref}/nix-store.xml         |    7 +-
 doc/manual/{ => command-ref}/opt-common-syn.xml    |    0
 doc/manual/{ => command-ref}/opt-common.xml        |    6 +-
 doc/manual/{ => command-ref}/opt-inst-syn.xml      |    0
 doc/manual/command-ref/utilities.xml               |   23 +
 doc/manual/expressions/advanced-attributes.xml     |  262 ++
 doc/manual/expressions/arguments-variables.xml     |  121 +
 doc/manual/expressions/build-script.xml            |  119 +
 doc/manual/expressions/builder-syntax.xml          |  119 +
 doc/manual/{ => expressions}/builtins.xml          |    9 +-
 doc/manual/expressions/custom-builder.xml          |   26 +
 doc/manual/expressions/debug-build.xml             |   33 +
 doc/manual/expressions/derivations.xml             |  211 ++
 doc/manual/expressions/expression-language.xml     |   30 +
 doc/manual/expressions/expression-syntax.xml       |  148 ++
 doc/manual/expressions/generic-builder.xml         |   98 +
 doc/manual/expressions/language-constructs.xml     |  344 +++
 doc/manual/expressions/language-operators.xml      |  113 +
 doc/manual/expressions/language-values.xml         |  268 +++
 doc/manual/expressions/simple-building-testing.xml |   86 +
 doc/manual/expressions/simple-expression.xml       |   47 +
 doc/manual/expressions/standard-env.xml            |   60 +
 doc/manual/expressions/writing-nix-expressions.xml |   27 +
 doc/manual/{ => glossary}/glossary.xml             |    0
 doc/manual/installation.xml                        |  447 ----
 doc/manual/installation/building-source.xml        |   57 +
 doc/manual/installation/env-variables.xml          |   24 +
 doc/manual/installation/installation.xml           |   34 +
 doc/manual/installation/installing-binary.xml      |   81 +
 doc/manual/installation/installing-source.xml      |   17 +
 doc/manual/installation/multi-user.xml             |  106 +
 doc/manual/installation/nix-security.xml           |   27 +
 doc/manual/installation/obtaining-source.xml       |   30 +
 doc/manual/installation/prerequisites-source.xml   |   73 +
 doc/manual/installation/single-user.xml            |   21 +
 doc/manual/installation/supported-platforms.xml    |   38 +
 .../about-nix.xml}                                 |   32 +-
 doc/manual/introduction/introduction.xml           |   16 +
 doc/manual/introduction/nix-license.xml            |   20 +
 doc/manual/manual.xml                              |   75 +-
 doc/manual/package-management.xml                  |  591 -----
 doc/manual/packages/basic-package-mgmt.xml         |  170 ++
 doc/manual/packages/channels.xml                   |   57 +
 doc/manual/packages/garbage-collection.xml         |   70 +
 doc/manual/packages/garbage-collector-roots.xml    |   29 +
 doc/manual/packages/one-click.xml                  |   37 +
 doc/manual/packages/package-management.xml         |   24 +
 doc/manual/packages/profiles.xml                   |  159 ++
 doc/manual/packages/sharing-packages.xml           |   82 +
 .../getting-started.xml}                           |   56 +-
 doc/manual/quick-start/quick-start.xml             |   17 +
 doc/manual/release-notes.xml                       | 2533 --------------------
 doc/manual/release-notes/release-notes.xml         |   43 +
 doc/manual/release-notes/rl-010.xml                |  323 +++
 doc/manual/release-notes/rl-0101.xml               |   13 +
 doc/manual/release-notes/rl-011.xml                |  261 ++
 doc/manual/release-notes/rl-012.xml                |  175 ++
 doc/manual/release-notes/rl-013.xml                |  106 +
 doc/manual/release-notes/rl-014.xml                |   44 +
 doc/manual/release-notes/rl-015.xml                |   14 +
 doc/manual/release-notes/rl-016.xml                |   55 +
 doc/manual/release-notes/rl-05.xml                 |   11 +
 doc/manual/release-notes/rl-06.xml                 |  122 +
 doc/manual/release-notes/rl-07.xml                 |   35 +
 doc/manual/release-notes/rl-08.xml                 |  246 ++
 doc/manual/release-notes/rl-081.xml                |   21 +
 doc/manual/release-notes/rl-09.xml                 |   98 +
 doc/manual/release-notes/rl-091.xml                |   13 +
 doc/manual/release-notes/rl-092.xml                |   28 +
 doc/manual/release-notes/rl-10.xml                 |  119 +
 doc/manual/release-notes/rl-11.xml                 |  100 +
 doc/manual/release-notes/rl-12.xml                 |  157 ++
 doc/manual/release-notes/rl-13.xml                 |   19 +
 doc/manual/release-notes/rl-14.xml                 |   39 +
 doc/manual/release-notes/rl-15.xml                 |   12 +
 doc/manual/release-notes/rl-151.xml                |   12 +
 doc/manual/release-notes/rl-152.xml                |   12 +
 doc/manual/release-notes/rl-16.xml                 |  127 +
 doc/manual/release-notes/rl-161.xml                |   69 +
 doc/manual/release-notes/rl-17.xml                 |  263 ++
 doc/manual/release-notes/rl-18.xml                 |   21 +
 doc/manual/troubleshooting.xml                     |   92 -
 doc/manual/troubleshooting/collisions-nixenv.xml   |   43 +
 doc/manual/troubleshooting/links-nix-store.xml     |   43 +
 doc/manual/troubleshooting/troubleshooting.xml     |   18 +
 doc/manual/writing-nix-expressions.xml             | 1918 ---------------
 107 files changed, 6191 insertions(+), 5751 deletions(-)

diff --cc doc/manual/expressions/advanced-attributes.xml
index 0000000,40a5a80..f8b84b9
mode 000000,100644..100644
--- a/doc/manual/expressions/advanced-attributes.xml
+++ b/doc/manual/expressions/advanced-attributes.xml
@@@ -1,0 -1,243 +1,262 @@@
+ <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-advanced-attributes">
+ 
+ <title>Advanced Attributes</title>
+ 
+ <para>Derivations can declare some infrequently used optional
+ attributes.</para>
+ 
+ <variablelist>
+ 
+   <varlistentry><term><varname>allowedReferences</varname></term>
+ 
+     <listitem><para>The optional attribute
+     <varname>allowedReferences</varname> specifies a list of legal
+     references (dependencies) of the output of the builder.  For
+     example,
+ 
+ <programlisting>
+ allowedReferences = [];
+ </programlisting>
+ 
+     enforces that the output of a derivation cannot have any runtime
+     dependencies on its inputs.  To allow an output to have a runtime
+     dependency on itself, use <literal>"out"</literal> as a list item.
+     This is used in NixOS to check that generated files such as
+     initial ramdisks for booting Linux don’t have accidental
+     dependencies on other paths in the Nix store.</para></listitem>
+ 
+   </varlistentry>
+ 
+ 
++  <varlistentry><term><varname>allowedRequisites</varname></term>
++
++    <listitem><para>This attribute is similar to
++    <varname>allowedReferences</varname>, but it specifies the legal
++    requisites of the whole closure, so all the dependencies
++    recursively.  For example,
++
++<programlisting>
++allowedReferences = [ foobar ];
++</programlisting>
++
++    enforces that the output of a derivation cannot have any other
++    runtime dependency than <varname>foobar</varname>, and in addition
++    it enforces that <varname>foobar</varname> itself doesn't
++    introduce any other dependency itself.</para></listitem>
++
++  </varlistentry>
++
++
+   <varlistentry><term><varname>exportReferencesGraph</varname></term>
+ 
+     <listitem><para>This attribute allows builders access to the
+     references graph of their inputs.  The attribute is a list of
+     inputs in the Nix store whose references graph the builder needs
+     to know.  The value of this attribute should be a list of pairs
+     <literal>[ <replaceable>name1</replaceable>
+     <replaceable>path1</replaceable> <replaceable>name2</replaceable>
+     <replaceable>path2</replaceable> <replaceable>...</replaceable>
+     ]</literal>.  The references graph of each
+     <replaceable>pathN</replaceable> will be stored in a text file
+     <replaceable>nameN</replaceable> in the temporary build directory.
+     The text files have the format used by <command>nix-store
+     --register-validity</command> (with the deriver fields left
+     empty).  For example, when the following derivation is built:
+ 
+ <programlisting>
+ derivation {
+   ...
+   exportReferencesGraph = [ "libfoo-graph" libfoo ];
+ };
+ </programlisting>
+ 
+     the references graph of <literal>libfoo</literal> is placed in the
+     file <filename>libfoo-graph</filename> in the temporary build
+     directory.</para>
+ 
+     <para><varname>exportReferencesGraph</varname> is useful for
+     builders that want to do something with the closure of a store
+     path.  Examples include the builders in NixOS that generate the
+     initial ramdisk for booting Linux (a <command>cpio</command>
+     archive containing the closure of the boot script) and the
+     ISO-9660 image for the installation CD (which is populated with a
+     Nix store containing the closure of a bootable NixOS
+     configuration).</para></listitem>
+ 
+   </varlistentry>
+ 
+ 
+   <varlistentry xml:id="fixed-output-drvs">
+     <term><varname>outputHash</varname></term>
+     <term><varname>outputHashAlgo</varname></term>
+     <term><varname>outputHashMode</varname></term>
+ 
+     <listitem><para>These attributes declare that the derivation is a
+     so-called <emphasis>fixed-output derivation</emphasis>, which
+     means that a cryptographic hash of the output is already known in
+     advance.  When the build of a fixed-output derivation finishes,
+     Nix computes the cryptographic hash of the output and compares it
+     to the hash declared with these attributes.  If there is a
+     mismatch, the build fails.</para>
+ 
+     <para>The rationale for fixed-output derivations is derivations
+     such as those produced by the <function>fetchurl</function>
+     function.  This function downloads a file from a given URL.  To
+     ensure that the downloaded file has not been modified, the caller
+     must also specify a cryptographic hash of the file.  For example,
+ 
+ <programlisting>
+ fetchurl {
+   url = http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz;
+   md5 = "70c9ccf9fac07f762c24f2df2290784d";
+ }
+ </programlisting>
+ 
+     It sometimes happens that the URL of the file changes, e.g.,
+     because servers are reorganised or no longer available.  We then
+     must update the call to <function>fetchurl</function>, e.g.,
+ 
+ <programlisting>
+ fetchurl {
+   url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
+   md5 = "70c9ccf9fac07f762c24f2df2290784d";
+ }
+ </programlisting>
+ 
+     If a <function>fetchurl</function> derivation was treated like a
+     normal derivation, the output paths of the derivation and
+     <emphasis>all derivations depending on it</emphasis> would change.
+     For instance, if we were to change the URL of the Glibc source
+     distribution in Nixpkgs (a package on which almost all other
+     packages depend) massive rebuilds would be needed.  This is
+     unfortunate for a change which we know cannot have a real effect
+     as it propagates upwards through the dependency graph.</para>
+ 
+     <para>For fixed-output derivations, on the other hand, the name of
+     the output path only depends on the <varname>outputHash*</varname>
+     and <varname>name</varname> attributes, while all other attributes
+     are ignored for the purpose of computing the output path.  (The
+     <varname>name</varname> attribute is included because it is part
+     of the path.)</para>
+ 
+     <para>As an example, here is the (simplified) Nix expression for
+     <varname>fetchurl</varname>:
+ 
+ <programlisting>
+ { stdenv, curl }: # The <command>curl</command> program is used for 
downloading.
+ 
+ { url, md5 }:
+ 
+ stdenv.mkDerivation {
+   name = baseNameOf (toString url);
+   builder = ./builder.sh;
+   buildInputs = [ curl ];
+ 
+   # This is a fixed-output derivation; the output must be a regular
+   # file with MD5 hash <varname>md5</varname>.
+   outputHashMode = "flat";
+   outputHashAlgo = "md5";
+   outputHash = md5;
+ 
+   inherit url;
+ }
+ </programlisting>
+ 
+     </para>
+ 
+     <para>The <varname>outputHashAlgo</varname> attribute specifies
+     the hash algorithm used to compute the hash.  It can currently be
+     <literal>"md5"</literal>, <literal>"sha1"</literal> or
+     <literal>"sha256"</literal>.</para>
+ 
+     <para>The <varname>outputHashMode</varname> attribute determines
+     how the hash is computed.  It must be one of the following two
+     values:
+ 
+     <variablelist>
+ 
+       <varlistentry><term><literal>"flat"</literal></term>
+ 
+         <listitem><para>The output must be a non-executable regular
+         file.  If it isn’t, the build fails.  The hash is simply
+         computed over the contents of that file (so it’s equal to what
+         Unix commands like <command>md5sum</command> or
+         <command>sha1sum</command> produce).</para>
+ 
+         <para>This is the default.</para></listitem>
+ 
+       </varlistentry>
+ 
+       <varlistentry><term><literal>"recursive"</literal></term>
+ 
+         <listitem><para>The hash is computed over the NAR archive dump
+         of the output (i.e., the result of <link
+         linkend="refsec-nix-store-dump"><command>nix-store
+         --dump</command></link>).  In this case, the output can be
+         anything, including a directory tree.</para></listitem>
+ 
+       </varlistentry>
+ 
+     </variablelist>
+ 
+     </para>
+ 
+     <para>The <varname>outputHash</varname> attribute, finally, must
+     be a string containing the hash in either hexadecimal or base-32
+     notation.  (See the <link
+     linkend="sec-nix-hash"><command>nix-hash</command> command</link>
+     for information about converting to and from base-32
+     notation.)</para></listitem>
+ 
+   </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><term><varname>preferLocalBuild</varname></term>
+ 
+     <listitem><para>If this attribute is set to
+     <literal>true</literal>, it has two effects.  First, the
+     derivation will always be built, not substituted, even if a
+     substitute is available.  Second, if <link
+     linkend="chap-distributed-builds">distributed building is
+     enabled</link>, then, if possible, the derivaton will be built
+     locally instead of forwarded to a remote machine.  This is
+     appropriate for trivial builders where the cost of doing a
+     download or remote build would exceed the cost of building
+     locally.</para></listitem>
+ 
+   </varlistentry>
+ 
+ </variablelist>
+ 
 -</section>
++</section>
diff --cc doc/manual/release-notes/rl-18.xml
index 0000000,0fe3c2d..aace952
mode 000000,100644..100644
--- a/doc/manual/release-notes/rl-18.xml
+++ b/doc/manual/release-notes/rl-18.xml
@@@ -1,0 -1,11 +1,21 @@@
+ <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="ssec-relnotes-1.8">
+ 
+ <title>Release 1.8 (TBA)</title>
+ 
 -<para>TODO</para>
++<itemizedlist>
+ 
 -</chapter>
++  <listitem><para>Derivations can specify the new special attribute
++  <varname>allowedRequisites</varname>, which has a similar meaning to
++  <varname>allowedReferences</varname>. But instead of only enforcing
++  to explicitly specify the immediate references, it requires the
++  derivation to specify all the dependencies recursively (hence the
++  name, requisites) that are used by the resulting
++  output.</para></listitem>
++
++</itemizedlist>
++
++</chapter>