diff options
Diffstat (limited to 'doc/manual/nix-push.xml')
| -rw-r--r-- | doc/manual/nix-push.xml | 214 |
1 files changed, 96 insertions, 118 deletions
diff --git a/doc/manual/nix-push.xml b/doc/manual/nix-push.xml index be704d74675c..c9c4b40c62ce 100644 --- a/doc/manual/nix-push.xml +++ b/doc/manual/nix-push.xml @@ -1,138 +1,116 @@ <refentry> - <refnamediv> - <refname>nix-push</refname> - <refpurpose>push store paths onto a network cache</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>nix-push</command> - <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 choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsection> - <title>Description</title> - - <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> - <command>nix-push</command> performs the following actions. + +<refnamediv> + <refname>nix-push</refname> + <refpurpose>push store paths onto a network cache</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <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> + + +<refsection><title>Description</title> + +<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> - - <listitem> - <para> - The store expressions stored in - <replaceable>paths</replaceable> are realised (using - <literal>nix-store --realise</literal>). - </para> - </listitem> - - <listitem> - <para> - All paths in the closure of the store expressions stored - in <replaceable>paths</replaceable> are determined (using - <literal>nix-store --query --requisites - --include-successors</literal>). It should be noted that - 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> - <para> - All store paths determined in the previous step are - packaged and compressed into a <command>bzip</command>ped - NAR archive (extension <filename>.nar.bz2</filename>). - </para> - </listitem> - - <listitem> - <para> - A <emphasis>manifest</emphasis> is created that contains - information on the store paths, their eventual URLs in the - cache, and cryptographic hashes of the contents of the NAR - archives. - </para> - </listitem> - - <listitem> - <para> - Each store path is uploaded to the remote directory - specified by <replaceable>archives-put-url</replaceable>. - HTTP PUT requests are used to do this. However, before a - file <varname>x</varname> is uploaded to - <literal><replaceable>archives-put-url</replaceable>/<varname>x</varname></literal>, - <command>nix-push</command> first determines whether this - upload is unnecessary by issuing a HTTP HEAD request on - <literal><replaceable>archives-get-url</replaceable>/<varname>x</varname></literal>. - This allows a cache to be shared between many partially - overlapping <command>nix-push</command> invocations. - (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> - <para> - The manifest is uploaded using an HTTP PUT request to - <replaceable>manifest-put-url</replaceable>. The - corresponding URL to download the manifest can then be - used by <command>nix-pull</command>. - </para> - </listitem> +<orderedlist> + + <listitem><para>Each path in <replaceable>paths</replaceable> is + realised (using <link + linkend='rsec-nix-store-realise'><literal>nix-store + --realise</literal></link>).</para></listitem> + + <listitem><para>All paths in the closure of the store expressions + stored in <replaceable>paths</replaceable> are determined (using + <literal>nix-store --query --requisites + --include-outputs</literal>). It should be noted that since the + <option>--include-outputs</option> flag is used, you get a combined + source/binary distribution.</para></listitem> + + <listitem><para>All store paths determined in the previous step are + packaged and compressed into a <command>bzip</command>ped NAR + archive (extension <filename>.nar.bz2</filename>).</para></listitem> + + <listitem><para>A <emphasis>manifest</emphasis> is created that + contains information on the store paths, their eventual URLs in the + cache, and cryptographic hashes of the contents of the NAR + archives.</para></listitem> + + <listitem><para>Each store path is uploaded to the remote directory + specified by <replaceable>archives-put-url</replaceable>. HTTP PUT + requests are used to do this. However, before a file + <varname>x</varname> is uploaded to + <literal><replaceable>archives-put-url</replaceable>/<varname>x</varname></literal>, + <command>nix-push</command> first determines whether this upload is + unnecessary by issuing a HTTP HEAD request on + <literal><replaceable>archives-get-url</replaceable>/<varname>x</varname></literal>. + This allows a cache to be shared between many partially overlapping + <command>nix-push</command> invocations. (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><para>The manifest is uploaded using an HTTP PUT request + to <replaceable>manifest-put-url</replaceable>. The corresponding + URL to download the manifest can then be used by + <command>nix-pull</command>.</para></listitem> - </orderedlist> - </para> +</orderedlist> + +</para> + +<para>TODO: <option>--copy</option></para> - </refsection> +</refsection> + - <refsection> - <title>Examples</title> +<refsection><title>Examples</title> - <para> - To upload files there typically is some CGI script on the server - side. This script should be be protected with a password. The - following example uploads the store paths resulting from - building the Nix expressions in <filename>foo.nix</filename>, - passing appropriate authentication information: +<para>To upload files there typically is some CGI script on the server +side. This script should be be protected with a password. The +following example uploads the store paths resulting from building the +Nix expressions in <filename>foo.nix</filename>, passing appropriate +authentication information: - <screen> +<screen> $ nix-push \ http://foo@bar:server.domain/cgi-bin/upload.pl/cache \ http://server.domain/cache \ http://foo@bar:server.domain/cgi-bin/upload.pl/MANIFEST \ $(nix-instantiate foo.nix)</screen> - This will push both sources and binaries (and any build-time - dependencies used in the build, such as compilers). - </para> +This will push both sources and binaries (and any build-time +dependencies used in the build, such as compilers).</para> - <para> - If we just want to push binaries, not sources and build-time - dependencies, we can do: +<para>If we just want to push binaries, not sources and build-time +dependencies, we can do: - <screen> +<screen> $ nix-push <replaceable>urls</replaceable> $(nix-instantiate $(nix-store -r foo.nix))</screen> - </para> +</para> - </refsection> +</refsection> </refentry> |