diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index 6106d15f42..ff005830e1 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -109,8 +109,13 @@ linkend="sec-common-options" />.
operations, this flag will cause
nix-env to print what
would be done if this flag had not been
- specified, without actually doing it.
-
+ specified, without actually doing it.
+
+ also prints out which paths will
+ be substituted (i.e.,
+ downloaded) and which paths will be built from source (because no
+ substitute is available).
+
system
@@ -205,6 +210,14 @@ number of possible ways:
is
specified.
+ If
+ () is specified, the arguments are
+ attribute paths that select attributes from the
+ top-level Nix expression. This is faster than using derivation
+ names and unambiguous. To find out the attribute paths of available
+ packages, use nix-env -qaA '*'.
+
If
path is given,
args is a set of names denoting installed
@@ -280,6 +293,14 @@ installing `gcc-3.3.2'
+To install using a specific attribute:
+
+
+$ nix-env -i -A gcc40mips
+$ nix-env -i -A xorg.xorgserver
+
+
+
To install all derivations in the Nix expression foo.nix:
@@ -322,6 +343,25 @@ selecting the subversionWithJava attribute from the
attribute set returned by calling the function defined in
./foo.nix.
+A dry-run tells you which paths will be downloaded or built from
+source:
+
+
+$ nix-env -f pkgs/top-level/all-packages.nix -i f-spot --dry-run
+(dry run; not doing anything)
+installing `f-spot-0.0.10'
+the following derivations will be built:
+ /nix/store/0g63jv9aagwbgci4nnzs2dkxqz84kdja-libgnomeprintui-2.12.1.tar.bz2.drv
+ /nix/store/0gfarvxq6sannsdw8a1ir40j1ys2mqb4-ORBit2-2.14.2.tar.bz2.drv
+ /nix/store/0i9gs5zc04668qiy60ga2rc16abkj7g8-sqlite-2.8.17.drv
+ ...
+the following paths will be substituted:
+ /nix/store/8zbipvm4gp9jfqh9nnk1n3bary1a37gs-perl-XML-Parser-2.34
+ /nix/store/b8a2bg7gnyvvvjjibp4axg9x1hzkw36c-mono-1.1.4
+ ...
+
+
+
@@ -343,6 +383,7 @@ attribute set returned by calling the function defined in
+ args
@@ -391,6 +432,17 @@ installed.
+
+
+ Only “upgrade” to derivations
+ that have the same version. This may not seem very useful, but it
+ actually is, e.g., when there is a new release of Nixpkgs and you
+ want to replace installed applications with the same versions
+ built against newer dependencies (to reduce the number of
+ dependencies floating around on your system).
+
+
+
In addition to upgrading to newer versions, also
@@ -523,21 +575,37 @@ $ nix-env -e '*' (remove everything)
+
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ names
@@ -549,7 +617,10 @@ $ nix-env -e '*' (remove everything)
paths that are installed in the current generation of the active
profile (), or the derivations that are
available for installation in the active Nix expression
-().
+(). It only prints information about
+derivations whose symbolic name matches one of
+names. The wildcard *
+shows all derivations.
The derivations are sorted by their name
attributes.
@@ -598,6 +669,18 @@ user environment elements, etc. -->
+
+
+ Print the result in an XML representation suitable
+ for automatic processing by other tools. The root element is
+ called items, which contains a
+ item element for each available or installed
+ derivation. The fields discussed below are all stored in
+ attributes of the item
+ elements.
+
+
+
@@ -617,6 +700,17 @@ user environment elements, etc. -->
+
+
+
+ Print the attribute path of
+ the derivation, which can be used to unambiguously select it using
+ the option
+ available in commands that install derivations like
+ nix-env --install.
+
+
+
Suppress printing of the name
@@ -690,6 +784,15 @@ user environment elements, etc. -->
+
+
+ Print a short (one-line) description of the
+ derivation, if available. The description is taken from the
+ meta.description attribute of the
+ derivation.
+
+
+
@@ -698,7 +801,7 @@ user environment elements, etc. -->
Examples
-$ nix-env -q (show installed derivations)
+$ nix-env -q '*' (show installed derivations)
bison-1.875c
docbook-xml-4.2
firefox-1.0.4
@@ -706,30 +809,39 @@ MPlayer-1.0pre7
ORBit2-2.8.3
...
-$ nix-env -qa (show available derivations)
+$ nix-env -qa '*' (show available derivations)
firefox-1.0.7
GConf-2.4.0.1
MPlayer-1.0pre7
ORBit2-2.8.3
...
-$ nix-env -qas (show status of available derivations)
+$ nix-env -qas '*' (show status of available derivations)
-P- firefox-1.0.7 (not installed but present)
--S GConf-2.4.0.1 (not present, but there is a substitute for fast installation)
--S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
IP- ORBit2-2.8.3 (installed and by definition present)
...
-$ nix-env -f ./foo.nix -qa (show available derivations in the Nix expression foo.nix)
+(show available derivations in the Nix expression foo.nix)
+$ nix-env -f ./foo.nix -qa '*'
foo-1.2.3
-$ nix-env -qc (compare installed versions to what’s available)
+$ nix-env -qc '*' (compare installed versions to what’s available)...
acrobat-reader-7.0 - ? (package is not available at all)
autoconf-2.59 = 2.59 (same version)
firefox-1.0.4 < 1.0.7 (a more recent version is available)...
-
+
+(show info about a specific package, in XML)
+$ nix-env -qa --xml --description firefox
+
+
+
+]]>