From a5be5e01200a12cc34d0e3a2e3f964d5c95208b9 Mon Sep 17 00:00:00 2001 From: Adam Joseph Date: Thu, 4 Aug 2022 14:07:06 -0700 Subject: [PATCH] doc/manual: define {local,remote} store, binary cache, substituter Nix veterans intuitively know what the following terms mean. They are used in several places in the nix documentation, but never defined: - local store - remote store - binary cache - substituter In particular, I found the last two terms to be confusingly similar. Let's give definitions for them. --- doc/manual/src/SUMMARY.md.in | 1 + .../src/package-management/terminology.md | 27 +++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 doc/manual/src/package-management/terminology.md diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index a47d39f31..f8da2247b 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -22,6 +22,7 @@ - [Garbage Collector Roots](package-management/garbage-collector-roots.md) - [Channels](package-management/channels.md) - [Sharing Packages Between Machines](package-management/sharing-packages.md) + - [Terminology](package-management/terminology.md) - [Serving a Nix store via HTTP](package-management/binary-cache-substituter.md) - [Copying Closures via SSH](package-management/copy-closure.md) - [Serving a Nix store via SSH](package-management/ssh-substituter.md) diff --git a/doc/manual/src/package-management/terminology.md b/doc/manual/src/package-management/terminology.md new file mode 100644 index 000000000..28e2a1f0b --- /dev/null +++ b/doc/manual/src/package-management/terminology.md @@ -0,0 +1,27 @@ +# Terminology + +A *local store* exists on the local filesystem of the machine where +Nix is invoked. The `/nix/store` directory is one example of a +local store. You can use other local stores by passing the +`--store` flag to `nix`. + +A *remote store* is a store which exists anywhere other than the +local filesystem. One example is the `/nix/store` directory on +another machine, accessed via `ssh` or served by the `nix-serve` +Perl script. + +A *binary cache* is a remote store which is not the local store of +any machine. Examples of binary caches include S3 buckets and the +[NixOS binary cache](https://cache.nixos.org). Binary caches use a +disk layout that is different from local stores; in particular, they +keep metadata and signatures in `.narinfo` files rather than in +`/nix/var/nix/db`. + +A *substituter* is a store other than `/nix/store` from which nix will +copy the realisation of a derivation instead of building it. Nix will +not copy a realisation from a remote store unless one of the following +is true: + +- the realisation is signed by one of the `trusted-public-key`s +- the substituter is in the `trusted-substituters` list +- the `no-require-sigs` option has been set to disable signature checking