diff options
Diffstat (limited to 'doc/functions/fetchers.xml')
-rw-r--r-- | doc/functions/fetchers.xml | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml new file mode 100644 index 00000000000..96937ca7182 --- /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> |