* Manpage for nix-copy-closure.

17 files changed, 308 insertions, 25 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 9c2e308dad..b9a6b6184b 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -15,7 +15,7 @@ man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
  nix-collect-garbage.1 nix-push.1 nix-pull.1 \
  nix-prefetch-url.1 nix-channel.1 \
  nix-pack-closure.1 nix-unpack-closure.1 \
- nix-install-package.1 nix-hash.1
+ nix-install-package.1 nix-hash.1 nix-copy-closure.1
 
 FIGURES = figures/user-environments.png
 
@@ -31,7 +31,7 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \
 manual.is-valid: $(MANUAL_SRCS) version.txt
 #	$(XMLLINT) --xinclude $< | $(XMLLINT) --noout --nonet --relaxng $(docbookrng)/docbook.rng -
 	if test "$(jing)" != "false"; then \
-		$(XMLLINT) --xinclude $< | $(jing) $(docbookrng)/docbook.rng /dev/stdin; \
+		$(XMLLINT) --xinclude $< | $(jing) $(docbookrng)/docbook.rng /dev/fd/0; \
 	else \
 		echo "Not validating."; \
 	fi
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 35b4417f10..a5a2902a7c 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -13,14 +13,21 @@
         <firstname>Eelco</firstname>
         <surname>Dolstra</surname>
       </personname>
+      <affiliation>
+        <orgname>Utrecht University</orgname>
+        <orgdiv>Faculty of Science, Department of Information and Computing Sciences</orgdiv>
+      </affiliation>
     </author>
 
     <copyright>
       <year>2004</year>
       <year>2005</year>
       <year>2006</year>
+      <year>2007</year>
       <holder>Eelco Dolstra</holder>
     </copyright>
+
+    <date>September 2007</date>
     
   </info>
 
@@ -49,7 +56,7 @@
         <title>nix-instantiate</title>
         <xi:include href="nix-instantiate.xml" />
       </section>
-      <section>
+      <section xml:id="sec-nix-store">
         <title>nix-store</title>
         <xi:include href="nix-store.xml" />
       </section>
@@ -65,10 +72,14 @@
         <title>nix-channel</title>
         <xi:include href="nix-channel.xml" />
       </section>
-      <section>
+      <section xml:id="sec-nix-collect-garbage">
         <title>nix-collect-garbage</title>
         <xi:include href="nix-collect-garbage.xml" />
       </section>
+      <section xml:id="sec-nix-copy-closure">
+        <title>nix-copy-closure</title>
+        <xi:include href="nix-copy-closure.xml" />
+      </section>
       <section xml:id="sec-nix-hash">
         <title>nix-hash</title>
         <xi:include href="nix-hash.xml" />
@@ -77,11 +88,11 @@
         <title>nix-install-package</title>
         <xi:include href="nix-install-package.xml" />
       </section>
-      <section>
+      <section xml:id="sec-nix-pack-closure">
         <title>nix-pack-closure</title>
         <xi:include href="nix-pack-closure.xml" />
       </section>
-      <section>
+      <section xml:id="sec-nix-prefetch-url">
         <title>nix-prefetch-url</title>
         <xi:include href="nix-prefetch-url.xml" />
       </section>
@@ -93,7 +104,7 @@
         <title>nix-push</title>
         <xi:include href="nix-push.xml" />
       </section>
-      <section>
+      <section xml:id="sec-nix-unpack-closure">
         <title>nix-unpack-closure</title>
         <xi:include href="nix-unpack-closure.xml" />
       </section>
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index 541275c523..3f35f5de39 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -1,5 +1,13 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-build</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
 
 <refnamediv>
   <refname>nix-build</refname>
diff --git a/doc/manual/nix-channel.xml b/doc/manual/nix-channel.xml
index f3fb7c1f6d..8ee4a5f274 100644
--- a/doc/manual/nix-channel.xml
+++ b/doc/manual/nix-channel.xml
@@ -1,6 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
   
+<refmeta>
+  <refentrytitle>nix-channel</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
 <refnamediv>
   <refname>nix-channel</refname>
   <refpurpose>manage Nix channels</refpurpose>
diff --git a/doc/manual/nix-collect-garbage.xml b/doc/manual/nix-collect-garbage.xml
index 9dd9b664d9..53cffe2ffd 100644
--- a/doc/manual/nix-collect-garbage.xml
+++ b/doc/manual/nix-collect-garbage.xml
@@ -1,6 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
   
+<refmeta>
+  <refentrytitle>nix-collect-garbage</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
 <refnamediv>
   <refname>nix-collect-garbage</refname>
   <refpurpose>delete unreachable store paths</refpurpose>
