diff options
Diffstat (limited to 'doc/functions/fetchers.xml')
| -rw-r--r-- | doc/functions/fetchers.xml | 318 |
1 files changed, 153 insertions, 165 deletions
diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml index b3bd2fe0f45e2..a736008c9d418 100644 --- a/doc/functions/fetchers.xml +++ b/doc/functions/fetchers.xml @@ -5,24 +5,21 @@ <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. + 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. + 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[ +<programlisting><![CDATA[ { stdenv, fetchurl }: stdenv.mkDerivation { @@ -35,172 +32,163 @@ stdenv.mkDerivation { ]]></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. + 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. + <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>. + 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> + <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. + 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> + <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> |