Manual updates

doc/manual/installation.xml

@@ -15,11 +15,11 @@
   <listitem><para>Linux (particularly on x86, x86_64, and
   PowerPC).</para></listitem>
 
-  <listitem><para>Mac OS X, both on Intel and
+  <listitem><para>Mac OS X.</para></listitem>
-  PowerPC.</para></listitem>
 
   <listitem><para>FreeBSD (only tested on Intel).</para></listitem>
 
+  <!--
   <listitem><para>Windows through <link
   xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
 
@@ -28,6 +28,7 @@
   partition.</para></warning>
 
   </listitem>
+  -->
 
 </itemizedlist>
 
@@ -47,7 +48,7 @@ for Red Hat, SuSE, and Fedora Core are also available.</para>
 
 <para>Alternatively, the most recent sources of Nix can be obtained
 from its <link
-xlink:href="https://github.com/NixOS/nix">git
+xlink:href="https://github.com/NixOS/nix">Git
 repository</link>.  For example, the following command will check out
 the latest revision into a directory called
 <filename>nix</filename>:</para>
@@ -56,8 +57,8 @@ the latest revision into a directory called
 $ git clone https://github.com/NixOS/nix</screen>
 
 <para>Likewise, specific releases can be obtained from the <link
-xlink:href="https://github.com/NixOS/nix/tags">tags
+xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the
-</link> of the repository.</para>
+repository.</para>
 
 </section>
 
@@ -85,9 +86,9 @@ installed, including development headers and libraries.  If your
 distribution does not provide these, you can obtain bzip2 from <link
 xlink:href="http://www.bzip.org/"/>.</para>
 
-<para>Nix requires the SQLite embedded database library.  If your
+<para>Nix requires the SQLite embedded database library, version
-distribution does not provide it, please install it from <link
+3.6.19 or higher.  If your distribution does not provide it, please
-xlink:href="http://www.sqlite.org/" />.</para>
+install it from <link xlink:href="http://www.sqlite.org/" />.</para>
 
 <para>Nix requires the Perl DBI and DBD::SQLite libraries, which are
 available from <link xlink:href="http://search.cpan.org/">CPAN</link>
@@ -109,21 +110,20 @@ xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook XSL
 stylesheets</link> and optionally the <link
 xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG
 schemas</link>.  Note that these are only required if you modify the
-manual sources or when you are building from the Subversion
+manual sources or when you are building from the Git
 repository.</para>
 
 <para>To build the parser, very <emphasis>recent</emphasis> versions
 of Bison and Flex are required.  (This is because Nix needs GLR
 support in Bison and reentrancy support in Flex.)  For Bison, you need
 version 2.3 or higher (1.875 does <emphasis>not</emphasis> work),
-which can be obtained from
+which can be obtained from the <link
-the <link xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP
+xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP server</link>.
-server</link>.  For Flex, you need version 2.5.33, which is available
+For Flex, you need version 2.5.33, which is available on <link
-on <link xlink:href="http://lex.sourceforge.net/">SourceForge</link>.
+xlink:href="http://lex.sourceforge.net/">SourceForge</link>.  Slightly
-Slightly older versions may also work, but ancient versions like the
+older versions may also work, but ancient versions like the ubiquitous
-ubiquitous 2.5.4a won't.  Note that these are only required if you
+2.5.4a won't.  Note that these are only required if you modify the
-modify the parser or when you are building from the Subversion
+parser or when you are building from the Git repository.</para>
-repository.</para>
 
 </section>
 
@@ -140,8 +140,8 @@ $ make install</screen>
 
 </para>
 
-<para>When building from the Subversion repository, these should be
+<para>When building from the Git repository, these should be preceded
-preceded by the command:
+by the command:
 
 <screen>
 $ ./bootstrap.sh</screen>

doc/manual/introduction.xml

@@ -17,10 +17,10 @@ store</emphasis>, usually the directory
 subdirectory such as
 
 <programlisting>
-/nix/store/r8vvq9kq18pz08v249h8my6r9vs7s0n3-firefox-2.0.0.1/
+/nix/store/nlc4z5y1hm8w9s8vm6m1f5hy962xjmp5-firefox-12.0
 </programlisting>
 
-where <literal>r8vvq9kq…</literal> is a unique identifier for the
+where <literal>nlc4z5…</literal> is a unique identifier for the
 package that captures all its dependencies (it’s a cryptographic hash
 of the package’s build dependency graph).  This enables many powerful
 features.</para>
