configure.ac

@@ -135,6 +135,7 @@ AC_PATH_PROG(bison, bison, false)
 NEED_PROG(perl, perl)
 NEED_PROG(tar, tar)
 AC_PATH_PROG(dot, dot)
+AC_PATH_PROG(dblatex, dblatex)
 
 AC_PATH_PROG(openssl_prog, openssl, openssl) # if not found, call openssl in $PATH
 AC_SUBST(openssl_prog)

doc/manual/Makefile.am

@@ -47,6 +47,14 @@ manual.html: $(MANUAL_SRCS) manual.is-valid images
 	$(XSLTPROC) --nonet --xinclude --output manual.html \
 	  $(docbookxsl)/html/docbook.xsl manual.xml
 
+manual.pdf: $(MANUAL_SRCS) manual.is-valid images
+	if test "$(dblatex)" != ""; then \
+		$(dblatex) manual.xml; \
+	else \
+		echo "Please install dblatex and rerun configure."; \
+		exit 1; \
+	fi
+
 
 NEWS_OPTS = \
  --stringparam generate.toc "article nop" \

doc/manual/env-common.xml

@@ -263,6 +263,17 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
 </varlistentry>
 
 
+<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term>
+
+  <listitem><para>This variable should be set to
+  <literal>daemon</literal> if you want to use the Nix daemon to
+  executed Nix operations, which is necessary in <link
+  linkend="ssec-multi-user">multi-user Nix installations</link>.
+  Otherwise, it should be left unset.</para></listitem>
+
+</varlistentry>
+
+    
 </variablelist>
 
 

doc/manual/installation.xml

@@ -100,14 +100,16 @@ ubiquitous 2.5.4a won't.  Note that these are only required if you
 modify the parser or when you are building from the Subversion
 repository.</para>
 
-<para>Nix uses Sleepycat's Berkeley DB and CWI's ATerm library.  These
+<para>Nix uses Sleepycat's Berkeley DB, CWI's ATerm library and the
-are included in the Nix source distribution.  If you build from the
+bzip2 compressor (including the bzip2 library).  These are included in
-Subversion repository, you must download them yourself and place them
+the Nix source distribution.  If you build from the Subversion
-in the <filename>externals/</filename> directory.  See
+repository, you must download them yourself and place them in the
+<filename>externals/</filename> directory.  See
 <filename>externals/Makefile.am</filename> for the precise URLs of
 these packages.  Alternatively, if you already have them installed,
-you can use <command>configure</command>'s <option>--with-bdb</option>
+you can use <command>configure</command>'s
-and <option>--with-aterm</option> options to point to their respective
+<option>--with-bdb</option>, <option>--with-aterm</option> and
+<option>--with-bzip2</option> options to point to their respective
 locations.  Note that Berkeley DB <emphasis>must</emphasis> be version
 4.5; other versions may not have compatible database formats.</para>
 
@@ -118,19 +120,21 @@ locations.  Note that Berkeley DB <emphasis>must</emphasis> be version
 
 <para>After unpacking or checking out the Nix sources, issue the
 following commands:
-    </para>
 
 <screen>
 $ ./configure <replaceable>options...</replaceable>
 $ make
 $ make install</screen>
 
-<para>When building from the Subversion repository, these should be
-preceded by the command:
 </para>
 
+<para>When building from the Subversion repository, these should be
+preceded by the command:
+
 <screen>
-$ ./boostrap</screen>
+$ ./bootstrap</screen>
+
+</para>
 
 <para>The installation path can be specified by passing the
 <option>--prefix=<replaceable>prefix</replaceable></option> to
@@ -165,20 +169,24 @@ Hat Linux.  They have been known to work work on SuSE Linux 8.1 and
 distribution based on <literal>glibc</literal> 2.3 or later.</para>
 
 <para>Once downloaded, the RPMs can be installed or upgraded using
-<command>rpm -U</command>.  For example,</para>
+<command>rpm -U</command>.  For example,
 
 <screen>
 $ rpm -U nix-0.5pre664-1.i386.rpm</screen>
 
+</para>
+
 <para>The RPMs install into the directory <filename>/nix</filename>.
 Nix can be uninstalled using <command>rpm -e nix</command>.  After
 this it will be necessary to manually remove the Nix store and other
