diff options
Diffstat (limited to 'doc/manual/command-ref/nix-env.xml')
| -rw-r--r-- | doc/manual/command-ref/nix-env.xml | 1503 |
1 files changed, 0 insertions, 1503 deletions
diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml deleted file mode 100644 index 55f25d959..000000000 --- a/doc/manual/command-ref/nix-env.xml +++ /dev/null @@ -1,1503 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - 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>Selectors</title> - -<para>Several commands, such as <command>nix-env -q</command> and -<command>nix-env -i</command>, take a list of arguments that specify -the packages on which to operate. These are extended regular -expressions that must match the entire name of the package. (For -details on regular expressions, see -<citerefentry><refentrytitle>regex</refentrytitle><manvolnum>7</manvolnum></citerefentry>.) -The match is case-sensitive. The regular expression can optionally be -followed by a dash and a version number; if omitted, any version of -the package will match. Here are some examples: - -<variablelist> - - <varlistentry> - <term><literal>firefox</literal></term> - <listitem><para>Matches the package name - <literal>firefox</literal> and any version.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>firefox-32.0</literal></term> - <listitem><para>Matches the package name - <literal>firefox</literal> and version - <literal>32.0</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>gtk\\+</literal></term> - <listitem><para>Matches the package name - <literal>gtk+</literal>. The <literal>+</literal> character must - be escaped using a backslash to prevent it from being interpreted - as a quantifier, and the backslash must be escaped in turn with - another backslash to ensure that the shell passes it - on.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>.\*</literal></term> - <listitem><para>Matches any package name. This is the default for - most commands.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>'.*zip.*'</literal></term> - <listitem><para>Matches any package name containing the string - <literal>zip</literal>. Note the dots: <literal>'*zip*'</literal> - does not work, because in a regular expression, the character - <literal>*</literal> is interpreted as a - quantifier.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>'.*(firefox|chromium).*'</literal></term> - <listitem><para>Matches any package name containing the strings - <literal>firefox</literal> or - <literal>chromium</literal>.</para></listitem> - </varlistentry> - -</variablelist> - -</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> / <option>-f</option> <replaceable>path</replaceable></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> - - <para>If the argument starts with <literal>http://</literal> or - <literal>https://</literal>, it is interpreted as the URL of a - tarball that will be downloaded and unpacked to a temporary - location. The tarball must include a single top-level directory - containing at least a file named <filename>default.nix</filename>.</para> - - </listitem> - - </varlistentry> - - <varlistentry><term><option>--profile</option> / <option>-p</option> <replaceable>path</replaceable></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>The source for 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>If <filename>~/.nix-defexpr</filename> is a file, - it is loaded as a Nix expression. If the expression - is a set, it is used as the default Nix expression. - If the expression is a function, an empty set is passed - as argument and the return value is used as - the default Nix expression.</para> - - <para>If <filename>~/.nix-defexpr</filename> is a directory - containing a <filename>default.nix</filename> file, that file - is loaded as in the above paragraph.</para> - - <para>If <filename>~/.nix-defexpr</filename> is a directory without - a <filename>default.nix</filename> file, then its contents - (both files and subdirectories) are loaded as Nix expressions. - The expressions are combined into a single set, each expression - under an attribute with the same name as the original file - or subdirectory. - </para> - - <para>For example, if <filename>~/.nix-defexpr</filename> contains - two files, <filename>foo.nix</filename> and <filename>bar.nix</filename>, - then the default Nix expression will essentially be - -<programlisting> -{ - foo = import ~/.nix-defexpr/foo.nix; - bar = import ~/.nix-defexpr/bar.nix; -}</programlisting> - - </para> - - <para>The file <filename>manifest.nix</filename> is always ignored. - Subdirectories without a <filename>default.nix</filename> file - are traversed recursively in search of more Nix expressions, - but the names of these intermediate directories are not - added to the attribute paths of the default Nix expression.</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> - - <listitem><para>By default all outputs are installed for each derivation. - That can be reduced by setting <literal>meta.outputsToInstall</literal>. - </para></listitem> <!-- TODO: link nixpkgs docs on the ability to override those. --> - -</itemizedlist> - -</para> - -</refsection> - - -<refsection><title>Flags</title> - -<variablelist> - - <varlistentry><term><option>--prebuilt-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 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 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 '<nixpkgs>' -iA hello --dry-run -(dry run; not doing anything) -installing ‘hello-2.10’ -this path will be fetched (0.04 MiB download, 0.19 MiB unpacked): - /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10 - <replaceable>...</replaceable></screen> - -</para> - -<para>To install Firefox from the latest revision in the Nixpkgs/NixOS -14.12 channel: - -<screen> -$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox -</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 followed 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"><title>Operation <option>--set</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--set</option></arg> - <arg choice='plain'><replaceable>drvname</replaceable></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The <option>--set</option> operation modifies the current generation of a -profile so that it contains exactly the specified derivation, and nothing else. -</para> - -</refsection> - -<refsection><title>Examples</title> - -<para> -The following updates a profile such that its current generation will contain -just Firefox: - -<screen> -$ nix-env -p /nix/var/nix/profiles/browser --set firefox</screen> - -</para> - -</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><option>--json</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>.</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>--json</option></term> - - <listitem><para>Print the result in a JSON representation suitable - for automatic processing by other tools.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--prebuilt-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>. This option only works - together with <option>--available</option></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> or <option>--json</option>.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To show installed packages: - -<screen> -$ nix-env -q -bison-1.875c -docbook-xml-4.2 -firefox-1.0.4 -MPlayer-1.0pre7 -ORBit2-2.8.3 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show available packages: - -<screen> -$ nix-env -qa -firefox-1.0.7 -GConf-2.4.0.1 -MPlayer-1.0pre7 -ORBit2-2.8.3 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show the status of available packages: - -<screen> -$ nix-env -qas --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> -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show available packages in the Nix expression <filename>foo.nix</filename>: - -<screen> -$ nix-env -f ./foo.nix -qa -foo-1.2.3 -</screen> - -</para> - -<para>To compare installed versions to what’s available: - -<screen> -$ nix-env -qc -<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> -</screen> - -</para> - -<para>To show all packages with “<literal>zip</literal>” in the name: - -<screen> -$ nix-env -qa '.*zip.*' -bzip2-1.0.6 -gzip-1.6 -zip-3.0 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show all packages with “<literal>firefox</literal>” or -“<literal>chromium</literal>” in the name: - -<screen> -$ nix-env -qa '.*(firefox|chromium).*' -chromium-37.0.2062.94 -chromium-beta-38.0.2125.24 -firefox-32.0.3 -firefox-with-plugins-13.0.1 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show all packages in the latest revision of the Nixpkgs -repository: - -<screen> -$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa -</screen> - -</para> - -</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, the -special value <literal>old</literal> to delete all non-current -generations, a value such as <literal>30d</literal> to delete all -generations older than the specified number of days (except for the -generation that was active at that point in time), or a value such as -<literal>+5</literal> to keep the last <literal>5</literal> generations -ignoring any newer than current, e.g., if <literal>30</literal> is the current -generation <literal>+5</literal> will delete generation <literal>25</literal> -and all older 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 --delete-generations +5 - -$ nix-env --delete-generations 30d - -$ 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> |