@@ -72,15 +72,14 @@ sounds risky, but it works extremely well.</para>
 
 <simplesect><title>Multi-user support</title>
 
-<para>Starting at version 0.11, Nix has multi-user support.  This
+<para>Nix has multi-user support.  This means that non-privileged
-means that non-privileged users can securely install software.  Each
+users can securely install software.  Each user can have a different
-user can have a different <emphasis>profile</emphasis>, a set of
+<emphasis>profile</emphasis>, a set of packages in the Nix store that
-packages in the Nix store that appear in the user’s
+appear in the user’s <envar>PATH</envar>.  If a user installs a
-<envar>PATH</envar>.  If a user installs a package that another user
+package that another user has already installed previously, the
-has already installed previously, the package won’t be built or
+package won’t be built or downloaded a second time.  At the same time,
-downloaded a second time.  At the same time, it is not possible for
+it is not possible for one user to inject a Trojan horse into a
-one user to inject a Trojan horse into a package that might be used by
+package that might be used by another user.</para>
-another user.</para>
 
 <!--
 <para>More details can be found in Section 3 of our <a
@@ -264,8 +263,10 @@ xlink:href="http://www.cs.uu.nl/wiki/Trace/WebHome">TraCE
 project</link> (2003-2008).  The project was funded by the Software
 Engineering Research Program <link
 xlink:href="http://www.jacquard.nl/">Jacquard</link> to improve the
-support for variability in software systems.  Further funding is now
+support for variability in software systems.  Further funding was
-provided by the NIRICT LaQuSo Build Farm project.</para>
+provided by the NIRICT LaQuSo Build Farm project.  Development is
+currently supported by <link
+xlink:href="http://www.logicblox.com/">LogicBlox</link>.</para>
 
 </section>
 
@@ -275,7 +276,7 @@ provided by the NIRICT LaQuSo Build Farm project.</para>
 <para>This manual tells you how to install and use Nix and how to
 write Nix expressions for software not already in the Nix Packages
 collection.  It also discusses some advanced topics, such as setting
-up a Nix-based build farm.</para>
+up distributed multi-platform building.</para>
 
 </section>
 
@@ -315,13 +316,12 @@ Upgrading in a Purely Functional Component Deployment Model
 paper <citetitle
 xlink:href='http://www.st.ewi.tudelft.nl/~dolstra/pubs/servicecm-scm12-final.pdf'>
 Service Configuration Management</citetitle> shows how services (e.g.,
-web servers) can be deployed and managed through Nix.  A short
+web servers) can be deployed and managed through Nix.  An overview of
-overview of NixOS is given in the HotOS XI paper <citetitle
+NixOS is given in the JFP article <citetitle
-xlink:href="http://www.st.ewi.tudelft.nl/~dolstra/pubs/hotos-final.pdf">Purely
+xlink:href="http://www.st.ewi.tudelft.nl/~dolstra/pubs/nixos-jfp-final.pdf">NixOS:
-Functional System Configuration Management</citetitle>.  The Nix
+A Purely Functional Linux Distribution</citetitle>.  The Nix homepage
-homepage has <link
+has <link xlink:href="http://nixos.org/docs/papers.html">an up-to-date
-xlink:href="http://nixos.org/docs/papers.html">an up-to-date list
+list of Nix-related papers</link>.</para>
-of Nix-related papers</link>.</para>
 
 <para>Nix is the subject of Eelco Dolstra’s PhD thesis <citetitle
 xlink:href="http://igitur-archive.library.uu.nl/dissertations/2006-0118-200031/index.htm">The

doc/manual/manual.xml

@@ -5,8 +5,7 @@
 
     <title>Nix User's Guide</title>
 
-    <subtitle>Draft (Version <xi:include href="version.txt"
+    <edition>Version <xi:include href="version.txt" parse="text" /></edition>
-    parse="text" />)</subtitle>
 
     <author>
       <personname>
@@ -24,7 +23,7 @@
       <holder>Eelco Dolstra</holder>
     </copyright>
 
-    <date>January 2012</date>
+    <date>May 2012</date>
     
   </info>
 

doc/manual/quick-start.xml

@@ -11,9 +11,9 @@ to the following chapters.</para>
 
 <orderedlist>
 
