diff options
author | Colin Arnott <colin@urandom.co.uk> | 2022-12-03 19:49:00 +0000 |
---|---|---|
committer | Colin Arnott <colin@urandom.co.uk> | 2022-12-04 06:12:18 +0000 |
commit | bac379f30a6fa1284e48b4224862e0b41ad42199 (patch) | |
tree | 0bad9b7cbe730a740ec027e19d34e1c237f058db /doc/builders/fetchers.chapter.md | |
parent | 88ae5d08250e206aad599c1bb9692bd9b3dd54c2 (diff) | |
download | nixpkgs-bac379f30a6fa1284e48b4224862e0b41ad42199.tar nixpkgs-bac379f30a6fa1284e48b4224862e0b41ad42199.tar.gz nixpkgs-bac379f30a6fa1284e48b4224862e0b41ad42199.tar.bz2 nixpkgs-bac379f30a6fa1284e48b4224862e0b41ad42199.tar.lz nixpkgs-bac379f30a6fa1284e48b4224862e0b41ad42199.tar.xz nixpkgs-bac379f30a6fa1284e48b4224862e0b41ad42199.tar.zst nixpkgs-bac379f30a6fa1284e48b4224862e0b41ad42199.zip |
doc: use sri hash syntax
The nixpkgs manual contains references to both sri hash and explicit sha256 attributes. This is at best confusing to new users. Since the final destination is exclusive use of sri hashes, see nixos/rfcs#131, might as well push new users in that direction gently. Notable exceptions to sri hash support are builtins.fetchTarball, cataclysm-dda, coq, dockerTools.pullimage, elixir.override, and fetchCrate. None, other than builtins.fetchTarball, are fundamentally incompatible, but all currently accept explicit sha256 attributes as input. Because adding backwards compatibility is out of scope for this change, they have been left intact, but migration to sri format has been made for any using old hash formats. All hashes have been manually tested to be accurate, and updates were only made for missing upstream artefacts or bugs.
Diffstat (limited to 'doc/builders/fetchers.chapter.md')
-rw-r--r-- | doc/builders/fetchers.chapter.md | 34 |
1 files changed, 17 insertions, 17 deletions
diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md index 43aead0ad5e..773eb3028dd 100644 --- a/doc/builders/fetchers.chapter.md +++ b/doc/builders/fetchers.chapter.md @@ -14,7 +14,7 @@ For example, consider the following fetcher: ```nix fetchurl { url = "http://www.example.org/hello-1.0.tar.gz"; - sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm"; + hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww="; }; ``` @@ -23,17 +23,17 @@ A common mistake is to update a fetcher’s URL, or a version parameter, without ```nix fetchurl { url = "http://www.example.org/hello-1.1.tar.gz"; - sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm"; + hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww="; }; ``` **This will reuse the old contents**. -Remember to invalidate the hash argument, in this case by setting the `sha256` attribute to an empty string. +Remember to invalidate the hash argument, in this case by setting the `hash` attribute to an empty string. ```nix fetchurl { url = "http://www.example.org/hello-1.1.tar.gz"; - sha256 = ""; + hash = ""; }; ``` @@ -42,14 +42,14 @@ Use the resulting error message to determine the correct hash. ``` error: hash mismatch in fixed-output derivation '/path/to/my.drv': specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= - got: sha256-RApQUm78dswhBLC/rfU9y0u6pSAzHceIJqgmetRD24E= + got: sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww= ``` A similar problem arises while testing changes to a fetcher's implementation. If the output of the derivation already exists in the Nix store, test failures can go undetected. The [`invalidateFetcherByDrvHash`](#tester-invalidateFetcherByDrvHash) function helps prevent reusing cached derivations. ## `fetchurl` and `fetchzip` {#fetchurl} -Two basic fetchers 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. +Two basic fetchers are `fetchurl` and `fetchzip`. Both of these have two required arguments, a URL and a hash. The hash is typically `hash`, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use `hash`. This hash will be used by Nix to identify your source. A typical usage of `fetchurl` is provided below. ```nix { stdenv, fetchurl }: @@ -58,7 +58,7 @@ stdenv.mkDerivation { name = "hello"; src = fetchurl { url = "http://www.example.org/hello.tar.gz"; - sha256 = "1111111111111111111111111111111111111111111111111111"; + hash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="; }; } ``` @@ -76,18 +76,18 @@ The main difference between `fetchurl` and `fetchzip` is in how they store the c - `includes`: Include only files matching these patterns (applies after the above arguments). - `revert`: Revert the patch. -Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `sha256` argument is changed as well. +Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `hash` argument is changed as well. Most other fetchers return a directory rather than a single file. ## `fetchsvn` {#fetchsvn} -Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `sha256`. +Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`. ## `fetchgit` {#fetchgit} -Used with Git. Expects `url` to a Git repo, `rev`, and `sha256`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`. +Used with Git. Expects `url` to a Git repo, `rev`, and `hash`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`. Additionally, the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout. @@ -104,32 +104,32 @@ stdenv.mkDerivation { "directory/to/be/included" "another/directory" ]; - sha256 = "0000000000000000000000000000000000000000000000000000"; + hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; }; } ``` ## `fetchfossil` {#fetchfossil} -Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `sha256`. +Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `hash`. ## `fetchcvs` {#fetchcvs} -Used with CVS. Expects `cvsRoot`, `tag`, and `sha256`. +Used with CVS. Expects `cvsRoot`, `tag`, and `hash`. ## `fetchhg` {#fetchhg} -Used with Mercurial. Expects `url`, `rev`, and `sha256`. +Used with Mercurial. Expects `url`, `rev`, and `hash`. 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. ## `fetchFromGitea` {#fetchfromgitea} -`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `sha256` is currently preferred. +`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `hash` is currently preferred. ## `fetchFromGitHub` {#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 (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `sha256` is currently preferred. +`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 (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred. `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options. @@ -156,7 +156,7 @@ This is used with repo.or.cz repositories. The arguments expected are very simil ## `fetchFromSourcehut` {#fetchfromsourcehut} This is used with sourcehut repositories. Similar to `fetchFromGitHub` above, -it expects `owner`, `repo`, `rev` and `sha256`, but don't forget the tilde (~) +it expects `owner`, `repo`, `rev` and `hash`, but don't forget the tilde (~) in front of the username! Expected arguments also include `vc` ("git" (default) or "hg"), `domain` and `fetchSubmodules`. |