-auxiliary data:</para>
+auxiliary data:
 
 <screen>
 $ rm -rf /nix/store
 $ rm -rf /nix/var</screen>
 
+</para>
+
 </section>
 
 
@@ -231,33 +239,215 @@ class="username">root</systemitem> all the time.</para>
 </section>
 
 
-<section><title>Multi-user mode</title>
+<section xml:id="ssec-multi-user"><title>Multi-user mode</title>
 
-<para></para>
+<para>To allow a Nix store to be shared safely among multiple users,
+it is important that users are not able to run builders that modify
+the Nix store or database in arbitrary ways, or that interfere with
+builds started by other users.  If they could do so, they could
+install a Trojan horse in some package and compromise the accounts of
+other users.</para>
 
-
+<para>To prevent this, the Nix store and database are owned by some
-<!--
+privileged user (usually <literal>root</literal>) and builders are
-
+executed under special user accounts (usually named
-warning: the nix-builders group should contain *only* the Nix
+<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.).  When a
-builders, and nothing else.  If the Nix account is compromised, you
+unprivileged user runs a Nix command, actions that operate on the Nix
-can execute programs under the accounts in the nix-builders group, so
+store (such as builds) are forwarded to a <emphasis>Nix
-it obviously shouldn’t contain any “real” user accounts.  So don’t use
+daemon</emphasis> running under the owner of the Nix store/database
-an existing group like <literal>users</literal> — just create a new
+that performs the operation.</para>
-one.
-
--->
 
 <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
+of pre-built binaries.  However, those registrations are shared by all
-<emphasis>are</emphasis> used by all users to speed up
+users, so they still get the benefit from <command>nix-pull</command>s
-builds.</para></note>
+done by <systemitem class="username">root</systemitem>.</para></note>
+
+
+<section><title>Setting up the build users</title>
+
+<para>The <emphasis>build users</emphasis> are the special UIDs under
+which builds are performed.  They should all be members of the
+<emphasis>build users group</emphasis> (usually called
+<literal>nixbld</literal>).  This group should have no other members.
+The build users should not be members of any other group.</para>
+
+<para>Here is a typical <filename>/etc/group</filename> definition of
+the build users group with 10 build users:
+
+<programlisting>
+nixbld:!:30000:nixbld1,nixbld2,nixbld3,nixbld4,nixbld5,nixbld6,nixbld7,nixbld8,nixbld9,nixbld10
+</programlisting>
+
+In this example the <literal>nixbld</literal> group has UID 30000, but
+of course it can be anything that doesn’t collide with an existing
+group.</para>
+
+<para>Here is the corresponding part of
+<filename>/etc/passwd</filename>:
+
+<programlisting>
+nixbld1:x:30001:65534:Nix build user 1:/var/empty:/noshell
+nixbld2:x:30002:65534:Nix build user 2:/var/empty:/noshell
+nixbld3:x:30003:65534:Nix build user 3:/var/empty:/noshell
+...
+nixbld10:x:30010:65534:Nix build user 10:/var/empty:/noshell
+</programlisting>
+
+The home directory of the build users should not exist or should be an
+empty directory to which they do not have write access.</para>
+
+<para>The build users should have write access to the Nix store, but
+they should not have the right to delete files.  Thus the Nix store’s
+group should be the build users group, and it should have the sticky
+bit turned on (like <filename>/tmp</filename>):
+
+<screen>
+$ chgrp nixbld /nix/store
+$ chmod 1777 /nix/store
+</screen>
+
+</para>
+
+<para>Finally, you should tell Nix to use the build users by
+specifying the build users group in the <link
+linkend="conf-build-users-group"><literal>build-users-group</literal>
+option</link> in the <link linkend="sec-conf-file">Nix configuration
+file</link> (<literal>/nix/etc/nix/nix.conf</literal>):
+
+<programlisting>
+build-users-group = nixbld
+</programlisting>
+
+</para>
 
 </section>
 
 
