alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases Activity

nixpkgs/manual: document fetcher functions

Browse source 
Fixes #32439.
This commit is contained in:
Matthew Bauer 2019-01-26 21:42:16 -05:00
parent 6604240a4b
commit 17ec7f3a16
2 changed files with 199 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/functions.xml
View file

@ -11,6 +11,7 @@
<xi:include href="functions/overrides.xml" />
<xi:include href="functions/generators.xml" />
<xi:include href="functions/debug.xml" />
<xi:include href="functions/fetchers.xml" />
<xi:include href="functions/fhs-environments.xml" />
<xi:include href="functions/shell.xml" />
<xi:include href="functions/dockertools.xml" />

198
doc/functions/fetchers.xml Normal file
View file

@ -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>