From 7b0e29b4dc42946b64fc3d616caa33ae442d94c6 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 26 Nov 2003 16:09:27 +0000 Subject: [PATCH] * Overview of nix-env. Recommended reading. :-) --- doc/manual/overview.xml | 224 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 220 insertions(+), 4 deletions(-) diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml index 1c2c283f0..b26d28604 100644 --- a/doc/manual/overview.xml +++ b/doc/manual/overview.xml @@ -9,18 +9,234 @@ Basic package management - Let's start from the perspective of an end-user. Common operations at + 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. + 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.) + + 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. + + + +$ 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 standard - distribution of Nix expressions for many common packages. + url='https://svn.cs.uu.nl:12443/dist/trace/trace-nixpkgs-trunk.tar.bz2'>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 -qf pkgs/system/i686-suse-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 +... + + + The Nix expression in the file i686-suse-linux.nix + yields the set of packages for a SuSE Linux system running on x86 + hardware. For other platforms, copy and modify this file for your + platform as appropriate. [TODO: improve this] + + + + 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: + + + +$ nix-env -qf pkgs/system/i686-suse-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 -i pkgs/system/i686-suse-linux.nix pan-0.14.2 + + + 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-push 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://losser.st-lab.cs.uu.nl/~eelco/nix-dist/ +obtaining list of Nix archives at http://losser.st-lab.cs.uu.nl/~eelco/nix-dist... +... + + + 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/links/current/bin, + where + prefix/var/nix/links/current + is just a symlink to the current user environment: + + + +$ ls -l /nix/var/nix/links/ +... +lrwxrwxrwx 1 eelco ... 15 -> /nix/store/1871...12b0-user-environment +lrwxrwxrwx 1 eelco ... 16 -> /nix/store/59ba...df6b-user-environment +lrwxrwxrwx 1 eelco ... current -> /nix/var/nix/links/16 + + + That is, current in this example is a link to + 16, which is the current user environment. Before + the installation, it pointed to 15. Note that this + means that you can atomically roll-back to the previous user environment + by pointing the symlink current at + 15 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/links/16/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 +... + + + Note that, e.g., svn = + /nix/var/nix/links/current/bin/svn = + /nix/var/nix/links/16/bin/svn = + /nix/store/59ba...df6b-user-environment/bin/svn = + /nix/store/3829...fb5d-subversion-0.32.1/bin/svn. + + + + Naturally, packages can also be uninstalled: + + + +$ nix-env -u pan-0.14.2 +