lix-releng-staging/doc/manual/nix-prefetch-url.xml

<refentry xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink">
  
<refnamediv>
  <refname>nix-prefetch-url</refname>
  <refpurpose>copy a file from a URL into the store and print its MD5 hash</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nix-prefetch-url</command>
    <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>The environment variable <envar>NIX_HASH_ALGO</envar> specifies
which hash algorithm to use.  It can be either <literal>md5</literal>,
<literal>sha1</literal>, or <literal>sha256</literal>.  The default is
<literal>md5</literal>.</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 environment variable <envar>PRINT_PATH</envar> is set, the path
of the downloaded file in the Nix store is also printed.</para>

</refsection>


<refsection><title>Examples</title>

<screen>
$ nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
0bbd1df101bc0294d440471e50feca71

$ PRINT_PATH=1 nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
0bbd1df101bc0294d440471e50feca71
/nix/store/wvyz8ifdn7wyz1p3pqyn0ra45ka2l492-make-3.80.tar.bz2</screen>

</refsection>

    
</refentry>