diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index 4d5017e440..cb46a53b8a 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -106,7 +106,7 @@ these files (and fetchurl.nix checks them). We should switch away from MD5, since it has been -cracked. We don't currently depend very much on the +more-or-less cracked. We don't currently depend very much on the collision-resistance of MD5, but we will once we start sharing build results between users. diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index 15463a9b64..05173590ff 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -204,7 +204,7 @@ variables is to include the file in your ~/.bashrc (or similar), like this: -. prefix/etc/profile.d/nix.sh +source prefix/etc/profile.d/nix.sh diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml index 0b7299e9af..b83cd0c4ef 100644 --- a/doc/manual/package-management.xml +++ b/doc/manual/package-management.xml @@ -131,8 +131,8 @@ defined by some pretty much arbitrary rules regarding ordering of version 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 whatever version is already installed. +-u; -i will remove +whatever version is already installed. You can also upgrade all components for which there are newer versions: @@ -142,7 +142,21 @@ $ nix-env -f nixpkgs-version -u '*' -If you grow tired of specifying the Nix expressions using +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 '*' --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' +upgrading `coreutils-5.0' to `coreutils-5.2.1' + + + +If you grow bored of specifying the Nix expressions using -f all the time, you can set a default location: @@ -162,14 +176,30 @@ set. Profiles -In Nix, operations such as upgrading or removing components -never overwrite or remove the files of those components, and they -don't even touch the user environments that point to them. Rather, -they cause a new user environment to be -constructed based on the old one. This is illustrated in Figure -bla. +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 +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/, +while another version might be stored in +/nix/store/58823d558a6a...-subversion-0.34/. The +long hexadecimal numbers prefixed to the directory names are +cryptographic hashes128 bit MD5 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. -
User environments +
User environments @@ -177,20 +207,139 @@ bla.
+Of course, you wouldn't want to type + + +$ /nix/store/eeeeaf42e56b...-subversion-0.32.1/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 +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 +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. + +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 +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 + + +$ nix-env -i subversion mozilla + +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: + + +$ 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 -> default-43-link + +This shows a profile called default. The file +default itself is actually a symlink that point +to the current generation. When we do a nix-env +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 +any way with old components, since they are stored in different +locations in the Nix store.) + +If you find that you want to undo a nix-env +operation, you can just do + + +$ nix-env --rollback + +which will just make the current generation link point at the previous +link. E.g., default would be made to point at +default-42-link. You can also switch to a +specific generation: + + +$ nix-env --switch-generation 43 + +which in this example would roll forward to generation 43 again. You +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 +/nix/var/nix/profiles/some-profile/bin +in your PATH. Rather, there is a symlink +~/.nix-profile that point to your current +profile. This means that you should put +~/.nix-profile/bin in your PATH +(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, which is exactly what the +command nix-env --switch-profile does: + + +$ 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 +be created automatically. You should be careful about storing a +profile in another location that the profiles +directory, since otherwise it might not be used as a root to the +garbage collection (see section ). + +All nix-env operations work on the profile +pointed to by ~/.nix-profile, but you can override +this on using the option (abbreviation +): + + +$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion + +This will not change the +~/.nix-profile symlink. -Garbage collection +Garbage collection -Bla +TODO Channels -Bla +TODO