nixpkgs/doc/functions/fetchers.xml
Matthew Bauer d7b62cb601 nixpkgs/manual: address review comments
Mostly taken from requested changes exactly as recommended.
2019-01-27 11:57:36 -05:00

207 lines
6.4 KiB
XML

<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-pkgs-fetchers">
<title>Fetcher functions</title>
<para>
When using Nix, you will frequently need to download source code
and other files from the internet. Nixpkgs comes with a few helper
functions that allow you to fetch fixed-output derivations in a
structured way.
</para>
<para>
The two fetcher primitives are <function>fetchurl</function> and
<function>fetchzip</function>. Both of these have two required
arguments, a URL and a hash. The hash is typically
<literal>sha256</literal>, although many more hash algorithms are
supported. Nixpkgs contributors are currently recommended to use
<literal>sha256</literal>. This hash will be used by Nix to
identify your source. A typical usage of fetchurl is provided
below.
</para>
<programlisting><![CDATA[
{ stdenv, fetchurl }:
stdenv.mkDerivation {
name = "hello";
src = fetchurl {
url = "http://www.example.org/hello.tar.gz";
sha256 = "1111111111111111111111111111111111111111111111111111";
};
}
]]></programlisting>
<para>
The main difference between <function>fetchurl</function> and
<function>fetchzip</function> is in how they store the contents.
<function>fetchurl</function> will store the unaltered contents of
the URL within the Nix store. <function>fetchzip</function> on the
other hand will decompress the archive for you, making files and
directories directly accessible in the future.
<function>fetchzip</function> can only be used with archives.
Despite the name, <function>fetchzip</function> is not limited to
.zip files and can also be used with any tarball.
</para>
<para>
<function>fetchpatch</function> works very similarly to
<function>fetchurl</function> with the same arguments expected. It
expects patch files as a source and and performs normalization on
them before computing the checksum. For example it will remove
comments or other unstable parts that are sometimes added by
version control systems and can change over time.
</para>
<para>
Other fetcher functions allow you to add source code directly from
a VCS such as subversion or git. These are mostly straightforward
names based on the name of the command used with the VCS system.
Because they give you a working repository, they act most like
<function>fetchzip</function>.
</para>
<variablelist>
<varlistentry>
<term>
<literal>fetchsvn</literal>
</term>
<listitem>
<para>
Used with Subversion. Expects <literal>url</literal> to a
Subversion directory, <literal>rev</literal>, and
<literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchgit</literal>
</term>
<listitem>
<para>
Used with Git. Expects <literal>url</literal> to a Git repo,
<literal>rev</literal>, and <literal>sha256</literal>.
<literal>rev</literal> in this case can be full the git commit
id (SHA1 hash) or a tag name like
<literal>refs/tags/v1.0</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchfossil</literal>
</term>
<listitem>
<para>
Used with Fossil. Expects <literal>url</literal> to a Fossil
archive, <literal>rev</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchcvs</literal>
</term>
<listitem>
<para>
Used with CVS. Expects <literal>cvsRoot</literal>,
<literal>tag</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchhg</literal>
</term>
<listitem>
<para>
Used with Mercurial. Expects <literal>url</literal>,
<literal>rev</literal>, and <literal>sha256</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
A number of fetcher functions wrap part of
<function>fetchurl</function> and <function>fetchzip</function>.
They are mainly convenience functions intended for commonly used
destinations of source code in Nixpkgs. These wrapper fetchers are
listed below.
</para>
<variablelist>
<varlistentry>
<term>
<literal>fetchFromGitHub</literal>
</term>
<listitem>
<para>
<function>fetchFromGitHub</function> expects four arguments.
<literal>owner</literal> is a string corresponding to the
GitHub user or organization that controls this repository.
<literal>repo</literal> corresponds to the name of the
software repository. These are located at the top of every
GitHub HTML page as
<literal>owner</literal>/<literal>repo</literal>.
<literal>rev</literal> corresponds to the Git commit hash or
tag (e.g <literal>v1.0</literal>) that will be downloaded from
Git. Finally, <literal>sha256</literal> corresponds to the
hash of the extracted directory. Again, other hash algorithms
are also available but <literal>sha256</literal> is currently
preferred.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromGitLab</literal>
</term>
<listitem>
<para>
This is used with GitLab repositories. The arguments expected
are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromBitbucket</literal>
</term>
<listitem>
<para>
This is used with BitBucket repositories. The arguments expected
are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromSavannah</literal>
</term>
<listitem>
<para>
This is used with Savannah repositories. The arguments expected
are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>fetchFromRepoOrCz</literal>
</term>
<listitem>
<para>
This is used with repo.or.cz repositories. The arguments
expected are very similar to fetchFromGitHub above.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>