diff options
Diffstat (limited to 'doc/manual/nix-env.xml')
| -rw-r--r-- | doc/manual/nix-env.xml | 1287 |
1 files changed, 1287 insertions, 0 deletions
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml new file mode 100644 index 000000000000..5f87093ac163 --- /dev/null +++ b/doc/manual/nix-env.xml @@ -0,0 +1,1287 @@ +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-nix-env"> + +<refmeta> + <refentrytitle>nix-env</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">Nix</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> +</refmeta> + +<refnamediv> + <refname>nix-env</refname> + <refpurpose>manipulate or query Nix user environments</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>nix-env</command> + <xi:include href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> + <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> + <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--file</option></arg> + <arg choice='plain'><option>-f</option></arg> + </group> + <replaceable>path</replaceable> + </arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--profile</option></arg> + <arg choice='plain'><option>-p</option></arg> + </group> + <replaceable>path</replaceable> + </arg> + <arg> + <arg choice='plain'><option>--system-filter</option></arg> + <replaceable>system</replaceable> + </arg> + <arg><option>--dry-run</option></arg> + <arg choice='plain'><replaceable>operation</replaceable></arg> + <arg rep='repeat'><replaceable>options</replaceable></arg> + <arg rep='repeat'><replaceable>arguments</replaceable></arg> + </cmdsynopsis> +</refsynopsisdiv> + + +<refsection><title>Description</title> + +<para>The command <command>nix-env</command> is used to manipulate Nix +user environments. User environments are sets of software packages +available to a user at some point in time. In other words, they are a +synthesised view of the programs available in the Nix store. There +may be many user environments: different users can have different +environments, and individual users can switch between different +environments.</para> + +<para><command>nix-env</command> takes exactly one +<emphasis>operation</emphasis> flag which indicates the subcommand to +be performed. These are documented below.</para> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Common options</title> + +<para>This section lists the options that are common to all +operations. These options are allowed for every subcommand, though +they may not always have an effect. <phrase condition="manual">See +also <xref linkend="sec-common-options" />.</phrase></para> + +<variablelist> + + <varlistentry><term><option>--file</option></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 a sequence of + user environments called <emphasis>generations</emphasis>, one of + which is the <emphasis>current + generation</emphasis>.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--dry-run</option></term> + + <listitem><para>For the <option>--install</option>, + <option>--upgrade</option>, <option>--uninstall</option>, + <option>--switch-generation</option>, + <option>--delete-generations</option> and + <option>--rollback</option> operations, this flag will cause + <command>nix-env</command> to print what + <emphasis>would</emphasis> be done if this flag had not been + specified, without actually doing it.</para> + + <para><option>--dry-run</option> also prints out which paths will + be <link linkend="gloss-substitute">substituted</link> (i.e., + downloaded) and which paths will be built from source (because no + substitute is available).</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term> + + <listitem><para>By default, operations such as <option>--query + --available</option> show derivations matching any platform. This + option allows you to use derivations for the specified platform + <replaceable>system</replaceable>.</para></listitem> + + </varlistentry> + +</variablelist> + +<variablelist condition="manpage"> + <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> +</variablelist> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Files</title> + +<variablelist> + + <varlistentry><term><filename>~/.nix-defexpr</filename></term> + + <listitem><para>A directory that contains the default Nix + expressions used by the <option>--install</option>, + <option>--upgrade</option>, and <option>--query + --available</option> operations to obtain derivations. The + <option>--file</option> option may be used to override this + default.</para> + + <para>The Nix expressions in this directory are combined into a + single set, with each file as an attribute that has the name of + the file. Thus, if <filename>~/.nix-defexpr</filename> contains + two files, <filename>foo</filename> and <filename>bar</filename>, + then the default Nix expression will essentially be + +<programlisting> +{ + foo = import ~/.nix-defexpr/foo; + bar = import ~/.nix-defexpr/bar; +}</programlisting> + + </para> + + <para>The command <command>nix-channel</command> places symlinks + to the downloaded Nix expressions from each subscribed channel in + this directory.</para> + + </listitem> + + </varlistentry> + + <varlistentry><term><filename>~/.nix-profile</filename></term> + + <listitem><para>A symbolic link to the user's current profile. By + default, this symlink points to + <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>. + The <envar>PATH</envar> environment variable should include + <filename>~/.nix-profile/bin</filename> for the user environment + to be visible to the user.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + + +<!--######################################################################--> + +<refsection xml:id="rsec-nix-env-install"><title>Operation <option>--install</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice='req'> + <arg choice='plain'><option>--install</option></arg> + <arg choice='plain'><option>-i</option></arg> + </group> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> + <group choice='opt'> + <arg choice='plain'><option>--preserve-installed</option></arg> + <arg choice='plain'><option>-P</option></arg> + </group> + <group choice='opt'> + <arg choice='plain'><option>--remove-all</option></arg> + <arg choice='plain'><option>-r</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>The install operation creates a new user environment, based on +the current generation of the active profile, to which a set of store +paths described by <replaceable>args</replaceable> is added. The +arguments <replaceable>args</replaceable> map to store paths in a +number of possible ways: + +<itemizedlist> + + <listitem><para>By default, <replaceable>args</replaceable> is a set + of derivation names denoting derivations in the active Nix + expression. These are realised, and the resulting output paths are + installed. Currently installed derivations with a name equal to the + name of a derivation being added are removed unless the option + <option>--preserve-installed</option> is + specified.</para> + + <para>If there are multiple derivations matching a name in + <replaceable>args</replaceable> that have the same name (e.g., + <literal>gcc-3.3.6</literal> and <literal>gcc-4.1.1</literal>), then + the derivation with the highest <emphasis>priority</emphasis> is + used. A derivation can define a priority by declaring the + <varname>meta.priority</varname> attribute. This attribute should + be a number, with a higher value denoting a lower priority. The + default priority is <literal>0</literal>.</para> + + <para>If there are multiple matching derivations with the same + priority, then the derivation with the highest version will be + installed.</para> + + <para>You can force the installation of multiple derivations with + the same name by being specific about the versions. For instance, + <literal>nix-env -i gcc-3.3.6 gcc-4.1.1</literal> will install both + version of GCC (and will probably cause a user environment + conflict!).</para></listitem> + + <listitem><para>If <link + linkend='opt-attr'><option>--attr</option></link> + (<option>-A</option>) is specified, the arguments are + <emphasis>attribute paths</emphasis> that select attributes from the + top-level Nix expression. This is faster than using derivation + names and unambiguous. To find out the attribute paths of available + packages, use <literal>nix-env -qaP '*'</literal>.</para></listitem> + + <listitem><para>If <option>--from-profile</option> + <replaceable>path</replaceable> is given, + <replaceable>args</replaceable> is a set of names denoting installed + store paths in the profile <replaceable>path</replaceable>. This is + an easy way to copy user environment elements from one profile to + another.</para></listitem> + + <listitem><para>If <option>--from-expression</option> is given, + <replaceable>args</replaceable> are Nix <link + linkend="ss-functions">functions</link> that are called with the + active Nix expression as their single argument. The derivations + returned by those function calls are installed. This allows + derivations to be specified in an unambiguous way, which is necessary + if there are multiple derivations with the same + name.</para></listitem> + + <listitem><para>If <replaceable>args</replaceable> are store + derivations, then these are <link + linkend="rsec-nix-store-realise">realised</link>, and the resulting + output paths are installed.</para></listitem> + + <listitem><para>If <replaceable>args</replaceable> are store paths + that are not store derivations, then these are <link + linkend="rsec-nix-store-realise">realised</link> and + installed.</para></listitem> + +</itemizedlist> + +</para> + +</refsection> + + +<refsection><title>Flags</title> + +<variablelist> + + <varlistentry><term><option>--prebuild-only</option> / <option>-b</option></term> + + <listitem><para>Use only derivations for which a substitute is + registered, i.e., there is a pre-built binary available that can + be downloaded in lieu of building the derivation. Thus, no + packages will be built from source.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--preserve-installed</option></term> + <term><option>-P</option></term> + + <listitem><para>Do not remove derivations with a name matching one + of the derivations being installed. Usually, trying to have two + versions of the same package installed in the same generation of a + profile will lead to an error in building the generation, due to + file name clashes between the two versions. However, this is not + the case for all packages.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--remove-all</option></term> + <term><option>-r</option></term> + + <listitem><para>Remove all previously installed packages first. + This is equivalent to running <literal>nix-env -e '*'</literal> + first, except that everything happens in a single + transaction.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + + +<refsection xml:id='refsec-nix-env-install-examples'><title>Examples</title> + +<para>To install a specific version of <command>gcc</command> from the +active Nix expression: + +<screen> +$ nix-env --install gcc-3.3.2 +installing `gcc-3.3.2' +uninstalling `gcc-3.1'</screen> + +Note the 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 +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 xml:id="rsec-nix-env-upgrade"><title>Operation <option>--upgrade</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice='req'> + <arg choice='plain'><option>--upgrade</option></arg> + <arg choice='plain'><option>-u</option></arg> + </group> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> + <group choice='opt'> + <arg choice='plain'><option>--lt</option></arg> + <arg choice='plain'><option>--leq</option></arg> + <arg choice='plain'><option>--eq</option></arg> + <arg choice='plain'><option>--always</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> +</cmdsynopsis> + +</refsection> + +<refsection><title>Description</title> + +<para>The upgrade operation creates a new user environment, based on +the current generation of the active profile, in which all store paths +are replaced for which there are newer versions in the set of paths +described by <replaceable>args</replaceable>. Paths for which there +are no newer versions are left untouched; this is not an error. It is +also not an error if an element of <replaceable>args</replaceable> +matches no installed derivations.</para> + +<para>For a description of how <replaceable>args</replaceable> is +mapped to a set of store paths, see <link +linkend="rsec-nix-env-install"><option>--install</option></link>. If +<replaceable>args</replaceable> describes multiple store paths with +the same symbolic name, only the one with the highest version is +installed.</para> + +</refsection> + +<refsection><title>Flags</title> + +<variablelist> + + <varlistentry><term><option>--lt</option></term> + + <listitem><para>Only upgrade a derivation to newer versions. This + is the default.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--leq</option></term> + + <listitem><para>In addition to upgrading to newer versions, also + “upgrade” to derivations that have the same version. Version are + not a unique identification of a derivation, so there may be many + derivations that have the same version. This flag may be useful + to force “synchronisation” between the installed and available + derivations.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--eq</option></term> + + <listitem><para><emphasis>Only</emphasis> “upgrade” to derivations + that have the same version. This may not seem very useful, but it + actually is, e.g., when there is a new release of Nixpkgs and you + want to replace installed applications with the same versions + built against newer dependencies (to reduce the number of + dependencies floating around on your system).</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--always</option></term> + + <listitem><para>In addition to upgrading to newer versions, also + “upgrade” to derivations that have the same or a lower version. + I.e., derivations may actually be downgraded depending on what is + available in the active Nix expression.</para></listitem> + + </varlistentry> + +</variablelist> + +<para>For the other flags, see <option +linkend="rsec-nix-env-install">--install</option>.</para> + +</refsection> + +<refsection><title>Examples</title> + +<screen> +$ nix-env --upgrade gcc +upgrading `gcc-3.3.1' to `gcc-3.4' + +$ nix-env -u gcc-3.3.2 --always <lineannotation>(switch to a specific version)</lineannotation> +upgrading `gcc-3.4' to `gcc-3.3.2' + +$ nix-env --upgrade pan +<lineannotation>(no upgrades available, so nothing happens)</lineannotation> + +$ nix-env -u '*' <lineannotation>(try to upgrade everything)</lineannotation> +upgrading `hello-2.1.2' to `hello-2.1.3' +upgrading `mozilla-1.2' to `mozilla-1.4'</screen> + +</refsection> + +<refsection xml:id="ssec-version-comparisons"><title>Versions</title> + +<para>The upgrade operation determines whether a derivation +<varname>y</varname> is an upgrade of a derivation +<varname>x</varname> by looking at their respective +<literal>name</literal> attributes. The names (e.g., +<literal>gcc-3.3.1</literal> are split into two parts: the package +name (<literal>gcc</literal>), and the version +(<literal>3.3.1</literal>). The version part starts after the first +dash not 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 xml:id="rsec-nix-env-set-flag"><title>Operation <option>--set-flag</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <arg choice='plain'><option>--set-flag</option></arg> + <arg choice='plain'><replaceable>name</replaceable></arg> + <arg choice='plain'><replaceable>value</replaceable></arg> + <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg> +</cmdsynopsis> +</refsection> + +<refsection><title>Description</title> + +<para>The <option>--set-flag</option> operation allows meta attributes +of installed packages to be modified. There are several attributes +that can be usefully modified, because they affect the behaviour of +<command>nix-env</command> or the user environment build +script: + +<itemizedlist> + + <listitem><para><varname>priority</varname> can be changed to + resolve filename clashes. The user environment build script uses + the <varname>meta.priority</varname> attribute of derivations to + resolve filename collisions between packages. Lower priority values + denote a higher priority. For instance, the GCC wrapper package and + the Binutils package in Nixpkgs both have a file + <filename>bin/ld</filename>, so previously if you tried to install + both you would get a collision. Now, on the other hand, the GCC + wrapper declares a higher priority than Binutils, so the former’s + <filename>bin/ld</filename> is symlinked in the user + environment.</para></listitem> + + <listitem><para><varname>keep</varname> can be set to + <literal>true</literal> to prevent the package from being upgraded + or replaced. This is useful if you want to hang on to an older + version of a package.</para></listitem> + + <listitem><para><varname>active</varname> can be set to + <literal>false</literal> to “disable” the package. That is, no + symlinks will be generated to the files of the package, but it + remains part of the profile (so it won’t be garbage-collected). It + can be set back to <literal>true</literal> to re-enable the + package.</para></listitem> + +</itemizedlist> + +</para> + +</refsection> + +<refsection><title>Examples</title> + +<para>To prevent the currently installed Firefox from being upgraded: + +<screen> +$ nix-env --set-flag keep true firefox</screen> + +After this, <command>nix-env -u</command> will ignore Firefox.</para> + +<para>To disable the currently installed Firefox, then install a new +Firefox while the old remains part of the profile: + +<screen> +$ nix-env -q \* +firefox-2.0.0.9 <lineannotation>(the current one)</lineannotation> + +$ nix-env --preserve-installed -i firefox-2.0.0.11 +installing `firefox-2.0.0.11' +building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment' +collision between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox' + and `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.9/bin/firefox'. +<lineannotation>(i.e., can’t have two active at the same time)</lineannotation> + +$ nix-env --set-flag active false firefox +setting flag on `firefox-2.0.0.9' + +$ nix-env --preserve-installed -i firefox-2.0.0.11 +installing `firefox-2.0.0.11' + +$ nix-env -q \* +firefox-2.0.0.11 <lineannotation>(the enabled one)</lineannotation> +firefox-2.0.0.9 <lineannotation>(the disabled one)</lineannotation></screen> + +</para> + +<para>To make files from <literal>binutils</literal> take precedence +over files from <literal>gcc</literal>: + +<screen> +$ nix-env --set-flag priority 5 binutils +$ nix-env --set-flag priority 10 gcc</screen> + +</para> + +</refsection> + +</refsection> + + + +<!--######################################################################--> + +<refsection><title>Operation <option>--query</option></title> + +<refsection><title>Synopsis</title> + +<cmdsynopsis> + <command>nix-env</command> + <group choice='req'> + <arg choice='plain'><option>--query</option></arg> + <arg choice='plain'><option>-q</option></arg> + </group> + <group choice='opt'> + <arg choice='plain'><option>--installed</option></arg> + <arg choice='plain'><option>--available</option></arg> + <arg choice='plain'><option>-a</option></arg> + </group> + + <sbr /> + + <arg> + <group choice='req'> + <arg choice='plain'><option>--status</option></arg> + <arg choice='plain'><option>-s</option></arg> + </group> + </arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--attr-path</option></arg> + <arg choice='plain'><option>-P</option></arg> + </group> + </arg> + <arg><option>--no-name</option></arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--compare-versions</option></arg> + <arg choice='plain'><option>-c</option></arg> + </group> + </arg> + <arg><option>--system</option></arg> + <arg><option>--drv-path</option></arg> + <arg><option>--out-path</option></arg> + <arg><option>--description</option></arg> + <arg><option>--meta</option></arg> + + <sbr /> + + <arg><option>--xml</option></arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--prebuilt-only</option></arg> + <arg choice='plain'><option>-b</option></arg> + </group> + </arg> + + <arg> + <group choice='req'> + <arg choice='plain'><option>--attr</option></arg> + <arg choice='plain'><option>-A</option></arg> + </group> + <replaceable>attribute-path</replaceable> + </arg> + + <sbr /> + + <arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg> +</cmdsynopsis> + +</refsection> + + +<refsection><title>Description</title> + +<para>The query operation displays information about either the store +paths that are installed in the current generation of the active +profile (<option>--installed</option>), or the derivations that are +available for installation in the active Nix expression +(<option>--available</option>). It only prints information about +derivations whose symbolic name matches one of +<replaceable>names</replaceable>. 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>--prebuild-only</option> / <option>-b</option></term> + + <listitem><para>Show only derivations for which a substitute is + registered, i.e., there is a pre-built binary available that can + be downloaded in lieu of building the derivation. Thus, this + shows all packages that probably can be installed + quickly.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--status</option></term> + <term><option>-s</option></term> + + <listitem><para>Print the <emphasis>status</emphasis> of the + derivation. The status consists of three characters. The first + is <literal>I</literal> or <literal>-</literal>, indicating + whether the derivation is currently installed in the current + generation of the active profile. This is by definition the case + for <option>--installed</option>, but not for + <option>--available</option>. The second is <literal>P</literal> + or <literal>-</literal>, indicating whether the derivation is + present on the system. This indicates whether installation of an + available derivation will require the derivation to be built. The + third is <literal>S</literal> or <literal>-</literal>, indicating + whether a substitute is available for the + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--attr-path</option></term> + <term><option>-P</option></term> + + <listitem><para>Print the <emphasis>attribute path</emphasis> of + the derivation, which can be used to unambiguously select it using + the <link linkend="opt-attr"><option>--attr</option> option</link> + available in commands that install derivations like + <literal>nix-env --install</literal>.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--no-name</option></term> + + <listitem><para>Suppress printing of the <literal>name</literal> + attribute of each derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--compare-versions</option> / + <option>-c</option></term> + + <listitem><para>Compare installed versions to available versions, + or vice versa (if <option>--available</option> is given). This is + useful for quickly seeing whether upgrades for installed + packages are available in a Nix expression. A column is added + with the following meaning: + + <variablelist> + + <varlistentry><term><literal><</literal> <replaceable>version</replaceable></term> + + <listitem><para>A newer version of the package is available + or installed.</para></listitem> + + </varlistentry> + + <varlistentry><term><literal>=</literal> <replaceable>version</replaceable></term> + + <listitem><para>At most the same version of the package is + available or installed.</para></listitem> + + </varlistentry> + + <varlistentry><term><literal>></literal> <replaceable>version</replaceable></term> + + <listitem><para>Only older versions of the package are + available or installed.</para></listitem> + + </varlistentry> + + <varlistentry><term><literal>- ?</literal></term> + + <listitem><para>No version of the package is available or + installed.</para></listitem> + + </varlistentry> + + </variablelist> + + </para></listitem> + + </varlistentry> + + <varlistentry><term><option>--system</option></term> + + <listitem><para>Print the <literal>system</literal> attribute of + the derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--drv-path</option></term> + + <listitem><para>Print the path of the store + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--out-path</option></term> + + <listitem><para>Print the output path of the + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--description</option></term> + + <listitem><para>Print a short (one-line) description of the + derivation, if available. The description is taken from the + <literal>meta.description</literal> attribute of the + derivation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--meta</option></term> + + <listitem><para>Print all of the meta-attributes of the + derivation. This option is only available with + <option>--xml</option>.</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 --rollback +error: no generation older than the current (91) exists</screen> + +</refsection> + +</refsection> + + +<refsection condition="manpage"><title>Environment variables</title> + +<variablelist> + + <varlistentry><term><envar>NIX_PROFILE</envar></term> + + <listitem><para>Location of the Nix profile. Defaults to the + target of the symlink <filename>~/.nix-profile</filename>, if it + exists, or <filename>/nix/var/nix/profiles/default</filename> + otherwise.</para></listitem> + + </varlistentry> + + <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> +</variablelist> + +</refsection> + + +</refentry> |