diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index 51804eb9b..5c968edfc 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -5,51 +5,123 @@ has grown to 5, with more expected.
Nix is a system for the deployment of software. Software
deployment is concerned with the creation, distribution, and
-management of software components (packages
). There
-are many tools for this, but they tend to ignore some important
-requirements for deployment:
+management of software components (packages
). Its main
+features are:
-Correctness. The basic goal of
-software deployment is to transfer software from one machine (e.g.,
-the developer's, where it presumably works) to another machine (e.g.,
-the end user's). The software should work exactly the same on the
-target machine as on the source machine. But this in practice turns
-out to be rather difficult due to dependencies between
-components and interference between
-components. If we deploy a component that depends on other
-components, then we should deploy those dependencies as well. If they
-are missing on the target system, the component probably won't work.
-If they are present but are not the right
-version, the component might not work. And if even if they are the
-right version, they may have been built with different flags or
-options, which can cause incompatibilities. Interference occurs when
-components collide
with each other in the file system.
-For instance, different versions of the same package tend to overwrite
-each other, so they cannot be installed at the same time. But always
-picking the latest version might break components that only work with
-some older version.
+It makes sure that dependency specifications are
+complete. In general in a deployment system you have to specify for
+each component what its dependencies are, but there are no guarantees
+that this specification is complete. If you forget a dependency, then
+the component will build and work correctly on
+your machine if you have the dependency
+installed, but not on the end user's machine if it's not
+there.
-Variability. Many package
-management tools have difficulty supporting the installation of
-multiple versions or variants of the same component. This is bad
-because as ...
+It is possible to have multiple versions or
+variants of a component installed at the same time. In
+contrast, in systems such as RPM different versions of the same
+package tend to install to the same location in the file system, so
+you installing one version will remove the other. This is especially
+important if you want to have use applications that have conflicting
+requirements on different versions of a component (e.g., application A
+requires version 1.0 of library X, while application B requires a
+non-backwards compatible version 1.1).
+
+Users can have different views
+(profiles
in Nix parlance) on the set of installed
+applications in a system. For instance, one user can have version 1.0
+of some package visible, while another is using version 1.1, and a
+third doesn't use it at all.
+
+It is possible to atomically
+upgrade software. I.e., there is no time window
+during an upgrade in which part of the old version and part of the new
+version are simultaneously visible (which might well cause the
+component to fail).
+
+Likewise, it is possible to atomically roll-back after
+an install, upgrade, or uninstall action. That is, in a fast (O(1))
+operation the previous configuration of the system will be
+restored. This is because upgrade or uninstall actions doesn't
+actually remove components from the system.
+
+Unused components can be
+garbage-collected automatically and safely.
+I.e., when you remove an application from a profile, its dependencies
+will be deleted by the garbage collector if there are no other active
+applications that are using it.
+
+Nix supports both source-based deployment models
+(where you distribute Nix expressions that tell
+Nix how to build software from source) and binary-based deployment
+models. The latter is more-or-less transparent: installation of
+components is always based on Nix expressions, but if those
+expressions have been built before and Nix knows that the resulting
+binaries are available somewhere, it will use those
+instead.
+
+Nix is flexible in the deployment policies that it
+supports. There is a clear separation between the tools that
+implement basic Nix mechanisms (e.g., building
+Nix expressions), and the tools that implement various deployment
+policies. For instance, there is a concept of
+Nix channels
that can be used to keep software
+installations up-to-date automatically from a network source. This is
+a policy that is implemented by a fairly short Perl script, which can
+be adapted easily to achieve similar policies.
+
+Nix component builds aim to be pure
;
+that is, unaffected by anything other than the declared dependencies.
+This means that if a component was built succesfully once, it can be
+rebuilt again on another machine and the result will be the same. We
+cannot guarantee this (e.g., if the build depends
+on the time-of-day), but Nix (and the tools in the Nix Packages
+collection) takes special measures to help achieve
+this.
+
+Nix expressions (the things that tell Nix how to build
+components) are self-contained: they describe not just components but
+complete compositions. In other words, Nix expressions also describe
+how to build all the dependencies. This is contrast to component
+specification languages like RPM spec files, which might say that a
+component X depends on some other component Y, but since it does not
+describe exactly what Y is, the result of
+building or running X might be different on different machines.
+Combined with purity, self-containedness ensures that a component that
+works
on one machine also works on another, when
+deployed using Nix.
+
+The Nix expression language makes it easy to describe
+variability in components (e.g., optional features or
+dependencies).
+
+Nix is ideal for building build farms that do
+continuous builds of software from a version management system, since
+it can take care of building all the dependencies as well. Also, Nix
+only rebuilds components that have changed, so there are no
+unnecessary builds. In addition, Nix can transparently distribute
+build jobs over different machines, including different
+platforms.
+
+Nix can be used not only for software deployment, but
+also for service deployment, such as the
+deployment of a complete web server with all its configuration files,
+static pages, software dependencies, and so on. Nix's advantages for
+software deployment also apply here, for instance, the ability
+trivially to have multiple configurations at the same time, or the
+ability to do roll-backs.
-Here are some of Nix's main features:
-
-
-
-Nix can quite reliably figure out the dependencies
-between components.
-
-
-
-
+This manual tells you how to install and use Nix and how to
+write Nix expressions for software not already in the Nix Packages
+collection. It also discusses some advanced topics, such as setting
+up a Nix-based build farm, and doing service deployment using
+Nix.
This manual is a work in progress. It's quite likely
to be incomplete, inconsistent with the current implementation, or
@@ -62,85 +134,10 @@ a Memory Management Discipline on Software
Deployment discusses the hashing mechanism used to
ensure reliable dependency identification and non-interference between
different versions and variants of packages. The LISA 2004 paper
-Nix: A Safe and Policy-Free System for Software
-Deployment gives a more general discussion of Nix from a
-system-administration perspective.
-
-
- Nix solves some large problems that exist in most current deployment and
- package management systems. Dependency determination
- is a big one: the correct installation of a software component requires
- that all dependencies of that component (i.e., other components used by it)
- are also installed. Most systems have no way to verify that the specified
- dependencies of a component are actually sufficient.
-
-
-
- Another big problem is the lack of support for concurrent availability of
- multiple variants of a component. It must be possible
- to have several versions of a component installed at the same time, or
- several instances of the same version built with different parameters.
- Unfortunately, components are in general not properly isolated from each
- other. For instance, upgrading a component that is a dependency for some
- other component might break the latter.
-
-
-
- Nix solves these problems by building and storing packages in paths that
- are infeasible to predict in advance. For example, the artifacts of a
- package X might be stored in
- /nix/store/d58a0606ed616820de291d594602665d-X, rather
- than in, say, /usr/lib. The path component
- d58a... is actually a cryptographic hash of all the
- inputs (i.e., sources, requisites, and build flags) used in building
- X, and as such is very fragile: any change to the inputs
- will change the hash. Therefore it is not sensible to
- hard-code such a path into the build scripts of a
- package Y that uses X (as does happen
- with fixed
paths such as /usr/lib).
- Rather, the build script of package Y is parameterised
- with the actual location of X, which is supplied by the
- Nix system.
-
-
-
- As stated above, the path name of a file system object contain a
- cryptographic hash of all inputs involved in building it. A change to any
- of the inputs will cause the hash to change--and by extension, the path
- name. These inputs include both sources (variation in time) and
- configuration options (variation in space). Therefore variants of the same
- package don't clash---they can co-exist peacefully within the same file
- system.
-
-
-
- Other features:
-
-
-
- Transparent source/binary deployment.
-
-
-
- Unambiguous identification of configuration.
-
-
-
- Automatic storage management.
-
-
-
- Atomic upgrades and rollbacks.
-
-
-
- Support for many simultaneous configurations.
-
-
-
- Portability. Nix is quite portable. Contrary to
- build systems like those in, e.g., Vesta and ClearCase, it does not rely on
- operating system extensions.
-
+Nix:
+A Safe and Policy-Free System for Software
+Deployment gives a more general discussion of Nix
+from a system-administration perspective.
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index bd11fe0f2..930da3a89 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -26,7 +26,7 @@
]>
- Nix: A System for Software Deployment
+ Nix User's Guide
Draft (Version &version;)
diff --git a/doc/manual/style.css b/doc/manual/style.css
index a9b6fd2c6..893e7db3f 100644
--- a/doc/manual/style.css
+++ b/doc/manual/style.css
@@ -112,10 +112,16 @@ div.note,div.warning
font-style: italic;
}
-div.note h3,div.warning h3
+div.warning h3
{
color: red;
- text-decoration: underline;
+ font-size: 100%;
+}
+
+div.note h3
+{
+ color: blue;
+ font-size: 100%;
}
div.navfooter *