lix/doc/manual/nix-env.xml

1104 lines
34 KiB
XML
Raw Normal View History

<refentry xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
2005-04-10 20:54:21 +00:00
<refnamediv>
<refname>nix-env</refname>
<refpurpose>manipulate or query Nix user environments</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-env</command>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xpointer(/nop/*)" />
2006-10-05 09:08:52 +00:00
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
2006-10-05 20:07:41 +00:00
<arg>
<group choice='req'>
<arg choice='plain'><option>--attr</option></arg>
<arg choice='plain'><option>-A</option></arg>
</group>
<replaceable>attrPath</replaceable>
</arg>
2005-04-10 20:54:21 +00:00
<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><option>--from-expression</option></arg>
<arg><option>-E</option></arg>
<arg><option>--from-profile</option> <replaceable>path</replaceable></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 components
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>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
2005-04-10 20:54:21 +00:00
<refsection><title>Common options</title>
2005-04-10 20:54:21 +00:00
<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. See also <xref
linkend="sec-common-options" />.</para>
2005-04-10 20:54:21 +00:00
<variablelist>
2005-04-10 20:54:21 +00:00
<varlistentry><term><option>--file</option></term>
<term><option>-f</option></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></listitem>
</varlistentry>
2005-04-10 20:54:21 +00:00
<varlistentry><term><option>--profile</option></term>
<term><option>-p</option></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 sequence of
user environments called <emphasis>generations</emphasis>, one of
which is the <emphasis>current generation</emphasis>. The default
profile is the target of the symbolic link
<filename>~/.nix-profile</filename> (see below).</para></listitem>
</varlistentry>
2005-04-10 20:54:21 +00:00
<varlistentry><term><option>--dry-run</option></term>
<listitem><para>For the <option>--install</option>,
<option>--upgrade</option>, <option>--uninstall</option>,
<option>--switch-generation</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
2006-10-05 22:56:52 +00:00
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>
2005-04-10 20:54:21 +00:00
</varlistentry>
2005-04-10 20:54:21 +00:00
<varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term>
<listitem><para>By default, operations such as <option>--query
--available</option> only include derivations matching the current
platform. This option allows you to use derivations for the
specified platform <replaceable>system</replaceable>. The special
value <literal>*</literal> causes derivations for any platform to
be included.</para></listitem>
</varlistentry>
</variablelist>
</refsection>
<!--######################################################################-->
<refsection><title>Files</title>
<variablelist>
<varlistentry><term><filename>~/.nix-defexpr</filename></term>
<listitem><para>The default Nix expression used by the
<option>--install</option>, <option>--upgrade</option>, and
<option>--query --available</option> operations to obtain
derivations. It is generally a symbolic link to some other
location set using the <option>--import</option> operation. The
<option>--file</option> option may be used to override this
default.</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>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
<refsection xml:id="rsec-nix-env-install"><title>Operation <option>--install</option></title>
2005-04-10 20:54:21 +00:00
<refsection><title>Synopsis</title>
2005-04-10 20:54:21 +00:00
<cmdsynopsis>
<command>nix-env</command>
<group choice='req'>
<arg choice='plain'><option>--install</option></arg>
<arg choice='plain'><option>-i</option></arg>
</group>
<group choice='opt'>
<arg choice='plain'><option>--preserve-installed</option></arg>
<arg choice='plain'><option>-P</option></arg>
</group>
<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
</cmdsynopsis>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<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
2006-10-06 07:47:56 +00:00
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
only the highest version will be installed. 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>
2005-04-10 20:54:21 +00:00
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
<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 a 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>
</itemizedlist>
</para>
</refsection>
<refsection><title>Flags</title>
<variablelist>
<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>
</variablelist>
</refsection>
2006-10-05 20:07:41 +00:00
<refsection xml:id='refsec-nix-env-install-examples'><title>Examples</title>
2005-04-10 20:54:21 +00:00
<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'
2005-04-10 20:54:21 +00:00
uninstalling `gcc-3.1'</screen>
Note the 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>
2006-10-05 22:56:52 +00:00
<para>To install using a specific attribute:
<screen>
$ nix-env -i -A gcc40mips
$ nix-env -i -A xorg.xorgserver</screen>
</para>
2005-04-10 20:54:21 +00:00
<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 -i 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>
2005-04-10 20:54:21 +00:00
</para>
<para>To install from a Nix expression specified on the command-line:
2005-04-10 20:54:21 +00:00
<screen>
$ nix-env -f ./foo.nix -i -E \
'f: (f {system = "i686-linux";}).subversionWithJava'</screen>
2005-04-10 20:54:21 +00:00
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
attribute set returned by calling the function defined in
<filename>./foo.nix</filename>.</para>
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
<!--######################################################################-->
<refsection><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>
<group choice='opt'>
<arg choice='plain'><option>--lt</option></arg>
<arg choice='plain'><option>--leq</option></arg>
2006-10-05 22:56:52 +00:00
<arg choice='plain'><option>--eq</option></arg>
2005-04-10 20:54:21 +00:00
<arg choice='plain'><option>--always</option></arg>
</group>
<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
</cmdsynopsis>
</refsection>
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
<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>
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
<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>
</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>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<refsection><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 following 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>
2005-04-10 20:54:21 +00:00
</para>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
<refsection><title>Operation <option>--uninstall</option></title>
2005-04-10 20:54:21 +00:00
<refsection><title>Synopsis</title>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
<refsection><title>Examples</title>
2005-04-10 20:54:21 +00:00
<screen>
$ nix-env --uninstall gcc
$ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</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>
2006-10-05 22:56:52 +00:00
<arg><option>--xml</option></arg>
2005-04-10 20:54:21 +00:00
<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>
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
</cmdsynopsis>
</refsection>
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<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
2006-10-05 22:56:52 +00:00
(<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>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
</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>
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
<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>
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
<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
components 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 component is available
or installed.</para></listitem>
</varlistentry>
<varlistentry><term><literal>=</literal> <replaceable>version</replaceable></term>
<listitem><para>At most the same version of the component is
available or installed.</para></listitem>
</varlistentry>
<varlistentry><term><literal>></literal> <replaceable>version</replaceable></term>
<listitem><para>Only older versions of the component are
available or installed.</para></listitem>
</varlistentry>
<varlistentry><term><literal>- ?</literal></term>
<listitem><para>No version of the component is available or
installed.</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
2005-04-10 20:54:21 +00:00
<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>
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
</variablelist>
</refsection>
<refsection><title>Examples</title>
<screen>
2006-10-05 22:56:52 +00:00
$ nix-env -q '*' <lineannotation>(show installed derivations)</lineannotation>
bison-1.875c
docbook-xml-4.2
firefox-1.0.4
MPlayer-1.0pre7
ORBit2-2.8.3
...
2006-10-05 22:56:52 +00:00
$ nix-env -qa '*' <lineannotation>(show available derivations)</lineannotation>
firefox-1.0.7
GConf-2.4.0.1
MPlayer-1.0pre7
ORBit2-2.8.3
...
2006-10-05 22:56:52 +00:00
$ 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>
...
2006-10-05 22:56:52 +00:00
<lineannotation>(show available derivations in the Nix expression <!-- !!! <filename>-->foo.nix<!-- </filename> -->)</lineannotation>
$ nix-env -f ./foo.nix -qa '*'
foo-1.2.3
2006-10-05 22:56:52 +00:00
$ nix-env -qc '*' <lineannotation>(compare installed versions to whats 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>
2006-10-05 22:56:52 +00:00
<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>
2005-04-10 20:54:21 +00:00
</refsection>
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
<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>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
<refsection><title>Examples</title>
2005-04-10 20:54:21 +00:00
<screen>
$ nix-env -S ~/my-profile</screen>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
2005-04-10 20:54:21 +00:00
<refsection><title>Operation <option>--list-generations</option></title>
2005-04-10 20:54:21 +00:00
<refsection><title>Synopsis</title>
2005-04-10 20:54:21 +00:00
<cmdsynopsis>
<command>nix-env</command>
<arg choice='plain'><option>--list-generations</option></arg>
</cmdsynopsis>
</refsection>
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
<refsection><title>Operation <option>--delete-generations</option></title>
<refsection><title>Synopsis</title>
2005-04-10 20:54:21 +00:00
<cmdsynopsis>
<command>nix-env</command>
<arg choice='plain'><option>--delete-generations</option></arg>
<arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg>
</cmdsynopsis>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<para>This operation deletes the specified generations of the current
profile. The generations can be a list of generation numbers, or the
special value <literal>old</literal> to delete all non-current
generations. Periodically deleting old generations is important to
make garbage collection effective.</para>
</refsection>
2005-04-10 20:54:21 +00:00
<refsection><title>Examples</title>
2005-04-10 20:54:21 +00:00
<screen>
$ nix-env --delete-generations 3 4 8
$ nix-env -p other_profile --delete-generations old</screen>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
2005-04-10 20:54:21 +00:00
<refsection><title>Operation <option>--switch-generation</option></title>
2005-04-10 20:54:21 +00:00
<refsection><title>Synopsis</title>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
<refsection><title>Examples</title>
<screen>
$ nix-env -G 42
switching from generation 50 to 42</screen>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
2005-04-10 20:54:21 +00:00
<refsection><title>Operation <option>--rollback</option></title>
2005-04-10 20:54:21 +00:00
<refsection><title>Synopsis</title>
2005-04-10 20:54:21 +00:00
<cmdsynopsis>
<command>nix-env</command>
<arg choice='plain'><option>--rollback</option></arg>
</cmdsynopsis>
</refsection>
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<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>
2005-04-10 20:54:21 +00:00
</refsection>
<refsection><title>Examples</title>
<screen>
$ nix-env --rollback
switching from generation 92 to 91
$ nix-env --rolback
error: no generation older than the current (91) exists</screen>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
<!--######################################################################-->
2005-04-10 20:54:21 +00:00
<refsection><title>Operation <option>--import</option></title>
2005-04-10 20:54:21 +00:00
<refsection><title>Synopsis</title>
2005-04-10 20:54:21 +00:00
<cmdsynopsis>
<command>nix-env</command>
<group choice='req'>
<arg choice='plain'><option>--import</option></arg>
<arg choice='plain'><option>-I</option></arg>
</group>
<arg choice='req'><replaceable>path</replaceable></arg>
</cmdsynopsis>
</refsection>
<refsection><title>Description</title>
2005-04-10 20:54:21 +00:00
<para>This operation makes <replaceable>path</replaceable> the default
active Nix expression for the user. That is, the symlink
<filename>~/.nix-userenv</filename> is made to point to
<replaceable>path</replaceable>.</para>
</refsection>
<refsection><title>Examples</title>
2005-04-10 20:54:21 +00:00
<screen>
$ nix-env -I ~/nixpkgs-0.5/</screen>
2005-04-10 20:54:21 +00:00
</refsection>
2005-04-10 20:54:21 +00:00
</refsection>
</refentry>