lix/doc/manual/command-ref/nix-prefetch-url.xml

132 lines
4.6 KiB
XML
Raw Normal View History

2007-02-05 12:10:10 +00:00
<refentry xmlns="http://docbook.org/ns/docbook"
2014-08-27 16:41:09 +00:00
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">
2007-09-19 14:01:41 +00:00
<refmeta>
<refentrytitle>nix-prefetch-url</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">Nix</refmiscinfo>
2014-09-16 12:57:45 +00:00
<refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
2007-09-19 14:01:41 +00:00
</refmeta>
2005-04-07 15:51:27 +00:00
<refnamediv>
<refname>nix-prefetch-url</refname>
2011-12-30 13:43:29 +00:00
<refpurpose>copy a file from a URL into the store and print its hash</refpurpose>
2005-04-07 15:51:27 +00:00
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-prefetch-url</command>
<arg><option>--version</option></arg>
<arg><option>--type</option> <emphasis>hashAlgo</emphasis></arg>
<arg><option>--print-path</option></arg>
<arg><option>--unpack</option></arg>
<arg><option>--name</option> <emphasis>name</emphasis></arg>
<arg choice='plain'><emphasis>url</emphasis></arg>
<arg><emphasis>hash</emphasis></arg>
2005-04-07 15:51:27 +00:00
</cmdsynopsis>
</refsynopsisdiv>
<refsection><title>Description</title>
<para>The command <command>nix-prefetch-url</command> downloads the
file referenced by the URL <emphasis>url</emphasis>, prints its
2005-04-07 15:51:27 +00:00
cryptographic hash, and copies it into the Nix store. The file name
in the store is
<filename><emphasis>hash</emphasis>-<emphasis>baseName</emphasis></filename>,
where <emphasis>baseName</emphasis> is everything following the
final slash in <emphasis>url</emphasis>.</para>
2005-04-07 15:51:27 +00:00
<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 <emphasis>hash</emphasis> is specified, then a download
2005-04-07 15:51:27 +00:00
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
2019-10-08 18:02:40 +00:00
error is signaled if the actual hash of the file does not match the
2005-04-07 15:51:27 +00:00
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>
2005-04-07 15:51:27 +00:00
</refsection>
<refsection><title>Options</title>
<variablelist>
<varlistentry><term><option>--type</option> <emphasis>hashAlgo</emphasis></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 Nixpkgss
<varname>fetchzip</varname> or
<varname>fetchFromGitHub</varname>.</para></listitem>
</varlistentry>
<varlistentry><term><option>--name</option> <emphasis>name</emphasis></term>
<listitem><para>Override the name of the file in the Nix store. By
default, this is
<literal><emphasis>hash</emphasis>-<emphasis>basename</emphasis></literal>,
where <emphasis>basename</emphasis> is the last component of
<emphasis>url</emphasis>. Overriding the name is necessary
when <emphasis>basename</emphasis> contains characters that
are not allowed in Nix store paths.</para></listitem>
</varlistentry>
</variablelist>
</refsection>
2005-04-07 15:51:27 +00:00
<refsection><title>Examples</title>
<screen>
$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
2005-04-07 15:51:27 +00:00
$ 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>
2005-04-07 15:51:27 +00:00
</refsection>
</refentry>