-</section> <!-- end of permissions section -->
+<section><title>Nix store/database owned by root</title>
+
+<para>The simplest setup is to let <literal>root</literal> own the Nix
+store and database.  I.e.,
+
+<screen>
+$ chown -R root /nix/store /nix/var/nix</screen>
+
+</para>
+
+<para>The Nix daemon should be started as follows (as
+<literal>root</literal>):
+
+<screen>
+$ nix-worker --daemon</screen>
+
+You’ll want to put that line somewhere in your system’s boot
+scripts.</para>
+
+<para>To let unprivileged users use the daemon, they should set the
+<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment
+variable</link> to <literal>daemon</literal>.  So you should put a
+line like
+
+<programlisting>
+export NIX_REMOTE=daemon</programlisting>
+
+into the users’ login scripts.</para>
+
+</section>
+
+
+<section><title>Nix store/database not owned by root</title>
+
+<para>It is also possible to let the Nix store and database be owned
+by a non-root user, which should be more secure<footnote><para>Note
+however that even when the Nix daemon runs as root, not
+<emphasis>that</emphasis> much code is executed as root: Nix
+expression evaluation is performed by the calling (unprivileged) user,
+and builds are performed under the special build user accounts.  So
+only the code that accesses the database and starts builds is executed
+as <literal>root</literal>.</para></footnote>.  Typically, this user
+is a special account called <literal>nix</literal>, but it can be
+named anything.  It should own the Nix store and database:
+
+<screen>
+$ chown -R root /nix/store /nix/var/nix</screen>
+
+and of course <command>nix-worker --daemon</command> should be started
+under that user, e.g.,
+
+<screen>
+$ su - nix -c "exec /nix/bin/nix-worker --daemon"</screen>
+
+</para>
+
+<para>There is a catch, though: non-<literal>root</literal> users
+cannot start builds under the build user accounts, since the
+<function>setuid</function> system call is obviously privileged.  To
+allow a non-<literal>root</literal> Nix daemon to use the build user
+feature, it calls a setuid-root helper program,
+<command>nix-setuid-helper</command>.  This program is installed in
+<filename><replaceable>prefix</replaceable>/libexec/nix-setuid-helper</filename>.
+To set the permissions properly (Nix’s <command>make install</command>
+doesn’t do this, since we don’t want to ship setuid-root programs
+out-of-the-box):
+
+<screen>
+$ chown root.root /nix/libexec/nix-setuid-helper
+$ chmod 4755 /nix/libexec/nix-setuid-helper
+</screen>
+
+(This example assumes that the Nix binaries are installed in
+<filename>/nix</filename>.)</para>
+
+<para>Of course, the <command>nix-setuid-helper</command> command
+should not be usable by just anybody, since then anybody could run
+commands under the Nix build user accounts.  For that reason there is
+a configuration file <filename>/etc/nix-setuid.conf</filename> that
+restricts the use of the helper.  This file should be a text file
+containing precisely two lines, the first being the Nix daemon user
+and the second being the build users group, e.g.,
+
+<programlisting>
+nix
+nixbld
+</programlisting>
+
+The setuid-helper barfs if it is called by a user other than the one
+specified on the first line, or if it is asked to execute a build
+under a user who is not a member of the group specified on the second
+line.  The file <filename>/etc/nix-setuid.conf</filename> must be
+owned by root, and must not be group- or world-writable.  The
+setuid-helper barfs if this is not the case.</para>
+
+</section>
+
+
+<section><title>Restricting access</title>
+
+<para>To limit which users can perform Nix operations, you can use the
+permissions on the directory
+<filename>/nix/var/nix/daemon-socket</filename>.  For instance, if you
+want to restrict the use of Nix to the members of a group called
+<literal>nix-users</literal>, do
+
+<screen>
+$ chgrp nix-users /nix/var/nix/daemon-socket
+$ chmod ug=rwx,o= /nix/var/nix/daemon-socket
+</screen>
+
+This way, users who are not in the <literal>nix-users</literal> group
+cannot connect to the Unix domain socket
+<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot
+perform Nix operations.</para>
+
+</section>
+
+
+</section> <!-- end of multi-user -->
+
+
+</section> <!-- end of security -->
 
 
 <section><title>Using Nix</title>

doc/manual/nix-env.xml

@@ -19,13 +19,6 @@
     <command>nix-env</command>
     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
     <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
-    <arg>
-      <group choice='req'>
-        <arg choice='plain'><option>--attr</option></arg>
-        <arg choice='plain'><option>-A</option></arg>
-      </group>
-      <replaceable>attrPath</replaceable>
-    </arg>
     <arg>
       <group choice='req'>
         <arg choice='plain'><option>--file</option></arg>
