diff options
Diffstat (limited to 'doc/manual/package-management.xml')
| -rw-r--r-- | doc/manual/package-management.xml | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml new file mode 100644 index 000000000000..90f8f95b6581 --- /dev/null +++ b/doc/manual/package-management.xml @@ -0,0 +1,229 @@ +<chapter id='chap-package-management'><title>Package Management</title> + +<para>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 <emphasis>user environment</emphasis>: the +set of packages that a user <quote>sees</quote>. In a command line +Unix environment, this means the set of programs that are available +through the <envar>PATH</envar> environment variable. (In other +environments it might mean the set of programs available on the +desktop, through the start menu, and so on.)</para> + +<para>The terms <quote>installation</quote> and +<quote>uninstallation</quote> 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.</para> + +<para>User environments are manipulated through the +<command>nix-env</command> command. The query operation can be used +to see what packages are currently installed.</para> + +<screen> +$ nix-env -q +MozillaFirebird-0.7 +sylpheed-0.9.7 +pan-0.14.2</screen> + +<para>(<option>-q</option> is actually short for <option>--query +--installed</option>.) 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 <literal>gtk+</literal> 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.</para> + +<para>To install packages, a <emphasis>Nix expression</emphasis> is +required that tells Nix how to build that package. There is a <ulink +url='https://svn.cs.uu.nl:12443/dist/trace/trace-nixpkgs-trunk.tar.bz2'>set +of standard of Nix expressions</ulink> for many common packages. +Assuming that you have downloaded and unpacked these, you can view the +set of available packages:</para> + +<screen> +$ 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 +...</screen> + +<para>The Nix expression in the file +<filename>i686-linux.nix</filename> 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]</para> + +<para>It is also possible to see the <emphasis>status</emphasis> of +available packages, i.e., whether they are installed into the user +environment and/or present in the system:</para> + +<screen> +$ 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</screen> + +<para>This reveals that the <literal>sylpheed</literal> package is +already installed, or more precisely, that exactly the same +instantiation of <literal>sylpheed</literal> 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 <literal>gettext</literal> and +<literal>gtk+</literal> packages are present but not installed in the +user environment, while the <literal>aterm</literal> package is not +installed or present at all (so, if we were to install it, it would +have to be built or downloaded first).</para> + +<para>The install operation is used install available packages from a +Nix environment. To install the <literal>pan</literal> package (a +newsreader), you would do:</para> + +<screen> +$ nix-env -if pkgs/system/i686-linux.nix pan</screen> + +<para>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 +<command>nix-env</command> run verbosely by using the +<option>-v</option> (<option>--verbose</option>) option. This option +may be repeated to increase the level of verbosity. A good value is 3 +(<option>-vvv</option>).</para> + +<para>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 <literal>glibc</literal> and <literal>gcc</literal>. +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 <quote>binary</quote> +installation is generally preferable.</para> + +<para>Rather than provide different mechanisms to create and perform +the installation of binary packages, Nix supports binary deployment +<emphasis>transparently</emphasis> through a generic mechanism of +<emphasis>substitute expressions</emphasis>. 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.</para> + +<para>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.</para> + +<para>While the substitute mechanism is a generic mechanism, Nix +provides two standard tools called <command>nix-pull</command> and +<command>nix-push</command> 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 <quote>pushed</quote> into the cache, and you +have done a <quote>pull</quote> to register substitutes that download +these prebuilt packages, then the installation will automatically use +these.</para> + +<para>For example, to pull from our <ulink +url='http://losser.st-lab.cs.uu.nl/~eelco/nix-dist/'>cache</ulink> of +prebuilt packages (at the time of writing, for SuSE Linux/x86), use +the following command:</para> + +<screen> +$ nix-pull http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-<replaceable>version</replaceable>/MANIFEST +obtaining list of Nix archives at http://catamaran.labs.cs.uu.nl/dist/nix/nixpkgs-<replaceable>version</replaceable>/MANIFEST... +...</screen> + +<para>If <command>nix-pull</command> is run without any arguments, it +will pull from the URLs specified in the file +<filename><replaceable>prefix</replaceable>/etc/nix/prebuilts.conf</filename>.</para> + +<para>Assuming that the <literal>pan</literal> installation produced +no errors, it can be used immediately, that is, it now appears in a +directory in the <envar>PATH</envar> environment variable. +Specifically, <envar>PATH</envar> includes the entry +<filename><replaceable>prefix</replaceable>/var/nix/profiles/default/bin</filename>, +where +<filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename> +is just a symlink to the current user environment:</para> + +<screen> +$ ls -l /nix/var/nix/profiles/ +... +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</screen> + +<para>That is, <filename>default</filename> in this example is a link +to <filename>default-16-link</filename>, which is the current user +environment. Before the installation, it pointed to +<filename>default-15-link</filename>. Note that this means that you +can atomically roll-back to the previous user environment by pointing +the symlink <filename>default</filename> at +<filename>default-15-link</filename> 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).</para> + +<para>What's in a user environment? It's just a set of symlinks to the +files that constitute the installed packages. For instance:</para> + +<screen> +$ 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 +...</screen> + +<para>Note that, e.g., <filename>svn</filename> = +<filename>/nix/var/nix/profiles/default/bin/svn</filename> = +<filename>/nix/var/nix/profiles/default-16-link/bin/svn</filename> = +<filename>/nix/store/59ba...df6b-user-environment/bin/svn</filename> = +<filename>/nix/store/3829...fb5d-subversion-0.32.1/bin/svn</filename>.</para> + +<para>Naturally, packages can also be uninstalled:</para> + +<screen> +$ nix-env -e pan</screen> + +<para>This means that the package is removed from the user +environment. It is <emphasis>not</emphasis> 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 <quote>physically</quote> deleted by running the Nix garbage +collector, which searches for all packages in the Nix store that are +no longer <quote>reachable</quote> from outside the store. Thus, +uninstalling a package is always safe: it cannot break other +packages.</para> + +<para>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), <command>nix-env +-u</command> will replace the installed package in the user +environment with the newer package. For example, + +<screen> +$ nix-env -uf pkgs/system/i686-linux.nix pan</screen> + +looks for a newer version of Pan, and installs it if found. Also +useful is the ability to upgrade <emphasis>all</emphasis> packages: + +<screen> +$ nix-env -uf pkgs/system/i686-linux.nix '*'</screen> + +The asterisk matches all installed packages<footnote><para>No, we +don't support arbitrary regular expressions</para></footnote>. Note +that <literal>*</literal> must be quoted to prevent shell +globbing.</para> + +</chapter> \ No newline at end of file |