* Lots of manual stuff. Reference pages for most Nix commands.

* nix-pull now requires the full url to the manifest, i.e.,
  `/MANIFEST/' is no longer automatically appended.
* nix-prefetch-url works again.  

1 files changed, 67 insertions, 6 deletions

diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
index 77579776b07d..eb479945aba5 100644
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -11,6 +11,16 @@
 
     <listitem>
       <para>
+        Generations properly form a tree.  E.g., if after switching to
+        generation 39, we perform an installation action, a generation
+        43 is created which is a descendant of 39, not 42.  So a
+        rollback from 43 ought to go back to 39.  This is not
+        currently implemented; generations form a linear sequence.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
         Unify the concepts of successors and substitutes into a
         general notion of <emphasis>equivalent expressions</emphasis>.
         Expressions are equivalent if they have the same target paths
@@ -43,12 +53,63 @@
       </para>
     </listitem>
 
+    <listitem>
+      <para>
+        The current garbage collector is a hack.  It should be
+        integrated into <command>nix-store</command>.  It should
+        delete derivations in an order determined by topologically
+        sorting derivations under the points-to relation.  This
+        ensures that no store paths ever exist that point to
+        non-existant store paths.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        There are race conditions between the garbage collector and
+        other Nix tools.  For instance, when we run
+        <command>nix-env</command> to build and install a derivation
+        and run the garbage collector at the same time, the garbage
+        collector may kick in exactly between the build and
+        installation steps, i.e., before the newly built derivation
+        has become reachable from a root of the garbage collector.
+      </para>
+
+      <para>
+        One solution would be for these programs to properly register
+        temporary roots for the collector.  Another would be to use
+        stop-the-world garbage collection: if any tool is running, the
+        garbage collector blocks, and vice versa.  These solutions do
+        not solve the situation where multiple tools are involved,
+        e.g.,
+
+        <screen>
+$ nix-store -r $(nix-instantiate foo.nix)</screen>
+
+        since even if <command>nix-instantiate</command> where to
+        register a temporary root, it would be released by the time
+        <command>nix-store</command> is started.  A solution would be
+        to write the intermediate value to a file that is used as a
+        root to the collector, e.g.,
+        
+        <screen>
+$ nix-instantiate foo.nix > /nix/var/nix/roots/bla
+$ nix-store -r $(cat /nix/var/nix/roots/bla)</screen>
+
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        For security, <command>nix-push</command> manifests should be
+        digitally signed, and <command>nix-pull</command> should
+        verify the signatures.  The actual NAR archives in the cache
+        do not need to be signed, since the manifest contains
+        cryptographic hashes of these files (and
+        <filename>fetchurl.nix</filename> checks them).
+      </para>
+    </listitem>
+
   </itemizedlist>
 
 </appendix>
-
-<!--
-local variables:
-sgml-parent-document: ("book.xml" "appendix")
-end:
--->