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