* More doc updates.

This commit is contained in:
Eelco Dolstra 2005-04-07 15:51:27 +00:00
parent 7d876f8fa7
commit b9d8ecbc6a
2 changed files with 81 additions and 46 deletions

View file

@ -1,54 +1,69 @@
<refentry>
<refnamediv>
<refnamediv>
<refname>nix-prefetch-url</refname>
<refpurpose>copy a file from a URL into the store and print its MD5 hash</refpurpose>
</refnamediv>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-prefetch-url</command>
<arg choice='plain'><replaceable>url</replaceable></arg>
<arg><replaceable>hash</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
</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>
<refsection><title>Description</title>
<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>
<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>
</refsection>
<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>
<refsection>
<title>Examples</title>
<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>
<screen>
<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>

View file

@ -189,7 +189,7 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
<cmdsynopsis>
<command>nix-store</command>
<arg choice='plain'><option>--gc</option></arg>
<group choice='req'>
<group>
<arg choice='plain'><option>--print-roots</option></arg>
<arg choice='plain'><option>--print-live</option></arg>
<arg choice='plain'><option>--print-dead</option></arg>
@ -451,7 +451,7 @@ most one query can be specified. The default query is
<cmdsynopsis>
<command>nix-store</command>
<arg choice='req'><option>--register-validity</option></arg>
<arg choice='plain'><option>--register-validity</option></arg>
</cmdsynopsis>
</refsection>
@ -473,7 +473,7 @@ most one query can be specified. The default query is
<cmdsynopsis>
<command>nix-store</command>
<arg choice='req'><option>--substitute</option></arg>
<arg choice='plain'><option>--substitute</option></arg>
<arg choice='plain'
rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg>
</cmdsynopsis>
@ -501,7 +501,8 @@ deployment.</para>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix-store</command>
<arg choice='req'><option>--verify</option></arg>
<arg choice='plain'><option>--verify</option></arg>
<arg><option>--check-contents</option></arg>
</cmdsynopsis>
</refsection>
@ -514,6 +515,25 @@ automatically repaired. Inconsistencies are generally the result of
the Nix store or database being modified by non-Nix tools, or of bugs
in Nix itself.</para>
<para>There is one option:
<variablelist>
<varlistentry><term><option>--check-contents</option></term>
<listitem><para>Checks that the contents of every valid store path
has not been altered by computing a SHA-256 hash of the contents
and comparing it with the hash stored in the Nix database at build
time. Paths that have been modified are printed out. For large
stores, <option>--check-contents</option> is obviously quite
slow.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsection>
</refsection>