From 17ec7f3a16a473e3ff3de6328c98cb36db6b112e Mon Sep 17 00:00:00 2001 From: Matthew Bauer Date: Sat, 26 Jan 2019 21:42:16 -0500 Subject: [PATCH] nixpkgs/manual: document fetcher functions Fixes #32439. --- doc/functions.xml | 1 + doc/functions/fetchers.xml | 198 +++++++++++++++++++++++++++++++++++++ 2 files changed, 199 insertions(+) create mode 100644 doc/functions/fetchers.xml diff --git a/doc/functions.xml b/doc/functions.xml index e6d59ebde978..0dc32bbc5bd5 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -11,6 +11,7 @@ + diff --git a/doc/functions/fetchers.xml b/doc/functions/fetchers.xml new file mode 100644 index 000000000000..96937ca7182e --- /dev/null +++ b/doc/functions/fetchers.xml @@ -0,0 +1,198 @@ +
+ Fetcher functions + + + 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. + + + + The two fetcher primitives are fetchurl and + fetchzip. Both of these have two required + arguments, a URL and a hash. The hash is typically + sha256, although many more hash algorithms are + supported. Nixpkgs contributors are currently recommended to use + sha256. This hash will be used by Nix to + identify your source. A typical usage of fetchurl is provided + below. + + + + + + The main difference between fetchurl and + fetchzip is in how they store the contents. + fetchurl will store the unaltered contents of + the URL within the Nix store. fetchzip on the + other hand will decompress the archive for you, making files and + directories directly accessible in the future. + fetchzip can only be used with archives. + Despite the name, fetchzip is not limited to + .zip files and can also be used with any tarball. + + + + fetchpatch works very similarly to + fetchurl with the same arguments expected. + + + + 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 + fetchzip. + + + + + + fetchsvn + + + + Used with Subversion. Expects url to a + Subversion directory, rev, and + sha256. + + + + + + fetchgit + + + + Used with Git. Expects url to a Git repo, + rev, and sha256. + + + + + + fetchfossil + + + + Used with Fossil. Expects url to a Fossil + archive, rev, and sha256. + + + + + + fetchcvs + + + + Used with CVS. Expects cvsRoot, + tag, and sha256. + + + + + + fetchhg + + + + Used with Mercurial. Expects url, + rev, and sha256. + + + + + + + A number of fetcher functions wrap part of + fetchurl and fetchzip. + They are mainly convenience functions intended for commonly used + destinations of source code in Nixpkgs. These wrapper fetchers are + listed below. + + + + + + fetchFromGitHub + + + + fetchFromGitHub expects four arguments. + owner is a string corresponding to the + GitHub user or organization that controls this repository. + repo corresponds to the name of the + software repository. These are located at the top of every + GitHub HTML page as + owner/repo. + rev corresponds to the Git commit hash or + tag that will be downloaded from Git. Finally, + sha256. Again, other hash algorithms are + also available but sha256 is currently + preferred. + + + + + + fetchFromGitLab + + + + This is used with GitLab repositories. The arguments expected + are very similar to fetchFromGitHub above. + + + + + + fetchFromBitbucket + + + + This is used with BitBucket repositories. The arguments expected + are very similar to fetchFromGitHub above. + + + + + + fetchFromSavannah + + + + This is used with Savannah repositories. The arguments expected + are very similar to fetchFromGitHub above. + + + + + + fetchFromRepoOrCz + + + + This is used with repo.or.cz repositories. The arguments + expected are very similar to fetchFromGitHub above. + + + + + + +