nixpkgs/manual: document fetcher functions

Fixes #32439.

2 files changed, 199 insertions, 0 deletions

diff --git a/doc/functions.xml b/doc/functions.xml
index e6d59ebde978..0dc32bbc5bd5 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -11,6 +11,7 @@
  <xi:include href="functions/overrides.xml" />
  <xi:include href="functions/generators.xml" />
  <xi:include href="functions/debug.xml" />
+ <xi:include href="functions/fetchers.xml" />
  <xi:include href="functions/fhs-environments.xml" />
  <xi:include href="functions/shell.xml" />
  <xi:include href="functions/dockertools.xml" />
diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml
new file mode 100644
index 000000000000..96937ca7182e
--- /dev/null
+++ b/doc/functions/fetchers.xml
@@ -0,0 +1,198 @@
+<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 file from the internet. Nixpkgs comes with a few helper
+   functions that allow you to fetch fixed-output derivations in
+   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.
+ </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>.
+      </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 that will be downloaded from Git. Finally,
+        <literal>sha256</literal>. 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>