-<listitem><para>Download a source tarball, RPM or Deb from <link
+<listitem><para>Download a source tarball or RPM or Debian/Ubuntu
-xlink:href='http://nixos.org/'/>.  Build source distributions using
+package from <link xlink:href='http://nixos.org/'/>.  Build source
-the regular sequence:
+distributions using the regular sequence:
         
 <screen>
 $ tar xvfj nix-<replaceable>version</replaceable>.tar.bz2
@@ -41,8 +41,7 @@ file).</para></listitem>
 <listitem><para>Subscribe to the Nix Packages channel.
 
 <screen>
-$ nix-channel --add \
+$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable</screen>
-    http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable</screen>
 
 </para></listitem>
 
@@ -108,10 +107,10 @@ numbers).</para></listitem>
 
 <listitem><para>You can also install specific packages directly from
 your web browser.  For instance, you can go to <link
-xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest" />
+xlink:href="http://hydra.nixos.org/jobset/nixpkgs/trunk/channel/latest"
-and click on any link for the individual packages for your platform.
+/> and click on any link for the individual packages for your
-Associate <literal>application/nix-package</literal> with the program
+platform.  Associate <literal>application/nix-package</literal> with
-<filename>/nix/bin/nix-install-package</filename>.  A window should
+the program <command>nix-install-package</command>.  A window should
 appear asking you whether it’s okay to install the package.  Say
 <literal>Y</literal>.  The package and all its dependencies will be
 installed.</para></listitem>

doc/manual/style.css

@@ -234,7 +234,6 @@ div.glosslist dt
 
 span.command strong
 {
-    font-family: monospace;
     font-weight: normal;
     color: #400000;
 }
@@ -249,3 +248,8 @@ table
     border-collapse: collapse;
     box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
 }
+
+div.affiliation
+{
+    font-style: italic;
+}

doc/manual/writing-nix-expressions.xml

@@ -11,6 +11,13 @@ the things that tell Nix how to build packages.  It starts with a
 simple example (a Nix expression for GNU Hello), and then moves
 on to a more in-depth look at the Nix expression language.</para>
 
+<note><para>This chapter is mostly about the Nix expression language.
+For more extensive information on adding packages to the Nix Packages
+collection (such as functions in the standard environment and coding
+conventions), please consult <link
+xlink:href="http://hydra.nixos.org/job/nixpkgs/trunk/tarball/latest/download-by-type/doc/manual">its
+manual</link>.</para></note>
+
 
 <section><title>A simple Nix expression</title>
 
@@ -315,15 +322,15 @@ error check.</para>
 
 rec { <co xml:id='ex-hello-composition-co-1' />
   
-  hello = (import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' />) { <co xml:id='ex-hello-composition-co-3' />
+  hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' />
     inherit fetchurl stdenv perl;
   };
 
-  perl = (import ../development/interpreters/perl) { <co xml:id='ex-hello-composition-co-4' />
+  perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' />
     inherit fetchurl stdenv;
   };
 
-  fetchurl = (import ../build-support/fetchurl) { 
+  fetchurl = import ../build-support/fetchurl { 
     inherit stdenv; ...
   };
   
@@ -390,6 +397,23 @@ some fragments of
     <varname>stdenv.mkDerivation</varname> in <xref
     linkend='ex-hello-nix' />).</para>
 
+    <note><para>Nixpkgs has a convenience function
+    <function>callPackage</function> that imports and calls a
+    function, filling in any missing arguments by passing the
+    corresponding attribute from the Nixpkgs set, like this:
+
+<programlisting>
+hello = callPackage ../applications/misc/hello/ex-1 { };
+</programlisting>
+
+    If necessary, you can set or override arguments:
+
+<programlisting>
+hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; };
+</programlisting>
+
+    </para></note>
+
   </callout>
 
   <callout arearefs='ex-hello-composition-co-4'>
@@ -813,7 +837,23 @@ occur once.</para>
 <programlisting>
 { a = "Foo"; b = "Bar"; }.a</programlisting>
 
