From e0ca6714911e34f86f6a644634ebaef86666e6dc Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Mon, 31 Dec 2007 02:52:17 +0000 Subject: * More documentation. --- doc/manual/nix-build.xml | 1 + doc/manual/nix-channel.xml | 10 +-- doc/manual/nix-env.xml | 204 ++++++++++++++++++++++++++++++++++++++++---- doc/manual/opt-common.xml | 11 +++ doc/manual/opt-inst-syn.xml | 7 ++ 5 files changed, 212 insertions(+), 21 deletions(-) (limited to 'doc/manual') diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml index 3f35f5de39fc..695ddcf46bbf 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/nix-build.xml @@ -19,6 +19,7 @@ nix-build name value + name value diff --git a/doc/manual/nix-channel.xml b/doc/manual/nix-channel.xml index 8ee4a5f2748b..14021067cb78 100644 --- a/doc/manual/nix-channel.xml +++ b/doc/manual/nix-channel.xml @@ -62,11 +62,11 @@ also . Downloads the Nix expressions of all subscribed - channels, makes the conjunction of these the default for - nix-env operations (by calling nix-env - -I), and performs a nix-pull on the - manifests of all channels to make pre-built binaries - available. + channels, makes them the default for nix-env + operations (by symlinking them in the directory + ~/.nix-defexpr), and performs a + nix-pull on the manifests of all channels to + make pre-built binaries available. diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml index a0ec489fd9e5..9f73b2d4c0f7 100644 --- a/doc/manual/nix-env.xml +++ b/doc/manual/nix-env.xml @@ -19,6 +19,7 @@ nix-env name value + name value @@ -141,13 +142,33 @@ linkend="sec-common-options" />. ~/.nix-defexpr - - - The default Nix expression used by the - , , and - operations to obtain - derivations. The option may be used to - override this default. + A directory that contains the default Nix + expressions used by the , + , and operations to obtain derivations. The + option may be used to override this + default. + + 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 ~/.nix-defexpr + contains two files, foo and + bar, then the default Nix expression will + essentially be + + +{ + foo = import ~/.nix-defexpr/foo; + bar = import ~/.nix-defexpr/bar; +} + + + + The command nix-channel places symlinks + to the downloaded Nix expressions from each subscribed channel in + this directory. + + @@ -212,11 +233,21 @@ number of possible ways: If there are multiple derivations matching a name in args that have the same name (e.g., gcc-3.3.6 and gcc-4.1.1), 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, nix-env -i - gcc-3.3.6 gcc-4.1.1 will install both version of GCC (and - will probably cause a user environment conflict!). + the derivation with the highest priority is + used. A derivation can define a priority by declaring the + meta.priority attribute. This attribute should + be a number, with a higher value denoting a lower priority. The + default priority is 0. + + If there are multiple matching derivations with the same + priority, then the derivation with 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, + nix-env -i gcc-3.3.6 gcc-4.1.1 will install both + version of GCC (and will probably cause a user environment + conflict!). If @@ -263,6 +294,15 @@ number of possible ways: + / + + 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. + + + @@ -378,7 +418,7 @@ the following paths will be substituted: -Operation <option>--upgrade</option> +Operation <option>--upgrade</option> Synopsis @@ -463,6 +503,9 @@ installed. +For the other flags, see . + Examples @@ -572,6 +615,111 @@ $ nix-env -e '*' (remove everything) + + +Operation <option>--set-flag</option> + +Synopsis + + + nix-env + + name + value + drvnames + + + +Description + +The 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 +nix-env or the user environment build +script: + + + + priority can be changed to + resolve filename clashes. The user environment build script uses + the meta.priority 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 + bin/ld, 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 + bin/ld is symlinked in the user + environment. + + keep can be set to + true 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. + + active can be set to + false 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 true to re-enable the + package. + + + + + + + +Examples + +To prevent the currently installed Firefox from being upgraded: + + +$ nix-env --set-flag keep true firefox + +After this, nix-env -u will ignore Firefox. + +To disable the currently installed Firefox, then install a new +Firefox while the old remains part of the profile: + + +$ nix-env -q \* +firefox-2.0.0.9 (the current one) + +$ 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/...-firefox-2.0.0.11/bin/firefox' + and `/nix/store/...-firefox-2.0.0.9/bin/firefox'. +(i.e., can’t have two active at the same time) + +$ 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 (the enabled one) +firefox-2.0.0.9 (the disabled one) + + + +To make files from binutils take precedence +over files from gcc: + + +$ nix-env --set-flag priority 5 binutils +$ nix-env --set-flag priority 10 gcc + + + + + + + + + Operation <option>--query</option> @@ -598,7 +746,12 @@ $ nix-env -e '*' (remove everything) - + + + + + + @@ -621,6 +774,7 @@ $ nix-env -e '*' (remove everything) + @@ -707,6 +861,16 @@ user environment elements, etc. --> + / + + 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. + + + @@ -726,8 +890,8 @@ user environment elements, etc. --> - - + + Print the attribute path of the derivation, which can be used to unambiguously select it using @@ -819,6 +983,14 @@ user environment elements, etc. --> + + + Print all of the meta-attributes of the + derivation. This option is only available with + . + + + diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml index 7dfb7b8f856c..316ad6658f74 100644 --- a/doc/manual/opt-common.xml +++ b/doc/manual/opt-common.xml @@ -268,6 +268,17 @@ + name value + + This option is like , only the + value is not a Nix expression but a string. So instead of + --arg system \"i686-linux\" (the outer quotes are + to keep the shell happy) you can say --argstr system + i686-linux. + + + + / attrPath diff --git a/doc/manual/opt-inst-syn.xml b/doc/manual/opt-inst-syn.xml index 1c32325e5089..e8c3f1ec6f04 100644 --- a/doc/manual/opt-inst-syn.xml +++ b/doc/manual/opt-inst-syn.xml @@ -1,5 +1,12 @@ + + + + + + + -- cgit 1.4.1