From 2b20701f7895101c8ef8c989fccf702081615120 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 13 Oct 2004 15:08:35 +0000 Subject: [PATCH] * Better introduction. * Set notes in a different color than warnings. --- doc/manual/introduction.xml | 229 ++++++++++++++++++------------------ doc/manual/manual.xml | 2 +- doc/manual/style.css | 10 +- 3 files changed, 122 insertions(+), 119 deletions(-) diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml index 51804eb9b6..5c968edfc8 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 bd11fe0f20..930da3a891 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 a9b6fd2c67..893e7db3f1 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 *