* Documented new nix-env options.

1 files changed, 131 insertions, 19 deletions

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" />.</para>
     <option>--rollback</option> operations, this flag will cause
     <command>nix-env</command> to print what
     <emphasis>would</emphasis> be done if this flag had not been
-    specified, without actually doing it.</para></listitem>
-    
+    specified, without actually doing it.</para>
+
+    <para><option>--dry-run</option> also prints out which paths will
+    be <link linkend="gloss-substitute">substituted</link> (i.e.,
+    downloaded) and which paths will be built from source (because no
+    substitute is available).</para></listitem>
+
   </varlistentry>
       
   <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term>
@@ -205,6 +210,14 @@ number of possible ways:
   <option>--preserve-installed</option> is
   specified.</para></listitem>
 
+  <listitem><para>If <link
+  linkend='opt-attr'><option>--attr</option></link>
+  (<option>-A</option>) is specified, the arguments are
+  <emphasis>attribute paths</emphasis> 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 <literal>nix-env -qaA '*'</literal>.</para></listitem>
+
   <listitem><para>If <option>--from-profile</option>
   <replaceable>path</replaceable> is given,
   <replaceable>args</replaceable> is a set of names denoting installed
@@ -280,6 +293,14 @@ installing `gcc-3.3.2'</screen>
 
 </para>
 
+<para>To install using a specific attribute:
+
+<screen>
+$ nix-env -i -A gcc40mips
+$ nix-env -i -A xorg.xorgserver</screen>
+
+</para>
+
 <para>To install all derivations in the Nix expression <filename>foo.nix</filename>:
 
 <screen>
@@ -322,6 +343,25 @@ selecting the <literal>subversionWithJava</literal> attribute from the
 attribute set returned by calling the function defined in
 <filename>./foo.nix</filename>.</para>
 
+<para>A dry-run tells you which paths will be downloaded or built from
+source:
+
+<screen>
+$ 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
+  <replaceable>...</replaceable>
+the following paths will be substituted:
+  /nix/store/8zbipvm4gp9jfqh9nnk1n3bary1a37gs-perl-XML-Parser-2.34
+  /nix/store/b8a2bg7gnyvvvjjibp4axg9x1hzkw36c-mono-1.1.4
+  <replaceable>...</replaceable></screen>
+  
+</para>
+
 </refsection>
     
 </refsection>
@@ -343,6 +383,7 @@ attribute set returned by calling the function defined in
   <group choice='opt'>
     <arg choice='plain'><option>--lt</option></arg>
     <arg choice='plain'><option>--leq</option></arg>
+    <arg choice='plain'><option>--eq</option></arg>
     <arg choice='plain'><option>--always</option></arg>
   </group>
   <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
@@ -391,6 +432,17 @@ installed.</para>
     
   </varlistentry>
 
+  <varlistentry><term><option>--eq</option></term>
+  
+    <listitem><para><emphasis>Only</emphasis> “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).</para></listitem>
+    
+  </varlistentry>
+
   <varlistentry><term><option>--always</option></term>
   
     <listitem><para>In addition to upgrading to newer versions, also
@@ -523,21 +575,37 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
     <arg choice='plain'><option>--query</option></arg>
     <arg choice='plain'><option>-q</option></arg>
   </group>
+  <arg><option>--xml</option></arg>
   <group choice='opt'>
     <arg choice='plain'><option>--installed</option></arg>
     <arg choice='plain'><option>--available</option></arg>
     <arg choice='plain'><option>-a</option></arg>
   </group>
-  <group choice='req'>
-    <arg choice='plain'><option>--status</option></arg>
-    <arg choice='plain'><option>-s</option></arg>
-    <arg choice='plain'><option>--no-name</option></arg>
-    <arg choice='plain'><option>--compare-versions</option></arg>
-    <arg choice='plain'><option>-c</option></arg>
-    <arg choice='plain'><option>--system</option></arg>
-    <arg choice='plain'><option>--drv-path</option></arg>
-    <arg choice='plain'><option>--out-path</option></arg>
-  </group>
+  <sbr />
+  <arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--status</option></arg>
+      <arg choice='plain'><option>-s</option></arg>
+    </group>
+  </arg>
+  <arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--attr</option></arg>
+      <arg choice='plain'><option>-A</option></arg>
+    </group>
+  </arg>
+  <arg><option>--no-name</option></arg>
+  <arg>
+    <group choice='req'>
+      <arg choice='plain'><option>--compare-versions</option></arg>
+      <arg choice='plain'><option>-c</option></arg>
+    </group>
+  </arg>
+  <arg><option>--system</option></arg>
+  <arg><option>--drv-path</option></arg>
+  <arg><option>--out-path</option></arg>
+  <arg><option>--description</option></arg>
+  <arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg>
 </cmdsynopsis>
 
 </refsection>
@@ -549,7 +617,10 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
 paths that are installed in the current generation of the active
 profile (<option>--installed</option>), or the derivations that are
 available for installation in the active Nix expression
-(<option>--available</option>).</para>
+(<option>--available</option>).  It only prints information about
+derivations whose symbolic name matches one of
+<replaceable>names</replaceable>.  The wildcard <literal>*</literal>
+shows all derivations.</para>
 
 <para>The derivations are sorted by their <literal>name</literal>
 attributes.</para>
@@ -598,6 +669,18 @@ user environment elements, etc. -->
 
 <variablelist>
 
+  <varlistentry><term><option>--xml</option></term>
+
+    <listitem><para>Print the result in an XML representation suitable
+    for automatic processing by other tools.  The root element is
+    called <literal>items</literal>, which contains a
+    <literal>item</literal> element for each available or installed
+    derivation.  The fields discussed below are all stored in
+    attributes of the <literal>item</literal>
+    elements.</para></listitem>
+
+  </varlistentry>
+
   <varlistentry><term><option>--status</option></term>
     <term><option>-s</option></term>
   
@@ -617,6 +700,17 @@ user environment elements, etc. -->
     
   </varlistentry>
 
+  <varlistentry><term><option>--attr</option></term>
+    <term><option>-a</option></term>
+
+    <listitem><para>Print the <emphasis>attribute path</emphasis> of
+    the derivation, which can be used to unambiguously select it using
+    the <link linkend="opt-attr"><option>--attr</option> option</link>
+    available in commands that install derivations like
+    <literal>nix-env --install</literal>.</para></listitem>
+
+  </varlistentry>
+  
   <varlistentry><term><option>--no-name</option></term>
   
     <listitem><para>Suppress printing of the <literal>name</literal>
@@ -690,6 +784,15 @@ user environment elements, etc. -->
     
   </varlistentry>
 
+  <varlistentry><term><option>--description</option></term>
+  
+    <listitem><para>Print a short (one-line) description of the
+    derivation, if available.  The description is taken from the
+    <literal>meta.description</literal> attribute of the
+    derivation.</para></listitem>
+    
+  </varlistentry>
+
 </variablelist>
 
 </refsection>
@@ -698,7 +801,7 @@ user environment elements, etc. -->
 <refsection><title>Examples</title>
 
 <screen>
-$ nix-env -q <lineannotation>(show installed derivations)</lineannotation>
+$ nix-env -q '*' <lineannotation>(show installed derivations)</lineannotation>
 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 <lineannotation>(show available derivations)</lineannotation>
+$ nix-env -qa '*' <lineannotation>(show available derivations)</lineannotation>
 firefox-1.0.7
 GConf-2.4.0.1
 MPlayer-1.0pre7
 ORBit2-2.8.3
 ...
 
-$ nix-env -qas <lineannotation>(show status of available derivations)</lineannotation>
+$ nix-env -qas '*' <lineannotation>(show status of available derivations)</lineannotation>
 -P- firefox-1.0.7   <lineannotation>(not installed but present)</lineannotation>
 --S GConf-2.4.0.1   <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation>
 --S MPlayer-1.0pre3 <lineannotation>(i.e., this is not the installed MPlayer, even though the version is the same!)</lineannotation>
 IP- ORBit2-2.8.3    <lineannotation>(installed and by definition present)</lineannotation>
 ...
 
-$ nix-env -f ./foo.nix -qa <lineannotation>(show available derivations in the Nix expression <!-- !!! <filename>-->foo.nix<!-- </filename> -->)</lineannotation>
+<lineannotation>(show available derivations in the Nix expression <!-- !!! <filename>-->foo.nix<!-- </filename> -->)</lineannotation>
+$ nix-env -f ./foo.nix -qa '*' 
 foo-1.2.3
 
-$ nix-env -qc <lineannotation>(compare installed versions to what’s available)</lineannotation>
+$ nix-env -qc '*' <lineannotation>(compare installed versions to what’s available)</lineannotation>
 <replaceable>...</replaceable>
 acrobat-reader-7.0 - ?      <lineannotation>(package is not available at all)</lineannotation>
 autoconf-2.59      = 2.59   <lineannotation>(same version)</lineannotation>
 firefox-1.0.4      &lt; 1.0.7  <lineannotation>(a more recent version is available)</lineannotation>
 <replaceable>...</replaceable>
-</screen>
+
+<lineannotation>(show info about a specific package, in XML)</lineannotation>
+$ nix-env -qa --xml --description firefox 
+<![CDATA[<?xml version='1.0' encoding='utf-8'?>
+<items>
+  <item attrPath="0.0.firefoxWrapper"
+    description="Mozilla Firefox - the browser, reloaded (with various plugins)"
+    name="firefox-1.5.0.7" system="i686-linux" />
+</items>]]></screen>
 
 </refsection>