forked from lix-project/lix
598 lines
19 KiB
XML
598 lines
19 KiB
XML
<refentry>
|
|
<refnamediv>
|
|
<refname>nix-env</refname>
|
|
<refpurpose>manipulate or query Nix user environments</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>nix-env</command>
|
|
&opt-common-syn;
|
|
<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><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
|
|
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>
|
|
Environments are manipulated by operations such as the
|
|
installation and removal of components (hereafter called
|
|
<emphasis>derivations</emphasis>). These operations are not
|
|
destructive: rather than overwrite the current environment, they
|
|
create a new environment to which we can then atomically
|
|
<emphasis>switch</emphasis> by flipping a symlink.
|
|
</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.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
&opt-common;
|
|
|
|
<varlistentry>
|
|
<term><option>--file</option> / <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> / <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> and
|
|
<option>--uninstall</option> operations, this flag will
|
|
cause <command>nix-env</command> to print what
|
|
<emphasis>would</emphasis> be done if this flag had not
|
|
been specified, without actually doing it.
|
|
</para>
|
|
</listitem>
|
|
</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>
|
|
<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>
|
|
<arg choice='plain' rep='repeat'><replaceable>drvnames</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 the
|
|
derivations designated by <replaceable>drvnames</replaceable>
|
|
in the active Nix expression are added.
|
|
</para>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<screen>
|
|
$ nix-env --install gcc-3.3.2 <lineannotation>(install specific version)</lineannotation>
|
|
$ nix-env --install gcc <lineannotation>(just pick any version)</lineannotation>
|
|
$ nix-env -f ~/foo.nix -i '*' <lineannotation>(install everything in <filename>foo.nix</filename>)</lineannotation></screen>
|
|
|
|
</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>--always</option></arg>
|
|
</group>
|
|
<arg choice='plain' rep='repeat'><replaceable>drvnames</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
|
|
derivations designated by <replaceable>drvnames</replaceable>
|
|
for which there are newer versions in the active Nix
|
|
expression are replaced by those newer versions. Matching
|
|
derivations 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>drvnames</replaceable> matches no
|
|
installed derivations.
|
|
</para>
|
|
|
|
<para>
|
|
If multiple derivations in the active Nix expression match an
|
|
installed derivation, the one with the highest version is
|
|
selected.
|
|
</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
|
|
<quote>upgrade</quote> 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
|
|
<quote>synchronisation</quote> between the installed and
|
|
available derivations.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--always</option></term>
|
|
<listitem>
|
|
<para>
|
|
In addition to upgrading to newer versions, also
|
|
<quote>upgrade</quote> 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 --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
|
|
derivations designated by <replaceable>drvnames</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>
|
|
<group choice='opt'>
|
|
<arg choice='plain'><option>--installed</option></arg>
|
|
<arg choice='plain'><option>--available</option></arg>
|
|
<arg choice='plain'><option>-a</option></arg>
|
|
</group>
|
|
<group choice='req'>
|
|
<arg choice='plain'><option>--name</option></arg>
|
|
<arg choice='plain'><option>--expr</option></arg>
|
|
<arg choice='plain'><option>--status</option></arg>
|
|
<arg choice='plain'><option>-s</option></arg>
|
|
</group>
|
|
</cmdsynopsis>
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
The query operation displays information about either the
|
|
derivations that are installed in the current generation of
|
|
the active profile (<option>--installed</option>), or the
|
|
derivations that are available for installation in the active
|
|
Nix expression (<option>--available</option>).
|
|
</para>
|
|
|
|
<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 derivations on which
|
|
the query operates.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--installed</option></term>
|
|
<listitem>
|
|
<para>
|
|
The query operates on the derivations that are installed
|
|
in the current generation of the active profile. This
|
|
is the default
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--available</option> / <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. Only one type of query may be
|
|
specified.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><option>--name</option></term>
|
|
<listitem>
|
|
<para>
|
|
Prints the <literal>name</literal> attribute of each
|
|
derivation. This is the default.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--expr</option></term>
|
|
<listitem>
|
|
<para>
|
|
Prints the store expression in the Nix store that
|
|
described the derivation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>--status</option> / <option>-s</option></term>
|
|
<listitem>
|
|
<para>
|
|
Prints the <emphasis>status</emphasis> of each
|
|
derivation, followed by its <literal>name</literal>
|
|
attribute. 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>
|
|
|
|
</variablelist>
|
|
|
|
</refsection>
|
|
|
|
<refsection>
|
|
<title>Examples</title>
|
|
|
|
<screen>
|
|
$ nix-env -q <lineannotation>(show installed derivations)</lineannotation>
|
|
MozillaFirebird-0.7
|
|
bison-1.875c
|
|
docbook-xml-4.2
|
|
...
|
|
|
|
$ nix-env -qa <lineannotation>(show available derivations)</lineannotation>
|
|
GConf-2.4.0.1
|
|
MPlayer-1.0pre3
|
|
MozillaFirebird-0.7
|
|
ORBit2-2.8.3
|
|
...
|
|
|
|
$ nix-env -qas <lineannotation>(show status of available derivations)</lineannotation>
|
|
-P- GConf-2.4.0.1 <lineannotation>(not installed but present)</lineannotation>
|
|
--S MPlayer-1.0pre3 <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation>
|
|
--S MozillaFirebird-0.7 <lineannotation>(i.e., this is not the installed Firebird, even though the version is the same!)</lineannotation>
|
|
IP- bison-1.875c <lineannotation>(installed and by definition present)</lineannotation>
|
|
...
|
|
|
|
$ nix-env -f ./foo.nix -qa <lineannotation>(show available derivations in the Nix expression <filename>foo.nix</filename>)</lineannotation>
|
|
foo-1.2.3</screen>
|
|
|
|
</refsection>
|
|
|
|
</refsection>
|
|
|
|
|
|
</refentry>
|