From 8901acc97664aa8ebf687ee904428aa57a5192be Mon Sep 17 00:00:00 2001 From: Mikey Ariel Date: Wed, 27 Aug 2014 18:41:09 +0200 Subject: Restructuring the Nix manual --- doc/manual/command-ref/nix-push.xml | 399 ++++++++++++++++++++++++++++++++++++ 1 file changed, 399 insertions(+) create mode 100644 doc/manual/command-ref/nix-push.xml (limited to 'doc/manual/command-ref/nix-push.xml') diff --git a/doc/manual/command-ref/nix-push.xml b/doc/manual/command-ref/nix-push.xml new file mode 100644 index 000000000000..9c6cdfa2f268 --- /dev/null +++ b/doc/manual/command-ref/nix-push.xml @@ -0,0 +1,399 @@ + + + + nix-push + 1 + Nix + + + + + nix-push + generate a binary cache + + + + + nix-push + dest-dir + + + + + + filename + url + paths + + + + +Description + +The command nix-push produces a +binary cache, a directory containing compressed +Nix archives (NARs) plus some metadata of the closure of the specified +store paths. This directory can then be made available through a web +server to other Nix installations, allowing them to skip building from +source and instead download binaries from the cache +automatically. + +nix-push performs the following actions. + + + + Each path in paths is + built (using nix-store + --realise). + + All paths in the closure of + paths are determined (using + nix-store --query --requisites + --include-outputs). Note that since the + flag is used, if + paths includes a store derivation, you + get a combined source/binary distribution (e.g., source tarballs + will be included). + + All store paths determined in the previous step are + packaged into a NAR (using nix-store --dump) and + compressed using xz or bzip2. + The resulting files have the extension .nar.xz + or .nar.bz2. Also for each store path, Nix + generates a file with extension .narinfo + containing metadata such as the references, cryptographic hash and + size of each path. + + Optionally, a single manifest + file is created that contains the same metadata as the + .narinfo files. This is for compatibility with + Nix versions prior to 1.2 (see nix-pull for + details). + + A file named is + placed in the destination directory. The existence of this file + marks the directory as a binary cache. + + + + + + + + +Options + + + + dest-dir + + Set the destination directory to + dir, which is created if it does not + exist. This flag is required. + + + + + + Compress NARs using bzip2 + instead of xz -9. The latter compresses about + 30% better on typical archives, decompresses about twice as fast, + but compresses a lot slower and is not supported by Nix prior to + version 1.2. + + + + + + Do not compress NARs. + + + + + + Overwrite .narinfo files if + they already exist. + + + + + + By default, NARs are generated in the Nix store + and then copied to dest-dir. If this + option is given, hard links are used instead. This only works if + dest-dir is on the same filesystem as + the Nix store. + + + + + + Force the generation of a manifest suitable for + use by nix-pull. The manifest is stored as + dest-dir/MANIFEST. + + + + filename + + Like , but store the + manifest in filename. + + + + url + + Manifests are expected to contain the absolute + URLs of NARs. For generating these URLs, the prefix + url is used. It defaults to + file://dest-dir. + + + + + + + + +Examples + +To add the closure of Thunderbird to a binary cache: + + +$ nix-push --dest /tmp/cache $(nix-build -A thunderbird) + + +Assuming that /tmp/cache is exported by a web +server as http://example.org/cache, you can then use this +cache on another machine to speed up the installation of Thunderbird: + + +$ nix-build -A thunderbird --option binary-caches http://example.org/cache + + +Alternatively, you could add binary-caches = +http://example.org/cache to +nix.conf. + +To also include build-time dependencies (such as source +tarballs): + + +$ nix-push --dest /tmp/cache $(nix-instantiate -A thunderbird) + + + + +To generate a manifest suitable for nix-pull: + + +$ nix-push --dest /tmp/cache $(nix-build -A thunderbird) --manifest + + +On another machine you can then do: + + +$ nix-pull http://example.org/cache + + +to cause the binaries to be used by subsequent Nix operations. + + + + +Binary cache format and operation + +A binary cache with URL url only +denotes a valid binary cache if the file +url/nix-cache-info exists. If +this file does not exist (or cannot be downloaded), the cache is +ignored. If it does exist, it must be a text file containing cache +properties. Here’s an example: + + +StoreDir: /nix/store +WantMassQuery: 1 +Priority: 10 + + +The properties that are currently supported are: + + + + StoreDir + + The path of the Nix store to which this binary + cache applies. Binaries are not relocatable — a binary built for + /nix/store won’t generally work in + /home/alice/store — so to prevent binaries + from being used in a wrong store, a binary cache is only used if + its StoreDir matches the local Nix + configuration. The default is + /nix/store. + + + + WantMassQuery + + Query operations such as nix-env + -qas can cause thousands of cache queries, and thus + thousands of HTTP requests, to determine which packages are + available in binary form. While these requests are small, not + every server may appreciate a potential onslaught of queries. If + WantMassQuery is set to 0 + (default), “mass queries” such as nix-env -qas + will skip this cache. Thus a package may appear not to have a + binary substitute. However, the binary will still be used when + you actually install the package. If + WantMassQuery is set to 1, + mass queries will use this cache. + + + + Priority + + Each binary cache has a priority (defaulting to + 50). Binary caches are checked for binaries in order of ascending + priority; thus a higher number denotes a lower priority. The + binary cache http://cache.nixos.org has priority + 40. + + + + + + + +Every time Nix needs to build some store path +p, it will check each configured binary +cache to see if it has a NAR file for p, +until it finds one. If no cache has a NAR, Nix will fall back to +building the path from source (if applicable). To see if a cache with +URL url has a binary for +p, Nix fetches +url/h, where h +is the hash part of p. Thus, if we have a +cache http://cache.nixos.org and we want to obtain +the store path + +/nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7 + +then Nix will attempt to fetch + +http://cache.nixos.org/a8922c0h87iilxzzvwn2hmv8x210aqb9.narinfo + +(Commands such as nix-env -qas will issue an HTTP +HEAD request, since it only needs to know if the +.narinfo file exists.) The +.narinfo file is a simple text file that looks +like this: + + +StorePath: /nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7 +URL: nar/0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70.nar.bz2 +Compression: bzip2 +FileHash: sha256:0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70 +FileSize: 24473768 +NarHash: sha256:0s491y1h9hxj5ghiizlxk7ax6jwbha00zwn7lpyd5xg5bhf60vzg +NarSize: 109521136 +References: 2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16 ... +Deriver: 7akyyc87ka32xwmqza9dvyg5pwx3j212-glibc-2.7.drv + + +The fields are as follows: + + + + StorePath + + The full store path, including the name part + (e.g., glibc-2.7). It must match the + requested store path. + + + + URL + + The URL of the NAR, relative to the binary cache + URL. + + + + Compression + + The compression method; either + xz or + bzip2. + + + + FileHash + + The SHA-256 hash of the compressed + NAR. + + + + FileSize + + The size of the compressed NAR. + + + + NarHash + + The SHA-256 hash of the uncompressed NAR. This is + equal to the hash of the store path as returned by + nix-store -q --hash + p. + + + + NarSize + + The size of the uncompressed NAR. + + + + References + + The references of the store path, without the Nix + store prefix. + + + + Deriver + + The deriver of the store path, without the Nix + store prefix. This field is optional. + + + + System + + The Nix platform type of this binary, if known. + This field is optional. + + + + + + + +Thus, in our example, after recursively ensuring that the +references exist (e.g., +/nix/store/2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16), +Nix will fetch +http://cache.nixos.org/nar/0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70.nar.bz2 + and decompress and unpack it to +/nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7. + + + + + -- cgit 1.4.1