diff --git a/doc/manual/nix-copy-closure.xml b/doc/manual/nix-copy-closure.xml
new file mode 100644
index 0000000000..fcb6be2343
--- /dev/null
+++ b/doc/manual/nix-copy-closure.xml
@@ -0,0 +1,151 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-copy-closure</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
+<refnamediv>
+  <refname>nix-copy-closure</refname>
+  <refpurpose>copy a closure to or from a remote machine via SSH</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-copy-closure</command>
+    <group>
+      <arg choice='plain'><option>--to</option></arg>
+      <arg choice='plain'><option>--from</option></arg>
+    </group>
+    <arg><option>--sign</option></arg>
+    <arg><option>--gzip</option></arg>
+    <arg choice='plain'>
+      <arg><replaceable>user@</replaceable></arg><replaceable>machine</replaceable>
+    </arg>
+    <arg choice='plain'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para><command>nix-copy-closure</command> gives you an easy and
+efficient way to exchange software between machines.  Given one or
+more Nix store paths <replaceable>paths</replaceable> on the local
+machine, <command>nix-copy-closure</command> computes the closure of
+those paths (i.e. all their dependencies in the Nix store), and copies
+all paths in the closure to the remote machine via the
+<command>ssh</command> (Secure Shell) command.  With the
+<option>--from</option>, the direction is reversed:
+the closure of <replaceable>paths</replaceable> on a remote machine is
+copied to the Nix store on the local machine.</para>
+
+<para>This command is efficient because it only sends the store paths
+that are missing on the target machine.</para>
+
+<para>Since <command>nix-copy-closure</command> calls
+<command>ssh</command>, you may be asked to type in the appropriate
+password or passphrase.  In fact, you may be asked
+<emphasis>twice</emphasis> because <command>nix-copy-closure</command>
+currently connects twice to the remote machine, first to get the set
+of paths missing on the target machine, and second to send the dump of
+those paths.  If this bothers you, use
+<command>ssh-agent</command>.</para>
+
+
+<refsection><title>Options</title>
+
+<variablelist>
+  
+  <varlistentry><term><option>--to</option></term>
+
+    <listitem><para>Copy the closure of
+    <replaceable>paths</replaceable> from the local Nix store to the
+    Nix store on <replaceable>machine</replaceable>.  This is the
+    default.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--from</option></term>
+
+    <listitem><para>Copy the closure of
+    <replaceable>paths</replaceable> from the Nix store on
+    <replaceable>machine</replaceable> to the local Nix
+    store.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--sign</option></term>
+
+    <listitem><para>Let the sending machine cryptographically sign the
+    dump of each path with the key in
+    <filename>/nix/etc/nix/signing-key.sec</filename>.  If the user on
+    the target machine does not have direct access to the Nix store
+    (i.e., if the target machine has a multi-user Nix installation),
+    then the target machine will check the dump against
+    <filename>/nix/etc/nix/signing-key.pub</filename> before unpacking
+    it in its Nix store.  This allows secure sharing of store paths
+    between untrusted users on two machines, provided that there is a
+    trust relation between the Nix installations on both machines
+    (namely, they have matching public/secret keys).</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--gzip</option></term>
+
+    <listitem><para>Compress the dump of each path with
+    <command>gzip</command> before sending it.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Environment variables</title>
+
+<variablelist>
+
+  <varlistentry><term><envar>NIX_SSHOPTS</envar></term>
+
+    <listitem><para>Additional options to be passed to
+    <command>ssh</command> on the command line.</para></listitem>
+
+  </varlistentry>
+  
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>Copy Firefox with all its dependencies to a remote machine:
+
+<screen>
+$ nix-copy-closure alice@itchy.labs $(type -tP firefox)</screen>
+
+</para>
+
+<para>Copy Subversion from a remote machine and then install it into a
+user environment:
+
+<screen>
+$ nix-copy-closure --from alice@itchy.labs \
+    /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4
+$ nix-env -i /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4
+</screen>
+
+</para>
+
+</refsection>
+
+
+</refsection>
+
+</refentry>
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index 9c9114a901..9b91279211 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -1,6 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
   
+<refmeta>
+  <refentrytitle>nix-env</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
 <refnamediv>
   <refname>nix-env</refname>
   <refpurpose>manipulate or query Nix user environments</refpurpose>
diff --git a/doc/manual/nix-hash.xml b/doc/manual/nix-hash.xml
index 227eb94217..dcf01d3a2c 100644
--- a/doc/manual/nix-hash.xml
+++ b/doc/manual/nix-hash.xml
@@ -1,6 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
   
+<refmeta>
+  <refentrytitle>nix-hash</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
 <refnamediv>
   <refname>nix-hash</refname>
   <refpurpose>compute the cryptographic hash of a path</refpurpose>
