From 3892f516ca7362919a94f226c1c8ede1161b3ee9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= <ludo@gnu.org>
Date: Wed, 12 Oct 2011 14:20:02 +0000
Subject: [PATCH] doc: Write "Building from the Command Line".

---
 doc/manual/projects.xml | 65 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 58 insertions(+), 7 deletions(-)

diff --git a/doc/manual/projects.xml b/doc/manual/projects.xml
index a954efb9..886a65d1 100644
--- a/doc/manual/projects.xml
+++ b/doc/manual/projects.xml
@@ -353,15 +353,66 @@ in
   </section>
 
   <section>
-    <title>Building on the Command Line</title>
+    <title>Building from the Command Line</title>
 
-Overigens zijn die helemaal niet Hydra-specifiek, je kunt ze gewoon vanaf de
-command line bouwen, bijv. als je een patchelf checkout hebt (met een nixpkgs
-checkout in ../nixpkgs):
+    <para>
+      It is often useful to test a build recipe, for instance before
+      it is actually used by Hydra, when testing changes, or when
+      debugging a build issue.  Since build recipes for Hydra jobsets
+      are just plain Nix expressions, they can be evaluated using the
+      standard Nix tools.
+    </para>
 
-<screen>
-$ nix-build release.nix -A rpm_fedora10i386
-</screen>
+    <para>
+      To evaluate the <varname>tarball</varname> jobset of <xref
+      linkend='ex-hello' />, just run:
+
+      <screen>
+	$ nix-build release.nix -A tarball
+      </screen>
+
+      However, doing this with <xref linkend='ex-hello' /> as is will
+      probably yield an error like this:
+
+      <screen>
+	error: cannot auto-call a function that has an argument without a default value (`nixpkgs')
+      </screen>
+
+      This is because no value was specified for the
+      <varname>nixpkgs</varname> argument of the Nix expression.
+    </para>
+
+    <para>
+      This is fixed by providing a default value for that argument in
+      the Nix expression, which will allow <command>nix-build</command>
+      to auto-call the function: instfead of writing <literal>{ nixpkgs
+      }:</literal>, we now write <literal>{ nixpkgs ? &lt;nixpkgs&gt;
+      }:</literal>.  What it means is that, by default, the
+      <varname>nixpkgs</varname> variable will be bound to the absolute
+      path of any <filename>nixpkgs</filename> file found in the Nix
+      search path.  Similarly, a default value for
+      <varname>helloSrc</varname> needs to be provided.
+    </para>
+
+    <para>
+      Thus, assuming a checkout of Nixpkgs is available under
+      <filename>$HOME/src/nixpkgs</filename>, the
+      <varname>tarball</varname> jobset can now be evaluated by running:
+
+      <screen>
+	$ nix-build -I ~/src release.nix -A tarball
+      </screen>
+
+      Similarly, the <varname>build</varname> jobset can be evaluated:
+
+      <screen>
+	$ nix-build -I ~/src release.nix -A build
+      </screen>
+
+      The <varname>build</varname> job reuses the result of the
+      <varname>tarball</varname> job, rebuilding it only if it needs to.
+    </para>
+      
 
   </section>
 </chapter>