diff --git a/doc/manual/command-ref/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml index c4cc04ce2..b777c6b6b 100644 --- a/doc/manual/command-ref/nix-channel.xml +++ b/doc/manual/command-ref/nix-channel.xml @@ -33,8 +33,8 @@ A Nix channel is mechanism that allows you to automatically stay up-to-date with a set of pre-built Nix expressions. A Nix channel is -just a URL that points to a place containing a set of Nix expressions -and a nix-push manifest. See also . @@ -99,13 +99,6 @@ an update. The list of subscribed channels is stored in ~/.nix-channels. -A channel consists of two elements: a bzipped Tar archive -containing the Nix expressions, and a manifest created by -nix-push. These must be stored under -url/nixexprs.tar.bz2 and -url/MANIFEST, -respectively. - Examples @@ -163,4 +156,49 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.nixpkgsVersion' +Channel format + +A channel URL should point to a directory containing the +following files: + + + + nixexprs.tar.xz + + A tarball containing Nix expressions and files + referenced by them (such as build scripts and patches). At + top-level, the tarball should contain a single directory. That + directory must contain a file default.nix + that serves as the channel’s “entry point”. + + + + binary-cache-url + + A file containing the URL to a binary cache (such + as https://cache.nixos.org. Nix will automatically + check this cache for pre-built binaries, if the user has + sufficient rights to add binary caches. For instance, in a + multi-user Nix setup, the binary caches provided by the channels + of the root user are used automatically, but caches corresponding + to the channels of non-root users are ignored. Binary caches can + be created and maintained using + nix-push. + + + + MANIFEST.bz2 + + (Deprecated in favour of binary caches.) A + manifest as created by nix-push. Only used if + binary-cache-url is not present or if the + nix.conf option + is set. + + + + + + + diff --git a/doc/manual/command-ref/nix-pull.xml b/doc/manual/command-ref/nix-pull.xml index 598c651b5..eb471677b 100644 --- a/doc/manual/command-ref/nix-pull.xml +++ b/doc/manual/command-ref/nix-pull.xml @@ -13,7 +13,7 @@ nix-pull - pull substitutes from a network cache + register availability of pre-built binaries (deprecated) @@ -26,6 +26,9 @@ Description +This command and the use of manifests is deprecated. It is +better to use binary caches. + The command nix-pull obtains a list of pre-built store paths from the URL url, and for each of these store paths, registers a substitute derivation that @@ -43,7 +46,7 @@ with the files created by nix-push. Examples -$ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST +$ nix-pull https://nixos.org/releases/nixpkgs/nixpkgs-15.05pre54468.69858d7/MANIFEST diff --git a/doc/manual/installation/multi-user.xml b/doc/manual/installation/multi-user.xml index 312f59664..69ae1ef27 100644 --- a/doc/manual/installation/multi-user.xml +++ b/doc/manual/installation/multi-user.xml @@ -23,11 +23,11 @@ daemon running under the owner of the Nix store/database that performs the operation. Multi-user mode has one important limitation: only -root can run nix-pull to register the availability -of pre-built binaries. However, those registrations are shared by all -users, so they still get the benefit from nix-pulls -done by root. +root and a set of trusted +users specified in nix.conf can specify arbitrary +binary caches. So while unprivileged users may install packages from +arbitrary Nix expressions, they may not get pre-built +binaries. diff --git a/doc/manual/packages/basic-package-mgmt.xml b/doc/manual/packages/basic-package-mgmt.xml index 69c955c1d..540d3ec22 100644 --- a/doc/manual/packages/basic-package-mgmt.xml +++ b/doc/manual/packages/basic-package-mgmt.xml @@ -28,40 +28,71 @@ Nix expressions called the Nix Package collection that contains packages ranging from basic development stuff such as GCC and Glibc, to end-user applications like Mozilla Firefox. (Nix is however not tied to the Nix Package collection; you could write your own Nix -expressions based on it, or completely new ones.) You can download -the latest version from . +expressions based on it, or completely new ones.) -Assuming that you have downloaded and unpacked a release of Nix -Packages, you can view the set of available packages in the release: +You can manually download the latest version of Nixpkgs from +. However, +it’s much more convenient to use the Nixpkgs +channel, since it makes it easy to stay up to +date with new versions of Nixpkgs. (Channels are described in more +detail in .) Nixpkgs is automatically +added to your list of “subscribed” channels when when you install +Nix. If this is not the case for some reason, you can add it as +follows: -$ nix-env -qaf nixpkgs-version '*' -ant-blackdown-1.4.2 +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable +$ nix-channel --update + + + + +On NixOS, you’re automatically subscribed to a NixOS +channel corresponding to your NixOS major release +(e.g. http://nixos.org/channels/nixos-14.12). A NixOS +channel is identical to the Nixpkgs channel, except that it contains +only Linux binaries and is updated only if a set of regression tests +succeed. + +You can view the set of available packages in Nixpkgs: + + +$ nix-env -qa aterm-2.2 bash-3.0 binutils-2.15 bison-1.875d blackdown-1.4.2 bzip2-1.0.2 -... +… -where nixpkgs-version is -where you’ve unpacked the release. The flag -specifies a query operation; means that you want -to show the “available” (i.e., installable) packages, as opposed to -the installed packages; and -nixpkgs-version -specifies the source of the packages. The argument -'*' shows all installable packages. (The quotes are -necessary to prevent shell expansion.) You can also select specific -packages by name: +The flag specifies a query operation, and + means that you want to show the “available” (i.e., +installable) packages, as opposed to the installed packages. If you +downloaded Nixpkgs yourself, or if you checked it out from GitHub, +then you need to pass the path to your Nixpkgs tree using the + flag: -$ nix-env -qaf nixpkgs-version gcc -gcc-3.4.6 -gcc-4.0.3 -gcc-4.1.1 +$ nix-env -qaf /path/to/nixpkgs + + +where /path/to/nixpkgs is where you’ve +unpacked or checked out Nixpkgs. + +You can select specific packages by name: + + +$ nix-env -qa firefox +firefox-34.0.5 +firefox-with-plugins-34.0.5 + + +and using regular expressions: + + +$ nix-env -qa 'firefox.*' + @@ -70,12 +101,12 @@ available packages, i.e., whether they are installed into the user environment and/or present in the system: -$ nix-env -qasf nixpkgs-version '*' -... +$ nix-env -qas +… -PS bash-3.0 --S binutils-2.15 IPS bison-1.875d -... +… The first character (I) indicates whether the package is installed in your current user environment. The second @@ -88,40 +119,33 @@ just means that Nix knows that it can fetch a pre-built package from somewhere (typically a network server) instead of building it locally. -So now that we have a set of Nix expressions we can build the -packages contained in them. This is done using nix-env --i. For instance, +You can install a package using nix-env -i. +For instance, -$ nix-env -f nixpkgs-version -i subversion +$ nix-env -i subversion will install the package called subversion (which is, of course, the Subversion version management system). -When you do this for the first time, Nix will start building -Subversion and all its dependencies. This will take quite a while — -typically an hour or two on modern machines. Fortunately, there is a -faster way (so do a Ctrl-C on that install operation!): you just need -to tell Nix that pre-built binaries of all those packages are -available somewhere. This is done using the -nix-pull command, which must be supplied with a URL -containing a manifest describing what binaries -are available. This URL should correspond to the Nix Packages release -that you’re using. For instance, if you obtained a release from , then you should do: - - -$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST - -If you then issue the installation command, it should start -downloading binaries from nixos.org, instead of building -them from source. This might still take a while since all -dependencies must be downloaded, but on a reasonably fast connection -such as a DSL line it’s on the order of a few minutes. +When you ask Nix to install a package, it will first try +to get it in pre-compiled form from a binary +cache. By default, Nix will use the binary cache +https://cache.nixos.org; it contains binaries for most +packages in Nixpkgs. Only if no binary is available in the binary +cache, Nix will build the package from source. So if nix-env +-i subversion results in Nix building stuff from source, +then either the package is not built for your platform by the Nixpkgs +build servers, or your version of Nixpkgs is too old or too new. For +instance, if you have a very recent checkout of Nixpkgs, then the +Nixpkgs build servers may not have had a chance to build everything +and upload the resulting binaries to +https://cache.nixos.org. The Nixpkgs channel is only +updated after all binaries have been uploaded to the cache, so if you +stick to the Nixpkgs channel (rather than using a Git checkout of the +Nixpkgs tree), you will get binaries for most packages. Naturally, packages can also be uninstalled: @@ -134,7 +158,7 @@ $ nix-env -e subversion release of Nix Packages, you can do: -$ nix-env -f nixpkgs-version -u subversion +$ nix-env -u subversion This will only upgrade Subversion if there is a “newer” version in the new set of Nix expressions, as @@ -149,17 +173,17 @@ whatever version is already installed. versions: -$ nix-env -f nixpkgs-version -u '*' +$ nix-env -u Sometimes it’s useful to be able to ask what nix-env would do, without actually doing it. For instance, to find out what packages would be upgraded by -nix-env -u '*', you can do +nix-env -u, you can do -$ nix-env ... -u '*' --dry-run +$ nix-env -u --dry-run (dry run; not doing anything) upgrading `libxslt-1.1.0' to `libxslt-1.1.10' upgrading `graphviz-1.10' to `graphviz-1.12' @@ -167,4 +191,4 @@ upgrading `coreutils-5.0' to `coreutils-5.2.1' - \ No newline at end of file + diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml index 094e11fe3..15c119fcb 100644 --- a/doc/manual/packages/channels.xml +++ b/doc/manual/packages/channels.xml @@ -8,10 +8,9 @@ If you want to stay up to date with a set of packages, it’s not very convenient to manually download the latest set of Nix expressions -for those packages, use nix-pull to register -pre-built binaries (if available), and upgrade using -nix-env. Fortunately, there’s a better way: -Nix channels. +for those packages and upgrade using nix-env. +Fortunately, there’s a better way: Nix +channels. A Nix channel is just a URL that points to a place that contains a set of Nix expressions and a manifest. Using the command nix-channel --add, e.g., -$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable subscribes you to a channel that always contains that latest version -of the Nix Packages collection. (Instead of -nixpkgs-unstable you could also subscribe to -nixpkgs-stable, which should have a higher level of -stability, but right now is just outdated.) Subscribing really just -means that the URL is added to the file -~/.nix-channels. Right now there is no command -to “unsubscribe”; you should just edit that file manually -and delete the offending URL. +of the Nix Packages collection. (Subscribing really just means that +the URL is added to the file ~/.nix-channels, +where it is read by subsequent calls to nix-channel +--update.) You can “unsubscribe” using nix-channel +--remove: + + +$ nix-channel --remove nixpkgs + + To obtain the latest Nix expressions available in a channel, do $ nix-channel --update -This downloads the Nix expressions in every channel (downloaded from -url/nixexprs.tar.bz2) -and registers any available pre-built binaries in every channel -(by nix-pulling -url/MANIFEST). It also -makes the union of each channel’s Nix expressions the default for -nix-env operations. Consequently, you can then say +This downloads and unpacks the Nix expressions in every channel +(downloaded from url/nixexprs.tar.bz2). +It also makes the union of each channel’s Nix expressions available by +default to nix-env operations (via the symlink +~/.nix-defexpr/channels). Consequently, you can +then say -$ nix-env -u '*' +$ nix-env -u to upgrade all packages in your profile to the latest versions available in the subscribed channels. - \ No newline at end of file + diff --git a/doc/manual/packages/garbage-collection.xml b/doc/manual/packages/garbage-collection.xml index ae28c485f..05a06d6f4 100644 --- a/doc/manual/packages/garbage-collection.xml +++ b/doc/manual/packages/garbage-collection.xml @@ -67,4 +67,4 @@ is a quick and easy way to clean up your system. - \ No newline at end of file + diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml index ad5e92aeb..932e58302 100644 --- a/doc/manual/packages/profiles.xml +++ b/doc/manual/packages/profiles.xml @@ -73,9 +73,9 @@ generated based on the current one. For instance, generation 43 was created from generation 42 when we did -$ nix-env -i subversion mozilla +$ nix-env -i subversion firefox -on a set of Nix expressions that contained Mozilla and a new version +on a set of Nix expressions that contained Firefox and a new version of Subversion. Generations are grouped together into @@ -156,4 +156,4 @@ $ nix-env -p /nix/var/nix/profiles/other-profile -i subversion This will not change the ~/.nix-profile symlink. - \ No newline at end of file +