diff options
author | Alyssa Ross <hi@alyssa.is> | 2023-11-05 16:15:01 +0100 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2023-11-05 16:15:01 +0100 |
commit | a2c1eff83c3118a9aee8076c7f84f58137416b6e (patch) | |
tree | 4668c9ad2bba229a0eb3ccc8adbe78402e04ab07 /nixpkgs/doc | |
parent | fa7e5142244bb8fd1c51b66df6e623a7f41cc0d3 (diff) | |
parent | 85f1ba3e51676fa8cc604a3d863d729026a6b8eb (diff) | |
download | nixlib-a2c1eff83c3118a9aee8076c7f84f58137416b6e.tar nixlib-a2c1eff83c3118a9aee8076c7f84f58137416b6e.tar.gz nixlib-a2c1eff83c3118a9aee8076c7f84f58137416b6e.tar.bz2 nixlib-a2c1eff83c3118a9aee8076c7f84f58137416b6e.tar.lz nixlib-a2c1eff83c3118a9aee8076c7f84f58137416b6e.tar.xz nixlib-a2c1eff83c3118a9aee8076c7f84f58137416b6e.tar.zst nixlib-a2c1eff83c3118a9aee8076c7f84f58137416b6e.zip |
Merge branch 'nixos-unstable' of https://github.com/NixOS/nixpkgs into HEAD
Diffstat (limited to 'nixpkgs/doc')
-rw-r--r-- | nixpkgs/doc/builders/fetchers.chapter.md | 23 |
1 files changed, 19 insertions, 4 deletions
diff --git a/nixpkgs/doc/builders/fetchers.chapter.md b/nixpkgs/doc/builders/fetchers.chapter.md index c99b46097e9f..7bd1bbd6de02 100644 --- a/nixpkgs/doc/builders/fetchers.chapter.md +++ b/nixpkgs/doc/builders/fetchers.chapter.md @@ -1,12 +1,27 @@ # Fetchers {#chap-pkgs-fetchers} Building software with Nix often requires downloading source code and other files from the internet. -`nixpkgs` provides *fetchers* for different protocols and services. Fetchers are functions that simplify downloading files. +To this end, Nixpkgs provides *fetchers*: functions to obtain remote sources via various protocols and services. -## Caveats {#chap-pkgs-fetchers-caveats} +Nixpkgs fetchers differ from built-in fetchers such as [`builtins.fetchTarball`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-fetchTarball): +- A built-in fetcher will download and cache files at evaluation time and produce a [store path](https://nixos.org/manual/nix/stable/glossary#gloss-store-path). + A Nixpkgs fetcher will create a ([fixed-output](https://nixos.org/manual/nix/stable/glossary#gloss-fixed-output-derivation)) [derivation](https://nixos.org/manual/nix/stable/language/derivations), and files are downloaded at build time. +- Built-in fetchers will invalidate their cache after [`tarball-ttl`](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-tarball-ttl) expires, and will require network activity to check if the cache entry is up to date. + Nixpkgs fetchers only re-download if the specified hash changes or the store object is not otherwise available. +- Built-in fetchers do not use [substituters](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters). + Derivations produced by Nixpkgs fetchers will use any configured binary cache transparently. + +This significantly reduces the time needed to evaluate the entirety of Nixpkgs, and allows [Hydra](https://nixos.org/hydra) to retain and re-distribute sources used by Nixpkgs in the [public binary cache](https://cache.nixos.org). +For these reasons, built-in fetchers are not allowed in Nixpkgs source code. + +The following table shows an overview of the differences: -Fetchers create [fixed output derivations](https://nixos.org/manual/nix/stable/#fixed-output-drvs) from downloaded files. -Nix can reuse the downloaded files via the hash of the resulting derivation. +| Fetchers | Download | Output | Cache | Re-download when | +|-|-|-|-|-| +| `builtins.fetch*` | evaluation time | store path | `/nix/store`, `~/.cache/nix` | `tarball-ttl` expires, cache miss in `~/.cache/nix`, output store object not in local store | +| `pkgs.fetch*` | build time | derivation | `/nix/store`, substituters | output store object not available | + +## Caveats {#chap-pkgs-fetchers-caveats} The fact that the hash belongs to the Nix derivation output and not the file itself can lead to confusion. For example, consider the following fetcher: |