From 0b79a1208228298d3abda7c03153c1abec2406d4 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Sun, 14 Nov 2004 00:24:57 +0000 Subject: [PATCH] * Manual fixes. --- doc/manual/introduction.xml | 40 +++++++++++----------- doc/manual/package-management.xml | 57 ++++++++++++++++--------------- doc/manual/quick-start.xml | 4 +-- 3 files changed, 50 insertions(+), 51 deletions(-) diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml index a50db8d39..35f18dee2 100644 --- a/doc/manual/introduction.xml +++ b/doc/manual/introduction.xml @@ -12,11 +12,11 @@ features are: -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 +It helps you make 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. @@ -25,8 +25,8 @@ there. 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 +installing one version will remove the other. This is especially +important if you want to 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). @@ -45,24 +45,23 @@ 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 +operation the previous configuration of the system can be restored. +This is because upgrade or uninstall actions don'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. +garbage-collected automatically and safely: when +you remove an application from a profile, its dependencies will be +deleted by the garbage collector only if there are no other active +applications using them. 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. +components is always based on Nix expressions, but if the 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 @@ -80,13 +79,12 @@ 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. +collection) takes special care 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 +how to build all the dependencies. This is in 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 @@ -111,7 +109,7 @@ platforms. 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 +software deployment also apply here: for instance, the ability trivially to have multiple configurations at the same time, or the ability to do rollbacks. diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml index d299bf054..4e86b2601 100644 --- a/doc/manual/package-management.xml +++ b/doc/manual/package-management.xml @@ -31,7 +31,7 @@ Nix expressions called the Nix Package collection that contains components ranging from basic development stuff such as GCC and Glibc, to end-user applications like Mozilla Firefox. (Nix is however not tied to the Nix Package collection; you could write your own Nix -expression based on that, or completely new.) You can download the +expression based on it, or completely new ones.) You can download the latest version from . You probably want the latest unstable release; currently the stable releases tend to lag @@ -55,7 +55,7 @@ where nixpkgs-version is where you've unpacked the release. It is also possible to see the status of -available component, i.e., whether they are installed into the user +available components, i.e., whether they are installed into the user environment and/or present in the system: @@ -69,12 +69,13 @@ IPS bison-1.875d The first character (I) indicates whether the component is installed in your current user environment. The second (P) indicates whether it is present on your system -(in which case installing it into your user environment would be very -quick). The last one (S) indicates whether there -is a so-called substitute for the component, -which is Nix's mechanism for doing binary deployment. It just means -that Nix know that it can fetch a pre-built component from somewhere -(typically a network server) instead of building it locally. +(in which case installing it into your user environment would be a +very quick operation). The last one (S) indicates +whether there is a so-called substitute for the +component, which is Nix's mechanism for doing binary deployment. It +just means that Nix know that it can fetch a pre-built component from +somewhere (typically a network server) instead of building it +locally. So now that we have a set of Nix expressions we can build the components contained in them. This is done using nix-env @@ -91,8 +92,8 @@ system). When you do this for the first time, Nix will start building Subversion and all its dependencies. This will take quite a while — typically an hour or two on modern machines. Fortunately, there is a -faster way (so just do a Ctrl-C on that install operation!): you just -need to tell Nix that pre-built binaries of all those components are +faster way (so do a Ctrl-C on that install operation!): you just need +to tell Nix that pre-built binaries of all those components are available somewhere. This is done using the nix-pull command, which must be supplied with a URL containing a manifest describing what binaries @@ -110,7 +111,7 @@ downloading binaries from catamaran.labs.cs.uu.nl, instead of building them from source. This might still take a while since all dependencies must be downloaded, but on a reasonably fast connection -such as an ADSL line it's on the order of a few minutes. +such as an DSL line it's on the order of a few minutes. Naturally, packages can also be uninstalled: @@ -127,10 +128,10 @@ $ nix-env -f nixpkgs-version -u subversion This will only upgrade Subversion if there is a newer version in the new set of Nix expressions, as -defined by some pretty much arbitrary rules regarding ordering of -version numbers (which generally do what you'd expect of them). To -just unconditionally replace Subversion with whatever version is in -the Nix expressions, use -i instead of +defined by some pretty arbitrary rules regarding ordering of version +numbers (which generally do what you'd expect of them). To just +unconditionally replace Subversion with whatever version is in the Nix +expressions, use -i instead of -u; -i will remove whatever version is already installed. @@ -261,7 +262,7 @@ lrwxrwxrwx 1 eelco ... default-43-link -> /nix/store/84c85f89ddbf...-user-env lrwxrwxrwx 1 eelco ... default -> default-43-link This shows a profile called default. The file -default itself is actually a symlink that point +default itself is actually a symlink that points to the current generation. When we do a nix-env operation, a new user environment and generation link are created based on the current one, and finally the default @@ -295,13 +296,13 @@ $ nix-env --list-generations figure above. You generally wouldn't have /nix/var/nix/profiles/some-profile/bin in your PATH. Rather, there is a symlink -~/.nix-profile that point to your current +~/.nix-profile that points to your current profile. This means that you should put ~/.nix-profile/bin in your PATH (and indeed, that's what the initialisation script /nix/etc/profile.d/nix.sh does). This makes it -easier to switch to a different profile, which is exactly what the -command nix-env --switch-profile does: +easier to switch to a different profile. You can do that using the +command nix-env --switch-profile: $ nix-env --switch-profile /nix/var/nix/profiles/my-profile @@ -311,14 +312,14 @@ $ nix-env --switch-profile /nix/var/nix/profiles/default These commands switch to the my-profile and default profile, respectively. If the profile doesn't exist, it will be created automatically. You should be careful about storing a -profile in another location that the profiles -directory, since otherwise it might not be used as a root to the -garbage collection (see section profiles +directory, since otherwise it might not be used as a root of the +garbage collector (see section ). All nix-env operations work on the profile pointed to by ~/.nix-profile, but you can override -this on using the option (abbreviation +this using the option (abbreviation ): @@ -335,7 +336,7 @@ This will not change the nix-env operations such as upgrades () and uninstall () never actually delete components from the system. All they do (as shown -above) is to make a new user environment that no longer contains +above) is to create a new user environment that no longer contains symlinks to the deleted components. Of course, since disk space is not infinite, unused components @@ -414,10 +415,10 @@ a set of Nix expressions and a manifest. Using the command with whatever is available at that URL. You can subscribe to a channel using -nix-channel --subscribe, e.g., +nix-channel --add, e.g., -$ nix-channel --subscribe http://catamaran.labs.cs.uu.nl/dist/nix/channels/nixpkgs-unstable +$ nix-channel --add http://catamaran.labs.cs.uu.nl/dist/nix/channels/nixpkgs-unstable subscribes you to a channel that always contains that latest version of the Nix Packages collection. (Instead of @@ -446,9 +447,9 @@ makes the union of each channel's Nix expressions the default for $ nix-env -u '*' to upgrade all components in your profile to the latest versions -available in the channels. +available in the subscribed channels. - \ No newline at end of file + diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml index 2350aed34..e12b28da2 100644 --- a/doc/manual/quick-start.xml +++ b/doc/manual/quick-start.xml @@ -102,7 +102,7 @@ $ nix-env --rollback You should periodically run the Nix garbage collector to get rid of unused packages, since uninstalls or upgrades don't -actual delete them: +actually delete them: $ nix-env --delete-generations old @@ -115,4 +115,4 @@ second command actually deletes them. - \ No newline at end of file +