diff --git a/doc/manual/nix-install-package.xml b/doc/manual/nix-install-package.xml
index 5e4f03d734..f0eab5df87 100644
--- a/doc/manual/nix-install-package.xml
+++ b/doc/manual/nix-install-package.xml
@@ -1,6 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
   
+<refmeta>
+  <refentrytitle>nix-install-package</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
 <refnamediv>
   <refname>nix-install-package</refname>
   <refpurpose>install a Nix Package file</refpurpose>
diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index 24d4c45d32..d61d6d59de 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -1,6 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
   
+<refmeta>
+  <refentrytitle>nix-instantiate</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
 <refnamediv>
   <refname>nix-instantiate</refname>
   <refpurpose>instantiate store derivations from Nix expressions</refpurpose>
diff --git a/doc/manual/nix-pack-closure.xml b/doc/manual/nix-pack-closure.xml
index 8f79a4f690..c11dacd26f 100644
--- a/doc/manual/nix-pack-closure.xml
+++ b/doc/manual/nix-pack-closure.xml
@@ -1,5 +1,13 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-pack-closure</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
 
 <refnamediv>
   <refname>nix-pack-closure</refname>
diff --git a/doc/manual/nix-prefetch-url.xml b/doc/manual/nix-prefetch-url.xml
index b03169376e..777bbe140b 100644
--- a/doc/manual/nix-prefetch-url.xml
+++ b/doc/manual/nix-prefetch-url.xml
@@ -1,6 +1,14 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
   
+<refmeta>
+  <refentrytitle>nix-prefetch-url</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
+
 <refnamediv>
   <refname>nix-prefetch-url</refname>
   <refpurpose>copy a file from a URL into the store and print its MD5 hash</refpurpose>
diff --git a/doc/manual/nix-pull.xml b/doc/manual/nix-pull.xml
index 28b5e354bb..37ca88fcce 100644
--- a/doc/manual/nix-pull.xml
+++ b/doc/manual/nix-pull.xml
@@ -1,5 +1,13 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-pull</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
 
 <refnamediv>
   <refname>nix-pull</refname>
diff --git a/doc/manual/nix-push.xml b/doc/manual/nix-push.xml
index d58350e2d9..f439af563d 100644
--- a/doc/manual/nix-push.xml
+++ b/doc/manual/nix-push.xml
@@ -1,5 +1,13 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-push</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
 
 <refnamediv>
   <refname>nix-push</refname>
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index d787c337be..a168be024d 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -1,5 +1,13 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-store</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
 
 <refnamediv>
   <refname>nix-store</refname>
diff --git a/doc/manual/nix-unpack-closure.xml b/doc/manual/nix-unpack-closure.xml
index e95225e819..dce0d1db43 100644
--- a/doc/manual/nix-unpack-closure.xml
+++ b/doc/manual/nix-unpack-closure.xml
@@ -1,5 +1,13 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
-          xmlns:xlink="http://www.w3.org/1999/xlink">
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle>nix-unpack-closure</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
 
 <refnamediv>
   <refname>nix-unpack-closure</refname>
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index c3bc060cb1..b19d9a3823 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -1,5 +1,6 @@
 <article xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink">
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="sec-relnotes">
 
 <title>Nix Release Notes</title>
 
@@ -7,7 +8,7 @@
 
 <!--==================================================================-->
 
-<section><title>Release 0.11 (TBA)</title>
+<section xml:id="ssec-relnotes-0.11"><title>Release 0.11 (TBA)</title>
 
 <itemizedlist>
 
@@ -17,9 +18,10 @@
   removed.</para></listitem>
 
 
-  <listitem><para><command>nix-copy-closure</command> copies the
-  missing parts of a closure to or from a remote
-  machine.</para></listitem>
+  <listitem><para>The new command <command>nix-copy-closure</command>
+  gives you an easy and efficient way to exchange software between
+  machines.  It copies the missing parts of the closure of a set of
+  store path to or from a remote machine.</para></listitem>
 
 
   <listitem><para><command>nix-prefetch-url</command> now by default
@@ -99,6 +101,21 @@
   <function>builtins.sub</function>,
   <function>builtins.stringLength</function>,
   <function>builtins.substring</function>.</para></listitem>
+
+
+  <listitem><para>TODO: each subscribed channel is its own attribute
+  in the top-level expression generated for the channel, this allows
+  disambiguation (<command>nix-env -qaA</command>).</para></listitem>
+
+
+  <listitem><para>TODO: substitutes table is gone, registering
+  substitutes is now much faster.</para></listitem>
+
+
+  <listitem><para><command>nix-prefetch-url</command> now has a
+  limited form of caching.  This is used by
+  <command>nix-channel</command> to prevent unnecessary downloads when
+  the channel hasn’t changed.</para></listitem>
   
 
 </itemizedlist>