@@ -45,9 +38,6 @@
       <replaceable>system</replaceable>
     </arg>
     <arg><option>--dry-run</option></arg>
-    <arg><option>--from-expression</option></arg>
-    <arg><option>-E</option></arg>
-    <arg><option>--from-profile</option> <replaceable>path</replaceable></arg>
     <arg choice='plain'><replaceable>operation</replaceable></arg>
     <arg rep='repeat'><replaceable>options</replaceable></arg>
     <arg rep='repeat'><replaceable>arguments</replaceable></arg>
@@ -190,6 +180,7 @@ linkend="sec-common-options" />.</para>
     <arg choice='plain'><option>--install</option></arg>
     <arg choice='plain'><option>-i</option></arg>
   </group>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
   <group choice='opt'>
     <arg choice='plain'><option>--preserve-installed</option></arg>
     <arg choice='plain'><option>-P</option></arg>
@@ -397,6 +388,7 @@ the following paths will be substituted:
     <arg choice='plain'><option>--upgrade</option></arg>
     <arg choice='plain'><option>-u</option></arg>
   </group>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
   <group choice='opt'>
     <arg choice='plain'><option>--lt</option></arg>
     <arg choice='plain'><option>--leq</option></arg>
@@ -592,25 +584,21 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
     <arg choice='plain'><option>--query</option></arg>
     <arg choice='plain'><option>-q</option></arg>
   </group>
-  <arg><option>--xml</option></arg>
   <group choice='opt'>
     <arg choice='plain'><option>--installed</option></arg>
     <arg choice='plain'><option>--available</option></arg>
     <arg choice='plain'><option>-a</option></arg>
   </group>
+  
   <sbr />
+  
   <arg>
     <group choice='req'>
       <arg choice='plain'><option>--status</option></arg>
       <arg choice='plain'><option>-s</option></arg>
     </group>
   </arg>
-  <arg>
+  <arg><option>--attr-path</option></arg>
-    <group choice='req'>
-      <arg choice='plain'><option>--attr</option></arg>
-      <arg choice='plain'><option>-A</option></arg>
-    </group>
-  </arg>
   <arg><option>--no-name</option></arg>
   <arg>
     <group choice='req'>
@@ -622,6 +610,27 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
   <arg><option>--drv-path</option></arg>
   <arg><option>--out-path</option></arg>
   <arg><option>--description</option></arg>
+  <arg><option>--meta</option></arg>
+
+  <sbr />
+
+  <arg><option>--xml</option></arg>
+  <arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--prebuilt-only</option></arg>
+      <arg choice='plain'><option>-b</option></arg>
+    </group>
+  </arg>
+  <arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--attr</option></arg>
+      <arg choice='plain'><option>-A</option></arg>
+    </group>
+    <replaceable>attribute-path</replaceable>
+  </arg>
+
+  <sbr />
+  
   <arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg>
 </cmdsynopsis>
 

doc/manual/opt-inst-syn.xml

@@ -0,0 +1,15 @@
+<nop xmlns="http://docbook.org/ns/docbook">
+  
+  <arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--attr</option></arg>
+      <arg choice='plain'><option>-A</option></arg>
+    </group>
+  </arg>
+
+  <arg><option>--from-expression</option></arg>
+  <arg><option>-E</option></arg>
+    
+  <arg><option>--from-profile</option> <replaceable>path</replaceable></arg>
+
+</nop>

doc/manual/release-notes.xml

@@ -38,9 +38,13 @@
   paths.</para></listitem>
 
   
-  <listitem><para>TODO: <varname>allowedReferences</varname> for
+  <listitem><para>Derivations can specify the new special attribute
-  checking the set of references in the output of a
+  <varname>allowedReferences</varname> to enforce that the references
-  derivation.</para></listitem>
+  in the output of a derivation are a subset of a declared set of
+  paths.  For example, if <varname>allowedReferences</varname> is an
+  empty list, then the output must not have any references.  This is
+  used in NixOS to check that generated files such as initial ramdisks
+  for booting Linux don’t have any dependencies.</para></listitem>
 
 
   <listitem><para>TODO: semantic cleanups of string concatenation
@@ -54,8 +58,11 @@
   <command>nix-store --register-validity</command>.</para></listitem>
 
 
