mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-27 01:13:05 +00:00
Matthew Bauer
parent
6604240a4b
commit
17ec7f3a16
@ -11,6 +11,7 @@
|
|||||||
<xi:include href="functions/overrides.xml" />
|
<xi:include href="functions/overrides.xml" />
|
||||||
<xi:include href="functions/generators.xml" />
|
<xi:include href="functions/generators.xml" />
|
||||||
<xi:include href="functions/debug.xml" />
|
<xi:include href="functions/debug.xml" />
|
||||||
|
<xi:include href="functions/fetchers.xml" />
|
||||||
<xi:include href="functions/fhs-environments.xml" />
|
<xi:include href="functions/fhs-environments.xml" />
|
||||||
<xi:include href="functions/shell.xml" />
|
<xi:include href="functions/shell.xml" />
|
||||||
<xi:include href="functions/dockertools.xml" />
|
<xi:include href="functions/dockertools.xml" />
|
||||||
|
|||||||
198
doc/functions/fetchers.xml
Normal file
198
doc/functions/fetchers.xml
Normal 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>
|
||||||
Loading…
Reference in New Issue
Block a user