f08449ccbd
This allows overriding the name component of the resulting Nix store path, which is necessary if the base name of the URI contains "illegal" characters.
130 lines
4.5 KiB
XML
130 lines
4.5 KiB
XML
<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>--type</option> <replaceable>hashAlgo</replaceable></arg>
|
||
<arg><option>--print-path</option></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 if 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></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>
|