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

132 lines
4.7 KiB
XML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<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 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 Nixpkgss
<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>