Restructuring the Nix manual

doc/manual/expressions/debug-build.xml

@@ -0,0 +1,33 @@
+<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-debug-build">
+
+<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:
+
+<screen>
+$ nix-build -K ./foo.nix
+... fails, keeping build directory `/tmp/nix-1234-0'
+
+$ cd /tmp/nix-1234-0
+
+$ source env-vars
+
+<lineannotation>(edit some files...)</lineannotation>
+
+$ make
+
+<lineannotation>(execution continues with the same GCC, make, etc.)</lineannotation></screen>
+
+</para>
+
+</section>