diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml index 33bd96a02..77579776b 100644 --- a/doc/manual/bugs.xml +++ b/doc/manual/bugs.xml @@ -3,6 +3,12 @@ + + + The man-pages generated from the DocBook documentation are ugly. + + + Unify the concepts of successors and substitutes into a diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml index bdf35bd32..874f27081 100644 --- a/doc/manual/nix-env.xml +++ b/doc/manual/nix-env.xml @@ -15,6 +15,14 @@ path + + + + + + path + + operation options arguments @@ -72,7 +80,8 @@ / - Specifies the Nix expression used by the + Specifies the Nix expression (designated below as the + active Nix expression) used by the , , and operations to obtain derivations. The default is @@ -81,6 +90,36 @@ + + / + + + Specifies the profile to be used by those operations that + operate on a profile (designated below as the + active profile). A profile is + sequence of user environments called + generations, one of which is the + current generation. The default + profile is the target of the symbolic link + ~/.nix-profile (see below). + + + + + + + + + For the , + and + operations, this flag will + cause nix-env to print what + would be done if this flag had not + been specified, without actually doing it. + + + + @@ -114,12 +153,12 @@ ~/.nix-profile - A symbolic link to the user's current profile. The - default profile is + A symbolic link to the user's current profile. By + default, this symlink points to prefix/var/nix/profiles/default. The PATH environment variable should - include ~/.nix-profile/bin for the user - environment to be visible to the user. + include ~/.nix-profile/bin for the + user environment to be visible to the user. @@ -143,6 +182,7 @@ + drvnames @@ -150,6 +190,189 @@ Description + The install operation creates a new user environment, based on + the current generation of the active profile, to which the + derivations designated by drvnames + in the active Nix expression are added. + + + + + + Examples + + +$ nix-env --install gcc-3.3.2 (install specific version) +$ nix-env --install gcc (just pick any version) +$ nix-env -f ~/foo.nix -i '*' (install everything in foo.nix) + + + + + + + + + + + Operation <option>--upgrade</option> + + + Synopsis + + nix-env + + + + + + + + + + drvnames + + + + + Description + + + The upgrade operation creates a new user environment, based on + the current generation of the active profile, in which all + derivations designated by drvnames + for which there are newer versions in the active Nix + expression are replaced by those newer versions. Matching + derivations for which there are no newer versions are left + untouched; this is not an error. It is also not an error if + an element of drvnames matches no + installed derivations. + + + + If multiple derivations in the active Nix expression match an + installed derivation, the one with the highest version is + selected. + + + + + + Flags + + + + + + + + Only upgrade a derivation to newer versions. This is + the default. + + + + + + + + + In addition to upgrading to newer versions, also + upgrade to derivations that have the same + version. Version are not a unique identification of a + derivation, so there may be many derivations that have + the same version. This flag may be useful to force + synchronisation between the installed and + available derivations. + + + + + + + + + In addition to upgrading to newer versions, also + upgrade to derivations that have the same + or a lower version. I.e., derivations may actually be + downgraded depending on what is available in the active + Nix expression. + + + + + + + + + + Examples + + +$ nix-env --upgrade gcc +upgrading `gcc-3.3.1' to `gcc-3.4' + +$ nix-env --upgrade pan +(no upgrades available, so nothing happens) + +$ nix-env -u '*' (try to upgrade everything) +upgrading `hello-2.1.2' to `hello-2.1.3' +upgrading `mozilla-1.2' to `mozilla-1.4' + + + + + Versions + + + The upgrade operation determines whether a derivation + y is an upgrade of a derivation + x by looking at their respective + name attributes. The names (e.g., + gcc-3.3.1 are split into two parts: the + package name (gcc), and the version + (3.3.1). The version part starts after the + first dash not following by a letter. x is + considered an upgrade of y if their package + names match, and the version of y is higher + that that of x. + + + + The versions are compared by splitting them into contiguous + components of numbers and letters. E.g., + 3.3.1pre5 is split into [3, 3, 1, + "pre", 5]. These lists are then compared + lexicographically (from left to right). Corresponding + components a and b are + compared as follows. If they are both numbers, integer + comparison is used. If a is an empty + string and b is a number, + a is considered less than + b. The special string component + pre (for pre-release) + is considered to be less than other components. String + components are considered less than number components. + Otherwise, they are compared lexicographically (i.e., using + case-sensitive string comparison). + + + + This is illustrated by the following examples: + + +1.0 < 2.3 +2.1 < 2.3 +2.3 = 2.3 +2.5 > 2.3 +3.1 > 2.3 +2.3.1 > 2.3 +2.3.1 > 2.3a +2.3pre1 < 2.3 +2.3pre3 < 2.3pre12 +2.3a < 2.3c +2.3pre1 < 2.3c +2.3pre1 < 2.3q + @@ -157,4 +380,218 @@ + + + + + Operation <option>--uninstall</option> + + + Synopsis + + nix-env + + + + + drvnames + + + + + Description + + + The uninstall operation creates a new user environment, based + on the current generation of the active profile, from which the + derivations designated by drvnames + are removed. + + + + + + Examples + + +$ nix-env --uninstall gcc +$ nix-env -e '*' (remove everything) + + + + + + + + + + + Operation <option>--query</option> + + + Synopsis + + nix-env + + + + + + + + + + + + + + + + + + + + Description + + + The query operation displays information about either the + derivations that are installed in the current generation of + the active profile (), or the + derivations that are available for installation in the active + Nix expression (). + + + + The derivations are sorted by their name + attributes. + + + + + + Source selection + + + The following flags specify the set of derivations on which + the query operates. + + + + + + + + + The query operates on the derivations that are installed + in the current generation of the active profile. This + is the default + + + + + + / + + + The query operates on the derivations that are available + in the active Nix expression. + + + + + + + + + + Queries + + + The following flags specify what information to display about + the selected derivations. Only one type of query may be + specified. + + + + + + + + + Prints the name attribute of each + derivation. This is the default. + + + + + + + + + Prints the store expression in the Nix store that + described the derivation. + + + + + + / + + + Prints the status of each + derivation, followed by its name + attribute. The status consists of three characters. + The first is I or + -, indicating whether the derivation + is currently installed in the current generation of the + active profile. This is by definition the case for + , but not for + . The second is + P or -, indicating + whether the derivation is present on the system. This + indicates whether installation of an available + derivation will require the derivation to be built. The + third is S or -, + indicating whether a substitute is available for the + derivation. + + + + + + + + + + Examples + + +$ nix-env -q (show installed derivations) +MozillaFirebird-0.7 +bison-1.875c +docbook-xml-4.2 +... + +$ nix-env -qa (show available derivations) +GConf-2.4.0.1 +MPlayer-1.0pre3 +MozillaFirebird-0.7 +ORBit2-2.8.3 +... + +$ nix-env -qas (show status of available derivations) +-P- GConf-2.4.0.1 (not installed but present) +--S MPlayer-1.0pre3 (not present, but there is a substitute for fast installation) +--S MozillaFirebird-0.7 (i.e., this is not the installed Firebird, even though the version is the same!) +IP- bison-1.875c (installed and by definition present) +... + +$ nix-env -f ./foo.nix -qa (show available derivations in the Nix expression foo.nix) +foo-1.2.3 + + + + + +