* More documentation.

This commit is contained in:
Eelco Dolstra 2007-12-31 02:52:17 +00:00
parent 6bdecfacbb
commit e0ca671491
6 changed files with 213 additions and 23 deletions

View file

@ -19,6 +19,7 @@
<command>nix-build</command>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
<arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
<arg>
<group choice='req'>
<arg choice='plain'><option>--attr</option></arg>

View file

@ -62,11 +62,11 @@ also <xref linkend="sec-channels" />.</para>
<varlistentry><term><option>--update</option></term>
<listitem><para>Downloads the Nix expressions of all subscribed
channels, makes the conjunction of these the default for
<command>nix-env</command> operations (by calling <command>nix-env
-I</command>), and performs a <command>nix-pull</command> on the
manifests of all channels to make pre-built binaries
available.</para></listitem>
channels, makes them the default for <command>nix-env</command>
operations (by symlinking them in the directory
<filename>~/.nix-defexpr</filename>), and performs a
<command>nix-pull</command> on the manifests of all channels to
make pre-built binaries available.</para></listitem>
</varlistentry>

View file

@ -19,6 +19,7 @@
<command>nix-env</command>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
<arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
<arg>
<group choice='req'>
<arg choice='plain'><option>--file</option></arg>
@ -141,13 +142,33 @@ linkend="sec-common-options" />.</para>
<varlistentry><term><filename>~/.nix-defexpr</filename></term>
<!-- !!! .nix-defexpr can be a directory now -->
<listitem><para>The default Nix expression 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></listitem>
<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 attribute 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>
@ -212,11 +233,21 @@ number of possible ways:
<para>If there are multiple derivations matching a name in
<replaceable>args</replaceable> that have the same name (e.g.,
<literal>gcc-3.3.6</literal> and <literal>gcc-4.1.1</literal>), then
only the highest version will be installed. You can force the
installation of multiple derivations with the same name by being
specific about the versions. For instance, <literal>nix-env -i
gcc-3.3.6 gcc-4.1.1</literal> will install both version of GCC (and
will probably cause a user environment conflict!).</para></listitem>
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>
@ -263,6 +294,15 @@ number of possible ways:
<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>
@ -378,7 +418,7 @@ the following paths will be substituted:
<!--######################################################################-->
<refsection><title>Operation <option>--upgrade</option></title>
<refsection xml:id="rsec-nix-env-upgrade"><title>Operation <option>--upgrade</option></title>
<refsection><title>Synopsis</title>
@ -463,6 +503,9 @@ installed.</para>
</variablelist>
<para>For the other flags, see <option
linkend="rsec-nix-env-install">--install</option>.</para>
</refsection>
<refsection><title>Examples</title>
@ -572,6 +615,111 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
<!--######################################################################-->
<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 formers
<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 wont 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'
Collission 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., cant 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>
@ -598,7 +746,12 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
<arg choice='plain'><option>-s</option></arg>
</group>
</arg>
<arg><option>--attr-path</option></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'>
@ -621,6 +774,7 @@ $ nix-env -e '*' <lineannotation>(remove everything)</lineannotation></screen>
<arg choice='plain'><option>-b</option></arg>
</group>
</arg>
<arg>
<group choice='req'>
<arg choice='plain'><option>--attr</option></arg>
@ -707,6 +861,16 @@ user environment elements, etc. -->
</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>
@ -726,8 +890,8 @@ user environment elements, etc. -->
</varlistentry>
<varlistentry><term><option>--attr</option></term>
<term><option>-a</option></term>
<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
@ -819,6 +983,14 @@ user environment elements, etc. -->
</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>

View file

@ -268,6 +268,17 @@
</varlistentry>
<varlistentry><term><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term>
<listitem><para>This option is like <option>--arg</option>, only the
value is not a Nix expression but a string. So instead of
<literal>--arg system \"i686-linux\"</literal> (the outer quotes are
to keep the shell happy) you can say <literal>--argstr system
i686-linux</literal>.</para></listitem>
</varlistentry>
<varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option>
<replaceable>attrPath</replaceable></term>

View file

@ -1,5 +1,12 @@
<nop xmlns="http://docbook.org/ns/docbook">
<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>

View file

@ -9,6 +9,7 @@ Operations:
--set: create a user environment containing a single derivation
--uninstall / -e: remove derivations from the user environment
--query / -q: perform a query on an environment or Nix expression
--set-flag NAME VALUE: set derivation meta-attribute to given value
The previous operations take a list of derivation names. The special
name `*' may be used to indicate all derivations.
@ -20,8 +21,6 @@ name `*' may be used to indicate all derivations.
--delete-generations GENERATIONS...: deleted listed generations,
`old' for all non-current generations
--import / -I FILE: set default Nix expression
--version: output version information
--help: display help