nixpkgs/doc/functions/fetchers.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 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>