diff options
Diffstat (limited to 'doc/functions/fetchers.xml')
| -rw-r--r-- | doc/functions/fetchers.xml | 194 |
1 files changed, 0 insertions, 194 deletions
diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml deleted file mode 100644 index a736008c9d418..0000000000000 --- a/doc/functions/fetchers.xml +++ /dev/null @@ -1,194 +0,0 @@ -<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> |