diff options
author | github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> | 2024-01-01 00:14:29 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-01-01 00:14:29 +0000 |
commit | 9504795b14aa3056d1ae10c5126e71a6a3030959 (patch) | |
tree | cba2530702b53f7e3effbebd154406108bc97ff1 /doc | |
parent | 50d354db00061ebfc6992b6040e81e7bfbedd473 (diff) | |
parent | a9236d91a1d689ea1d41ade54d5fb5b5b08c38aa (diff) | |
download | nixlib-9504795b14aa3056d1ae10c5126e71a6a3030959.tar nixlib-9504795b14aa3056d1ae10c5126e71a6a3030959.tar.gz nixlib-9504795b14aa3056d1ae10c5126e71a6a3030959.tar.bz2 nixlib-9504795b14aa3056d1ae10c5126e71a6a3030959.tar.lz nixlib-9504795b14aa3056d1ae10c5126e71a6a3030959.tar.xz nixlib-9504795b14aa3056d1ae10c5126e71a6a3030959.tar.zst nixlib-9504795b14aa3056d1ae10c5126e71a6a3030959.zip |
Merge master into haskell-updates
Diffstat (limited to 'doc')
-rw-r--r-- | doc/build-helpers/images/binarycache.section.md | 51 |
1 files changed, 30 insertions, 21 deletions
diff --git a/doc/build-helpers/images/binarycache.section.md b/doc/build-helpers/images/binarycache.section.md index 62e47dad7c66..9946603c958e 100644 --- a/doc/build-helpers/images/binarycache.section.md +++ b/doc/build-helpers/images/binarycache.section.md @@ -1,49 +1,58 @@ # pkgs.mkBinaryCache {#sec-pkgs-binary-cache} -`pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches. 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. +`pkgs.mkBinaryCache` is a function for creating Nix flat-file binary caches. +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. -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. For example, you can copy it directly to another machine, or make it available on a network file system. It can also be a convenient way to make some Nix packages available inside a container via bind-mounting. +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. +For example, you can copy it directly to another machine, or make it available on a network file system. +It can also be a convenient way to make some Nix packages available inside a container via bind-mounting. -Note that this function is meant for advanced use-cases. 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. You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs. +`mkBinaryCache` expects an argument with the `rootPaths` attribute. +`rootPaths` must be a list of derivations. +The transitive closure of these derivations' outputs will be copied into the cache. -## Example {#sec-pkgs-binary-cache-example} +::: {.note} +This function is meant for advanced use cases. +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. +You may also want to consider [dockerTools](#sec-pkgs-dockerTools) for your containerization needs. +::: + +[]{#sec-pkgs-binary-cache-example} +:::{.example #ex-mkbinarycache-copying-package-closure} + +# Copying a package and its closure to another machine with `mkBinaryCache` The following derivation will construct a flat-file binary cache containing the closure of `hello`. ```nix +{ mkBinaryCache, hello }: mkBinaryCache { rootPaths = [hello]; } ``` -- `rootPaths` specifies a list of root derivations. The transitive closure of these derivations' outputs will be copied into the cache. - -Here's an example of building and using the cache. - -Build the cache on one machine, `host1`: - -```shellSession -nix-build -E 'with import <nixpkgs> {}; mkBinaryCache { rootPaths = [hello]; }' -``` +Build the cache on a machine. +Note that the command still builds the exact nix package above, but adds some boilerplate to build it directly from an expression. ```shellSession -/nix/store/cc0562q828rnjqjyfj23d5q162gb424g-binary-cache +$ nix-build -E 'let pkgs = import <nixpkgs> {}; in pkgs.callPackage ({ mkBinaryCache, hello }: mkBinaryCache { rootPaths = [hello]; }) {}' +/nix/store/azf7xay5xxdnia4h9fyjiv59wsjdxl0g-binary-cache ``` -Copy the resulting directory to the other machine, `host2`: +Copy the resulting directory to another machine, which we'll call `host2`: ```shellSession -scp result host2:/tmp/hello-cache +$ scp result host2:/tmp/hello-cache ``` -Substitute the derivation using the flat-file binary cache on the other machine, `host2`: +At this point, the cache can be used as a substituter when building derivations on `host2`: + ```shellSession -nix-build -A hello '<nixpkgs>' \ +$ nix-build -A hello '<nixpkgs>' \ --option require-sigs false \ --option trusted-substituters file:///tmp/hello-cache \ --option substituters file:///tmp/hello-cache +/nix/store/zhl06z4lrfrkw5rp0hnjjfrgsclzvxpm-hello-2.12.1 ``` -```shellSession -/nix/store/gl5a41azbpsadfkfmbilh9yk40dh5dl0-hello-2.12.1 -``` +::: |