doc/build-helpers/images/binarycache.section.md

   1 # pkgs.mkBinaryCache {#sec-pkgs-binary-cache}
   2
   3 `pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches.
   4 Such a cache exists as a directory on disk, and can be used as a Nix substituter by passing `--substituter file:///path/to/cache` to Nix commands.
   5
   6 Nix packages are most commonly shared between machines using [HTTP, SSH, or S3](https://nixos.org/manual/nix/stable/package-management/sharing-packages.html), but a flat-file binary cache can still be useful in some situations.
   7 For example, you can copy it directly to another machine, or make it available on a network file system.
   8 It can also be a convenient way to make some Nix packages available inside a container via bind-mounting.
   9
  10 `mkBinaryCache` expects an argument with the `rootPaths` attribute.
  11 `rootPaths` must be a list of derivations.
  12 The transitive closure of these derivations' outputs will be copied into the cache.
  13
  14 ::: {.note}
  15 This function is meant for advanced use cases.
  16 The more idiomatic way to work with flat-file binary caches is via the [nix-copy-closure](https://nixos.org/manual/nix/stable/command-ref/nix-copy-closure.html) command.
  17 You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs.
  18 :::
  19
  20 []{#sec-pkgs-binary-cache-example}
  21 :::{.example #ex-mkbinarycache-copying-package-closure}
  22
  23 # Copying a package and its closure to another machine with `mkBinaryCache`
  24
  25 The following derivation will construct a flat-file binary cache containing the closure of `hello`.
  26
  27 ```nix
  28 { mkBinaryCache, hello }:
  29 mkBinaryCache {
  30   rootPaths = [hello];
  31 }
  32 ```
  33
  34 Build the cache on a machine.
  35 Note that the command still builds the exact nix package above, but adds some boilerplate to build it directly from an expression.
  36
  37 ```shellSession
  38 $ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.callPackage ({ mkBinaryCache, hello }: mkBinaryCache { rootPaths = [hello]; }) {}'
  39 /nix/store/azf7xay5xxdnia4h9fyjiv59wsjdxl0g-binary-cache
  40 ```
  41
  42 Copy the resulting directory to another machine, which we'll call `host2`:
  43
  44 ```shellSession
  45 $ scp result host2:/tmp/hello-cache
  46 ```
  47
  48 At this point, the cache can be used as a substituter when building derivations on `host2`:
  49
  50 ```shellSession
  51 $ nix-build -A hello '<nixpkgs>' \
  52   --option require-sigs false \
  53   --option trusted-substituters file:///tmp/hello-cache \
  54   --option substituters file:///tmp/hello-cache
  55 /nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1
  56 ```
  57
  58 :::