diff options
Diffstat (limited to 'doc/manual/nix-env.xml')
| -rw-r--r-- | doc/manual/nix-env.xml | 1510 |
1 files changed, 751 insertions, 759 deletions
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml index 6d145a2129ff..8111775cedb8 100644 --- a/doc/manual/nix-env.xml +++ b/doc/manual/nix-env.xml @@ -1,387 +1,417 @@ <refentry> - <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/*)" /> - <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>--preserve-installed</option></arg> - <arg> - <arg choice='plain'><option>--system-filter</option></arg> - <replaceable>system</replaceable> - </arg> - <arg><option>--dry-run</option></arg> - <arg choice='plain'><replaceable>operation</replaceable></arg> - <arg rep='repeat'><replaceable>options</replaceable></arg> - <arg rep='repeat'><replaceable>arguments</replaceable></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsection> - <title>Description</title> - - <para> - The command <command>nix-env</command> is used to manipulate Nix - user environments. User environments are sets of software - 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> + +<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/*)" /> + <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>--preserve-installed</option></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> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Common options</title> +<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> +<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> +<variablelist> - <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>--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>--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> - </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>--preserve-installed</option></term> - <listitem> - <para> - By default, when you install a derivation with the - <option>--install</option> operation, it will replace - previously installed versions with the same derivation - name (regardless of the version number). This option - causes those previously installed versions to be kept in - the new generation of the profile. Note that this will - generally cause conflicts in the creation of the user - environment (since multiple versions of a package - typically contain the same programs). - </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></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> + <varlistentry><term><option>--preserve-installed</option></term> + + <listitem><para>By default, when you install a derivation with the + <option>--install</option> operation, it will replace previously + installed versions with the same derivation name (regardless of + the version number). This option causes those previously + installed versions to be kept in the new generation of the + profile. Note that this will generally cause conflicts in the + creation of the user environment (since multiple versions of a + package typically contain the same programs).</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> + <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> - <!--######################################################################--> +<!--######################################################################--> + +<refsection id="rsec-nix-env-install"><title>Operation <option>--install</option></title> + +<refsection><title>Synopsis</title> - <refsection> - <title>Operation <option>--install</option></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> - <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>drvnames</replaceable></arg> - </cmdsynopsis> - </refsection> +</refsection> - <refsection> - <title>Description</title> + +<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> - - <para> - 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> - - </refsection> - - <refsection> - <title>Flags</title> - - <variablelist> - - <varlistentry> - <term><option>--preserve-installed</option> / <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> +<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></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> - <title>Examples</title> - <screen> -$ nix-env --install gcc-3.3.2 <lineannotation>(install specific version)</lineannotation> +<refsection><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' <lineannotation>(previously installed version is removed)</lineannotation> +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 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/x3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</screen> + +</para> + +<para>To install from a Nix expression specified on the command-line: -$ nix-env --install gcc <lineannotation>(just pick any version)</lineannotation> +<screen> +$ nix-env -f ./foo.nix -i -E \ + 'f: (f {system = "i686-linux";}).subversionWithJava'</screen> -$ nix-env -f ~/foo.nix -i '*' <lineannotation>(install everything in <filename>foo.nix</filename>)</lineannotation></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> - </refsection> +</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> +</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>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 - 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> +<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 - <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> +<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>--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' @@ -395,48 +425,39 @@ $ 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> - <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> +<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 @@ -450,199 +471,189 @@ upgrading `mozilla-1.2' to `mozilla-1.4'</screen> 2.3pre1 < 2.3c 2.3pre1 < 2.3q</screen> - </para> +</para> - </refsection> +</refsection> - </refsection> +</refsection> - <!--######################################################################--> +<!--######################################################################--> + +<refsection><title>Operation <option>--uninstall</option></title> - <refsection> - <title>Operation <option>--uninstall</option></title> +<refsection><title>Synopsis</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> +<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> +<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> +<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> +<refsection><title>Examples</title> - <screen> +<screen> $ nix-env --uninstall gcc $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen> - </refsection> +</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> +</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> +<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>).</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. 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> +</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>--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>--no-name</option></term> + + <listitem><para>Suppress printing of the <literal>name</literal> + attribute of each derivation.</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> + +</variablelist> + +</refsection> + + +<refsection><title>Examples</title> + +<screen> $ nix-env -q <lineannotation>(show installed derivations)</lineannotation> MozillaFirebird-0.7 bison-1.875c @@ -666,270 +677,251 @@ IP- bison-1.875c <lineannotation>(installed and by definition present)</lineanno $ 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> +</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> +<!--######################################################################--> + +<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> +<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> +<refsection><title>Examples</title> - <screen> +<screen> $ nix-env -S ~/my-profile</screen> - </refsection> +</refsection> - </refsection> +</refsection> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Operation <option>--list-generations</option></title> +<refsection><title>Operation <option>--list-generations</option></title> - <refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-env</command> - <arg choice='req'><option>--list-generations</option></arg> - </cmdsynopsis> - </refsection> +<refsection><title>Synopsis</title> - <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> +<cmdsynopsis> + <command>nix-env</command> + <arg choice='plain'><option>--list-generations</option></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> - <refsection> - <title>Examples</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> + - <screen> +<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> +</refsection> - <!--######################################################################--> +<!--######################################################################--> + +<refsection><title>Operation <option>--delete-generations</option></title> + +<refsection><title>Synopsis</title> - <refsection> - <title>Operation <option>--delete-generations</option></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> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-env</command> - <arg choice='req'><option>--delete-generations</option></arg> - <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg> - </cmdsynopsis> - </refsection> +</refsection> - <refsection> - <title>Description</title> + +<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> +<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> +<refsection><title>Examples</title> - <screen> +<screen> $ nix-env --delete-generations 3 4 8 $ nix-env -p other_profile --delete-generations old</screen> - </refsection> +</refsection> - </refsection> +</refsection> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Operation <option>--switch-generation</option></title> +<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>Synopsis</title> - <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> +<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> - <refsection> - <title>Examples</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> - <screen> + +<refsection><title>Examples</title> + +<screen> $ nix-env -G 42 switching from generation 50 to 42</screen> - </refsection> +</refsection> - </refsection> +</refsection> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Operation <option>--rollback</option></title> +<refsection><title>Operation <option>--rollback</option></title> - <refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-env</command> - <arg choice='req'><option>--rollback</option></arg> - </cmdsynopsis> - </refsection> +<refsection><title>Synopsis</title> - <refsection> - <title>Description</title> - - <para> - This operation switches to the <quote>previous</quote> - 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> +<cmdsynopsis> + <command>nix-env</command> + <arg choice='plain'><option>--rollback</option></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> - <refsection> - <title>Examples</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> - <screen> +</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> +</refsection> - <!--######################################################################--> +<!--######################################################################--> - <refsection> - <title>Operation <option>--import</option></title> +<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>Synopsis</title> - <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> +<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> - <refsection> - <title>Examples</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> +<screen> $ nix-env -I ~/nixpkgs-0.5/</screen> - </refsection> +</refsection> - </refsection> +</refsection> |