* Some more updates.

This commit is contained in:
Eelco Dolstra 2005-03-15 15:42:11 +00:00
parent 62dbfbc45b
commit 693ff4f6bf
2 changed files with 87 additions and 109 deletions

View file

@ -1,138 +1,116 @@
<refentry> <refentry>
<refnamediv>
<refname>nix-push</refname>
<refpurpose>push store paths onto a network cache</refpurpose>
</refnamediv>
<refsynopsisdiv> <refnamediv>
<cmdsynopsis> <refname>nix-push</refname>
<command>nix-push</command> <refpurpose>push store paths onto a network cache</refpurpose>
<arg choice='plain'><replaceable>archives-put-url</replaceable></arg> </refnamediv>
<arg choice='plain'><replaceable>archives-get-url</replaceable></arg>
<arg choice='plain'><replaceable>manifest-put-url</replaceable></arg>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsection> <refsynopsisdiv>
<title>Description</title> <cmdsynopsis>
<command>nix-push</command>
<group choice='req'>
<arg choice='req'>
<arg choice='plain'><replaceable>archives-put-url</replaceable></arg>
<arg choice='plain'><replaceable>archives-get-url</replaceable></arg>
<arg choice='plain'><replaceable>manifest-put-url</replaceable></arg>
</arg>
<arg choice='req'>
<arg choice='plain'><option>--copy</option></arg>
<arg choice='plain'><replaceable>archives-dir</replaceable></arg>
<arg choice='plain'><replaceable>manifest-file</replaceable></arg>
</arg>
</group>
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<para>
The command <command>nix-push</command> builds a set of store
expressions (if necessary), and then packages and uploads all
store paths in the resulting closures to a server. A network
cache thus populated can subsequently be used to speed up
software deployment on other machines using the
<command>nix-pull</command> command.
</para>
<para> <refsection><title>Description</title>
<command>nix-push</command> performs the following actions.
<para>The command <command>nix-push</command> builds a set of store
paths (if necessary), and then packages and uploads all store paths in
the resulting closures to a server. A network cache thus populated
can subsequently be used to speed up software deployment on other
machines using the <command>nix-pull</command> command.</para>
<para><command>nix-push</command> performs the following actions.
<orderedlist> <orderedlist>
<listitem> <listitem><para>Each path in <replaceable>paths</replaceable> is
<para> realised (using <link
The store expressions stored in linkend='rsec-nix-store-realise'><literal>nix-store
<replaceable>paths</replaceable> are realised (using --realise</literal></link>).</para></listitem>
<literal>nix-store --realise</literal>).
</para>
</listitem>
<listitem> <listitem><para>All paths in the closure of the store expressions
<para> stored in <replaceable>paths</replaceable> are determined (using
All paths in the closure of the store expressions stored <literal>nix-store --query --requisites
in <replaceable>paths</replaceable> are determined (using --include-outputs</literal>). It should be noted that since the
<literal>nix-store --query --requisites <option>--include-outputs</option> flag is used, you get a combined
--include-successors</literal>). It should be noted that source/binary distribution.</para></listitem>
since the <option>--include-successors</option> flag is
used, if you specify a derivation store expression, you
get a combined source/binary distribution. If you only
want a binary distribution, you should specify the closure
store expression that result from realising these (see
below).
</para>
</listitem>
<listitem> <listitem><para>All store paths determined in the previous step are
<para> packaged and compressed into a <command>bzip</command>ped NAR
All store paths determined in the previous step are archive (extension <filename>.nar.bz2</filename>).</para></listitem>
packaged and compressed into a <command>bzip</command>ped
NAR archive (extension <filename>.nar.bz2</filename>).
</para>
</listitem>
<listitem> <listitem><para>A <emphasis>manifest</emphasis> is created that
<para> contains information on the store paths, their eventual URLs in the
A <emphasis>manifest</emphasis> is created that contains cache, and cryptographic hashes of the contents of the NAR
information on the store paths, their eventual URLs in the archives.</para></listitem>
cache, and cryptographic hashes of the contents of the NAR
archives.
</para>
</listitem>
<listitem> <listitem><para>Each store path is uploaded to the remote directory
<para> specified by <replaceable>archives-put-url</replaceable>. HTTP PUT
Each store path is uploaded to the remote directory requests are used to do this. However, before a file
specified by <replaceable>archives-put-url</replaceable>. <varname>x</varname> is uploaded to
HTTP PUT requests are used to do this. However, before a <literal><replaceable>archives-put-url</replaceable>/<varname>x</varname></literal>,
file <varname>x</varname> is uploaded to <command>nix-push</command> first determines whether this upload is
<literal><replaceable>archives-put-url</replaceable>/<varname>x</varname></literal>, unnecessary by issuing a HTTP HEAD request on
<command>nix-push</command> first determines whether this <literal><replaceable>archives-get-url</replaceable>/<varname>x</varname></literal>.
upload is unnecessary by issuing a HTTP HEAD request on This allows a cache to be shared between many partially overlapping
<literal><replaceable>archives-get-url</replaceable>/<varname>x</varname></literal>. <command>nix-push</command> invocations. (We use two URLs because
This allows a cache to be shared between many partially the upload URL typically refers to a CGI script, while the download
overlapping <command>nix-push</command> invocations. URL just refers to a file system directory on the server.)</para></listitem>
(We use two URLs because the upload URL typically
refers to a CGI script, while the download URL just refers
to a file system directory on the server.)
</para>
</listitem>
<listitem> <listitem><para>The manifest is uploaded using an HTTP PUT request
<para> to <replaceable>manifest-put-url</replaceable>. The corresponding
The manifest is uploaded using an HTTP PUT request to URL to download the manifest can then be used by
<replaceable>manifest-put-url</replaceable>. The <command>nix-pull</command>.</para></listitem>
corresponding URL to download the manifest can then be
used by <command>nix-pull</command>.
</para>
</listitem>
</orderedlist> </orderedlist>
</para>
</para>
<para>TODO: <option>--copy</option></para>
</refsection> </refsection>
<refsection>
<title>Examples</title>
<para> <refsection><title>Examples</title>
To upload files there typically is some CGI script on the server
side. This script should be be protected with a password. The <para>To upload files there typically is some CGI script on the server
following example uploads the store paths resulting from side. This script should be be protected with a password. The
building the Nix expressions in <filename>foo.nix</filename>, following example uploads the store paths resulting from building the
passing appropriate authentication information: Nix expressions in <filename>foo.nix</filename>, passing appropriate
authentication information:
<screen> <screen>
$ nix-push \ $ nix-push \
http://foo@bar:server.domain/cgi-bin/upload.pl/cache \ http://foo@bar:server.domain/cgi-bin/upload.pl/cache \
http://server.domain/cache \ http://server.domain/cache \
http://foo@bar:server.domain/cgi-bin/upload.pl/MANIFEST \ http://foo@bar:server.domain/cgi-bin/upload.pl/MANIFEST \
$(nix-instantiate foo.nix)</screen> $(nix-instantiate foo.nix)</screen>
This will push both sources and binaries (and any build-time This will push both sources and binaries (and any build-time
dependencies used in the build, such as compilers). dependencies used in the build, such as compilers).</para>
</para>
<para> <para>If we just want to push binaries, not sources and build-time
If we just want to push binaries, not sources and build-time dependencies, we can do:
dependencies, we can do:
<screen> <screen>
$ nix-push <replaceable>urls</replaceable> $(nix-instantiate $(nix-store -r foo.nix))</screen> $ nix-push <replaceable>urls</replaceable> $(nix-instantiate $(nix-store -r foo.nix))</screen>
</para> </para>
</refsection> </refsection>
</refentry> </refentry>

View file

@ -86,7 +86,7 @@
<!--######################################################################--> <!--######################################################################-->
<refsection> <refsection id='rsec-nix-store-realise'>
<title>Operation <option>--realise</option></title> <title>Operation <option>--realise</option></title>
<refsection> <refsection>