about summary refs log tree commit diff
path: root/third_party/nix/doc/manual/command-ref/nix-env.xml
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/nix/doc/manual/command-ref/nix-env.xml')
-rw-r--r--third_party/nix/doc/manual/command-ref/nix-env.xml1505
1 files changed, 0 insertions, 1505 deletions
diff --git a/third_party/nix/doc/manual/command-ref/nix-env.xml b/third_party/nix/doc/manual/command-ref/nix-env.xml
deleted file mode 100644
index d257a5e49c70..000000000000
--- a/third_party/nix/doc/manual/command-ref/nix-env.xml
+++ /dev/null
@@ -1,1505 +0,0 @@
-<refentry xmlns="http://docbook.org/ns/docbook"
-      xmlns:xlink="http://www.w3.org/1999/xlink"
-      xmlns:xi="http://www.w3.org/2001/XInclude"
-      version="5.0"
-      xml:id="sec-nix-env">
-
-<refmeta>
-  <refentrytitle>nix-env</refentrytitle>
-  <manvolnum>1</manvolnum>
-  <refmiscinfo class="source">Nix</refmiscinfo>
-  <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
-</refmeta>
-
-<refnamediv>
-  <refname>nix-env</refname>
-  <refpurpose>manipulate or query Nix user environments</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-  <cmdsynopsis>
-    <command>nix-env</command>
-    <xi:include href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
-    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
-    <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
-    <arg>
-      <group choice='req'>
-        <arg choice='plain'><option>--file</option></arg>
-        <arg choice='plain'><option>-f</option></arg>
-      </group>
-      <replaceable>path</replaceable>
-    </arg>
-    <arg>
-      <group choice='req'>
-        <arg choice='plain'><option>--profile</option></arg>
-        <arg choice='plain'><option>-p</option></arg>
-      </group>
-      <replaceable>path</replaceable>
-    </arg>
-    <arg>
-      <arg choice='plain'><option>--system-filter</option></arg>
-      <replaceable>system</replaceable>
-    </arg>
-    <arg><option>--dry-run</option></arg>
-    <arg choice='plain'><replaceable>operation</replaceable></arg>
-    <arg rep='repeat'><replaceable>options</replaceable></arg>
-    <arg rep='repeat'><replaceable>arguments</replaceable></arg>
-  </cmdsynopsis>
-</refsynopsisdiv>
-
-
-<refsection><title>Description</title>
-
-<para>The command <command>nix-env</command> is used to manipulate Nix
-user environments.  User environments are sets of software packages
-available to a user at some point in time.  In other words, they are a
-synthesised view of the programs available in the Nix store.  There
-may be many user environments: different users can have different
-environments, and individual users can switch between different
-environments.</para>
-
-<para><command>nix-env</command> takes exactly one
-<emphasis>operation</emphasis> flag which indicates the subcommand to
-be performed.  These are documented below.</para>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Selectors</title>
-
-<para>Several commands, such as <command>nix-env -q</command> and
-<command>nix-env -i</command>, take a list of arguments that specify
-the packages on which to operate. These are extended regular
-expressions that must match the entire name of the package. (For
-details on regular expressions, see
-<citerefentry><refentrytitle>regex</refentrytitle><manvolnum>7</manvolnum></citerefentry>.)
-The match is case-sensitive. The regular expression can optionally be
-followed by a dash and a version number; if omitted, any version of
-the package will match.  Here are some examples:
-
-<variablelist>
-
-  <varlistentry>
-    <term><literal>firefox</literal></term>
-    <listitem><para>Matches the package name
-    <literal>firefox</literal> and any version.</para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><literal>firefox-32.0</literal></term>
-    <listitem><para>Matches the package name
-    <literal>firefox</literal> and version
-    <literal>32.0</literal>.</para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><literal>gtk\\+</literal></term>
-    <listitem><para>Matches the package name
-    <literal>gtk+</literal>. The <literal>+</literal> character must
-    be escaped using a backslash to prevent it from being interpreted
-    as a quantifier, and the backslash must be escaped in turn with
-    another backslash to ensure that the shell passes it
-    on.</para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><literal>.\*</literal></term>
-    <listitem><para>Matches any package name. This is the default for
-    most commands.</para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><literal>'.*zip.*'</literal></term>
-    <listitem><para>Matches any package name containing the string
-    <literal>zip</literal>. Note the dots: <literal>'*zip*'</literal>
-    does not work, because in a regular expression, the character
-    <literal>*</literal> is interpreted as a
-    quantifier.</para></listitem>
-  </varlistentry>
-
-  <varlistentry>
-    <term><literal>'.*(firefox|chromium).*'</literal></term>
-    <listitem><para>Matches any package name containing the strings
-    <literal>firefox</literal> or
-    <literal>chromium</literal>.</para></listitem>
-  </varlistentry>
-
-</variablelist>
-
-</para>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Common options</title>
-
-<para>This section lists the options that are common to all
-operations.  These options are allowed for every subcommand, though
-they may not always have an effect.  <phrase condition="manual">See
-also <xref linkend="sec-common-options" />.</phrase></para>
-
-<variablelist>
-
-  <varlistentry><term><option>--file</option> / <option>-f</option> <replaceable>path</replaceable></term>
-
-    <listitem><para>Specifies the Nix expression (designated below as
-    the <emphasis>active Nix expression</emphasis>) used by the
-    <option>--install</option>, <option>--upgrade</option>, and
-    <option>--query --available</option> operations to obtain
-    derivations.  The default is
-    <filename>~/.nix-defexpr</filename>.</para>
-
-    <para>If the argument starts with <literal>http://</literal> or
-    <literal>https://</literal>, it is interpreted as the URL of a
-    tarball that will be downloaded and unpacked to a temporary
-    location. The tarball must include a single top-level directory
-    containing at least a file named <filename>default.nix</filename>.</para>
-
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--profile</option> / <option>-p</option> <replaceable>path</replaceable></term>
-
-    <listitem><para>Specifies the profile to be used by those
-    operations that operate on a profile (designated below as the
-    <emphasis>active profile</emphasis>).  A profile is a sequence of
-    user environments called <emphasis>generations</emphasis>, one of
-    which is the <emphasis>current
-    generation</emphasis>.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--dry-run</option></term>
-
-    <listitem><para>For the <option>--install</option>,
-    <option>--upgrade</option>, <option>--uninstall</option>,
-    <option>--switch-generation</option>,
-    <option>--delete-generations</option> and
-    <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>
-
-    <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>
-
-    <listitem><para>By default, operations such as <option>--query
-    --available</option> show derivations matching any platform.  This
-    option allows you to use derivations for the specified platform
-    <replaceable>system</replaceable>.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-<variablelist condition="manpage">
-  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
-</variablelist>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Files</title>
-
-<variablelist>
-
-  <varlistentry><term><filename>~/.nix-defexpr</filename></term>
-
-    <listitem><para>The source for the default Nix
-    expressions used by the <option>--install</option>,
-    <option>--upgrade</option>, and <option>--query
-    --available</option> operations to obtain derivations. The
-    <option>--file</option> option may be used to override this
-    default.</para>
-
-    <para>If <filename>~/.nix-defexpr</filename> is a file,
-    it is loaded as a Nix expression. If the expression
-    is a set, it is used as the default Nix expression.
-    If the expression is a function, an empty set is passed
-    as argument and the return value is used as
-    the default Nix expression.</para>
-
-    <para>If <filename>~/.nix-defexpr</filename> is a directory
-    containing a <filename>default.nix</filename> file, that file
-    is loaded as in the above paragraph.</para>
-
-    <para>If <filename>~/.nix-defexpr</filename> is a directory without
-    a <filename>default.nix</filename> file, then its contents
-    (both files and subdirectories) are loaded as Nix expressions.
-    The expressions are combined into a single set, each expression
-    under an attribute with the same name as the original file
-    or subdirectory.
-    </para>
-
-    <para>For example, if <filename>~/.nix-defexpr</filename> contains
-    two files, <filename>foo.nix</filename> and <filename>bar.nix</filename>,
-    then the default Nix expression will essentially be
-
-<programlisting>
-{
-  foo = import ~/.nix-defexpr/foo.nix;
-  bar = import ~/.nix-defexpr/bar.nix;
-}</programlisting>
-
-    </para>
-
-    <para>The file <filename>manifest.nix</filename> is always ignored.
-    Subdirectories without a <filename>default.nix</filename> file
-    are traversed recursively in search of more Nix expressions,
-    but the names of these intermediate directories are not
-    added to the attribute paths of the default Nix expression.</para>
-
-    <para>The command <command>nix-channel</command> places symlinks
-    to the downloaded Nix expressions from each subscribed channel in
-    this directory.</para>
-    </listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><filename>~/.nix-profile</filename></term>
-
-    <listitem><para>A symbolic link to the user's current profile.  By
-    default, this symlink points to
-    <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>.
-    The <envar>PATH</envar> environment variable should include
-    <filename>~/.nix-profile/bin</filename> for the user environment
-    to be visible to the user.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection xml:id="rsec-nix-env-install"><title>Operation <option>--install</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <group choice='req'>
-    <arg choice='plain'><option>--install</option></arg>
-    <arg choice='plain'><option>-i</option></arg>
-  </group>
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
-  <group choice='opt'>
-    <arg choice='plain'><option>--preserve-installed</option></arg>
-    <arg choice='plain'><option>-P</option></arg>
-  </group>
-  <group choice='opt'>
-    <arg choice='plain'><option>--remove-all</option></arg>
-    <arg choice='plain'><option>-r</option></arg>
-  </group>
-  <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
-</cmdsynopsis>
-
-</refsection>
-
-
-<refsection><title>Description</title>
-
-<para>The install operation creates a new user environment, based on
-the current generation of the active profile, to which a set of store
-paths described by <replaceable>args</replaceable> is added.  The
-arguments <replaceable>args</replaceable> map to store paths in a
-number of possible ways:
-
-<itemizedlist>
-
-  <listitem><para>By default, <replaceable>args</replaceable> is a set
-  of derivation names denoting derivations in the active Nix
-  expression.  These are realised, and the resulting output paths are
-  installed.  Currently installed derivations with a name equal to the
-  name of a derivation being added are removed unless the option
-  <option>--preserve-installed</option> is
-  specified.</para>
-
-  <para>If there are multiple derivations matching a name in
-  <replaceable>args</replaceable> that have the same name (e.g.,
-  <literal>gcc-3.3.6</literal> and <literal>gcc-4.1.1</literal>), then
-  the derivation with the highest <emphasis>priority</emphasis> is
-  used.  A derivation can define a priority by declaring the
-  <varname>meta.priority</varname> attribute.  This attribute should
-  be a number, with a higher value denoting a lower priority.  The
-  default priority is <literal>0</literal>.</para>
-
-  <para>If there are multiple matching derivations with the same
-  priority, then the derivation with the highest version will be
-  installed.</para>
-
-  <para>You can force the installation of multiple derivations with
-  the same name by being specific about the versions.  For instance,
-  <literal>nix-env -i gcc-3.3.6 gcc-4.1.1</literal> will install both
-  version of GCC (and will probably cause a user environment
-  conflict!).</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 -qaP</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
-  store paths in the profile <replaceable>path</replaceable>.  This is
-  an easy way to copy user environment elements from one profile to
-  another.</para></listitem>
-
-  <listitem><para>If <option>--from-expression</option> is given,
-  <replaceable>args</replaceable> are Nix <link
-  linkend="ss-functions">functions</link> that are called with the
-  active Nix expression as their single argument.  The derivations
-  returned by those function calls are installed.  This allows
-  derivations to be specified in an unambiguous way, which is necessary
-  if there are multiple derivations with the same
-  name.</para></listitem>
-
-  <listitem><para>If <replaceable>args</replaceable> are store
-  derivations, then these are <link
-  linkend="rsec-nix-store-realise">realised</link>, and the resulting
-  output paths are installed.</para></listitem>
-
-  <listitem><para>If <replaceable>args</replaceable> are store paths
-  that are not store derivations, then these are <link
-  linkend="rsec-nix-store-realise">realised</link> and
-  installed.</para></listitem>
-
-  <listitem><para>By default all outputs are installed for each derivation.
-  That can be reduced by setting <literal>meta.outputsToInstall</literal>.
-  </para></listitem> <!-- TODO: link nixpkgs docs on the ability to override those. -->
-
-</itemizedlist>
-
-</para>
-
-</refsection>
-
-
-<refsection><title>Flags</title>
-
-<variablelist>
-
-  <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term>
-
-    <listitem><para>Use only derivations for which a substitute is
-    registered, i.e., there is a pre-built binary available that can
-    be downloaded in lieu of building the derivation.  Thus, no
-    packages will be built from source.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--preserve-installed</option></term>
-    <term><option>-P</option></term>
-
-    <listitem><para>Do not remove derivations with a name matching one
-    of the derivations being installed.  Usually, trying to have two
-    versions of the same package installed in the same generation of a
-    profile will lead to an error in building the generation, due to
-    file name clashes between the two versions.  However, this is not
-    the case for all packages.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--remove-all</option></term>
-    <term><option>-r</option></term>
-
-    <listitem><para>Remove all previously installed packages first.
-    This is equivalent to running <literal>nix-env -e '.*'</literal>
-    first, except that everything happens in a single
-    transaction.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-</refsection>
-
-
-<refsection xml:id='refsec-nix-env-install-examples'><title>Examples</title>
-
-<para>To install a specific version of <command>gcc</command> from the
-active Nix expression:
-
-<screen>
-$ nix-env --install gcc-3.3.2
-installing `gcc-3.3.2'
-uninstalling `gcc-3.1'</screen>
-
-Note the previously installed version is removed, since
-<option>--preserve-installed</option> was not specified.</para>
-
-<para>To install an arbitrary version:
-
-<screen>
-$ nix-env --install gcc
-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>
-$ nix-env -f ~/foo.nix -i '.*'</screen>
-
-</para>
-
-<para>To copy the store path with symbolic name <literal>gcc</literal>
-from another profile:
-
-<screen>
-$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc</screen>
-
-</para>
-
-<para>To install a specific store derivation (typically created by
-<command>nix-instantiate</command>):
-
-<screen>
-$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv</screen>
-
-</para>
-
-<para>To install a specific output path:
-
-<screen>
-$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</screen>
-
-</para>
-
-<para>To install from a Nix expression specified on the command-line:
-
-<screen>
-$ nix-env -f ./foo.nix -i -E \
-    'f: (f {system = "i686-linux";}).subversionWithJava'</screen>
-
-I.e., this evaluates to <literal>(f: (f {system =
-"i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus
-selecting the <literal>subversionWithJava</literal> attribute from the
-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 '&lt;nixpkgs>' -iA hello --dry-run
-(dry run; not doing anything)
-installing ‘hello-2.10’
-these paths will be fetched (0.04 MiB download, 0.19 MiB unpacked):
-  /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
-  <replaceable>...</replaceable></screen>
-
-</para>
-
-<para>To install Firefox from the latest revision in the Nixpkgs/NixOS
-14.12 channel:
-
-<screen>
-$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox
-</screen>
-
-(The GitHub repository <literal>nixpkgs-channels</literal> is updated
-automatically from the main <literal>nixpkgs</literal> repository
-after certain tests have succeeded and binaries have been built and
-uploaded to the binary cache at <uri>cache.nixos.org</uri>.)</para>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection xml:id="rsec-nix-env-upgrade"><title>Operation <option>--upgrade</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <group choice='req'>
-    <arg choice='plain'><option>--upgrade</option></arg>
-    <arg choice='plain'><option>-u</option></arg>
-  </group>
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
-  <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>
-</cmdsynopsis>
-
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>The upgrade operation creates a new user environment, based on
-the current generation of the active profile, in which all store paths
-are replaced for which there are newer versions in the set of paths
-described by <replaceable>args</replaceable>.  Paths 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 <replaceable>args</replaceable>
-matches no installed derivations.</para>
-
-<para>For a description of how <replaceable>args</replaceable> is
-mapped to a set of store paths, see <link
-linkend="rsec-nix-env-install"><option>--install</option></link>.  If
-<replaceable>args</replaceable> describes multiple store paths with
-the same symbolic name, only the one with the highest version is
-installed.</para>
-
-</refsection>
-
-<refsection><title>Flags</title>
-
-<variablelist>
-
-  <varlistentry><term><option>--lt</option></term>
-
-    <listitem><para>Only upgrade a derivation to newer versions.  This
-    is the default.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--leq</option></term>
-
-    <listitem><para>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.</para></listitem>
-
-  </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
-    “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.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-<para>For the other flags, see <option
-linkend="rsec-nix-env-install">--install</option>.</para>
-
-</refsection>
-
-<refsection><title>Examples</title>
-
-<screen>
-$ nix-env --upgrade gcc
-upgrading `gcc-3.3.1' to `gcc-3.4'
-
-$ nix-env -u gcc-3.3.2 --always <lineannotation>(switch to a specific version)</lineannotation>
-upgrading `gcc-3.4' to `gcc-3.3.2'
-
-$ nix-env --upgrade pan
-<lineannotation>(no upgrades available, so nothing happens)</lineannotation>
-
-$ nix-env -u <lineannotation>(try to upgrade everything)</lineannotation>
-upgrading `hello-2.1.2' to `hello-2.1.3'
-upgrading `mozilla-1.2' to `mozilla-1.4'</screen>
-
-</refsection>
-
-<refsection xml:id="ssec-version-comparisons"><title>Versions</title>
-
-<para>The upgrade operation determines whether a derivation
-<varname>y</varname> is an upgrade of a derivation
-<varname>x</varname> by looking at their respective
-<literal>name</literal> attributes.  The names (e.g.,
-<literal>gcc-3.3.1</literal> are split into two parts: the package
-name (<literal>gcc</literal>), and the version
-(<literal>3.3.1</literal>).  The version part starts after the first
-dash not followed by a letter.  <varname>x</varname> is considered an
-upgrade of <varname>y</varname> if their package names match, and the
-version of <varname>y</varname> is higher that that of
-<varname>x</varname>.</para>
-
-<para>The versions are compared by splitting them into contiguous
-components of numbers and letters.  E.g., <literal>3.3.1pre5</literal>
-is split into <literal>[3, 3, 1, "pre", 5]</literal>.  These lists are
-then compared lexicographically (from left to right).  Corresponding
-components <varname>a</varname> and <varname>b</varname> are compared
-as follows.  If they are both numbers, integer comparison is used.  If
-<varname>a</varname> is an empty string and <varname>b</varname> is a
-number, <varname>a</varname> is considered less than
-<varname>b</varname>.  The special string component
-<literal>pre</literal> (for <emphasis>pre-release</emphasis>) 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).</para>
-
-<para>This is illustrated by the following examples:
-
-<screen>
-1.0 &lt; 2.3
-2.1 &lt; 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 &lt; 2.3
-2.3pre3 &lt; 2.3pre12
-2.3a &lt; 2.3c
-2.3pre1 &lt; 2.3c
-2.3pre1 &lt; 2.3q</screen>
-
-</para>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--uninstall</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <group choice='req'>
-    <arg choice='plain'><option>--uninstall</option></arg>
-    <arg choice='plain'><option>-e</option></arg>
-  </group>
-  <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
-</cmdsynopsis>
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>The uninstall operation creates a new user environment, based on
-the current generation of the active profile, from which the store
-paths designated by the symbolic names
-<replaceable>names</replaceable> are removed.</para>
-
-</refsection>
-
-<refsection><title>Examples</title>
-
-<screen>
-$ nix-env --uninstall gcc
-$ nix-env -e '.*' <lineannotation>(remove everything)</lineannotation></screen>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection xml:id="rsec-nix-env-set"><title>Operation <option>--set</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <arg choice='plain'><option>--set</option></arg>
-  <arg choice='plain'><replaceable>drvname</replaceable></arg>
-</cmdsynopsis>
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>The <option>--set</option> operation modifies the current generation of a
-profile so that it contains exactly the specified derivation, and nothing else.
-</para>
-
-</refsection>
-
-<refsection><title>Examples</title>
-
-<para>
-The following updates a profile such that its current generation will contain
-just Firefox:
-
-<screen>
-$ nix-env -p /nix/var/nix/profiles/browser --set firefox</screen>
-
-</para>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection xml:id="rsec-nix-env-set-flag"><title>Operation <option>--set-flag</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <arg choice='plain'><option>--set-flag</option></arg>
-  <arg choice='plain'><replaceable>name</replaceable></arg>
-  <arg choice='plain'><replaceable>value</replaceable></arg>
-  <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg>
-</cmdsynopsis>
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>The <option>--set-flag</option> operation allows meta attributes
-of installed packages to be modified.  There are several attributes
-that can be usefully modified, because they affect the behaviour of
-<command>nix-env</command> or the user environment build
-script:
-
-<itemizedlist>
-
-  <listitem><para><varname>priority</varname> can be changed to
-  resolve filename clashes.  The user environment build script uses
-  the <varname>meta.priority</varname> attribute of derivations to
-  resolve filename collisions between packages.  Lower priority values
-  denote a higher priority.  For instance, the GCC wrapper package and
-  the Binutils package in Nixpkgs both have a file
-  <filename>bin/ld</filename>, so previously if you tried to install
-  both you would get a collision.  Now, on the other hand, the GCC
-  wrapper declares a higher priority than Binutils, so the former’s
-  <filename>bin/ld</filename> is symlinked in the user
-  environment.</para></listitem>
-
-  <listitem><para><varname>keep</varname> can be set to
-  <literal>true</literal> to prevent the package from being upgraded
-  or replaced.  This is useful if you want to hang on to an older
-  version of a package.</para></listitem>
-
-  <listitem><para><varname>active</varname> can be set to
-  <literal>false</literal> to “disable” the package.  That is, no
-  symlinks will be generated to the files of the package, but it
-  remains part of the profile (so it won’t be garbage-collected).  It
-  can be set back to <literal>true</literal> to re-enable the
-  package.</para></listitem>
-
-</itemizedlist>
-
-</para>
-
-</refsection>
-
-<refsection><title>Examples</title>
-
-<para>To prevent the currently installed Firefox from being upgraded:
-
-<screen>
-$ nix-env --set-flag keep true firefox</screen>
-
-After this, <command>nix-env -u</command> will ignore Firefox.</para>
-
-<para>To disable the currently installed Firefox, then install a new
-Firefox while the old remains part of the profile:
-
-<screen>
-$ nix-env -q
-firefox-2.0.0.9 <lineannotation>(the current one)</lineannotation>
-
-$ nix-env --preserve-installed -i firefox-2.0.0.11
-installing `firefox-2.0.0.11'
-building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
-collision between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox'
-  and `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.9/bin/firefox'.
-<lineannotation>(i.e., can’t have two active at the same time)</lineannotation>
-
-$ nix-env --set-flag active false firefox
-setting flag on `firefox-2.0.0.9'
-
-$ nix-env --preserve-installed -i firefox-2.0.0.11
-installing `firefox-2.0.0.11'
-
-$ nix-env -q
-firefox-2.0.0.11 <lineannotation>(the enabled one)</lineannotation>
-firefox-2.0.0.9 <lineannotation>(the disabled one)</lineannotation></screen>
-
-</para>
-
-<para>To make files from <literal>binutils</literal> take precedence
-over files from <literal>gcc</literal>:
-
-<screen>
-$ nix-env --set-flag priority 5 binutils
-$ nix-env --set-flag priority 10 gcc</screen>
-
-</para>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--query</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <group choice='req'>
-    <arg choice='plain'><option>--query</option></arg>
-    <arg choice='plain'><option>-q</option></arg>
-  </group>
-  <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>
-
-  <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-path</option></arg>
-      <arg choice='plain'><option>-P</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><option>--meta</option></arg>
-
-  <sbr />
-
-  <arg><option>--xml</option></arg>
-  <arg><option>--json</option></arg>
-  <arg>
-    <group choice='req'>
-      <arg choice='plain'><option>--prebuilt-only</option></arg>
-      <arg choice='plain'><option>-b</option></arg>
-    </group>
-  </arg>
-
-  <arg>
-    <group choice='req'>
-      <arg choice='plain'><option>--attr</option></arg>
-      <arg choice='plain'><option>-A</option></arg>
-    </group>
-    <replaceable>attribute-path</replaceable>
-  </arg>
-
-  <sbr />
-
-  <arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg>
-</cmdsynopsis>
-
-</refsection>
-
-
-<refsection><title>Description</title>
-
-<para>The query operation displays information about either the store
-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>).  It only prints information about
-derivations whose symbolic name matches one of
-<replaceable>names</replaceable>.</para>
-
-<para>The derivations are sorted by their <literal>name</literal>
-attributes.</para>
-
-</refsection>
-
-
-<refsection><title>Source selection</title>
-
-<para>The following flags specify the set of things on which the query
-operates.</para>
-
-<variablelist>
-
-  <varlistentry><term><option>--installed</option></term>
-
-    <listitem><para>The query operates on the store paths that are
-    installed in the current generation of the active profile.  This
-    is the default.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--available</option></term>
-    <term><option>-a</option></term>
-
-    <listitem><para>The query operates on the derivations that are
-    available in the active Nix expression.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-</refsection>
-
-
-<refsection><title>Queries</title>
-
-<para>The following flags specify what information to display about
-the selected derivations.  Multiple flags may be specified, in which
-case the information is shown in the order given here.  Note that the
-name of the derivation is shown unless <option>--no-name</option> is
-specified.</para>
-
-<!-- TODO: fix the terminology here; i.e., derivations, store paths,
-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>--json</option></term>
-
-    <listitem><para>Print the result in a JSON representation suitable
-    for automatic processing by other tools.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term>
-
-    <listitem><para>Show only derivations for which a substitute is
-    registered, i.e., there is a pre-built binary available that can
-    be downloaded in lieu of building the derivation.  Thus, this
-    shows all packages that probably can be installed
-    quickly.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--status</option></term>
-    <term><option>-s</option></term>
-
-    <listitem><para>Print the <emphasis>status</emphasis> of the
-    derivation.  The status consists of three characters.  The first
-    is <literal>I</literal> or <literal>-</literal>, indicating
-    whether the derivation is currently installed in the current
-    generation of the active profile.  This is by definition the case
-    for <option>--installed</option>, but not for
-    <option>--available</option>.  The second is <literal>P</literal>
-    or <literal>-</literal>, 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 <literal>S</literal> or <literal>-</literal>, indicating
-    whether a substitute is available for the
-    derivation.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--attr-path</option></term>
-    <term><option>-P</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>
-    attribute of each derivation.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--compare-versions</option> /
-  <option>-c</option></term>
-
-    <listitem><para>Compare installed versions to available versions,
-    or vice versa (if <option>--available</option> is given).  This is
-    useful for quickly seeing whether upgrades for installed
-    packages are available in a Nix expression.  A column is added
-    with the following meaning:
-
-    <variablelist>
-
-      <varlistentry><term><literal>&lt;</literal> <replaceable>version</replaceable></term>
-
-        <listitem><para>A newer version of the package is available
-        or installed.</para></listitem>
-
-      </varlistentry>
-
-      <varlistentry><term><literal>=</literal> <replaceable>version</replaceable></term>
-
-        <listitem><para>At most the same version of the package is
-        available or installed.</para></listitem>
-
-      </varlistentry>
-
-      <varlistentry><term><literal>></literal> <replaceable>version</replaceable></term>
-
-        <listitem><para>Only older versions of the package are
-        available or installed.</para></listitem>
-
-      </varlistentry>
-
-      <varlistentry><term><literal>- ?</literal></term>
-
-        <listitem><para>No version of the package is available or
-        installed.</para></listitem>
-
-      </varlistentry>
-
-    </variablelist>
-
-    </para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--system</option></term>
-
-    <listitem><para>Print the <literal>system</literal> attribute of
-    the derivation.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--drv-path</option></term>
-
-    <listitem><para>Print the path of the store
-    derivation.</para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--out-path</option></term>
-
-    <listitem><para>Print the output path of the
-    derivation.</para></listitem>
-
-  </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>
-
-  <varlistentry><term><option>--meta</option></term>
-
-    <listitem><para>Print all of the meta-attributes of the
-    derivation.  This option is only available with
-    <option>--xml</option> or <option>--json</option>.</para></listitem>
-
-  </varlistentry>
-
-</variablelist>
-
-</refsection>
-
-
-<refsection><title>Examples</title>
-
-<para>To show installed packages:
-
-<screen>
-$ nix-env -q
-bison-1.875c
-docbook-xml-4.2
-firefox-1.0.4
-MPlayer-1.0pre7
-ORBit2-2.8.3
-<replaceable>…</replaceable>
-</screen>
-
-</para>
-
-<para>To show available packages:
-
-<screen>
-$ nix-env -qa
-firefox-1.0.7
-GConf-2.4.0.1
-MPlayer-1.0pre7
-ORBit2-2.8.3
-<replaceable>…</replaceable>
-</screen>
-
-</para>
-
-<para>To show the status of available packages:
-
-<screen>
-$ nix-env -qas
--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>
-<replaceable>…</replaceable>
-</screen>
-
-</para>
-
-<para>To show available packages in the Nix expression <filename>foo.nix</filename>:
-
-<screen>
-$ nix-env -f ./foo.nix -qa
-foo-1.2.3
-</screen>
-
-</para>
-
-<para>To compare installed versions to what’s available:
-
-<screen>
-$ nix-env -qc
-<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>
-
-</para>
-
-<para>To show all packages with “<literal>zip</literal>” in the name:
-
-<screen>
-$ nix-env -qa '.*zip.*'
-bzip2-1.0.6
-gzip-1.6
-zip-3.0
-<replaceable>…</replaceable>
-</screen>
-
-</para>
-
-<para>To show all packages with “<literal>firefox</literal>” or
-“<literal>chromium</literal>” in the name:
-
-<screen>
-$ nix-env -qa '.*(firefox|chromium).*'
-chromium-37.0.2062.94
-chromium-beta-38.0.2125.24
-firefox-32.0.3
-firefox-with-plugins-13.0.1
-<replaceable>…</replaceable>
-</screen>
-
-</para>
-
-<para>To show all packages in the latest revision of the Nixpkgs
-repository:
-
-<screen>
-$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
-</screen>
-
-</para>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--switch-profile</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <group choice='req'>
-    <arg choice='plain'><option>--switch-profile</option></arg>
-    <arg choice='plain'><option>-S</option></arg>
-  </group>
-  <arg choice='req'><replaceable>path</replaceable></arg>
-</cmdsynopsis>
-
-</refsection>
-
-
-<refsection><title>Description</title>
-
-<para>This operation makes <replaceable>path</replaceable> the current
-profile for the user.  That is, the symlink
-<filename>~/.nix-profile</filename> is made to point to
-<replaceable>path</replaceable>.</para>
-
-</refsection>
-
-<refsection><title>Examples</title>
-
-<screen>
-$ nix-env -S ~/my-profile</screen>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--list-generations</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <arg choice='plain'><option>--list-generations</option></arg>
-</cmdsynopsis>
-
-</refsection>
-
-
-<refsection><title>Description</title>
-
-<para>This operation print a list of all the currently existing
-generations for the active profile.  These may be switched to using
-the <option>--switch-generation</option> operation.  It also prints
-the creation date of the generation, and indicates the current
-generation.</para>
-
-</refsection>
-
-
-<refsection><title>Examples</title>
-
-<screen>
-$ nix-env --list-generations
-  95   2004-02-06 11:48:24
-  96   2004-02-06 11:49:01
-  97   2004-02-06 16:22:45
-  98   2004-02-06 16:24:33   (current)</screen>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--delete-generations</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <arg choice='plain'><option>--delete-generations</option></arg>
-  <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg>
-</cmdsynopsis>
-
-</refsection>
-
-
-<refsection><title>Description</title>
-
-<para>This operation deletes the specified generations of the current
-profile.  The generations can be a list of generation numbers, the
-special value <literal>old</literal> to delete all non-current
-generations,  a value such as <literal>30d</literal> to delete all
-generations older than the specified number of days (except for the
-generation that was active at that point in time), or a value such as
-<literal>+5</literal> to keep the last <literal>5</literal> generations
-ignoring any newer than current, e.g., if <literal>30</literal> is the current
-generation <literal>+5</literal> will delete generation <literal>25</literal>
-and all older generations.
-Periodically deleting old generations is important to make garbage collection
-effective.</para>
-
-</refsection>
-
-<refsection><title>Examples</title>
-
-<screen>
-$ nix-env --delete-generations 3 4 8
-
-$ nix-env --delete-generations +5
-
-$ nix-env --delete-generations 30d
-
-$ nix-env -p other_profile --delete-generations old</screen>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--switch-generation</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <group choice='req'>
-    <arg choice='plain'><option>--switch-generation</option></arg>
-    <arg choice='plain'><option>-G</option></arg>
-  </group>
-  <arg choice='req'><replaceable>generation</replaceable></arg>
-</cmdsynopsis>
-
-</refsection>
-
-
-<refsection><title>Description</title>
-
-<para>This operation makes generation number
-<replaceable>generation</replaceable> the current generation of the
-active profile.  That is, if the
-<filename><replaceable>profile</replaceable></filename> is the path to
-the active profile, then the symlink
-<filename><replaceable>profile</replaceable></filename> is made to
-point to
-<filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>,
-which is in turn a symlink to the actual user environment in the Nix
-store.</para>
-
-<para>Switching will fail if the specified generation does not exist.</para>
-
-</refsection>
-
-
-<refsection><title>Examples</title>
-
-<screen>
-$ nix-env -G 42
-switching from generation 50 to 42</screen>
-
-</refsection>
-
-</refsection>
-
-
-
-<!--######################################################################-->
-
-<refsection><title>Operation <option>--rollback</option></title>
-
-<refsection><title>Synopsis</title>
-
-<cmdsynopsis>
-  <command>nix-env</command>
-  <arg choice='plain'><option>--rollback</option></arg>
-</cmdsynopsis>
-
-</refsection>
-
-<refsection><title>Description</title>
-
-<para>This operation switches to the “previous” generation of the
-active profile, that is, the highest numbered generation lower than
-the current generation, if it exists.  It is just a convenience
-wrapper around <option>--list-generations</option> and
-<option>--switch-generation</option>.</para>
-
-</refsection>
-
-
-<refsection><title>Examples</title>
-
-<screen>
-$ nix-env --rollback
-switching from generation 92 to 91
-
-$ nix-env --rollback
-error: no generation older than the current (91) exists</screen>
-
-</refsection>
-
-</refsection>
-
-
-<refsection condition="manpage"><title>Environment variables</title>
-
-<variablelist>
-
-  <varlistentry><term><envar>NIX_PROFILE</envar></term>
-
-    <listitem><para>Location of the Nix profile.  Defaults to the
-    target of the symlink <filename>~/.nix-profile</filename>, if it
-    exists, or <filename>/nix/var/nix/profiles/default</filename>
-    otherwise.</para></listitem>
-
-  </varlistentry>
-
-  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
-</variablelist>
-
-</refsection>
-
-
-</refentry>