diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml index 90f8f95b65..a6ef0c947d 100644 --- a/doc/manual/package-management.xml +++ b/doc/manual/package-management.xml @@ -1,229 +1,190 @@ Package Management -Let's start from the perspective of an end user. Common -operations at this level are to install and remove packages, ask what -packages are installed or available for installation, and so on. -These are operations on the user environment: the -set of packages that a user sees. In a command line -Unix environment, this means the set of programs that are available -through the PATH environment variable. (In other -environments it might mean the set of programs available on the -desktop, through the start menu, and so on.) +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 +who want to create components should consult +. -The terms installation and -uninstallation are used in this context to denote the -act of adding or removing packages from the user environment. In Nix, -these operations are dissociated from the physical copying or deleting -of files. Installation requires that the files constituting the -package are present, but they may be present beforehand. Likewise, -uninstallation does not actually delete any files; this is done -automatically by running a garbage collector. -User environments are manipulated through the -nix-env command. The query operation can be used -to see what packages are currently installed. +Basic package management + +The main command for package management is +nix-env. You can use it to install, upgrade, and +erase components, and to query what components are installed or are +available for installation. + +In Nix, different users can have different views +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 installed applications is called a +user environment, which is just a directory tree +consisting of symlinks to the files of the active applications. 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. + +Components are installed from a set of Nix +expressions that tell Nix how to build those components, +including, if necessary, their dependencies. There is a collection of +Nix expressions called the Nix Package collection that contains +components 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 +expression based on that, or completely new.) You can download the +latest version from . You probably want +the latest unstable release; currently the stable releases tend to lag +behind quite a bit. + +Assuming that you have downloaded and unpacked a release of Nix +Packages, you can view the set of available components in the release: -$ nix-env -q -MozillaFirebird-0.7 -sylpheed-0.9.7 -pan-0.14.2 - -( is actually short for .) The package names are symbolic: they don't -have any particular significance to Nix (as they shouldn't, since they -are not unique—there can be many derivations with the same -name). Note that these packages have many dependencies (e.g., Mozilla -uses the gtk+ package) but these have not been -installed in the user environment, though they are present on the -system. Generally, there is no need to install such packages; only -packages containing programs should be installed. - -To install packages, a Nix expression is -required that tells Nix how to build that package. There is a set -of standard of Nix expressions for many common packages. -Assuming that you have downloaded and unpacked these, you can view the -set of available packages: - - -$ nix-env -qaf pkgs/system/i686-linux.nix -gettext-0.12.1 -sylpheed-0.9.7 -aterm-2.0 -gtk+-1.2.10 -apache-httpd-2.0.48 -pan-0.14.2 +$ nix-env -qaf nixpkgs-version +ant-blackdown-1.4.2 +aterm-2.2 +bash-3.0 +binutils-2.15 +bison-1.875d +blackdown-1.4.2 +bzip2-1.0.2 ... -The Nix expression in the file -i686-linux.nix yields the set of packages for a -Linux system running on x86 hardware. For other platforms, copy and -modify this file for your platform as appropriate. [TODO: improve -this] +where nixpkgs-version is +where you've unpacked the release. It is also possible to see the status of -available packages, i.e., whether they are installed into the user -environment and/or present in the system: +available component, i.e., whether they are installed into the user +environment and/or present in the system: -$ nix-env -qasf pkgs/system/i686-linux.nix --P gettext-0.12.1 -IP sylpheed-0.9.7 --- aterm-2.0 --P gtk+-1.2.10 - -This reveals that the sylpheed package is -already installed, or more precisely, that exactly the same -instantiation of sylpheed is installed. This -guarantees that the available package is exactly the same as the -installed package with regard to sources, dependencies, build flags, -and so on. Similarly, we see that the gettext and -gtk+ packages are present but not installed in the -user environment, while the aterm package is not -installed or present at all (so, if we were to install it, it would -have to be built or downloaded first). - -The install operation is used install available packages from a -Nix environment. To install the pan package (a -newsreader), you would do: - - -$ nix-env -if pkgs/system/i686-linux.nix pan - -Since installation may take a long time, depending on whether -any packages need to be built or downloaded, it's a good idea to make -nix-env run verbosely by using the - () option. This option -may be repeated to increase the level of verbosity. A good value is 3 -(). - -In fact, if you run this command verbosely you will observe that -Nix starts to build many packages, including large and fundamental -ones such as glibc and gcc. -I.e., you are performing a source installation. This is generally -undesirable, since installation from sources may require large amounts -of disk and CPU resources. Therefore a binary -installation is generally preferable. - -Rather than provide different mechanisms to create and perform -the installation of binary packages, Nix supports binary deployment -transparently through a generic mechanism of -substitute expressions. If an request is made to -build some Nix expression, Nix will first try to build any substitutes -for that expression. These substitutes presumably perform an -identical build operation with respect to the result, but require less -resources. For instance, a substitute that downloads a pre-built -package from the network requires less CPU and disk resources, and -possibly less time. - -Nix's use of cryptographic hashes makes this entirely safe. It -is not possible, for instance, to accidentally substitute a build of -some package for a Solaris or Windows system for a build on a SuSE/x86 -system. - -While the substitute mechanism is a generic mechanism, Nix -provides two standard tools called nix-pull and -nix-push that maintain and use a shared cache of -prebuilt derivations on some network site (reachable through HTTP). -If you attempt to install some package that someone else has -previously built and pushed into the cache, and you -have done a pull to register substitutes that download -these prebuilt packages, then the installation will automatically use -these. - -For example, to pull from our cache of -prebuilt packages (at the time of writing, for SuSE Linux/x86), use -the following command: - - -$ nix-pull http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-version/MANIFEST -obtaining list of Nix archives at http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-version/MANIFEST... -... - -If nix-pull is run without any arguments, it -will pull from the URLs specified in the file -prefix/etc/nix/prebuilts.conf. - -Assuming that the pan installation produced -no errors, it can be used immediately, that is, it now appears in a -directory in the PATH environment variable. -Specifically, PATH includes the entry -prefix/var/nix/profiles/default/bin, -where -prefix/var/nix/profiles/default -is just a symlink to the current user environment: - - -$ ls -l /nix/var/nix/profiles/ +$ nix-env -qasf nixpkgs-version ... -lrwxrwxrwx 1 eelco ... default-15-link -> /nix/store/1871...12b0-user-environment -lrwxrwxrwx 1 eelco ... default-16-link -> /nix/store/59ba...df6b-user-environment -lrwxrwxrwx 1 eelco ... default -> default-16-link - -That is, default in this example is a link -to default-16-link, which is the current user -environment. Before the installation, it pointed to -default-15-link. Note that this means that you -can atomically roll-back to the previous user environment by pointing -the symlink default at -default-15-link again. This also shows that -operations such as installation are atomic in the Nix system: any -arbitrarily complex set of installation, uninstallation, or upgrade -actions eventually boil down to the single operation of pointing a -symlink somewhere else (which can be implemented atomically in Unix). - -What's in a user environment? It's just a set of symlinks to the -files that constitute the installed packages. For instance: - - -$ ls -l /nix/var/nix/profiles/default-16-link/bin -lrwxrwxrwx 1 eelco ... MozillaFirebird -> /nix/store/35f8...4ae6-MozillaFirebird-0.7/bin/MozillaFirebird -lrwxrwxrwx 1 eelco ... svn -> /nix/store/3829...fb5d-subversion-0.32.1/bin/svn +-PS bash-3.0 +--S binutils-2.15 +IPS bison-1.875d ... -Note that, e.g., svn = -/nix/var/nix/profiles/default/bin/svn = -/nix/var/nix/profiles/default-16-link/bin/svn = -/nix/store/59ba...df6b-user-environment/bin/svn = -/nix/store/3829...fb5d-subversion-0.32.1/bin/svn. +The first character (I) indicates whether the +component is installed in your current user environment. The second +(P) indicates whether it is present on your system +(in which case installing it into your user environment would be very +quick). 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 just means +that Nix know that it can fetch a pre-built component from somewhere +(typically a network server) instead of building it locally. -Naturally, packages can also be uninstalled: +So now that we have a set of Nix expressions we can build the +components contained in them. This is done using nix-env +-i. For instance, -$ nix-env -e pan +$ nix-env -f nixpkgs-version -i subversion -This means that the package is removed from the user -environment. It is not yet removed from the -system. When a package is uninstalled from a user environment, it may -still be used by other packages, or may still be present in other user -environments. Deleting it under such conditions would break those -other packages or user environments. To prevent this, packages are -only physically deleted by running the Nix garbage -collector, which searches for all packages in the Nix store that are -no longer reachable from outside the store. Thus, -uninstalling a package is always safe: it cannot break other -packages. +will install the component 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 just do a Ctrl-C on that install +operation!): you just need to tell Nix that pre-built binaries of all +those components 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: -Upgrading packages is easy. Given a Nix expression that -contains newer versions of installed packages (that is, packages with -the same package name, but a higher version number), nix-env --u will replace the installed package in the user -environment with the newer package. For example, - -$ nix-env -uf pkgs/system/i686-linux.nix pan +$ nix-pull http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-0.6pre1554/MANIFEST + +If you then issue the installation command, it should start +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 ADSL line it's on the order of a few minutes. + +Naturally, packages can also be uninstalled: -looks for a newer version of Pan, and installs it if found. Also -useful is the ability to upgrade all packages: - -$ nix-env -uf pkgs/system/i686-linux.nix '*' +$ nix-env -e subversion + + + +Upgrading to a new version is just as easy. If you have a new +release of Nix Packages, you can do: + + +$ 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 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. + +You can also upgrade all components for which there are newer +versions: + + +$ nix-env -f nixpkgs-version -u '*' + + + +If you grow tired of specifying the Nix expressions using +-f all the time, you can set a default +location: + + +$ nix-env -I nixpkgs-version + +After this you can just say, for instance, nix-env -u +'*'.Setting a default using +-I currently clashes with using Nix channels, +since nix-channel --update calls nix-env +-I to set the default to the Nix expressions it downloaded +from the channel, replacing whatever default you had +set. + + + + +Profiles + +Bla + + + + +Garbage collection + +Bla + + + + +Channels + +Bla + + -The asterisk matches all installed packagesNo, we -don't support arbitrary regular expressions. Note -that * must be quoted to prevent shell -globbing. \ No newline at end of file