diff options
Diffstat (limited to 'third_party/nix/doc/manual/command-ref/nix-prefetch-url.xml')
| -rw-r--r-- | third_party/nix/doc/manual/command-ref/nix-prefetch-url.xml | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/third_party/nix/doc/manual/command-ref/nix-prefetch-url.xml b/third_party/nix/doc/manual/command-ref/nix-prefetch-url.xml new file mode 100644 index 0000000000..621ded72ec --- /dev/null +++ b/third_party/nix/doc/manual/command-ref/nix-prefetch-url.xml @@ -0,0 +1,131 @@ +<refentry 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-nix-prefetch-url"> + +<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 hash</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>nix-prefetch-url</command> + <arg><option>--version</option></arg> + <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg> + <arg><option>--print-path</option></arg> + <arg><option>--unpack</option></arg> + <arg><option>--name</option> <replaceable>name</replaceable></arg> + <arg choice='plain'><replaceable>url</replaceable></arg> + <arg><replaceable>hash</replaceable></arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsection><title>Description</title> + +<para>The command <command>nix-prefetch-url</command> downloads the +file referenced by the URL <replaceable>url</replaceable>, prints its +cryptographic hash, and copies it into the Nix store. The file name +in the store is +<filename><replaceable>hash</replaceable>-<replaceable>baseName</replaceable></filename>, +where <replaceable>baseName</replaceable> is everything following the +final slash in <replaceable>url</replaceable>.</para> + +<para>This command is just a convenience for Nix expression writers. +Often a Nix expression fetches some source distribution from the +network using the <literal>fetchurl</literal> expression contained in +Nixpkgs. However, <literal>fetchurl</literal> requires a +cryptographic hash. If you don't know the hash, you would have to +download the file first, and then <literal>fetchurl</literal> would +download it again when you build your Nix expression. Since +<literal>fetchurl</literal> uses the same name for the downloaded file +as <command>nix-prefetch-url</command>, the redundant download can be +avoided.</para> + +<para>If <replaceable>hash</replaceable> is specified, then a download +is not performed if the Nix store already contains a file with the +same hash and base name. Otherwise, the file is downloaded, and an +error is signaled if the actual hash of the file does not match the +specified hash.</para> + +<para>This command prints the hash on standard output. Additionally, +if the option <option>--print-path</option> is used, the path of the +downloaded file in the Nix store is also printed.</para> + +</refsection> + + +<refsection><title>Options</title> + +<variablelist> + + <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term> + + <listitem><para>Use the specified cryptographic hash algorithm, + which can be one of <literal>md5</literal>, + <literal>sha1</literal>, and + <literal>sha256</literal>.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--print-path</option></term> + + <listitem><para>Print the store path of the downloaded file on + standard output.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--unpack</option></term> + + <listitem><para>Unpack the archive (which must be a tarball or zip + file) and add the result to the Nix store. The resulting hash can + be used with functions such as Nixpkgs’s + <varname>fetchzip</varname> or + <varname>fetchFromGitHub</varname>.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--name</option> <replaceable>name</replaceable></term> + + <listitem><para>Override the name of the file in the Nix store. By + default, this is + <literal><replaceable>hash</replaceable>-<replaceable>basename</replaceable></literal>, + where <replaceable>basename</replaceable> is the last component of + <replaceable>url</replaceable>. Overriding the name is necessary + when <replaceable>basename</replaceable> contains characters that + are not allowed in Nix store paths.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection><title>Examples</title> + +<screen> +$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz +0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i + +$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz +0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i +/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz + +$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz +079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7 +/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz +</screen> + +</refsection> + + +</refentry> |