diff --git a/doc/manual/figures/user-environments.png b/doc/manual/figures/user-environments.png index f8f1b0185..2c2c052e5 100644 Binary files a/doc/manual/figures/user-environments.png and b/doc/manual/figures/user-environments.png differ diff --git a/doc/manual/figures/user-environments.sxd b/doc/manual/figures/user-environments.sxd new file mode 100644 index 000000000..bc661b640 Binary files /dev/null and b/doc/manual/figures/user-environments.sxd differ diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index 05173590f..3e2c62f5b 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -5,8 +5,8 @@ The easiest way to obtain Nix is to download a source -distribution. RPMs for Red Hat 9 are also available. These -distributions are generated automatically. +distribution. RPMs for Red Hat, SuSE, and Fedore Core are +also available. Alternatively, the most recent sources of Nix can be obtained from its This chapter discusses how to do package management with Nix, i.e., how to obtain, install, upgrade, and erase components. This is -the user's perspective of the Nix system — people +the user’s perspective of the Nix system — people who want to create components should consult . @@ -19,7 +19,7 @@ on the set of installed applications. That is, there might be lots of applications present on the system (possibly in many different versions), but users can have a specific selection of those active — where active just means that it appears in a directory -in the user's PATH. Such a view on the set of +in the user’s PATH. Such a view on the set of installed applications is called a user environment, which is just a directory tree consisting of symlinks to the files of the active applications. @@ -52,7 +52,7 @@ bzip2-1.0.2 ... where nixpkgs-version is -where you've unpacked the release. +where you’ve unpacked the release. It is also possible to see the status of available components, i.e., whether they are installed into the user @@ -72,7 +72,7 @@ component is installed in your current user environment. The second (in which case installing it into your user environment would be a very quick operation). The last one (S) indicates whether there is a so-called substitute for the -component, which is Nix's mechanism for doing binary deployment. It +component, which is Nix’s mechanism for doing binary deployment. It just means that Nix know that it can fetch a pre-built component from somewhere (typically a network server) instead of building it locally. @@ -98,7 +98,7 @@ 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 +that you’re using. For instance, if you obtained a release from , then you should do: @@ -111,7 +111,7 @@ downloading binaries from catamaran.labs.cs.uu.nl, 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 an DSL line it's on the order of a few minutes. +such as an DSL line it’s on the order of a few minutes. Naturally, packages can also be uninstalled: @@ -129,7 +129,7 @@ $ nix-env -f nixpkgs-version -u subversion This will only upgrade Subversion if there is a newer version in the new set of Nix expressions, as defined by some pretty arbitrary rules regarding ordering of version -numbers (which generally do what you'd expect of them). To just +numbers (which generally do what you’d expect of them). To just unconditionally replace Subversion with whatever version is in the Nix expressions, use -i instead of -u; -i will remove @@ -143,7 +143,7 @@ $ nix-env -f nixpkgs-version -u '*' -Sometimes it's useful to be able to ask what +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 @@ -177,28 +177,26 @@ set. Profiles -Profiles and user environments are Nix's mechanism for +Profiles and user environments are Nix’s mechanism for implementing the ability to allow differens users to have different configurations, and to do atomic upgrades and rollbacks. To -understand how they work, it's useful to know a bit about how Nix +understand how they work, it’s useful to know a bit about how Nix works. In Nix, components are stored in unique locations in the Nix store (typically, /nix/store). For instance, a particular version of the Subversion component might be stored in a directory -/nix/store/eeeeaf42e56b...-subversion-0.32.1/, +/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/, while another version might be stored in -/nix/store/58823d558a6a...-subversion-0.34/. The -long hexadecimal numbers prefixed to the directory names are -cryptographic hashes160-bit truncations of SHA-256 -hashes, to be precise. of all -inputs involved in building the component — sources, dependencies, -compiler flags, and so on. So if two components differ in any way, -they end up in different locations in the file system, so they don't -interfere with each other. TODO: the figure isn't entirely up to date. It -should show multiple profiles and -~/.nix-profile. shows a part of -a typical Nix store. +/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2. +The long strings prefixed to the directory names are cryptographic +hashes160-bit truncations of SHA-256 hashes encoded in +a base-32 notation, to be precise. of +all inputs involved in building the component — +sources, dependencies, compiler flags, and so on. So if two +components differ in any way, they end up in different locations in +the file system, so they don’t interfere with each other. shows a part of a typical Nix +store.
User environments @@ -208,41 +206,42 @@ a typical Nix store.
-Of course, you wouldn't want to type +Of course, you wouldn’t want to type -$ /nix/store/eeeeaf42e56b...-subversion-0.32.1/bin/svn +$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn every time you want to run Subversion. Of course we could set up the PATH environment variable to include the bin directory of every component we want to use, but this is not very convenient since changing PATH -doesn't take effect for already existing processes. The solution Nix +doesn’t take effect for already existing processes. The solution Nix uses is to create directory trees of symlinks to activated components. These are called user environments and they are components themselves (though automatically generated by nix-env), so they too reside in the Nix store. For instance, in the user -environment /nix/store/068150f63831...-user-env -contains a symlink to just Subversion 0.32.1 (arrows in the figure +environment /nix/store/5mq2jcn36ldl...-user-env +contains a symlink to just Subversion 1.1.2 (arrows in the figure indicate symlinks). This would be what we would obtain if we had done $ nix-env -i subversion -on a set of Nix expressions that contained Subversion 0.32.1. +on a set of Nix expressions that contained Subversion 1.1.2. -This doesn't in itself solve the problem, of course; you -wouldn't want to type -/nix/store/068150f63831...-user-env/bin/svn -either. Therefore there are symlinks outside of the store that point +This doesn’t in itself solve the problem, of course; you +wouldn’t want to type +/nix/store/0c1p5z4kda11...-user-env/bin/svn +either. That’s why there are symlinks outside of the store that point to the user environments in the store; for instance, the symlinks -42 and 43 in the example. -These are called generations since every time you -perform a nix-env operation, a new user environment -is generated based on the current one. For instance, generation 43 -was created from generation 42 when we did +default-42-link and +default-43-link in the example. These are called +generations since every time you perform a +nix-env operation, a new user environment is +generated based on the current one. For instance, generation 43 was +created from generation 42 when we did $ nix-env -i subversion mozilla @@ -251,14 +250,14 @@ on a set of Nix expressions that contained Mozilla and a new version of Subversion. Generations are grouped together into -profiles so that different users don't interfere -with each other if they don't want to. For example: +profiles so that different users don’t interfere +with each other if they don’t want to. For example: $ ls -l /nix/var/nix/profiles/ ... -lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/068150f63831...-user-env -lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/84c85f89ddbf...-user-env +lrwxrwxrwx 1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env +lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env lrwxrwxrwx 1 eelco ... default -> default-43-link This shows a profile called default. The file @@ -268,7 +267,7 @@ operation, a new user environment and generation link are created based on the current one, and finally the default symlink is made to point at the new generation. This last step is atomic on Unix, which explains how we can do atomic upgrades. (Note -that the building/installing of new components doesn't interfere in +that the building/installing of new components doesn’t interfere in any way with old components, since they are stored in different locations in the Nix store.) @@ -293,13 +292,13 @@ can also see all available generations: $ nix-env --list-generations Actually, there is another level of indirection not shown in the -figure above. You generally wouldn't have +figure above. You generally wouldn’t have /nix/var/nix/profiles/some-profile/bin in your PATH. Rather, there is a symlink ~/.nix-profile that points to your current profile. This means that you should put ~/.nix-profile/bin in your PATH -(and indeed, that's what the initialisation script +(and indeed, that’s what the initialisation script /nix/etc/profile.d/nix.sh does). This makes it easier to switch to a different profile. You can do that using the command nix-env --switch-profile: @@ -310,7 +309,7 @@ $ nix-env --switch-profile /nix/var/nix/profiles/my-profile $ nix-env --switch-profile /nix/var/nix/profiles/default These commands switch to the my-profile and -default profile, respectively. If the profile doesn't exist, it will +default profile, respectively. If the profile doesn’t exist, it will be created automatically. You should be careful about storing a profile in another location than the profiles directory, since otherwise it might not be used as a root of the @@ -346,7 +345,7 @@ not used (directly or indirectly) by any generation of any profile. Note however that as long as old generations reference a -component, it will not be deleted. After all, we wouldn't be able to +component, it will not be deleted. After all, we wouldn’t be able to do a rollback otherwise. So in order for garbage collection to be effective, you should also delete (some) old generations. Of course, this should only be done if you are certain that you will not need to @@ -378,7 +377,7 @@ You can alo first view what files would be deleted: $ nix-collect-garbage --print-dead Likewise, the option will show the paths -that won't be deleted. +that won’t be deleted. Garbage collector roots @@ -402,11 +401,11 @@ so all generations of all profiles are also roots of the collector. Channels -If you want to stay up to date with a set of packages, it's not +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-env. Fortunately, there’s a better way: Nix channels. A Nix channel is just a URL that points to a place that contains @@ -440,7 +439,7 @@ This downloads the Nix expressions in every channel (downloaded from 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 +makes the union of each channel’s Nix expressions the default for nix-env operations. Consequently, you can then say