mirror of
https://github.com/NixOS/nix.git
synced 2024-11-23 07:12:27 +00:00
1104 lines
34 KiB
XML
1104 lines
34 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink">
|
||
|
||
<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#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
|
||
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
|
||
<arg>
|
||
<group choice='req'>
|
||
<arg choice='plain'><option>--attr</option></arg>
|
||
<arg choice='plain'><option>-A</option></arg>
|
||
</group>
|
||
<replaceable>attrPath</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><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>
|
||
|
||
</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. See also <xref
|
||
linkend="sec-common-options" />.</para>
|
||
|
||
<variablelist>
|
||
|
||
<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>
|
||
|
||
<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>
|
||
|
||
<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
|
||
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> 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>
|
||
|
||
</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>
|
||
<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>
|
||
|
||
</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
|
||
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>
|
||
|
||
<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
|
||
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>
|
||
|
||
|
||
<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 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 -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>
|
||
|
||
</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
|
||
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>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<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>
|
||
<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>
|
||
|
||
</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><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 < 2.3
|
||
2.1 < 2.3
|
||
2.3 = 2.3
|
||
2.5 > 2.3
|
||
3.1 > 2.3
|
||
2.3.1 > 2.3
|
||
2.3.1 > 2.3a
|
||
2.3pre1 < 2.3
|
||
2.3pre3 < 2.3pre12
|
||
2.3a < 2.3c
|
||
2.3pre1 < 2.3c
|
||
2.3pre1 < 2.3q</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><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>
|
||
<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>
|
||
<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>
|
||
|
||
|
||
<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>. The wildcard <literal>*</literal>
|
||
shows all derivations.</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>--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</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>
|
||
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><</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>
|
||
|
||
<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>
|
||
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection><title>Examples</title>
|
||
|
||
<screen>
|
||
$ 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
|
||
...
|
||
|
||
$ 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>
|
||
-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>
|
||
...
|
||
|
||
<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>
|
||
<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 < 1.0.7 <lineannotation>(a more recent version is available)</lineannotation>
|
||
<replaceable>...</replaceable>
|
||
|
||
<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>
|
||
|
||
</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, 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>
|
||
|
||
<refsection><title>Examples</title>
|
||
|
||
<screen>
|
||
$ nix-env --delete-generations 3 4 8
|
||
|
||
$ 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 --rolback
|
||
error: no generation older than the current (91) exists</screen>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
<!--######################################################################-->
|
||
|
||
<refsection><title>Operation <option>--import</option></title>
|
||
|
||
<refsection><title>Synopsis</title>
|
||
|
||
<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>
|
||
|
||
<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>
|
||
|
||
<screen>
|
||
$ nix-env -I ~/nixpkgs-0.5/</screen>
|
||
|
||
</refsection>
|
||
|
||
</refsection>
|
||
|
||
|
||
|
||
</refentry>
|