diff options
Diffstat (limited to 'doc/manual/nix-prefetch-url.xml')
| -rw-r--r-- | doc/manual/nix-prefetch-url.xml | 113 |
1 files changed, 64 insertions, 49 deletions
diff --git a/doc/manual/nix-prefetch-url.xml b/doc/manual/nix-prefetch-url.xml index a6b3711e3373..a0d5a97f1f18 100644 --- a/doc/manual/nix-prefetch-url.xml +++ b/doc/manual/nix-prefetch-url.xml @@ -1,54 +1,69 @@ <refentry> - <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> - </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 MD5 cryptographic hash code, 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 to Nix expression writers. - Often a Nix expressions fetch some source distribution from the - network using the <literal>fetchurl</literal> expression - contained in <literal>nixpkgs</literal>. However, - <literal>fetchurl</literal> requires an MD5 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> - - </refsection> - - <refsection> - <title>Examples</title> - - <screen> + +<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 -... -file has hash 0bbd1df101bc0294d440471e50feca71 -...</screen> +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> - </refsection> </refentry> |