-evaluates to <literal>"Foo"</literal>.</para>
+evaluates to <literal>"Foo"</literal>.  It is possible to provide a
+default value in an attribute selection using the
+<literal>or</literal> keyword.  For example,
+
+<programlisting>
+{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting>
+
+will evaluate to <literal>"Xyzzy"</literal> because there is no
+<varname>c</varname> attribute in the set.</para>
+
+<para>You can use arbitrary string constants as attribute names by
+enclosing them in quotes:
+
+<programlisting>
+{ "foo bar" = 123; "nix-1.0" = 456; }."foo bar" </programlisting>
+
+This will evaluate to <literal>123</literal>.</para>
 
 </simplesect>
 
@@ -1189,12 +1229,17 @@ weakest binding).</para>
     </thead>
     <tbody>
       <row>
-        <entry><replaceable>e</replaceable> .
+        <entry><replaceable>e</replaceable> <literal>.</literal>
-        <replaceable>id</replaceable></entry>
+        <replaceable>attrpath</replaceable>
+        [ <literal>or</literal> <replaceable>def</replaceable> ]
+        </entry>
         <entry>none</entry>
-        <entry>Select attribute named <replaceable>id</replaceable>
+        <entry>Select attribute denoted by the attribute path
-        from attribute set <replaceable>e</replaceable>.  Abort
+        <replaceable>attrpath</replaceable> from attribute set
-        evaluation if the attribute doesn’t exist.</entry>
+        <replaceable>e</replaceable>.  (An attribute path is a
+        dot-separated list of attribute names.)  If the attribute
+        doesn’t exist, return <replaceable>def</replaceable> if
+        provided, otherwise abort evaluation.</entry>
       </row>
       <row>
         <entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry>
@@ -1203,31 +1248,31 @@ weakest binding).</para>
         argument <replaceable>e2</replaceable>.</entry>
       </row>
       <row>
-        <entry><replaceable>e</replaceable> ?
+        <entry><replaceable>e</replaceable> <literal>?</literal>
-        <replaceable>id</replaceable></entry>
+        <replaceable>attrpath</replaceable></entry>
         <entry>none</entry>
         <entry>Test whether attribute set <replaceable>e</replaceable>
-        contains an attribute named <replaceable>id</replaceable>;
+        contains the attribute denoted by <replaceable>attrpath</replaceable>;
         return <literal>true</literal> or
         <literal>false</literal>.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ++ <replaceable>e2</replaceable></entry>
+        <entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry>
         <entry>right</entry>
         <entry>List concatenation.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> + <replaceable>e2</replaceable></entry>
+        <entry><replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable></entry>
         <entry>left</entry>
         <entry>String or path concatenation.</entry>
       </row>
       <row>
-        <entry>! <replaceable>e</replaceable></entry>
+        <entry><literal>!</literal> <replaceable>e</replaceable></entry>
         <entry>left</entry>
         <entry>Boolean negation.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> //
+        <entry><replaceable>e1</replaceable> <literal>//</literal>
         <replaceable>e2</replaceable></entry>
         <entry>right</entry>
         <entry>Return an attribute set consisting of the attributes in
@@ -1236,31 +1281,31 @@ weakest binding).</para>
         precedence over the former in case of equally named attributes).</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ==
+        <entry><replaceable>e1</replaceable> <literal>==</literal>
         <replaceable>e2</replaceable></entry>
         <entry>none</entry>
         <entry>Equality.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> !=
+        <entry><replaceable>e1</replaceable> <literal>!=</literal>
         <replaceable>e2</replaceable></entry>
         <entry>none</entry>
         <entry>Inequality.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> &amp;&amp;
+        <entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
         <replaceable>e2</replaceable></entry>
         <entry>left</entry>
         <entry>Logical AND.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ||
+        <entry><replaceable>e1</replaceable> <literal>||</literal>
         <replaceable>e2</replaceable></entry>
         <entry>left</entry>
         <entry>Logical OR.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> ->
+        <entry><replaceable>e1</replaceable> <literal>-></literal>
         <replaceable>e2</replaceable></entry>
         <entry>none</entry>
         <entry>Logical implication (equivalent to
@@ -1662,7 +1707,17 @@ impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ];
   </varlistentry>
 
   
+  <varlistentry><term><varname>preferLocalBuild</varname></term>
 
+    <listitem><para>If this attribute is set to
+    <literal>true</literal> and <link
+    linkend="chap-distributed-builds">distributed building is
+    enabled</link>, then, if possible, perform this build locally
+    instead of forwarding it to a remote machine.  This is appropriate
+    for trivial builders where the cost of doing a remote build would
+    exceed the cost of building locally.</para></listitem>
+
+  </varlistentry>
 
 </variablelist>