* Split overview chapter into a chapter on package management and a

  chapter on writing Nix expressions.

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&mdash;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