-  <listitem><para>TODO: magic <varname>exportReferencesGraph</varname>
+  <listitem><para>The new attribute
-  attribute.</para></listitem>
+  <varname>exportReferencesGraph</varname> allows builders access to
+  the references graph of their inputs.  This is used in NixOS for
+  tasks such as generating ISO-9660 images that contain a Nix store
+  populated with the closure of certain paths.</para></listitem>
 
 
   <listitem><para>TODO: option <option>--max-silent-time</option>,
@@ -109,8 +116,10 @@
   disambiguation (<command>nix-env -qaA</command>).</para></listitem>
 
 
-  <listitem><para>TODO: substitutes table is gone, registering
+  <listitem><para>The substitutes table has been removed from the
-  substitutes is now much faster.</para></listitem>
+  database.  This makes operations such as <command>nix-pull</command>
+  and <command>nix-channel --update</command>
+  <emphasis>much</emphasis> faster.</para></listitem>
 
 
   <listitem><para><command>nix-prefetch-url</command> now has a

doc/manual/writing-nix-expressions.xml

@@ -701,7 +701,7 @@ configureFlags = "
 <simplesect><title>Lists</title>
 
 <para>Lists are formed by enclosing a whitespace-separated list of
-values between square bracktes.  For example,
+values between square brackets.  For example,
 
 <programlisting>
 [ 123 ./foo.nix "abc" (f {x=y;}) ]</programlisting>
@@ -927,7 +927,7 @@ evaluates to <literal>["foobar" "foobla" "fooabc"]</literal>.</para>
 if <replaceable>e1</replaceable> then <replaceable>e2</replaceable> else <replaceable>e3</replaceable></programlisting>
 
 where <replaceable>e1</replaceable> is an expression that should
-evaluate to a boolean value (<literal>true</literal> or
+evaluate to a Boolean value (<literal>true</literal> or
 <literal>false</literal>).</para>
 
 </simplesect>
@@ -942,7 +942,7 @@ on or between features and dependencies hold.  They look like this:
 assert <replaceable>e1</replaceable>; <replaceable>e2</replaceable></programlisting>
 
 where <replaceable>e1</replaceable> is an expression that should
-evaluate to a boolean value.  If it evaluates to
+evaluate to a Boolean value.  If it evaluates to
 <literal>true</literal>, <replaceable>e2</replaceable> is returned;
 otherwise expression evaluation is aborted and a backtrace is printed.</para>
 
@@ -1234,7 +1234,7 @@ set, the attributes of which specify the inputs of the build.</para>
 
   </para></listitem>
 
-  <listitem><para>The optional argument <varname>args</varname>
+  <listitem><para>The optional attribute <varname>args</varname>
   specifies command-line arguments to be passed to the builder.  It
   should be a list.</para></listitem>
 
@@ -1337,6 +1337,233 @@ command-line argument.  See <xref linkend='sec-standard-environment'
 
 </para>
 
+
+<section><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.  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>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>
+
+  
+  
+
+</variablelist>
+
+</section>
+
+
 </section>
 
 

mergeTrunkBackIn.sh

@@ -1,4 +1,4 @@
-svn merge -r 9549:9561 https://svn.cs.uu.nl:12443/repos/trace/nix/trunk
+svn merge -r 9561:9584 https://svn.cs.uu.nl:12443/repos/trace/nix/trunk
 
 #already done:
 # 8628 
@@ -26,3 +26,5 @@ svn merge -r 9549:9561 https://svn.cs.uu.nl:12443/repos/trace/nix/trunk
 # 9536
 # 9549
 # 9561
+# 9584
+

src/libexpr/primops.cc

@@ -937,6 +937,7 @@ static Expr prim_listToAttrs(EvalState & state, const ATermVector & args)
     }
 }
 
+
 static Expr prim_removeAttrs(EvalState & state, const ATermVector & args)
 {
     ATermMap attrs;
@@ -951,6 +952,7 @@ static Expr prim_removeAttrs(EvalState & state, const ATermVector & args)
     return makeAttrs(attrs);
 }
 
+
 /* Determine whether the argument is a list. */
 static Expr prim_isAttrs(EvalState & state, const ATermVector & args)
 {
@@ -958,6 +960,7 @@ static Expr prim_isAttrs(EvalState & state, const ATermVector & args)
     return makeBool(matchAttrs(evalExpr(state, args[0]), list));
 }
 
+
 /*************************************************************
  * Lists
  *************************************************************/