From 802150f987e720452920a3d1993c3b4b36861116 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 23 Jul 2020 14:28:05 +0200 Subject: [PATCH] -> Pandoc doesn't know so let's force it to be rendered as italics. --- .../advanced-topics/distributed-builds.xml | 4 +- doc/manual/command-ref/conf-file.xml | 34 +- doc/manual/command-ref/env-common.xml | 18 +- doc/manual/command-ref/nix-build.xml | 24 +- doc/manual/command-ref/nix-channel.xml | 32 +- .../command-ref/nix-collect-garbage.xml | 6 +- doc/manual/command-ref/nix-copy-closure.xml | 16 +- doc/manual/command-ref/nix-env.xml | 120 ++--- doc/manual/command-ref/nix-hash.xml | 24 +- doc/manual/command-ref/nix-instantiate.xml | 28 +- doc/manual/command-ref/nix-prefetch-url.xml | 30 +- doc/manual/command-ref/nix-shell.xml | 48 +- doc/manual/command-ref/nix-store.xml | 122 ++--- doc/manual/command-ref/opt-common-syn.xml | 16 +- doc/manual/command-ref/opt-common.xml | 46 +- doc/manual/command-ref/opt-inst-syn.xml | 2 +- .../expressions/advanced-attributes.xml | 18 +- doc/manual/expressions/build-script.xml | 2 +- doc/manual/expressions/builtins.xml | 420 +++++++++--------- doc/manual/expressions/expression-syntax.xml | 10 +- doc/manual/expressions/generic-builder.xml | 2 +- .../expressions/language-constructs.xml | 24 +- doc/manual/expressions/language-operators.xml | 78 ++-- doc/manual/expressions/language-values.xml | 8 +- .../expressions/simple-building-testing.xml | 2 +- doc/manual/installation/building-source.xml | 10 +- doc/manual/installation/env-variables.xml | 6 +- doc/manual/installation/installing-binary.xml | 2 +- doc/manual/installation/single-user.xml | 4 +- doc/manual/introduction/about-nix.xml | 2 +- doc/manual/introduction/quick-start.xml | 2 +- doc/manual/packages/basic-package-mgmt.xml | 4 +- doc/manual/packages/channels.xml | 2 +- .../packages/garbage-collector-roots.xml | 4 +- doc/manual/packages/profiles.xml | 2 +- doc/manual/release-notes/rl-0.10.xml | 16 +- doc/manual/release-notes/rl-0.12.xml | 16 +- doc/manual/release-notes/rl-0.13.xml | 4 +- doc/manual/release-notes/rl-0.16.xml | 8 +- doc/manual/release-notes/rl-0.6.xml | 8 +- doc/manual/release-notes/rl-0.8.xml | 4 +- doc/manual/release-notes/rl-1.1.xml | 4 +- doc/manual/release-notes/rl-1.11.xml | 8 +- doc/manual/release-notes/rl-1.2.xml | 2 +- doc/manual/release-notes/rl-1.4.xml | 4 +- doc/manual/release-notes/rl-1.6.1.xml | 8 +- doc/manual/release-notes/rl-1.7.xml | 12 +- doc/manual/release-notes/rl-1.8.xml | 4 +- doc/manual/release-notes/rl-2.0.xml | 12 +- doc/manual/src/command-ref/conf-file.md | 10 +- doc/manual/src/command-ref/nix-build.md | 12 +- doc/manual/src/command-ref/nix-channel.md | 21 +- .../src/command-ref/nix-collect-garbage.md | 2 +- doc/manual/src/command-ref/nix-env.md | 61 +-- doc/manual/src/command-ref/nix-hash.md | 14 +- doc/manual/src/command-ref/nix-instantiate.md | 8 +- .../src/command-ref/nix-prefetch-url.md | 22 +- doc/manual/src/command-ref/nix-shell.md | 30 +- doc/manual/src/command-ref/nix-store.md | 80 ++-- doc/manual/src/command-ref/opt-common.md | 26 +- .../src/expressions/advanced-attributes.md | 10 +- doc/manual/src/expressions/builtins.md | 372 ++++++++-------- .../src/expressions/expression-syntax.md | 2 +- .../src/expressions/language-constructs.md | 14 +- .../src/expressions/language-operators.md | 48 +- .../src/installation/building-source.md | 2 +- .../package-management/basic-package-mgmt.md | 3 +- doc/manual/src/release-notes/rl-0.10.md | 2 +- doc/manual/src/release-notes/rl-0.12.md | 4 +- doc/manual/src/release-notes/rl-0.13.md | 4 +- doc/manual/src/release-notes/rl-0.16.md | 2 +- doc/manual/src/release-notes/rl-0.6.md | 4 +- doc/manual/src/release-notes/rl-1.11.md | 2 +- doc/manual/src/release-notes/rl-1.4.md | 2 +- doc/manual/src/release-notes/rl-1.6.1.md | 4 +- doc/manual/src/release-notes/rl-1.7.md | 6 +- 76 files changed, 1029 insertions(+), 1020 deletions(-) diff --git a/doc/manual/advanced-topics/distributed-builds.xml b/doc/manual/advanced-topics/distributed-builds.xml index a649b6f8d..ec9e98e77 100644 --- a/doc/manual/advanced-topics/distributed-builds.xml +++ b/doc/manual/advanced-topics/distributed-builds.xml @@ -86,7 +86,7 @@ To leave a field at its default, set it to -. The URI of the remote store in the format - ssh://[username@]hostname, + ssh://[username@]hostname, e.g. ssh://nix@mac or ssh://mac. For backward compatibility, ssh:// may be omitted. The hostname may be an @@ -171,7 +171,7 @@ builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd Finally, remote builders can be configured in a separate configuration file included in via the syntax -@file. For example, +@file. For example, builders = @/etc/nix/machines diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml index 4c103f505..62cc117b6 100644 --- a/doc/manual/command-ref/conf-file.xml +++ b/doc/manual/command-ref/conf-file.xml @@ -26,7 +26,7 @@ The system-wide configuration file - sysconfdir/nix/nix.conf + sysconfdir/nix/nix.conf (i.e. /etc/nix/nix.conf on most systems), or $NIX_CONF_DIR/nix.conf if NIX_CONF_DIR is set. Values loaded in this @@ -52,11 +52,11 @@ The configuration files consist of -name = -value pairs, one per line. Other +name = +value pairs, one per line. Other files can be included with a line like include -path, where -path is interpreted relative to the current +path, where +path is interpreted relative to the current conf file and a missing file is an error unless !include is used instead. Comments start with a # character. Here is an @@ -244,7 +244,7 @@ false. instance, in Nixpkgs, if the derivation attribute enableParallelBuilding is set to true, the builder passes the - flag to GNU Make. + flag to GNU Make. It can be overridden using the command line switch and defaults to 1. The value 0 @@ -383,10 +383,10 @@ false. builtins.fetchurl to obtain files by hash. The default is http://tarballs.nixos.org/. Given a hash type - ht and a base-16 hash - h, Nix will try to download the file + ht and a base-16 hash + h, Nix will try to download the file from - hashed-mirror/ht/h. + hashed-mirror/ht/h. This allows files to be downloaded even if they have disappeared from their original URI. For example, given the default mirror http://tarballs.nixos.org/, when building the derivation @@ -421,7 +421,7 @@ builtins.fetchurl { output and error of its builder) to the directory /nix/var/log/nix/drvs. The build log can be retrieved using the command nix-store -l - path. + path. @@ -592,9 +592,9 @@ builtins.fetchurl { accounts in the following format: -machine my-machine -login my-username -password my-password +machine my-machine +login my-username +password my-password For the exact syntax, see my-password A list of paths bind-mounted into Nix sandbox environments. You can use the syntax - target=source + target=source to mount a path in a different location in the sandbox; for instance, /bin=/nix-bin will mount the path /nix-bin as /bin inside the - sandbox. If source is followed by + sandbox. If source is followed by ?, then it is not an error if - source does not exist; for example, + source does not exist; for example, /dev/nvidiactl? specifies that /dev/nvidiactl will only be mounted in the sandbox if it exists in the host filesystem. @@ -1035,7 +1035,7 @@ function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684 A list of URLs of substituters, separated by whitespace. These are not used by default, but can be enabled by users of the Nix daemon by specifying --option - substituters urls on the + substituters urls on the command line. Unprivileged users are only allowed to pass a subset of the URLs listed in substituters and trusted-substituters. diff --git a/doc/manual/command-ref/env-common.xml b/doc/manual/command-ref/env-common.xml index 3196cbbd2..ac40fccf7 100644 --- a/doc/manual/command-ref/env-common.xml +++ b/doc/manual/command-ref/env-common.xml @@ -25,7 +25,7 @@ A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (i.e., - <path>). For + <path>). For instance, the value @@ -40,10 +40,10 @@ nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos will cause Nix to search for - <nixpkgs/path> in - /home/eelco/Dev/nixpkgs-branch/path + <nixpkgs/path> in + /home/eelco/Dev/nixpkgs-branch/path and - /etc/nixos/nixpkgs/path. + /etc/nixos/nixpkgs/path. If a path in the Nix search path starts with http:// or https://, it is @@ -105,7 +105,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix NIX_STORE_DIR Overrides the location of the Nix store (default - prefix/store). + prefix/store). @@ -114,7 +114,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix Overrides the location of the Nix static data directory (default - prefix/share). + prefix/share). @@ -122,7 +122,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix NIX_LOG_DIR Overrides the location of the Nix log directory - (default prefix/var/log/nix). + (default prefix/var/log/nix). @@ -130,7 +130,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix NIX_STATE_DIR Overrides the location of the Nix state directory - (default prefix/var/nix). + (default prefix/var/nix). @@ -139,7 +139,7 @@ $ mount -o bind /mnt/otherdisk/nix /nix Overrides the location of the system Nix configuration directory (default - prefix/etc/nix). + prefix/etc/nix). diff --git a/doc/manual/command-ref/nix-build.xml b/doc/manual/command-ref/nix-build.xml index 886d25910..ec9145143 100644 --- a/doc/manual/command-ref/nix-build.xml +++ b/doc/manual/command-ref/nix-build.xml @@ -20,14 +20,14 @@ nix-build - name value - name value + name value + name value - attrPath + attrPath @@ -36,16 +36,16 @@ - outlink + outlink - paths + paths Description The nix-build command builds the derivations -described by the Nix expressions in paths. +described by the Nix expressions in paths. If the build succeeds, it places a symlink to the result in the current directory. The symlink is called result. If there are multiple Nix expressions, or the Nix expressions evaluate @@ -53,11 +53,11 @@ to multiple derivations, multiple sequentially numbered symlinks are created (result, result-2, and so on). -If no paths are specified, then +If no paths are specified, then nix-build will use default.nix in the current directory, if it exists. -If an element of paths starts with +If an element of paths starts with http:// or https://, 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 @@ -104,11 +104,11 @@ also . / - outlink + outlink Change the name of the symlink to the output path created from result to - outlink. + outlink. @@ -131,7 +131,7 @@ store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv /nix/store/d18hyl92g30l...-firefox-1.5.0.7 $ ls -l result -lrwxrwxrwx ... result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 +lrwxrwxrwx ... result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 $ ls ./result/bin/ firefox firefox-config @@ -143,7 +143,7 @@ You can also build all outputs: $ nix-build '<nixpkgs>' -A openssl.all This will create a symlink for each output named -result-outputname. +result-outputname. The suffix is omitted if the output name is out. So if openssl has outputs out, bin and man, diff --git a/doc/manual/command-ref/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml index ebcf56aff..2abeca0a0 100644 --- a/doc/manual/command-ref/nix-channel.xml +++ b/doc/manual/command-ref/nix-channel.xml @@ -20,11 +20,11 @@ nix-channel - url name - name + url name + name - names - generation + names + generation @@ -44,22 +44,22 @@ xlink:href="https://nixos.org/channels" />. - url [name] + url [name] Adds a channel named - name with URL - url to the list of subscribed channels. - If name is omitted, it defaults to the - last component of url, with the + name with URL + url to the list of subscribed channels. + If name is omitted, it defaults to the + last component of url, with the suffixes -stable or -unstable removed. - name + name Removes the channel named - name from the list of subscribed + name from the list of subscribed channels. @@ -71,18 +71,18 @@ xlink:href="https://nixos.org/channels" />. - [names…] + [names…] Downloads the Nix expressions of all subscribed channels (or only those included in - names if specified) and makes them the + names if specified) and makes them the default for nix-env operations (by symlinking them from the directory ~/.nix-defexpr). - [generation] + [generation] Reverts the previous call to nix-channel --update. Optionally, you can specify a specific channel @@ -130,7 +130,7 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' - /nix/var/nix/profiles/per-user/username/channels + /nix/var/nix/profiles/per-user/username/channels nix-channel uses a nix-env profile to keep track of previous @@ -145,7 +145,7 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' ~/.nix-defexpr/channels This is a symlink to - /nix/var/nix/profiles/per-user/username/channels. It + /nix/var/nix/profiles/per-user/username/channels. It ensures that nix-env can find your channels. In a multi-user installation, you may also have ~/.nix-defexpr/channels_root, which links to diff --git a/doc/manual/command-ref/nix-collect-garbage.xml b/doc/manual/command-ref/nix-collect-garbage.xml index 43e068796..cbcb5add5 100644 --- a/doc/manual/command-ref/nix-collect-garbage.xml +++ b/doc/manual/command-ref/nix-collect-garbage.xml @@ -21,8 +21,8 @@ nix-collect-garbage - period - bytes + period + bytes @@ -39,7 +39,7 @@ which deletes all old generations of all profiles in nix-env --delete-generations old on all profiles (of course, this makes rollbacks to previous configurations impossible); and - period, + period, where period is a value such as 30d, which deletes all generations older than the specified number of days in all profiles in /nix/var/nix/profiles (except for the generations diff --git a/doc/manual/command-ref/nix-copy-closure.xml b/doc/manual/command-ref/nix-copy-closure.xml index 8c07984fb..6fc8c312b 100644 --- a/doc/manual/command-ref/nix-copy-closure.xml +++ b/doc/manual/command-ref/nix-copy-closure.xml @@ -33,9 +33,9 @@ - user@machine + user@machine - paths + paths @@ -44,13 +44,13 @@ nix-copy-closure gives you an easy and efficient way to exchange software between machines. Given one or -more Nix store paths on the local +more Nix store paths on the local machine, nix-copy-closure computes the closure of those paths (i.e. all their dependencies in the Nix store), and copies all paths in the closure to the remote machine via the ssh (Secure Shell) command. With the , the direction is reversed: -the closure of paths on a remote machine is +the closure of paths on a remote machine is copied to the Nix store on the local machine. This command is efficient because it only sends the store paths @@ -73,8 +73,8 @@ those paths. If this bothers you, use Copy the closure of - paths from the local Nix store to the - Nix store on machine. This is the + paths from the local Nix store to the + Nix store on machine. This is the default. @@ -82,8 +82,8 @@ those paths. If this bothers you, use Copy the closure of - paths from the Nix store on - machine to the local Nix + paths from the Nix store on + machine to the local Nix store. diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml index 4dedd90ca..6a97c7e37 100644 --- a/doc/manual/command-ref/nix-env.xml +++ b/doc/manual/command-ref/nix-env.xml @@ -20,30 +20,30 @@ nix-env - name value - name value + name value + name value - path + path - path + path - system + system - operation - options - arguments + operation + options + arguments @@ -146,7 +146,7 @@ also . - / path + / path Specifies the Nix expression (designated below as the active Nix expression) used by the @@ -165,7 +165,7 @@ also . - / path + / path Specifies the profile to be used by those operations that operate on a profile (designated below as the @@ -194,12 +194,12 @@ also . - system + system By default, operations such as show derivations matching any platform. This option allows you to use derivations for the specified platform - system. + system. @@ -276,7 +276,7 @@ also . A symbolic link to the user's current profile. By default, this symlink points to - prefix/var/nix/profiles/default. + prefix/var/nix/profiles/default. The PATH environment variable should include ~/.nix-profile/bin for the user environment to be visible to the user. @@ -310,7 +310,7 @@ also . - args + args @@ -320,13 +320,13 @@ also . 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 args is added. The -arguments args map to store paths in a +paths described by args is added. The +arguments args map to store paths in a number of possible ways: - By default, args is a set + By default, args 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 @@ -335,7 +335,7 @@ number of possible ways: specified. If there are multiple derivations matching a name in - args that have the same name (e.g., + args that have the same name (e.g., gcc-3.3.6 and gcc-4.1.1), then the derivation with the highest priority is used. A derivation can define a priority by declaring the @@ -362,14 +362,14 @@ number of possible ways: packages, use nix-env -qaP. If - path is given, - args is a set of names denoting installed - store paths in the profile path. This is + path is given, + args is a set of names denoting installed + store paths in the profile path. This is an easy way to copy user environment elements from one profile to another. If is given, - args are Nix args are Nix functions that are called with the active Nix expression as their single argument. The derivations returned by those function calls are installed. This allows @@ -377,12 +377,12 @@ number of possible ways: if there are multiple derivations with the same name. - If args are store + If args are store derivations, then these are realised, and the resulting output paths are installed. - If args are store paths + If args are store paths that are not store derivations, then these are realised and installed. @@ -518,7 +518,7 @@ $ nix-env -f '<nixpkgs>' -iA hello --dry-run installing ‘hello-2.10’ this path will be fetched (0.04 MiB download, 0.19 MiB unpacked): /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10 - ... + ... @@ -556,7 +556,7 @@ $ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA fir - args + args @@ -566,15 +566,15 @@ $ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA fir 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 args. Paths for which there +described by args. 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 args +also not an error if an element of args matches no installed derivations. -For a description of how args is +For a description of how args is mapped to a set of store paths, see . If -args describes multiple store paths with +args describes multiple store paths with the same symbolic name, only the one with the highest version is installed. @@ -711,7 +711,7 @@ lexicographically (i.e., using case-sensitive string comparison). - drvnames + drvnames @@ -720,7 +720,7 @@ lexicographically (i.e., using case-sensitive string comparison). 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 -names are removed. +names are removed. @@ -745,7 +745,7 @@ $ nix-env -e '.*' (remove everything) nix-env - drvname + drvname @@ -783,9 +783,9 @@ $ nix-env -p /nix/var/nix/profiles/browser --set firefox nix-env - name - value - drvnames + name + value + drvnames @@ -848,8 +848,8 @@ 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' -collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox' - and `/nix/store/...-firefox-2.0.0.9/bin/firefox'. +collision 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 @@ -940,12 +940,12 @@ $ nix-env --set-flag priority 10 gcc - attribute-path + attribute-path - names + names @@ -959,7 +959,7 @@ profile (), or the derivations that are available for installation in the active Nix expression (). It only prints information about derivations whose symbolic name matches one of -names. +names. The derivations are sorted by their name attributes. @@ -1086,21 +1086,21 @@ user environment elements, etc. --> - < version + < version A newer version of the package is available or installed. - = version + = version At most the same version of the package is available or installed. - > version + > version Only older versions of the package are available or installed. @@ -1174,7 +1174,7 @@ docbook-xml-4.2 firefox-1.0.4 MPlayer-1.0pre7 ORBit2-2.8.3 -… +… @@ -1187,7 +1187,7 @@ firefox-1.0.7 GConf-2.4.0.1 MPlayer-1.0pre7 ORBit2-2.8.3 -… +… @@ -1200,7 +1200,7 @@ $ nix-env -qas --S GConf-2.4.0.1 (not present, but there is a substitute for fast installation) --S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!) IP- ORBit2-2.8.3 (installed and by definition present) -… +… @@ -1218,11 +1218,11 @@ foo-1.2.3 $ nix-env -qc -... +... acrobat-reader-7.0 - ? (package is not available at all) autoconf-2.59 = 2.59 (same version) firefox-1.0.4 < 1.0.7 (a more recent version is available) -... +... @@ -1234,7 +1234,7 @@ $ nix-env -qa '.*zip.*' bzip2-1.0.6 gzip-1.6 zip-3.0 -… +… @@ -1248,7 +1248,7 @@ chromium-37.0.2062.94 chromium-beta-38.0.2125.24 firefox-32.0.3 firefox-with-plugins-13.0.1 -… +… @@ -1280,7 +1280,7 @@ $ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa - path + path @@ -1288,10 +1288,10 @@ $ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa Description -This operation makes path the current +This operation makes path the current profile for the user. That is, the symlink ~/.nix-profile is made to point to -path. +path. @@ -1355,7 +1355,7 @@ $ nix-env --list-generations nix-env - generations + generations @@ -1407,7 +1407,7 @@ $ nix-env -p other_profile --delete-generations old - generation + generation @@ -1416,13 +1416,13 @@ $ nix-env -p other_profile --delete-generations old Description This operation makes generation number -generation the current generation of the +generation the current generation of the active profile. That is, if the -profile is the path to +profile is the path to the active profile, then the symlink -profile is made to +profile is made to point to -profile-generation-link, +profile-generation-link, which is in turn a symlink to the actual user environment in the Nix store. diff --git a/doc/manual/command-ref/nix-hash.xml b/doc/manual/command-ref/nix-hash.xml index 80263e18e..2f80dc568 100644 --- a/doc/manual/command-ref/nix-hash.xml +++ b/doc/manual/command-ref/nix-hash.xml @@ -22,18 +22,18 @@ - hashAlgo - path + hashAlgo + path nix-hash - hash + hash nix-hash - hash + hash @@ -42,7 +42,7 @@ The command nix-hash computes the cryptographic hash of the contents of each -path and prints it on standard output. By +path and prints it on standard output. By default, it computes an MD5 hash, but other hash algorithms are available as well. The hash is printed in hexadecimal. To generate the same hash as nix-prefetch-url you have to @@ -54,9 +54,9 @@ allows directories and symlinks to be hashed as well as regular files. The dump is in the NAR format produced by nix-store . Thus, nix-hash -path yields the same +path yields the same cryptographic hash as nix-store --dump -path | md5sum. +path | md5sum. @@ -68,9 +68,9 @@ cryptographic hash as nix-store --dump Print the cryptographic hash of the contents of - each regular file path. That is, do + each regular file path. That is, do not compute the hash over the dump of - path. The result is identical to that + path. The result is identical to that produced by the GNU commands md5sum and sha1sum. @@ -92,7 +92,7 @@ cryptographic hash as nix-store --dump - hashAlgo + hashAlgo Use the specified cryptographic hash algorithm, which can be one of md5, @@ -104,7 +104,7 @@ cryptographic hash as nix-store --dump Don’t hash anything, but convert the base-32 hash - representation hash to + representation hash to hexadecimal. @@ -112,7 +112,7 @@ cryptographic hash as nix-store --dump Don’t hash anything, but convert the hexadecimal - hash representation hash to + hash representation hash to base-32. diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml index 4ff967ecf..d67be4924 100644 --- a/doc/manual/command-ref/nix-instantiate.xml +++ b/doc/manual/command-ref/nix-instantiate.xml @@ -29,26 +29,26 @@ - name value + name value - attrPath + attrPath - path + path - files + files nix-instantiate - files + files @@ -58,13 +58,13 @@ The command nix-instantiate generates store derivations from (high-level) Nix expressions. It evaluates the Nix expressions in each of -files (which defaults to -./default.nix). Each top-level expression +files (which defaults to +./default.nix). Each top-level expression should evaluate to a derivation, a list of derivations, or a set of derivations. The paths of the resulting store derivations are printed on standard output. -If files is the character +If files is the character -, then a Nix expression will be read from standard input. @@ -79,7 +79,7 @@ input. - path + path See the corresponding @@ -181,7 +181,7 @@ $ nix-instantiate test.nix (instantiate) /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv $ nix-store -r $(nix-instantiate test.nix) (build) -... +... /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path) $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 @@ -226,28 +226,28 @@ $ nix-instantiate --eval --xml -E '1 + 2' $ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }' -...... ]]> -... +... Note that y is left unevaluated (the XML representation doesn’t attempt to show non-normal forms). $ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }' -...... ]]> -... +... diff --git a/doc/manual/command-ref/nix-prefetch-url.xml b/doc/manual/command-ref/nix-prefetch-url.xml index 621ded72e..db2a6960a 100644 --- a/doc/manual/command-ref/nix-prefetch-url.xml +++ b/doc/manual/command-ref/nix-prefetch-url.xml @@ -20,24 +20,24 @@ nix-prefetch-url - hashAlgo + hashAlgo - name - url - hash + name + url + hash Description The command nix-prefetch-url downloads the -file referenced by the URL url, prints its +file referenced by the URL url, prints its cryptographic hash, and copies it into the Nix store. The file name in the store is -hash-baseName, -where baseName is everything following the -final slash in url. +hash-baseName, +where baseName is everything following the +final slash in url. This command is just a convenience for Nix expression writers. Often a Nix expression fetches some source distribution from the @@ -50,7 +50,7 @@ download it again when you build your Nix expression. Since as nix-prefetch-url, the redundant download can be avoided. -If hash is specified, then a download +If hash is specified, then a download is not performed if the Nix store already contains a file with the same hash and base name. Otherwise, the file is downloaded, and an error is signaled if the actual hash of the file does not match the @@ -67,7 +67,7 @@ downloaded file in the Nix store is also printed. - hashAlgo + hashAlgo Use the specified cryptographic hash algorithm, which can be one of md5, @@ -93,14 +93,14 @@ downloaded file in the Nix store is also printed. - name + name Override the name of the file in the Nix store. By default, this is - hash-basename, - where basename is the last component of - url. Overriding the name is necessary - when basename contains characters that + hash-basename, + where basename is the last component of + url. Overriding the name is necessary + when basename contains characters that are not allowed in Nix store paths. diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml index de9755d58..1d55b5622 100644 --- a/doc/manual/command-ref/nix-shell.xml +++ b/doc/manual/command-ref/nix-shell.xml @@ -19,20 +19,20 @@ nix-shell - name value - name value + name value + name value - attrPath + attrPath - cmd - cmd - regexp + cmd + cmd + regexp - name + name @@ -41,12 +41,12 @@ - packages - expressions + packages + expressions - path + path @@ -57,17 +57,17 @@ dependencies of the specified derivation, but not the derivation itself. It will then start an interactive shell in which all environment variables defined by the derivation -path have been set to their corresponding +path have been set to their corresponding values, and the script $stdenv/setup has been sourced. This is useful for reproducing the environment of a derivation for development. -If path is not given, +If path is not given, nix-shell defaults to shell.nix if it exists, and default.nix otherwise. -If path starts with +If path starts with http:// or https://, 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 @@ -103,10 +103,10 @@ also . - cmd + cmd In the environment of the derivation, run the - shell command cmd. This command is + shell command cmd. This command is executed in an interactive shell. (Use to use a non-interactive shell instead.) However, a call to exit is implicitly added to the command, so the @@ -118,7 +118,7 @@ also . - cmd + cmd Like , but executes the command in a non-interactive shell. This means (among other @@ -127,10 +127,10 @@ also . - regexp + regexp Do not build any dependencies whose store path - matches the regular expression regexp. + matches the regular expression regexp. This option may be specified multiple times. @@ -150,7 +150,7 @@ also . - / packages… + / packages… Set up an environment in which the specified packages are present. The command line arguments are interpreted @@ -162,7 +162,7 @@ also . - interpreter + interpreter The chained script interpreter to be invoked by nix-shell. Only applicable in @@ -171,7 +171,7 @@ also . - name + name When a shell is started, keep the listed environment variables. @@ -278,13 +278,13 @@ following lines: #! /usr/bin/env nix-shell -#! nix-shell -i real-interpreter -p packages +#! nix-shell -i real-interpreter -p packages -where real-interpreter is the “real” script +where real-interpreter is the “real” script interpreter that will be invoked by nix-shell after it has obtained the dependencies and initialised the environment, and -packages are the attribute names of the +packages are the attribute names of the dependencies in Nixpkgs. The lines starting with #! nix-shell specify diff --git a/doc/manual/command-ref/nix-store.xml b/doc/manual/command-ref/nix-store.xml index 459100984..352e716ae 100644 --- a/doc/manual/command-ref/nix-store.xml +++ b/doc/manual/command-ref/nix-store.xml @@ -20,11 +20,11 @@ nix-store - path + path - operation - options - arguments + operation + options + arguments @@ -55,14 +55,14 @@ options. - path + path Causes the result of a realisation ( and ) to be registered as a root of the garbage collector (see ). The root is stored in - path, which must be inside a directory + path, which must be inside a directory that is scanned for roots by the garbage collector (i.e., typically in a subdirectory of /nix/var/nix/gcroots/) @@ -88,11 +88,11 @@ options. garbage-collected unless the symlink is removed. The flag causes a uniquely named - symlink to path to be stored in + symlink to path to be stored in /nix/var/nix/gcroots/auto/. For instance, -$ nix-store --add-root /home/eelco/bla/result --indirect -r ... +$ nix-store --add-root /home/eelco/bla/result --indirect -r ... $ ls -l /nix/var/nix/gcroots/auto lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result @@ -135,7 +135,7 @@ lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134 - paths + paths @@ -204,7 +204,7 @@ printed.) with , if an output path is not identical to the corresponding output from the previous build, the new output path is left in - /nix/store/name.check. + /nix/store/name.check. See also the configuration option, which repeats a derivation a number of times and prevents @@ -361,7 +361,7 @@ EOF - bytes + bytes @@ -413,11 +413,11 @@ options control what gets deleted and in what order: - bytes + bytes Keep deleting paths until at least - bytes bytes have been deleted, then - stop. The argument bytes can be + bytes bytes have been deleted, then + stop. The argument bytes can be followed by the multiplicative suffix K, M, G or T, denoting KiB, MiB, GiB or TiB @@ -450,7 +450,7 @@ be freed. $ nix-store --gc deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv' -... +... 8825586 bytes freed (8.42 MiB) @@ -479,7 +479,7 @@ $ nix-store --gc --max-freed $((100 * 1024 * 1024)) nix-store - paths + paths @@ -487,7 +487,7 @@ $ nix-store --gc --max-freed $((100 * 1024 * 1024)) Description The operation deletes the store paths -paths from the Nix store, but only if it is +paths from the Nix store, but only if it is safe to do so; that is, when the path is not reachable from a root of the garbage collector. This means that you can only delete paths that would also be deleted by nix-store --gc. Thus, @@ -537,8 +537,8 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' - name - name + name + name @@ -547,7 +547,7 @@ error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' - paths + paths @@ -560,7 +560,7 @@ information about the store paths . The queries are described below. At most one query can be specified. The default query is . -The paths paths may also be symlinks +The paths paths may also be symlinks from outside of the Nix store, to the Nix store. In that case, the query is applied to the target of the symlink. @@ -603,7 +603,7 @@ query is applied to the target of the symlink. Prints out the output paths of the store - derivations paths. These are the paths + derivations paths. These are the paths that will be produced when the derivation is built. @@ -614,7 +614,7 @@ query is applied to the target of the symlink. Prints out the closure of the store path - paths. + paths. This query has one option: @@ -647,7 +647,7 @@ query is applied to the target of the symlink. Prints the set of references of the store paths - paths, that is, their immediate + paths, that is, their immediate dependencies. (For all dependencies, use .) @@ -656,9 +656,9 @@ query is applied to the target of the symlink. Prints the set of referrers of - the store paths paths, that is, the + the store paths paths, that is, the store paths currently existing in the Nix store that refer to one - of paths. Note that contrary to the + of paths. Note that contrary to the references, the set of referrers is not constant; it can change as store paths are added or removed. @@ -667,11 +667,11 @@ query is applied to the target of the symlink. Prints the closure of the set of store paths - paths under the referrers relation; that + paths under the referrers relation; that is, all store paths that directly or indirectly refer to one of - paths. These are all the path currently + paths. These are all the path currently in the Nix store that are dependent on - paths. + paths. @@ -680,7 +680,7 @@ query is applied to the target of the symlink. Prints the deriver of the store paths - paths. If the path has no deriver + paths. If the path has no deriver (e.g., if it is a source file), or if the deriver is not known (e.g., in the case of a binary-only deployment), the string unknown-deriver is printed. @@ -690,7 +690,7 @@ query is applied to the target of the symlink. Prints the references graph of the store paths - paths in the format of the + paths in the format of the dot tool of AT&T's Graphviz package. This can be used to visualise dependency graphs. To obtain a @@ -703,7 +703,7 @@ query is applied to the target of the symlink. Prints the references graph of the store paths - paths as a nested ASCII tree. + paths as a nested ASCII tree. References are ordered by descending closure size; this tends to flatten the tree, making it more readable. The query only recurses into a store path when it is first encountered; this @@ -715,7 +715,7 @@ query is applied to the target of the symlink. Prints the references graph of the store paths - paths in the paths in the GraphML file format. This can be used to visualise dependency graphs. To obtain a build-time dependency graph, apply this to a store derivation. To @@ -724,12 +724,12 @@ query is applied to the target of the symlink. - name - name + name + name Prints the value of the attribute - name (i.e., environment variable) of - the store derivations paths. It is an + name (i.e., environment variable) of + the store derivations paths. It is an error for a derivation to not have the specified attribute. @@ -738,7 +738,7 @@ query is applied to the target of the symlink. Prints the SHA-256 hash of the contents of the - store paths paths (that is, the hash of + store paths paths (that is, the hash of the output of nix-store --dump on the given paths). Since the hash is stored in the Nix database, this is a fast operation. @@ -748,7 +748,7 @@ query is applied to the target of the symlink. Prints the size in bytes of the contents of the - store paths paths — to be precise, the + store paths paths — to be precise, the size of the output of nix-store --dump on the given paths. Note that the actual disk space required by the store paths may be higher, especially on filesystems with large @@ -760,7 +760,7 @@ query is applied to the target of the symlink. Prints the garbage collector roots that point, directly or indirectly, at the store paths - paths. + paths. @@ -778,7 +778,7 @@ query is applied to the target of the symlink. $ nix-store -qR $(which svn) /nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 /nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4 -... +... @@ -789,7 +789,7 @@ $ nix-store -qR $(nix-store -qd $(which svn)) /nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv /nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh /nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv -... lots of other paths ... +... lots of other paths ... The difference with the previous example is that we ask the closure of the derivation (), not the closure of the output @@ -804,7 +804,7 @@ $ nix-store -q --tree $(nix-store -qd $(which svn)) +---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv | +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash | +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh -... +... @@ -827,7 +827,7 @@ $ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(wh $ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}') /nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2 /nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4 -... +... Note that ldd is a command that prints out the dynamic libraries used by an ELF executable. @@ -893,7 +893,7 @@ $ nix-store -q --roots $(which svn) nix-store - paths + paths @@ -926,8 +926,8 @@ $ nix-store --add ./foo.c nix-store - algorithm - paths + algorithm + paths @@ -1039,7 +1039,7 @@ in Nix itself. nix-store - paths + paths @@ -1077,7 +1077,7 @@ $ nix-store --verify-path $(nix-store -qR $(which svn)) nix-store - paths + paths @@ -1123,7 +1123,7 @@ fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'... nix-store - path + path @@ -1131,7 +1131,7 @@ fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'... The operation produces a NAR (Nix ARchive) file containing the contents of the file system tree rooted -at path. The archive is written to +at path. The archive is written to standard output. A NAR archive is like a TAR or Zip archive, but it contains only @@ -1173,14 +1173,14 @@ links, but not other types of files (such as device nodes). nix-store - path + path Description The operation unpacks a NAR archive -to path, which must not already exist. The +to path, which must not already exist. The archive is read from standard input. @@ -1198,7 +1198,7 @@ archive is read from standard input. nix-store - paths + paths @@ -1220,7 +1220,7 @@ that are missing in the target Nix store, the import will fail. To copy a whole closure, do something like: -$ nix-store --export $(nix-store -qR paths) > out +$ nix-store --export $(nix-store -qR paths) > out To import the whole closure again, run: @@ -1299,7 +1299,7 @@ progress indication. $ nix-store --optimise hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1' -... +... 541838819 bytes (516.74 MiB) freed by hard-linking 54143 files; there are 114486 files with equal contents out of 215894 files in total @@ -1322,7 +1322,7 @@ there are 114486 files with equal contents out of 215894 files in total - paths + paths @@ -1351,7 +1351,7 @@ unpacking sources unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz ktorrent-2.2.1/ ktorrent-2.2.1/NEWS -... +... @@ -1369,7 +1369,7 @@ ktorrent-2.2.1/NEWS nix-store - paths + paths @@ -1424,7 +1424,7 @@ loads it into the Nix database. nix-store - drvpath + drvpath @@ -1441,7 +1441,7 @@ variable _args. $ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox) -… +… export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2' export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv' export system; system='x86_64-linux' diff --git a/doc/manual/command-ref/opt-common-syn.xml b/doc/manual/command-ref/opt-common-syn.xml index 2660e3bb1..6b7b5c833 100644 --- a/doc/manual/command-ref/opt-common-syn.xml +++ b/doc/manual/command-ref/opt-common-syn.xml @@ -13,7 +13,7 @@ - format + format @@ -26,19 +26,19 @@ - number + number - number + number - number + number - number + number @@ -56,12 +56,12 @@ - path + path - name - value + name + value diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml index 150e732ff..67950e94b 100644 --- a/doc/manual/command-ref/opt-common.xml +++ b/doc/manual/command-ref/opt-common.xml @@ -92,12 +92,12 @@ - format + format This option can be used to change the output of the log format, with - format being one of: + format being one of: @@ -130,13 +130,13 @@ error. This option suppresses this behaviour. Note that the builder's standard output and error are always written to a log file in - prefix/nix/var/log/nix. + prefix/nix/var/log/nix. / -number +number @@ -166,7 +166,7 @@ of parallelism. For instance, in Nixpkgs, if the derivation attribute enableParallelBuilding is set to true, the builder passes the - flag to GNU Make. + flag to GNU Make. It defaults to the value of the cores configuration setting, if set, or 1 otherwise. @@ -271,7 +271,7 @@ - name value + name value This option is accepted by nix-env, nix-instantiate, @@ -280,14 +280,14 @@ automatically try to call functions that it encounters. It can automatically call functions for which every argument has a default value - (e.g., { argName ? - defaultValue }: - ...). With + (e.g., { argName ? + defaultValue }: + ...). With , you can also call functions that have arguments without a default value (or override a default value). That is, if the evaluator encounters a function with an argument - named name, it will call it with value - value. + named name, it will call it with value + value. For instance, the top-level default.nix in Nixpkgs is actually a function: @@ -295,23 +295,23 @@ { # The system (e.g., `i686-linux') for which to build the packages. system ? builtins.currentSystem - ... -}: ... + ... +}: ... So if you call this Nix expression (e.g., when you do - nix-env -i pkgname), + nix-env -i pkgname), the function will be called automatically using the value builtins.currentSystem for the system argument. You can override this using , e.g., nix-env -i - pkgname --arg system + pkgname --arg system \"i686-freebsd\". (Note that since the argument is a Nix string literal, you have to escape the quotes.) - name value + name value This option is like , only the value is not a Nix expression but a string. So instead of @@ -323,17 +323,17 @@ / -attrPath +attrPath Select an attribute from the top-level Nix expression being evaluated. (nix-env, nix-instantiate, nix-build and nix-shell only.) The attribute - path attrPath is a sequence of + path attrPath is a sequence of attribute names separated by dots. For instance, given a top-level - Nix expression e, the attribute path + Nix expression e, the attribute path xorg.xorgserver would cause the expression - e.xorg.xorgserver to + e.xorg.xorgserver to be used. See nix-env --install for some concrete examples. @@ -366,7 +366,7 @@ - path + path Add a path to the Nix expression search path. This option may be given multiple times. See the - name value + name value Set the Nix configuration option - name to value. + name to value. This overrides settings in the Nix configuration file (see nix.conf5). diff --git a/doc/manual/command-ref/opt-inst-syn.xml b/doc/manual/command-ref/opt-inst-syn.xml index e8c3f1ec6..e324a5e6d 100644 --- a/doc/manual/command-ref/opt-inst-syn.xml +++ b/doc/manual/command-ref/opt-inst-syn.xml @@ -17,6 +17,6 @@ - path + path diff --git a/doc/manual/expressions/advanced-attributes.xml b/doc/manual/expressions/advanced-attributes.xml index 3a0413ceb..794d020d9 100644 --- a/doc/manual/expressions/advanced-attributes.xml +++ b/doc/manual/expressions/advanced-attributes.xml @@ -91,12 +91,12 @@ disallowedRequisites = [ foobar ]; references graph of their inputs. The attribute is a list of inputs in the Nix store whose references graph the builder needs to know. The value of this attribute should be a list of pairs - [ name1 - path1 name2 - path2 ... + [ name1 + path1 name2 + path2 ... ]. The references graph of each - pathN will be stored in a text file - nameN in the temporary build directory. + pathN will be stored in a text file + nameN in the temporary build directory. The text files have the format used by nix-store --register-validity (with the deriver fields left empty). For example, when the following derivation is built: @@ -135,7 +135,7 @@ derivation { Nixpkgs has the line -impureEnvVars = [ "http_proxy" "https_proxy" ... ]; +impureEnvVars = [ "http_proxy" "https_proxy" ... ]; to make it use the proxy server configuration specified by the @@ -297,11 +297,11 @@ big = "a very long string"; bigPath will contain the absolute path to a temporary file containing a very long string. That is, for any attribute - x listed in + x listed in passAsFile, Nix will pass an environment - variable xPath holding + variable xPath holding the path of the file containing the value of attribute - x. This is useful when you need to pass + x. This is useful when you need to pass large strings to a builder, since most operating systems impose a limit on the size of the environment (typically, a few hundred kilobyte). diff --git a/doc/manual/expressions/build-script.xml b/doc/manual/expressions/build-script.xml index 892274f50..c9af198f2 100644 --- a/doc/manual/expressions/build-script.xml +++ b/doc/manual/expressions/build-script.xml @@ -58,7 +58,7 @@ steps: the PATH. The perl environment variable points to the location of the Perl package (since it was passed in as an attribute to the derivation), so - $perl/bin is the + $perl/bin is the directory containing the Perl interpreter. diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index 877fd3a1b..4ad481ad3 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -22,34 +22,34 @@ available as builtins.derivation. - abort s - builtins.abort s + abort s + builtins.abort s Abort Nix expression evaluation, print error - message s. + message s. builtins.add - e1 e2 + e1 e2 Return the sum of the numbers - e1 and - e2. + e1 and + e2. builtins.all - pred list + pred list Return true if the function - pred returns true - for all elements of list, + pred returns true + for all elements of list, and false otherwise. @@ -57,11 +57,11 @@ available as builtins.derivation. builtins.any - pred list + pred list Return true if the function - pred returns true - for at least one element of list, + pred returns true + for at least one element of list, and false otherwise. @@ -69,10 +69,10 @@ available as builtins.derivation. builtins.attrNames - set + set Return the names of the attributes in the set - set in an alphabetically sorted list. For instance, + set in an alphabetically sorted list. For instance, builtins.attrNames { y = 1; x = "foo"; } evaluates to [ "x" "y" ]. @@ -81,20 +81,20 @@ available as builtins.derivation. builtins.attrValues - set + set Return the values of the attributes in the set - set in the order corresponding to the + set in the order corresponding to the sorted attribute names. - baseNameOf s + baseNameOf s Return the base name of the - string s, that is, everything following + string s, that is, everything following the final slash in the string. This is similar to the GNU basename command. @@ -103,33 +103,33 @@ available as builtins.derivation. builtins.bitAnd - e1 e2 + e1 e2 Return the bitwise AND of the integers - e1 and - e2. + e1 and + e2. builtins.bitOr - e1 e2 + e1 e2 Return the bitwise OR of the integers - e1 and - e2. + e1 and + e2. builtins.bitXor - e1 e2 + e1 e2 Return the bitwise XOR of the integers - e1 and - e2. + e1 and + e2. @@ -154,15 +154,15 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" builtins.compareVersions - s1 s2 + s1 s2 Compare two strings representing versions and return -1 if version - s1 is older than version - s2, 0 if they are + s1 is older than version + s2, 0 if they are the same, and 1 if - s1 is newer than - s2. The version comparison algorithm + s1 is newer than + s2. The version comparison algorithm is the same as the one used by nix-env -u. @@ -172,7 +172,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" builtins.concatLists - lists + lists Concatenate a list of lists into a single list. @@ -181,7 +181,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" builtins.concatStringsSep - separator list + separator list Concatenate a list of strings with a separator between each element, e.g. concatStringsSep "/" @@ -225,12 +225,12 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" builtins.deepSeq - e1 e2 + e1 e2 This is like seq - e1 - e2, except that - e1 is evaluated + e1 + e2, except that + e1 is evaluated deeply: if it’s a list or set, its elements or attributes are also evaluated recursively. @@ -239,9 +239,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" derivation - attrs + attrs builtins.derivation - attrs + attrs derivation is described in . @@ -250,11 +250,11 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - dirOf s - builtins.dirOf s + dirOf s + builtins.dirOf s Return the directory part of the string - s, that is, everything before the final + s, that is, everything before the final slash in the string. This is similar to the GNU dirname command. @@ -263,21 +263,21 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" builtins.div - e1 e2 + e1 e2 Return the quotient of the numbers - e1 and - e2. + e1 and + e2. builtins.elem - x xs + x xs Return true if a value equal to - x occurs in the list - xs, and false + x occurs in the list + xs, and false otherwise. @@ -285,10 +285,10 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" builtins.elemAt - xs n + xs n - Return element n from - the list xs. Elements are counted + Return element n from + the list xs. Elements are counted starting from 0. A fatal error occurs if the index is out of bounds. @@ -297,7 +297,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" builtins.fetchurl - url + url Download the specified URL and return the path of the downloaded file. This function is not available if fetchTarball - url + url builtins.fetchTarball - url + url Download the specified URL, unpack it and return the path of the unpacked tree. The file must be a tape archive @@ -333,9 +333,9 @@ stdenv.mkDerivation { … } The fetched tarball is cached for a certain amount of time (1 hour by default) in ~/.cache/nix/tarballs/. You can change the cache timeout either on the command line with - or + or in the Nix configuration file with this option: - number of seconds to cache. + number of seconds to cache. Note that when obtaining the hash with nix-prefetch-url @@ -367,12 +367,12 @@ stdenv.mkDerivation { … } builtins.fetchGit - args + args - Fetch a path from git. args can be + Fetch a path from git. args can be a URL, in which case the HEAD of the repo at that URL is fetched. Otherwise, it can be an attribute with the following attributes (all except url optional): @@ -526,11 +526,11 @@ stdenv.mkDerivation { … } builtins.filter - f xs + f xs Return a list consisting of the elements of - xs for which the function - f returns + xs for which the function + f returns true. @@ -538,7 +538,7 @@ stdenv.mkDerivation { … } builtins.filterSource - e1 e2 + e1 e2 @@ -569,10 +569,10 @@ stdenv.mkDerivation { - Thus, the first argument e1 + Thus, the first argument e1 must be a predicate function that is called for each regular file, directory or symlink in the source tree - e2. If the function returns + e2. If the function returns true, the file is copied to the Nix store, otherwise it is omitted. The function is called with two arguments. The first is the full path of the file. The second @@ -584,7 +584,7 @@ stdenv.mkDerivation { the Nix store, so if the predicate returns true for them, the copy will fail). If you exclude a directory, the entire corresponding subtree of - e2 will be excluded. + e2 will be excluded. @@ -593,7 +593,7 @@ stdenv.mkDerivation { builtins.foldl’ - op nul list + op nul list Reduce a list by applying a binary operator, from left to right, e.g. foldl’ op nul [x0 x1 x2 ...] = op (op @@ -607,11 +607,11 @@ stdenv.mkDerivation { builtins.functionArgs - f + f Return a set containing the names of the formal arguments expected - by the function f. + by the function f. The value of each attribute is a Boolean denoting whether the corresponding argument has a default value. For instance, functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }. @@ -625,7 +625,7 @@ stdenv.mkDerivation { - builtins.fromJSON e + builtins.fromJSON e Convert a JSON string to a Nix value. For example, @@ -642,12 +642,12 @@ builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' builtins.genList - generator length + generator length Generate list of size - length, with each element - i equal to the value returned by - generator i. For + length, with each element + i equal to the value returned by + generator i. For example, @@ -661,13 +661,13 @@ builtins.genList (x: x * x) 5 builtins.getAttr - s set + s set getAttr returns the attribute - named s from - set. Evaluation aborts if the + named s from + set. Evaluation aborts if the attribute doesn’t exist. This is a dynamic version of the - . operator, since s + . operator, since s is an expression rather than an identifier. @@ -675,10 +675,10 @@ builtins.genList (x: x * x) 5 builtins.getEnv - s + s getEnv returns the value of - the environment variable s, or an empty + the environment variable s, or an empty string if the variable doesn’t exist. This function should be used with care, as it can introduce all sorts of nasty environment dependencies in your Nix expression. @@ -694,14 +694,14 @@ builtins.genList (x: x * x) 5 builtins.hasAttr - s set + s set hasAttr returns - true if set has an - attribute named s, and + true if set has an + attribute named s, and false otherwise. This is a dynamic version of the ? operator, since - s is an expression rather than an + s is an expression rather than an identifier. @@ -709,11 +709,11 @@ builtins.genList (x: x * x) 5 builtins.hashString - type s + type s Return a base-16 representation of the - cryptographic hash of string s. The - hash algorithm specified by type must + cryptographic hash of string s. The + hash algorithm specified by type must be one of "md5", "sha1", "sha256" or "sha512". @@ -722,11 +722,11 @@ builtins.genList (x: x * x) 5 builtins.hashFile - type p + type p Return a base-16 representation of the - cryptographic hash of the file at path p. The - hash algorithm specified by type must + cryptographic hash of the file at path p. The + hash algorithm specified by type must be one of "md5", "sha1", "sha256" or "sha512". @@ -735,7 +735,7 @@ builtins.genList (x: x * x) 5 builtins.head - list + list Return the first element of a list; abort evaluation if the argument isn’t a list or is an empty list. You @@ -747,13 +747,13 @@ builtins.genList (x: x * x) 5 import - path + path builtins.import - path + path Load, parse and return the Nix expression in the - file path. If path - is a directory, the file default.nix + file path. If path + is a directory, the file default.nix in that directory is loaded. Evaluation aborts if the file doesn’t exist or contains an incorrect Nix expression. import implements Nix’s module system: you @@ -763,7 +763,7 @@ builtins.genList (x: x * x) 5 Unlike some languages, import is a regular function in Nix. Paths using the angle bracket syntax (e.g., - import <foo>) are normal path + import <foo>) are normal path values (see ). A Nix expression loaded by import must @@ -810,21 +810,21 @@ x: x + 456 builtins.intersectAttrs - e1 e2 + e1 e2 Return a set consisting of the attributes in the - set e2 that also exist in the set - e1. + set e2 that also exist in the set + e1. builtins.isAttrs - e + e Return true if - e evaluates to a set, and + e evaluates to a set, and false otherwise. @@ -832,20 +832,20 @@ x: x + 456 builtins.isList - e + e Return true if - e evaluates to a list, and + e evaluates to a list, and false otherwise. builtins.isFunction - e + e Return true if - e evaluates to a function, and + e evaluates to a function, and false otherwise. @@ -853,10 +853,10 @@ x: x + 456 builtins.isString - e + e Return true if - e evaluates to a string, and + e evaluates to a string, and false otherwise. @@ -864,10 +864,10 @@ x: x + 456 builtins.isInt - e + e Return true if - e evaluates to an int, and + e evaluates to an int, and false otherwise. @@ -875,10 +875,10 @@ x: x + 456 builtins.isFloat - e + e Return true if - e evaluates to a float, and + e evaluates to a float, and false otherwise. @@ -886,31 +886,31 @@ x: x + 456 builtins.isBool - e + e Return true if - e evaluates to a bool, and + e evaluates to a bool, and false otherwise. builtins.isPath - e + e Return true if - e evaluates to a path, and + e evaluates to a path, and false otherwise. isNull - e + e builtins.isNull - e + e Return true if - e evaluates to null, + e evaluates to null, and false otherwise. This function is deprecated; @@ -923,23 +923,23 @@ x: x + 456 builtins.length - e + e Return the length of the list - e. + e. builtins.lessThan - e1 e2 + e1 e2 Return true if the number - e1 is less than the number - e2, and false + e1 is less than the number + e2, and false otherwise. Evaluation aborts if either - e1 or e2 + e1 or e2 does not evaluate to a number. @@ -947,7 +947,7 @@ x: x + 456 builtins.listToAttrs - e + e Construct a set from a list specifying the names and values of each attribute. Each element of the list should be @@ -975,12 +975,12 @@ builtins.listToAttrs map - f list + f list builtins.map - f list + f list - Apply the function f to - each element in the list list. For + Apply the function f to + each element in the list list. For example, @@ -994,12 +994,12 @@ map (x: "foo" + x) [ "bar" "bla" "abc" ] builtins.match - regex str + regex str Returns a list if the extended - POSIX regular expression regex - matches str precisely, otherwise returns + POSIX regular expression regex + matches str precisely, otherwise returns null. Each item in the list is a regex group. @@ -1031,20 +1031,20 @@ Evaluates to [ "foo" ]. builtins.mul - e1 e2 + e1 e2 Return the product of the numbers - e1 and - e2. + e1 and + e2. builtins.parseDrvName - s + s - Split the string s into + Split the string s into a package name and version. The package name is everything up to but not including the first dash followed by a digit, and the version is everything following that dash. The result is returned @@ -1058,13 +1058,13 @@ Evaluates to [ "foo" ]. builtins.path - args + args An enrichment of the built-in path type, based on the attributes - present in args. All are optional + present in args. All are optional except path: @@ -1127,20 +1127,20 @@ Evaluates to [ "foo" ]. builtins.pathExists - path + path Return true if the path - path exists at evaluation time, and + path exists at evaluation time, and false otherwise. builtins.placeholder - output + output Return a placeholder string for the specified - output that will be substituted by the + output that will be substituted by the corresponding output path at build time. Typical outputs would be "out", "bin" or "dev". @@ -1148,10 +1148,10 @@ Evaluates to [ "foo" ]. builtins.readDir - path + path Return the contents of the directory - path as a set mapping directory entries + path as a set mapping directory entries to the corresponding file type. For instance, if directory A contains a regular file B and another directory @@ -1171,24 +1171,24 @@ Evaluates to [ "foo" ]. builtins.readFile - path + path Return the contents of the file - path as a string. + path as a string. removeAttrs - set list + set list builtins.removeAttrs - set list + set list Remove the attributes listed in - list from - set. The attributes don’t have to - exist in set. For instance, + list from + set. The attributes don’t have to + exist in set. For instance, removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ] @@ -1200,12 +1200,12 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ] builtins.replaceStrings - from to s + from to s - Given string s, replace - every occurrence of the strings in from + Given string s, replace + every occurrence of the strings in from with the corresponding string in - to. For example, + to. For example, builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" @@ -1218,23 +1218,23 @@ builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" builtins.seq - e1 e2 + e1 e2 - Evaluate e1, then - evaluate and return e2. This ensures + Evaluate e1, then + evaluate and return e2. This ensures that a computation is strict in the value of - e1. + e1. builtins.sort - comparator list + comparator list - Return list in sorted + Return list in sorted order. It repeatedly calls the function - comparator with two elements. The + comparator with two elements. The comparator should return true if the first element is less than the second, and false otherwise. For example, @@ -1254,13 +1254,13 @@ builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] builtins.split - regex str + regex str Returns a list composed of non matched strings interleaved with the lists of the extended - POSIX regular expression regex matches - of str. Each item in the lists of matched + POSIX regular expression regex matches + of str. Each item in the lists of matched sequences is a regex group. @@ -1293,7 +1293,7 @@ Evaluates to [ " " [ "FOO" ] " " ]. builtins.splitVersion - s + s Split a string representing a version into its components, by the same version splitting logic underlying the @@ -1305,10 +1305,10 @@ Evaluates to [ " " [ "FOO" ] " " ]. builtins.stringLength - e + e Return the length of the string - e. If e is + e. If e is not a string, evaluation is aborted. @@ -1316,29 +1316,29 @@ Evaluates to [ " " [ "FOO" ] " " ]. builtins.sub - e1 e2 + e1 e2 Return the difference between the numbers - e1 and - e2. + e1 and + e2. builtins.substring - start len - s + start len + s Return the substring of - s from character position - start (zero-based) up to but not - including start + len. If - start is greater than the length of the - string, an empty string is returned, and if start + - len lies beyond the end of the string, only the + s from character position + start (zero-based) up to but not + including start + len. If + start is greater than the length of the + string, an empty string is returned, and if start + + len lies beyond the end of the string, only the substring up to the end of the string is returned. - start must be + start must be non-negative. For example, @@ -1353,7 +1353,7 @@ builtins.substring 0 3 "nixos" builtins.tail - list + list Return the second to last elements of a list; abort evaluation if the argument isn’t a list or is an empty @@ -1364,12 +1364,12 @@ builtins.substring 0 3 "nixos" throw - s + s builtins.throw - s + s Throw an error message - s. This usually aborts Nix expression + s. This usually aborts Nix expression evaluation, but in nix-env -qa and other commands that try to evaluate a set of derivations to get information about those derivations, a derivation that throws an @@ -1381,12 +1381,12 @@ builtins.substring 0 3 "nixos" builtins.toFile - name - s + name + s - Store the string s in a + Store the string s in a file in the Nix store and return its path. The file has suffix - name. This file can be used as an + name. This file can be used as an input to derivations. One application is to write builders “inline”. For instance, the following Nix expression combines and ... + ... "; in builtins.toFile "builder.sh" " source $stdenv/setup - ... + ... cp ${configFile} $out/etc/foo.conf "; @@ -1459,10 +1459,10 @@ in foo - builtins.toJSON e + builtins.toJSON e Return a string containing a JSON representation - of e. Strings, integers, floats, booleans, + of e. Strings, integers, floats, booleans, nulls and lists are mapped to their JSON equivalents. Sets (except derivations) are represented as objects. Derivations are translated to a JSON string containing the derivation’s output @@ -1473,7 +1473,7 @@ in foo - builtins.toPath s + builtins.toPath s DEPRECATED. Use /. + "/path" to convert a string into an absolute path. For relative paths, @@ -1484,12 +1484,12 @@ in foo - toString e - builtins.toString e + toString e + builtins.toString e Convert the expression - e to a string. - e can be: + e to a string. + e can be: A string (in which case the string is returned unmodified). A path (e.g., toString /foo/bar yields "/foo/bar". @@ -1505,10 +1505,10 @@ in foo - builtins.toXML e + builtins.toXML e Return a string containing an XML representation - of e. The main application for + of e. The main application for toXML is to communicate information with the builder in a more structured format than plain environment variables. @@ -1612,26 +1612,26 @@ stdenv.mkDerivation (rec { builtins.trace - e1 e2 + e1 e2 - Evaluate e1 and print its + Evaluate e1 and print its abstract syntax representation on standard error. Then return - e2. This function is useful for + e2. This function is useful for debugging. builtins.tryEval - e + e - Try to shallowly evaluate e. + Try to shallowly evaluate e. Return a set containing the attributes success - (true if e evaluated + (true if e evaluated successfully, false if an error was thrown) and - value, equalling e + value, equalling e if successful and false otherwise. Note that this - doesn't evaluate e deeply, so + doesn't evaluate e deeply, so let e = { x = throw ""; }; in (builtins.tryEval e).success will be true. Using builtins.deepSeq one can get the expected result: let e = { x = throw ""; @@ -1644,10 +1644,10 @@ stdenv.mkDerivation (rec { builtins.typeOf - e + e Return a string representing the type of the value - e, namely "int", + e, namely "int", "bool", "string", "path", "null", "set", "list", diff --git a/doc/manual/expressions/expression-syntax.xml b/doc/manual/expressions/expression-syntax.xml index 562a9e9f4..853e40b58 100644 --- a/doc/manual/expressions/expression-syntax.xml +++ b/doc/manual/expressions/expression-syntax.xml @@ -50,7 +50,7 @@ the single Nix expression in that directory Nix functions generally have the form { x, y, ..., z }: e where x, y, etc. are the names of the expected arguments, and where - e is the body of the function. So + e is the body of the function. So here, the entire remainder of the file is the body of the function; when given the required arguments, the body should describe how to build an instance of the Hello package. @@ -69,10 +69,10 @@ the single Nix expression in that directory attributes. A set is just a list of key/value pairs where each key is a string and each value is an arbitrary Nix expression. They take the general form { - name1 = - expr1; ... - nameN = - exprN; }. + name1 = + expr1; ... + nameN = + exprN; }. diff --git a/doc/manual/expressions/generic-builder.xml b/doc/manual/expressions/generic-builder.xml index 71b342f99..f6e67813d 100644 --- a/doc/manual/expressions/generic-builder.xml +++ b/doc/manual/expressions/generic-builder.xml @@ -44,7 +44,7 @@ genericBuild ③ subdirectory, it's added to GCC's header search path; and so on.How does it work? setup tries to source the file - pkg/nix-support/setup-hook + pkg/nix-support/setup-hook of all dependencies. These “setup hooks” can then set up whatever environment variables they want; for instance, the setup hook for Perl sets the PERL5LIB environment variable to diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml index 82d3afed1..86c25d723 100644 --- a/doc/manual/expressions/language-constructs.xml +++ b/doc/manual/expressions/language-constructs.xml @@ -137,7 +137,7 @@ while defining a set. Functions have the following form: -pattern: body +pattern: body The pattern specifies what the argument of the function must look like, and binds variables in the body to (parts of) the @@ -190,9 +190,9 @@ map (concat "foo") [ "bar" "bla" "abc" ] It is possible to provide default values for attributes, in which case they are allowed to be missing. A default value is specified by writing - name ? - e, where - e is an arbitrary expression. For example, + name ? + e, where + e is an arbitrary expression. For example, { x, y ? "foo", z ? "bar" }: z + y + x @@ -256,9 +256,9 @@ in concat { x = "foo"; y = "bar"; } Conditionals look like this: -if e1 then e2 else e3 +if e1 then e2 else e3 -where e1 is an expression that should +where e1 is an expression that should evaluate to a Boolean value (true or false). @@ -271,11 +271,11 @@ evaluate to a Boolean value (true or on or between features and dependencies hold. They look like this: -assert e1; e2 +assert e1; e2 -where e1 is an expression that should +where e1 is an expression that should evaluate to a Boolean value. If it evaluates to -true, e2 is returned; +true, e2 is returned; otherwise expression evaluation is aborted and a backtrace is printed. Here is a Nix expression for the Subversion package that shows @@ -358,10 +358,10 @@ stdenv.mkDerivation { A with-expression, -with e1; e2 +with e1; e2 -introduces the set e1 into the lexical -scope of the expression e2. For instance, +introduces the set e1 into the lexical +scope of the expression e2. For instance, let as = { x = "foo"; y = "bar"; }; diff --git a/doc/manual/expressions/language-operators.xml b/doc/manual/expressions/language-operators.xml index 4f11bf529..7f69bfcef 100644 --- a/doc/manual/expressions/language-operators.xml +++ b/doc/manual/expressions/language-operators.xml @@ -25,48 +25,48 @@ weakest binding). Select - e . - attrpath - [ or def ] + e . + attrpath + [ or def ] none Select attribute denoted by the attribute path - attrpath from set - e. (An attribute path is a + attrpath from set + e. (An attribute path is a dot-separated list of attribute names.) If the attribute - doesn’t exist, return def if + doesn’t exist, return def if provided, otherwise abort evaluation. 1 Application - e1 e2 + e1 e2 left - Call function e1 with - argument e2. + Call function e1 with + argument e2. 2 Arithmetic Negation - - e + - e none Arithmetic negation. 3 Has Attribute - e ? - attrpath + e ? + attrpath none - Test whether set e contains - the attribute denoted by attrpath; + Test whether set e contains + the attribute denoted by attrpath; return true or false. 4 List Concatenation - e1 ++ e2 + e1 ++ e2 right List concatenation. 5 @@ -74,7 +74,7 @@ weakest binding). Multiplication - e1 * e2, + e1 * e2, left Arithmetic multiplication. @@ -83,7 +83,7 @@ weakest binding). Division - e1 / e2 + e1 / e2 left Arithmetic division. @@ -92,7 +92,7 @@ weakest binding). Addition - e1 + e2 + e1 + e2 left Arithmetic addition. @@ -101,7 +101,7 @@ weakest binding). Subtraction - e1 - e2 + e1 - e2 left Arithmetic subtraction. @@ -110,7 +110,7 @@ weakest binding). String Concatenation - string1 + string2 + string1 + string2 left String concatenation. @@ -118,19 +118,19 @@ weakest binding). Not - ! e + ! e none Boolean negation. 8 Update - e1 // - e2 + e1 // + e2 right Return a set consisting of the attributes in - e1 and - e2 (with the latter taking + e1 and + e2 (with the latter taking precedence over the former in case of equally named attributes). 9 @@ -138,7 +138,7 @@ weakest binding). Less Than - e1 < e2, + e1 < e2, none Arithmetic comparison. @@ -147,7 +147,7 @@ weakest binding). Less Than or Equal To - e1 <= e2 + e1 <= e2 none Arithmetic comparison. @@ -156,7 +156,7 @@ weakest binding). Greater Than - e1 > e2 + e1 > e2 none Arithmetic comparison. @@ -165,7 +165,7 @@ weakest binding). Greater Than or Equal To - e1 >= e2 + e1 >= e2 none Arithmetic comparison. @@ -174,7 +174,7 @@ weakest binding). Equality - e1 == e2 + e1 == e2 none Equality. @@ -183,7 +183,7 @@ weakest binding). Inequality - e1 != e2 + e1 != e2 none Inequality. @@ -191,28 +191,28 @@ weakest binding). Logical AND - e1 && - e2 + e1 && + e2 left Logical AND. 12 Logical OR - e1 || - e2 + e1 || + e2 left Logical OR. 13 Logical Implication - e1 -> - e2 + e1 -> + e2 none Logical implication (equivalent to - !e1 || - e2). + !e1 || + e2). 14 diff --git a/doc/manual/expressions/language-values.xml b/doc/manual/expressions/language-values.xml index 6c0fcbacb..cebafb1f5 100644 --- a/doc/manual/expressions/language-values.xml +++ b/doc/manual/expressions/language-values.xml @@ -30,7 +30,7 @@ You can include the result of an expression into a string by enclosing it in - ${...}, a feature + ${...}, a feature known as antiquotation. The enclosed expression must evaluate to something that can be coerced into a string (meaning that it must be a string, a path, or a @@ -93,7 +93,7 @@ configureFlags = " text on the initial line. Antiquotation - (${expr}) is + (${expr}) is supported in indented strings. Since ${ and '' have @@ -119,7 +119,7 @@ configureFlags = " stdenv.mkDerivation { - ... + ... postInstall = '' mkdir $out/bin $out/etc @@ -127,7 +127,7 @@ stdenv.mkDerivation { echo "Hello World" > $out/etc/foo.conf ${if enableBar then "cp bar $out/bin" else ""} ''; - ... + ... } diff --git a/doc/manual/expressions/simple-building-testing.xml b/doc/manual/expressions/simple-building-testing.xml index 33a802e83..f82223df9 100644 --- a/doc/manual/expressions/simple-building-testing.xml +++ b/doc/manual/expressions/simple-building-testing.xml @@ -19,7 +19,7 @@ building path `/nix/store/632d2b22514d...-hello-2.1.1' hello-2.1.1/ hello-2.1.1/intl/ hello-2.1.1/intl/ChangeLog -... +... $ ls -l result lrwxrwxrwx ... 2006-09-29 10:43 result -> /nix/store/632d2b22514d...-hello-2.1.1 diff --git a/doc/manual/installation/building-source.xml b/doc/manual/installation/building-source.xml index 772cda9cc..469aaebe9 100644 --- a/doc/manual/installation/building-source.xml +++ b/doc/manual/installation/building-source.xml @@ -10,7 +10,7 @@ following commands: -$ ./configure options... +$ ./configure options... $ make $ make install @@ -26,16 +26,16 @@ $ ./bootstrap.sh The installation path can be specified by passing the - to + to configure. The default installation directory is /usr/local. You can change this to any location you like. You must have write permission to the -prefix path. +prefix path. Nix keeps its store (the place where packages are stored) in /nix/store by default. This can be changed using -. +. It is best not to change the Nix store from its default, since doing so makes it impossible to use @@ -44,6 +44,6 @@ packages will need to be built from source. Nix keeps state (such as its database and log files) in /nix/var by default. This can be changed using -. +. diff --git a/doc/manual/installation/env-variables.xml b/doc/manual/installation/env-variables.xml index 436f15f31..cbce8559a 100644 --- a/doc/manual/installation/env-variables.xml +++ b/doc/manual/installation/env-variables.xml @@ -8,18 +8,18 @@ To use Nix, some environment variables should be set. In particular, PATH should contain the directories -prefix/bin and +prefix/bin and ~/.nix-profile/bin. The first directory contains the Nix tools themselves, while ~/.nix-profile is a symbolic link to the current user environment (an automatically generated package consisting of symlinks to installed packages). The simplest way to set the required environment variables is to include the file -prefix/etc/profile.d/nix.sh +prefix/etc/profile.d/nix.sh in your ~/.profile (or similar), like this: -source prefix/etc/profile.d/nix.sh +source prefix/etc/profile.d/nix.sh
diff --git a/doc/manual/installation/installing-binary.xml b/doc/manual/installation/installing-binary.xml index ad47ce8b9..439198e6c 100644 --- a/doc/manual/installation/installing-binary.xml +++ b/doc/manual/installation/installing-binary.xml @@ -421,7 +421,7 @@ LABEL=Nix\040Store /nix apfs rw,nobrowse NixOS.org hosts version-specific installation URLs for all Nix versions since 1.11.16, at - https://releases.nixos.org/nix/nix-version/install. + https://releases.nixos.org/nix/nix-version/install. diff --git a/doc/manual/installation/single-user.xml b/doc/manual/installation/single-user.xml index 09cdaa5d4..e9a761af3 100644 --- a/doc/manual/installation/single-user.xml +++ b/doc/manual/installation/single-user.xml @@ -7,9 +7,9 @@ Single-User Mode In single-user mode, all Nix operations that access the database -in prefix/var/nix/db +in prefix/var/nix/db or modify the Nix store in -prefix/store must be +prefix/store must be performed under the user ID that owns those directories. This is typically root. (If you install from RPM packages, that’s in fact the default ownership.) diff --git a/doc/manual/introduction/about-nix.xml b/doc/manual/introduction/about-nix.xml index dd09e2283..039185703 100644 --- a/doc/manual/introduction/about-nix.xml +++ b/doc/manual/introduction/about-nix.xml @@ -99,7 +99,7 @@ there after an upgrade. This means that you can roll back to the old version: -$ nix-env --upgrade some-packages +$ nix-env --upgrade some-packages $ nix-env --rollback diff --git a/doc/manual/introduction/quick-start.xml b/doc/manual/introduction/quick-start.xml index 1992c14ed..5d9a55e4e 100644 --- a/doc/manual/introduction/quick-start.xml +++ b/doc/manual/introduction/quick-start.xml @@ -33,7 +33,7 @@ docbook-xml-4.5 firefox-33.0.2 hello-2.9 libxslt-1.1.28 -... +... diff --git a/doc/manual/packages/basic-package-mgmt.xml b/doc/manual/packages/basic-package-mgmt.xml index 758a4500d..b8a2c7ab3 100644 --- a/doc/manual/packages/basic-package-mgmt.xml +++ b/doc/manual/packages/basic-package-mgmt.xml @@ -74,10 +74,10 @@ then you need to pass the path to your Nixpkgs tree using the flag: -$ nix-env -qaf /path/to/nixpkgs +$ nix-env -qaf /path/to/nixpkgs -where /path/to/nixpkgs is where you’ve +where /path/to/nixpkgs is where you’ve unpacked or checked out Nixpkgs. You can select specific packages by name: diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml index 1ed2bba52..494a81966 100644 --- a/doc/manual/packages/channels.xml +++ b/doc/manual/packages/channels.xml @@ -45,7 +45,7 @@ $ nix-channel --remove nixpkgs $ nix-channel --update This downloads and unpacks the Nix expressions in every channel -(downloaded from url/nixexprs.tar.bz2). +(downloaded from url/nixexprs.tar.bz2). It also makes the union of each channel’s Nix expressions available by default to nix-env operations (via the symlink ~/.nix-defexpr/channels). Consequently, you can diff --git a/doc/manual/packages/garbage-collector-roots.xml b/doc/manual/packages/garbage-collector-roots.xml index 8338e5392..9c91862b0 100644 --- a/doc/manual/packages/garbage-collector-roots.xml +++ b/doc/manual/packages/garbage-collector-roots.xml @@ -8,7 +8,7 @@ The roots of the garbage collector are all store paths to which there are symlinks in the directory -prefix/nix/var/nix/gcroots. +prefix/nix/var/nix/gcroots. For instance, the following command makes the path /nix/store/d718ef...-foo a root of the collector: @@ -20,7 +20,7 @@ That is, after this command, the garbage collector will not remove dependencies. Subdirectories of -prefix/nix/var/nix/gcroots +prefix/nix/var/nix/gcroots are also searched for symlinks. Symlinks to non-store paths are followed and searched for roots, but symlinks to non-store paths inside the paths reached in that way are not diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml index 2809def24..d7529d56c 100644 --- a/doc/manual/packages/profiles.xml +++ b/doc/manual/packages/profiles.xml @@ -118,7 +118,7 @@ can also see all available generations: $ nix-env --list-generations You generally wouldn’t have -/nix/var/nix/profiles/some-profile/bin +/nix/var/nix/profiles/some-profile/bin in your PATH. Rather, there is a symlink ~/.nix-profile that points to your current profile. This means that you should put diff --git a/doc/manual/release-notes/rl-0.10.xml b/doc/manual/release-notes/rl-0.10.xml index 9b4233546..01f70acfd 100644 --- a/doc/manual/release-notes/rl-0.10.xml +++ b/doc/manual/release-notes/rl-0.10.xml @@ -46,9 +46,9 @@ irreversible. \*. nix-env -i - pkgname will now install + pkgname will now install the highest available version of - pkgname, rather than installing all + pkgname, rather than installing all available versions (which would probably give collisions) (NIX-31). @@ -85,7 +85,7 @@ irreversible. "--with-freetype2-library=${freetype}/lib" You can write arbitrary expressions within - ${...}, not just + ${...}, not just identifiers. Multi-line string literals. @@ -163,7 +163,7 @@ irreversible. attribute set are unique.) For instance, a quick way to perform a test build of a package in Nixpkgs is nix-build pkgs/top-level/all-packages.nix -A - foo. nix-env -q + foo. nix-env -q --attr shows the attribute names corresponding to each derivation. @@ -173,13 +173,13 @@ irreversible. nix-build evaluates to a function whose arguments all have default values, the function will be called automatically. Also, the new command-line switch can be used to specify + name + value can be used to specify function arguments on the command line. nix-install-package --url - URL allows a package to be + URL allows a package to be installed directly from the given URL. @@ -192,7 +192,7 @@ irreversible. nix-build -o - symlink allows the symlink to + symlink allows the symlink to the build result to be named something other than result. diff --git a/doc/manual/release-notes/rl-0.12.xml b/doc/manual/release-notes/rl-0.12.xml index 18978ac4b..c30124786 100644 --- a/doc/manual/release-notes/rl-0.12.xml +++ b/doc/manual/release-notes/rl-0.12.xml @@ -59,17 +59,17 @@ $ rm __db* log.* derivers references referrers reserved validpaths DB_CONFIGThe garbage collector has a number of new options to allow only some of the garbage to be deleted. The option - tells the - collector to stop after at least N bytes + tells the + collector to stop after at least N bytes have been deleted. The option tells it to stop after the + N tells it to stop after the link count on /nix/store has dropped below - N. This is useful for very large Nix + N. This is useful for very large Nix stores on filesystems with a 32000 subdirectories limit (like ext3). The option causes store paths to be deleted in order of ascending last access time. This allows non-recently used stuff to be deleted. The - option + option specifies an upper limit to the last accessed time of paths that may be deleted. For instance, @@ -119,7 +119,7 @@ the following paths will be downloaded/copied (30.02 MiB): @-patterns as in Haskell. For instance, in a function definition - f = args @ {x, y, z}: ...; + f = args @ {x, y, z}: ...; args refers to the argument as a whole, which is further pattern-matched against the attribute set pattern @@ -131,7 +131,7 @@ the following paths will be downloaded/copied (30.02 MiB): takes at least the listed attributes, while ignoring additional attributes. For instance, - {stdenv, fetchurl, fuse, ...}: ... + {stdenv, fetchurl, fuse, ...}: ... defines a function that accepts any attribute set that includes at least the three listed attributes. @@ -163,7 +163,7 @@ the following paths will be downloaded/copied (30.02 MiB): nix-pack-closure and nix-unpack-closure. You can do almost the same thing but much more efficiently by doing nix-store --export - $(nix-store -qR paths) > closure and + $(nix-store -qR paths) > closure and nix-store --import < closure. diff --git a/doc/manual/release-notes/rl-0.13.xml b/doc/manual/release-notes/rl-0.13.xml index cce2e4a26..8cb0ae9a5 100644 --- a/doc/manual/release-notes/rl-0.13.xml +++ b/doc/manual/release-notes/rl-0.13.xml @@ -95,9 +95,9 @@ features: The scoping rules for inherit - (e) ... in recursive + (e) ... in recursive attribute sets have changed. The expression - e can now refer to the attributes + e can now refer to the attributes defined in the containing set. diff --git a/doc/manual/release-notes/rl-0.16.xml b/doc/manual/release-notes/rl-0.16.xml index 43b7622c6..7039d4b0b 100644 --- a/doc/manual/release-notes/rl-0.16.xml +++ b/doc/manual/release-notes/rl-0.16.xml @@ -27,14 +27,14 @@ 2), but this was not desirable because the number of actions to be performed in parallel was not configurable. Nix now has an option as well as a configuration + N as well as a configuration setting build-cores = - N that causes the + N that causes the environment variable NIX_BUILD_CORES to be set to - N when the builder is invoked. The + N when the builder is invoked. The builder can use this at its discretion to perform a parallel build, e.g., by calling make -j - N. In Nixpkgs, this can be + N. In Nixpkgs, this can be enabled on a per-package basis by setting the derivation attribute enableParallelBuilding to true. diff --git a/doc/manual/release-notes/rl-0.6.xml b/doc/manual/release-notes/rl-0.6.xml index 6dc6521d3..23fbee173 100644 --- a/doc/manual/release-notes/rl-0.6.xml +++ b/doc/manual/release-notes/rl-0.6.xml @@ -91,10 +91,10 @@ New language construct: with - E1; - E2 brings all attributes - defined in the attribute set E1 in - scope in E2. + E1; + E2 brings all attributes + defined in the attribute set E1 in + scope in E2. Added a map function. diff --git a/doc/manual/release-notes/rl-0.8.xml b/doc/manual/release-notes/rl-0.8.xml index 825798fa9..1adb91a23 100644 --- a/doc/manual/release-notes/rl-0.8.xml +++ b/doc/manual/release-notes/rl-0.8.xml @@ -33,7 +33,7 @@ is too old (i.e., for Nix <= 0.7) then you should unsubscribe from the offending channel (nix-channel --remove -URL; leave out +URL; leave out /MANIFEST), and subscribe to the same URL, with channels replaced by channels-v3 (e.g., nix-store -r - PATHS now builds all the + PATHS now builds all the derivations PATHS in parallel. Previously it did them sequentially (though exploiting possible parallelism between subderivations). This is nice for build farms. diff --git a/doc/manual/release-notes/rl-1.1.xml b/doc/manual/release-notes/rl-1.1.xml index 2f26e7a24..f7dadb7cb 100644 --- a/doc/manual/release-notes/rl-1.1.xml +++ b/doc/manual/release-notes/rl-1.1.xml @@ -72,8 +72,8 @@ to get rid of the bootstrap binaries in the Nixpkgs source tree and download them instead. You can use it by doing import <nix/fetchurl.nix> { url = - url; sha256 = - "hash"; }. (Shea Levy) + url; sha256 = + "hash"; }. (Shea Levy) diff --git a/doc/manual/release-notes/rl-1.11.xml b/doc/manual/release-notes/rl-1.11.xml index fe422dd1f..28f6d4ac8 100644 --- a/doc/manual/release-notes/rl-1.11.xml +++ b/doc/manual/release-notes/rl-1.11.xml @@ -62,8 +62,8 @@ $ nix-prefetch-url -A nix-repl.src The new flag will cause every build to - be executed N+1 times. If the build + N will cause every build to + be executed N+1 times. If the build output differs between any round, the build is rejected, and the output paths are not registered as valid. This is primarily useful to verify build determinism. (We already had a @@ -78,11 +78,11 @@ $ nix-prefetch-url -A nix-repl.src The options and , if they + build-repeat N, if they detect a difference between two runs of the same derivation and is given, will make the output of the other run available under - store-path-check. This + store-path-check. This makes it easier to investigate the non-determinism using tools like diffoscope, e.g., diff --git a/doc/manual/release-notes/rl-1.2.xml b/doc/manual/release-notes/rl-1.2.xml index 29bd5bf81..f065f3ccc 100644 --- a/doc/manual/release-notes/rl-1.2.xml +++ b/doc/manual/release-notes/rl-1.2.xml @@ -56,7 +56,7 @@ outputs = [ "lib" "headers" "doc" ]; lib, headers and doc. Other packages can refer to a specific output by referring to - pkg.output, + pkg.output, e.g. buildInputs = [ pkg.lib pkg.headers ]; diff --git a/doc/manual/release-notes/rl-1.4.xml b/doc/manual/release-notes/rl-1.4.xml index aefb22f2b..8114ce6b5 100644 --- a/doc/manual/release-notes/rl-1.4.xml +++ b/doc/manual/release-notes/rl-1.4.xml @@ -20,8 +20,8 @@ xlink:href="https://github.com/NixOS/nix/commit/5526a282b5b44e9296e61e07d7d2626a builtins.hashString. Build logs are now stored in - /nix/var/log/nix/drvs/XX/, - where XX is the first two characters of + /nix/var/log/nix/drvs/XX/, + where XX is the first two characters of the derivation. This is useful on machines that keep a lot of build logs (such as Hydra servers). diff --git a/doc/manual/release-notes/rl-1.6.1.xml b/doc/manual/release-notes/rl-1.6.1.xml index 9ecc52734..982871b51 100644 --- a/doc/manual/release-notes/rl-1.6.1.xml +++ b/doc/manual/release-notes/rl-1.6.1.xml @@ -19,15 +19,15 @@ are: Previously, Nix optimised expressions such as - "${expr}" to - expr. Thus it neither checked whether - expr could be coerced to a string, nor + "${expr}" to + expr. Thus it neither checked whether + expr could be coerced to a string, nor applied such coercions. This meant that "${123}" evaluatued to 123, and "${./foo}" evaluated to ./foo (even though "${./foo} " evaluates to - "/nix/store/hash-foo "). + "/nix/store/hash-foo "). Nix now checks the type of antiquoted expressions and applies coercions. diff --git a/doc/manual/release-notes/rl-1.7.xml b/doc/manual/release-notes/rl-1.7.xml index 44ecaa78d..e736c15a2 100644 --- a/doc/manual/release-notes/rl-1.7.xml +++ b/doc/manual/release-notes/rl-1.7.xml @@ -34,7 +34,7 @@ following new features: download-via-ssh, that fetches binaries from remote machines via SSH. Specifying the flags --option use-ssh-substituter true --option ssh-substituter-hosts - user@hostname will cause Nix + user@hostname will cause Nix to download binaries from the specified machine, if it has them. @@ -49,9 +49,9 @@ following new features: $ nix-build '<nixpkgs>' -A patchelf -… +… $ nix-build '<nixpkgs>' -A patchelf --check -… +… error: derivation `/nix/store/1ipvxs…-patchelf-0.6' may not be deterministic: hash mismatch in output `/nix/store/4pc1dm…-patchelf-0.6.drv' @@ -173,11 +173,11 @@ $ nix-instantiate --eval '<nixos>' -A 'config.systemd.units."nscd.service".te nix-collect-garbage has a new flag - Nd, which deletes + Nd, which deletes all user environment generations older than - N days. Likewise, nix-env + N days. Likewise, nix-env --delete-generations accepts a - Nd age limit. + Nd age limit. diff --git a/doc/manual/release-notes/rl-1.8.xml b/doc/manual/release-notes/rl-1.8.xml index 326990774..d7e2e99ad 100644 --- a/doc/manual/release-notes/rl-1.8.xml +++ b/doc/manual/release-notes/rl-1.8.xml @@ -38,8 +38,8 @@ log-servers = http://hydra.nixos.org/log then it will try to get logs from -http://hydra.nixos.org/log/base name of the -store path. This allows you to do things like: +http://hydra.nixos.org/log/base name of the +store path. This allows you to do things like: $ nix-store -l $(which xterm) diff --git a/doc/manual/release-notes/rl-2.0.xml b/doc/manual/release-notes/rl-2.0.xml index 57acfd0ba..6bef003ca 100644 --- a/doc/manual/release-notes/rl-2.0.xml +++ b/doc/manual/release-notes/rl-2.0.xml @@ -42,7 +42,7 @@ The command nix-push has been removed as part of the effort to eliminate Nix's dependency on Perl. You can use nix copy instead, e.g. nix copy - --to file:///tmp/my-binary-cache paths… + --to file:///tmp/my-binary-cache paths… @@ -136,8 +136,8 @@ http-connections 100 you can write --http-connections 100. Boolean options can be written as - --foo or - --no-foo + --foo or + --no-foo (e.g. ). @@ -551,7 +551,7 @@ is still supported for compatibility, but it is also possible to specify builders in nix.conf by setting the option builders = - @path. + @path. @@ -580,9 +580,9 @@ You can now use - channel:channel-name as a + channel:channel-name as a short-hand for - https://nixos.org/channels/channel-name/nixexprs.tar.xz. For + https://nixos.org/channels/channel-name/nixexprs.tar.xz. For example, nix-build channel:nixos-15.09 -A hello will build the GNU Hello package from the nixos-15.09 channel. In the future, this may diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md index 3f84373e2..92abeb73e 100644 --- a/doc/manual/src/command-ref/conf-file.md +++ b/doc/manual/src/command-ref/conf-file.md @@ -28,8 +28,8 @@ By default Nix reads settings from the following places: The configuration files consist of `name = value` pairs, one per line. Other files can be included with a line like `include -path`, where path is interpreted relative to the current conf file and a -missing file is an error unless `!include` is used instead. Comments +path`, where *path* is interpreted relative to the current conf file and +a missing file is an error unless `!include` is used instead. Comments start with a `#` character. Here is an example configuration file: keep-outputs = true # Nice for developers @@ -216,7 +216,7 @@ The following settings are currently available: - `hashed-mirrors` A list of web servers used by `builtins.fetchurl` to obtain files by hash. The default is `http://tarballs.nixos.org/`. Given a hash type - ht and a base-16 hash h, Nix will try to download the file from + *ht* and a base-16 hash *h*, Nix will try to download the file from `hashed-mirror/ht/h`. This allows files to be downloaded even if they have disappeared from their original URI. For example, given the default mirror `http://tarballs.nixos.org/`, when building the @@ -504,8 +504,8 @@ The following settings are currently available: A list of paths bind-mounted into Nix sandbox environments. You can use the syntax `target=source` to mount a path in a different location in the sandbox; for instance, `/bin=/nix-bin` will mount - the path `/nix-bin` as `/bin` inside the sandbox. If source is - followed by `?`, then it is not an error if source does not exist; + the path `/nix-bin` as `/bin` inside the sandbox. If *source* is + followed by `?`, then it is not an error if *source* does not exist; for example, `/dev/nvidiactl?` specifies that `/dev/nvidiactl` will only be mounted in the sandbox if it exists in the host filesystem. diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 7d0567760..ddebc4b1b 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -43,16 +43,16 @@ paths # Description The `nix-build` command builds the derivations described by the Nix -expressions in paths. If the build succeeds, it places a symlink to the -result in the current directory. The symlink is called `result`. If +expressions in *paths*. If the build succeeds, it places a symlink to +the result in the current directory. The symlink is called `result`. If there are multiple Nix expressions, or the Nix expressions evaluate to multiple derivations, multiple sequentially numbered symlinks are created (`result`, `result-2`, and so on). -If no paths are specified, then `nix-build` will use `default.nix` in +If no *paths* are specified, then `nix-build` will use `default.nix` in the current directory, if it exists. -If an element of paths starts with `http://` or `https://`, it is +If an element of *paths* starts with `http://` or `https://`, 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 `default.nix`. @@ -83,9 +83,9 @@ All options not listed here are passed to `nix-store - `--dry-run` Show what store paths would be built or downloaded. - - `--out-link` / `-o` outlink + - `--out-link` / `-o` *outlink* Change the name of the symlink to the output path created from - `result` to outlink. + `result` to *outlink*. The following common options are supported: diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md index d427151a0..0c20788f0 100644 --- a/doc/manual/src/command-ref/nix-channel.md +++ b/doc/manual/src/command-ref/nix-channel.md @@ -42,25 +42,26 @@ To see the list of official NixOS channels, visit This command has the following operations: - - `--add` url \[name\] - Adds a channel named name with URL url to the list of subscribed - channels. If name is omitted, it defaults to the last component of - url, with the suffixes `-stable` or `-unstable` removed. + - `--add` *url* \[*name*\] + Adds a channel named *name* with URL *url* to the list of subscribed + channels. If *name* is omitted, it defaults to the last component of + *url*, with the suffixes `-stable` or `-unstable` removed. - - `--remove` name - Removes the channel named name from the list of subscribed channels. + - `--remove` *name* + Removes the channel named *name* from the list of subscribed + channels. - `--list` Prints the names and URLs of all subscribed channels on standard output. - - `--update` \[names…\] + - `--update` \[*names*…\] Downloads the Nix expressions of all subscribed channels (or only - those included in names if specified) and makes them the default for - `nix-env` operations (by symlinking them from the directory + those included in *names* if specified) and makes them the default + for `nix-env` operations (by symlinking them from the directory `~/.nix-defexpr`). - - `--rollback` \[generation\] + - `--rollback` \[*generation*\] Reverts the previous call to `nix-channel --update`. Optionally, you can specify a specific channel generation number to restore. diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md index 7946dc875..77b5d42d3 100644 --- a/doc/manual/src/command-ref/nix-collect-garbage.md +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -33,7 +33,7 @@ additional options: `-d` (`--delete-old`), which deletes all old generations of all profiles in `/nix/var/nix/profiles` by invoking `nix-env --delete-generations old` on all profiles (of course, this makes rollbacks to previous configurations impossible); and -`--delete-older-than` period, where period is a value such as `30d`, +`--delete-older-than` *period*, where period is a value such as `30d`, which deletes all generations older than the specified number of days in all profiles in `/nix/var/nix/profiles` (except for the generations that were active at that point in time). diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index 90bf6ea08..90a2bd351 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -98,7 +98,7 @@ This section lists the options that are common to all operations. These options are allowed for every subcommand, though they may not always have an effect. See also [???](#sec-common-options). - - `--file` / `-f` path + - `--file` / `-f` *path* Specifies the Nix expression (designated below as the *active Nix expression*) used by the `--install`, `--upgrade`, and `--query --available` operations to obtain derivations. The default is @@ -109,7 +109,7 @@ have an effect. See also [???](#sec-common-options). unpacked to a temporary location. The tarball must include a single top-level directory containing at least a file named `default.nix`. - - `--profile` / `-p` path + - `--profile` / `-p` *path* Specifies the profile to be used by those operations that operate on a profile (designated below as the *active profile*). A profile is a sequence of user environments called *generations*, one of which is @@ -125,10 +125,10 @@ have an effect. See also [???](#sec-common-options). [substituted](#gloss-substitute) (i.e., downloaded) and which paths will be built from source (because no substitute is available). - - `--system-filter` system + - `--system-filter` *system* By default, operations such as `--query --available` show derivations matching any platform. This option - allows you to use derivations for the specified platform system. + allows you to use derivations for the specified platform *system*. @@ -200,17 +200,17 @@ args 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 args is added. The arguments args map to store paths in a -number of possible ways: +described by *args* is added. The arguments *args* map to store paths in +a number of possible ways: - - By default, args is a set of derivation names denoting derivations + - By default, *args* 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 `--preserve-installed` is specified. - 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 the + 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 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 @@ -230,22 +230,23 @@ number of possible ways: unambiguous. To find out the attribute paths of available packages, use `nix-env -qaP`. - - If `--from-profile` path is given, args is a set of names denoting - installed store paths in the profile path. This is an easy way to - copy user environment elements from one profile to another. + - If `--from-profile` *path* is given, *args* is a set of names + denoting installed store paths in the profile *path*. This is an + easy way to copy user environment elements from one profile to + another. - - If `--from-expression` is given, args are Nix + - If `--from-expression` is given, *args* are Nix [functions](#ss-functions) 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. - - If args are store derivations, then these are + - If *args* are store derivations, then these are [realised](#rsec-nix-store-realise), and the resulting output paths are installed. - - If args are store paths that are not store derivations, then these + - If *args* are store paths that are not store derivations, then these are [realised](#rsec-nix-store-realise) and installed. - By default all outputs are installed for each derivation. That can @@ -359,12 +360,12 @@ args 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 args. 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 args matches no installed derivations. +described by *args*. 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 *args* matches no installed derivations. -For a description of how args is mapped to a set of store paths, see -[`--install`](#rsec-nix-env-install). If args describes multiple store +For a description of how *args* is mapped to a set of store paths, see +[`--install`](#rsec-nix-env-install). If *args* describes multiple store paths with the same symbolic name, only the one with the highest version is installed. @@ -462,7 +463,7 @@ drvnames 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 names are removed. +designated by the symbolic names *names* are removed. ## Examples @@ -629,7 +630,7 @@ The query operation displays information about either the store paths that are installed in the current generation of the active profile (`--installed`), or the derivations that are available for installation in the active Nix expression (`--available`). It only prints information -about derivations whose symbolic name matches one of names. +about derivations whose symbolic name matches one of *names*. The derivations are sorted by their `name` attributes. @@ -696,14 +697,14 @@ derivation is shown unless `--no-name` is specified. upgrades for installed packages are available in a Nix expression. A column is added with the following meaning: - - `<` version + - `<` *version* A newer version of the package is available or installed. - - `=` version + - `=` *version* At most the same version of the package is available or installed. - - `>` version + - `>` *version* Only older versions of the package are available or installed. - `- ?` @@ -806,8 +807,8 @@ path ## Description -This operation makes path the current profile for the user. That is, the -symlink `~/.nix-profile` is made to point to path. +This operation makes *path* the current profile for the user. That is, +the symlink `~/.nix-profile` is made to point to *path*. ## Examples @@ -882,9 +883,9 @@ generation ## Description -This operation makes generation number generation the current generation -of the active profile. That is, if the `profile` is the path to the -active profile, then the symlink `profile` is made to point to +This operation makes generation number *generation* the current +generation of the active profile. That is, if the `profile` is the path +to the active profile, then the symlink `profile` is made to point to `profile-generation-link`, which is in turn a symlink to the actual user environment in the Nix store. diff --git a/doc/manual/src/command-ref/nix-hash.md b/doc/manual/src/command-ref/nix-hash.md index d433cbc5b..3b8bbf740 100644 --- a/doc/manual/src/command-ref/nix-hash.md +++ b/doc/manual/src/command-ref/nix-hash.md @@ -37,7 +37,7 @@ hash # Description The command `nix-hash` computes the cryptographic hash of the contents -of each path and prints it on standard output. By default, it computes +of each *path* and prints it on standard output. By default, it computes an MD5 hash, but other hash algorithms are available as well. The hash is printed in hexadecimal. To generate the same hash as `nix-prefetch-url` you have to specify multiple arguments, see below for @@ -55,9 +55,9 @@ path | md5sum`. - `--flat` Print the cryptographic hash of the contents of each regular file - path. That is, do not compute the hash over the dump of path. The - result is identical to that produced by the GNU commands `md5sum` - and `sha1sum`. + *path*. That is, do not compute the hash over the dump of *path*. + The result is identical to that produced by the GNU commands + `md5sum` and `sha1sum`. - `--base32` Print the hash in a base-32 representation rather than hexadecimal. @@ -67,17 +67,17 @@ path | md5sum`. - `--truncate` Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits. - - `--type` hashAlgo + - `--type` *hashAlgo* Use the specified cryptographic hash algorithm, which can be one of `md5`, `sha1`, and `sha256`. - `--to-base16` Don’t hash anything, but convert the base-32 hash representation - hash to hexadecimal. + *hash* to hexadecimal. - `--to-base32` Don’t hash anything, but convert the hexadecimal hash representation - hash to base-32. + *hash* to base-32. # Examples diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index 449f5f70f..179fbf5ba 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -56,19 +56,19 @@ files The command `nix-instantiate` generates [store derivations](#gloss-derivation) from (high-level) Nix expressions. It -evaluates the Nix expressions in each of files (which defaults to -./default.nix). Each top-level expression should evaluate to a +evaluates the Nix expressions in each of *files* (which defaults to +*./default.nix*). Each top-level expression should evaluate to a derivation, a list of derivations, or a set of derivations. The paths of the resulting store derivations are printed on standard output. -If files is the character `-`, then a Nix expression will be read from +If *files* is the character `-`, then a Nix expression will be read from standard input. See also [???](#sec-common-options) for a list of common options. # Options - - `--add-root` path; `--indirect` + - `--add-root` *path*; `--indirect` See the [corresponding options](#opt-add-root) in `nix-store`. - `--parse` diff --git a/doc/manual/src/command-ref/nix-prefetch-url.md b/doc/manual/src/command-ref/nix-prefetch-url.md index bf8084e45..f7de27402 100644 --- a/doc/manual/src/command-ref/nix-prefetch-url.md +++ b/doc/manual/src/command-ref/nix-prefetch-url.md @@ -31,9 +31,9 @@ hash # Description The command `nix-prefetch-url` downloads the file referenced by the URL -url, prints its cryptographic hash, and copies it into the Nix store. -The file name in the store is `hash-baseName`, where baseName is -everything following the final slash in url. +*url*, prints its cryptographic hash, and copies it into the Nix store. +The file name in the store is `hash-baseName`, where *baseName* is +everything following the final slash in *url*. This command is just a convenience for Nix expression writers. Often a Nix expression fetches some source distribution from the network using @@ -44,10 +44,10 @@ again when you build your Nix expression. Since `fetchurl` uses the same name for the downloaded file as `nix-prefetch-url`, the redundant download can be avoided. -If hash is specified, then a download is not performed if the Nix store -already contains a file with the same hash and base name. Otherwise, the -file is downloaded, and an error is signaled if the actual hash of the -file does not match the specified hash. +If *hash* is specified, then a download is not performed if the Nix +store already contains a file with the same hash and base name. +Otherwise, the file is downloaded, and an error is signaled if the +actual hash of the file does not match the specified hash. This command prints the hash on standard output. Additionally, if the option `--print-path` is used, the path of the downloaded file in the @@ -55,7 +55,7 @@ Nix store is also printed. # Options - - `--type` hashAlgo + - `--type` *hashAlgo* Use the specified cryptographic hash algorithm, which can be one of `md5`, `sha1`, and `sha256`. @@ -67,10 +67,10 @@ Nix store is also printed. result to the Nix store. The resulting hash can be used with functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`. - - `--name` name + - `--name` *name* Override the name of the file in the Nix store. By default, this is - `hash-basename`, where basename is the last component of url. - Overriding the name is necessary when basename contains characters + `hash-basename`, where *basename* is the last component of *url*. + Overriding the name is necessary when *basename* contains characters that are not allowed in Nix store paths. # Examples diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md index c6910e3f5..9e2b781ab 100644 --- a/doc/manual/src/command-ref/nix-shell.md +++ b/doc/manual/src/command-ref/nix-shell.md @@ -61,14 +61,14 @@ path The command `nix-shell` will build the dependencies of the specified derivation, but not the derivation itself. It will then start an interactive shell in which all environment variables defined by the -derivation path have been set to their corresponding values, and the +derivation *path* have been set to their corresponding values, and the script `$stdenv/setup` has been sourced. This is useful for reproducing the environment of a derivation for development. -If path is not given, `nix-shell` defaults to `shell.nix` if it exists, -and `default.nix` otherwise. +If *path* is not given, `nix-shell` defaults to `shell.nix` if it +exists, and `default.nix` otherwise. -If path starts with `http://` or `https://`, it is interpreted as the +If *path* starts with `http://` or `https://`, 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 `default.nix`. @@ -91,8 +91,8 @@ All options not listed here are passed to `nix-store --realise`, except for `--arg` and `--attr` / `-A` which are passed to `nix-instantiate`. See also [???](#sec-common-options). - - `--command` cmd - In the environment of the derivation, run the shell command cmd. + - `--command` *cmd* + In the environment of the derivation, run the shell command *cmd*. This command is executed in an interactive shell. (Use `--run` to use a non-interactive shell instead.) However, a call to `exit` is implicitly added to the command, so the shell will exit after @@ -102,14 +102,14 @@ All options not listed here are passed to `nix-store interactive shell. This can be useful for doing any additional initialisation. - - `--run` cmd + - `--run` *cmd* Like `--command`, but executes the command in a non-interactive shell. This means (among other things) that if you hit Ctrl-C while the command is running, the shell exits. - - `--exclude` regexp + - `--exclude` *regexp* Do not build any dependencies whose store path matches the regular - expression regexp. This option may be specified multiple times. + expression *regexp*. This option may be specified multiple times. - `--pure` If this flag is specified, the environment is almost entirely @@ -120,19 +120,19 @@ All options not listed here are passed to `nix-store installation) `/etc/bashrc` are still sourced, so any variables set there will affect the interactive shell. - - `--packages` / `-p` packages… + - `--packages` / `-p` *packages*… Set up an environment in which the specified packages are present. The command line arguments are interpreted as attribute names inside the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk` will start a shell in which the packages denoted by the attribute names `libjpeg` and `openjdk` are present. - - `-i` interpreter + - `-i` *interpreter* The chained script interpreter to be invoked by `nix-shell`. Only applicable in `#!`-scripts (described [below](#ssec-nix-shell-shebang)). - - `--keep` name + - `--keep` *name* When a `--pure` shell is started, keep the listed environment variables. @@ -199,10 +199,10 @@ done by starting the script with the following lines: #! /usr/bin/env nix-shell #! nix-shell -i real-interpreter -p packages -where real-interpreter is the “real” script interpreter that will be +where *real-interpreter* is the “real” script interpreter that will be invoked by `nix-shell` after it has obtained the dependencies and -initialised the environment, and packages are the attribute names of the -dependencies in Nixpkgs. +initialised the environment, and *packages* are the attribute names of +the dependencies in Nixpkgs. The lines starting with `#! nix-shell` specify `nix-shell` options (see above). Note that you cannot write `#! /usr/bin/env nix-shell -i ...` diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md index 703e71076..a666de49b 100644 --- a/doc/manual/src/command-ref/nix-store.md +++ b/doc/manual/src/command-ref/nix-store.md @@ -37,10 +37,10 @@ options are allowed for every subcommand, though they may not always have an effect. See also [???](#sec-common-options) for a list of common options. - - `--add-root` path + - `--add-root` *path* Causes the result of a realisation (`--realise` and `--force-realise`) to be registered as a root of the garbage - collector(see [???](#ssec-gc-roots)). The root is stored in path, + collector(see [???](#ssec-gc-roots)). The root is stored in *path*, which must be inside a directory that is scanned for roots by the garbage collector (i.e., typically in a subdirectory of `/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used. @@ -56,8 +56,8 @@ options. result in the current directory; such a build result should not be garbage-collected unless the symlink is removed. - The `--indirect` flag causes a uniquely named symlink to path to be - stored in `/nix/var/nix/gcroots/auto/`. For instance, + The `--indirect` flag causes a uniquely named symlink to *path* to + be stored in `/nix/var/nix/gcroots/auto/`. For instance, $ nix-store --add-root /home/eelco/bla/result --indirect -r ... @@ -262,10 +262,11 @@ The following suboperations may be specified: By default, all unreachable paths are deleted. The following options control what gets deleted and in what order: - - `--max-freed` bytes - Keep deleting paths until at least bytes bytes have been deleted, - then stop. The argument bytes can be followed by the multiplicative - suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB or TiB units. + - `--max-freed` *bytes* + Keep deleting paths until at least *bytes* bytes have been deleted, + then stop. The argument *bytes* can be followed by the + multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB + or TiB units. The behaviour of the collector is also influenced by the [`keep-outputs`](#conf-keep-outputs) and @@ -303,7 +304,7 @@ paths ## Description -The operation `--delete` deletes the store paths paths from the Nix +The operation `--delete` deletes the store paths *paths* from the Nix store, but only if it is safe to do so; that is, when the path is not reachable from a root of the garbage collector. This means that you can only delete paths that would also be deleted by `nix-store --gc`. Thus, @@ -379,7 +380,7 @@ The operation `--query` displays various bits of information about the store paths . The queries are described below. At most one query can be specified. The default query is `--outputs`. -The paths paths may also be symlinks from outside of the Nix store, to +The paths *paths* may also be symlinks from outside of the Nix store, to the Nix store. In that case, the query is applied to the target of the symlink. @@ -397,11 +398,11 @@ symlink. - `--outputs` Prints out the [output paths](#gloss-output-path) of the store - derivations paths. These are the paths that will be produced when + derivations *paths*. These are the paths that will be produced when the derivation is built. - `--requisites`; `-R` - Prints out the [closure](#gloss-closure) of the store path paths. + Prints out the [closure](#gloss-closure) of the store path *paths*. This query has one option: @@ -419,29 +420,30 @@ symlink. - `--references` Prints the set of [references](#gloss-reference) of the store paths - paths, that is, their immediate dependencies. (For *all* + *paths*, that is, their immediate dependencies. (For *all* dependencies, use `--requisites`.) - `--referrers` - Prints the set of *referrers* of the store paths paths, that is, the - store paths currently existing in the Nix store that refer to one of - paths. Note that contrary to the references, the set of referrers is - not constant; it can change as store paths are added or removed. + Prints the set of *referrers* of the store paths *paths*, that is, + the store paths currently existing in the Nix store that refer to + one of *paths*. Note that contrary to the references, the set of + referrers is not constant; it can change as store paths are added or + removed. - `--referrers-closure` - Prints the closure of the set of store paths paths under the + Prints the closure of the set of store paths *paths* under the referrers relation; that is, all store paths that directly or - indirectly refer to one of paths. These are all the path currently - in the Nix store that are dependent on paths. + indirectly refer to one of *paths*. These are all the path currently + in the Nix store that are dependent on *paths*. - `--deriver`; `-d` - Prints the [deriver](#gloss-deriver) of the store paths paths. If + Prints the [deriver](#gloss-deriver) of the store paths *paths*. If the path has no deriver (e.g., if it is a source file), or if the deriver is not known (e.g., in the case of a binary-only deployment), the string `unknown-deriver` is printed. - `--graph` - Prints the references graph of the store paths paths in the format + Prints the references graph of the store paths *paths* in the format of the `dot` tool of AT\&T's [Graphviz package](http://www.graphviz.org/). This can be used to visualise dependency graphs. To obtain a build-time dependency graph, apply @@ -449,40 +451,40 @@ symlink. apply it to an output path. - `--tree` - Prints the references graph of the store paths paths as a nested + Prints the references graph of the store paths *paths* as a nested ASCII tree. References are ordered by descending closure size; this tends to flatten the tree, making it more readable. The query only recurses into a store path when it is first encountered; this prevents a blowup of the tree representation of the graph. - `--graphml` - Prints the references graph of the store paths paths in the + Prints the references graph of the store paths *paths* in the [GraphML](http://graphml.graphdrawing.org/) file format. This can be used to visualise dependency graphs. To obtain a build-time dependency graph, apply this to a store derivation. To obtain a runtime dependency graph, apply it to an output path. - - `--binding` name; `-b` name - Prints the value of the attribute name (i.e., environment variable) - of the store derivations paths. It is an error for a derivation to - not have the specified attribute. + - `--binding` *name*; `-b` *name* + Prints the value of the attribute *name* (i.e., environment + variable) of the store derivations *paths*. It is an error for a + derivation to not have the specified attribute. - `--hash` - Prints the SHA-256 hash of the contents of the store paths paths + Prints the SHA-256 hash of the contents of the store paths *paths* (that is, the hash of the output of `nix-store --dump` on the given paths). Since the hash is stored in the Nix database, this is a fast operation. - `--size` - Prints the size in bytes of the contents of the store paths paths — - to be precise, the size of the output of `nix-store --dump` on the - given paths. Note that the actual disk space required by the store - paths may be higher, especially on filesystems with large cluster - sizes. + Prints the size in bytes of the contents of the store paths *paths* + — to be precise, the size of the output of `nix-store --dump` on + the given paths. Note that the actual disk space required by the + store paths may be higher, especially on filesystems with large + cluster sizes. - `--roots` Prints the garbage collector roots that point, directly or - indirectly, at the store paths paths. + indirectly, at the store paths *paths*. ## Examples @@ -708,8 +710,8 @@ path ## Description The operation `--dump` produces a NAR (Nix ARchive) file containing the -contents of the file system tree rooted at path. The archive is written -to standard output. +contents of the file system tree rooted at *path*. The archive is +written to standard output. A NAR archive is like a TAR or Zip archive, but it contains only the information that Nix considers important. For instance, timestamps are @@ -745,8 +747,8 @@ path ## Description -The operation `--restore` unpacks a NAR archive to path, which must not -already exist. The archive is read from standard input. +The operation `--restore` unpacks a NAR archive to *path*, which must +not already exist. The archive is read from standard input. # Operation `--export` diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md index ac9d996c3..dce95773a 100644 --- a/doc/manual/src/command-ref/opt-common.md +++ b/doc/manual/src/command-ref/opt-common.md @@ -44,9 +44,9 @@ Most Nix commands accept the following command-line options: This option may be specified repeatedly. See the previous verbosity levels list. - - `--log-format` format + - `--log-format` *format* This option can be used to change the output of the log format, with - format being one of: + *format* being one of: - raw This is the raw format, as outputted by nix-build. @@ -68,7 +68,7 @@ Most Nix commands accept the following command-line options: output and error are always written to a log file in `prefix/nix/var/log/nix`. - - `--max-jobs` / `-j` number + - `--max-jobs` / `-j` *number* Sets the maximum number of build jobs that Nix will perform in parallel to the specified number. Specify `auto` to use the number of CPUs in the system. The default is specified by the @@ -144,7 +144,7 @@ Most Nix commands accept the following command-line options: database. Most Nix operations do need database access, so those operations will fail. - - `--arg` name value + - `--arg` *name* *value* This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell` and `nix-build`. When evaluating Nix expressions, the expression evaluator will automatically try to call functions that it @@ -153,8 +153,8 @@ Most Nix commands accept the following command-line options: defaultValue }: ...`). With `--arg`, you can also call functions that have arguments without a default value (or override a default value). That is, if - the evaluator encounters a function with an argument named name, it - will call it with value value. + the evaluator encounters a function with an argument named *name*, + it will call it with value *value*. For instance, the top-level `default.nix` in Nixpkgs is actually a function: @@ -172,18 +172,18 @@ Most Nix commands accept the following command-line options: \"i686-freebsd\"`. (Note that since the argument is a Nix string literal, you have to escape the quotes.) - - `--argstr` name value + - `--argstr` *name* *value* This option is like `--arg`, 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`. - - `--attr` / `-A` attrPath + - `--attr` / `-A` *attrPath* Select an attribute from the top-level Nix expression being evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and - `nix-shell` only.) The *attribute path* attrPath is a sequence of + `nix-shell` only.) The *attribute path* *attrPath* is a sequence of attribute names separated by dots. For instance, given a top-level - Nix expression e, the attribute path `xorg.xorgserver` would cause + Nix expression *e*, the attribute path `xorg.xorgserver` would cause the expression `e.xorg.xorgserver` to be used. See [`nix-env --install`](#refsec-nix-env-install-examples) for some concrete examples. @@ -204,14 +204,14 @@ Most Nix commands accept the following command-line options: use, give your expression to the `nix-shell -p` convenience flag instead. - - `-I` path + - `-I` *path* Add a path to the Nix expression search path. This option may be given multiple times. See the NIX\_PATH\ environment variable for information on the semantics of the Nix search path. Paths added through `-I` take precedence over `NIX_PATH`. - - `--option` name value - Set the Nix configuration option name to value. This overrides + - `--option` *name* *value* + Set the Nix configuration option *name* to *value*. This overrides settings in the Nix configuration file (see nix.conf5). - `--repair` diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md index 01e18513d..3582fa268 100644 --- a/doc/manual/src/expressions/advanced-attributes.md +++ b/doc/manual/src/expressions/advanced-attributes.md @@ -54,9 +54,9 @@ Derivations can declare some infrequently used optional attributes. attribute should be a list of pairs `[ name1 path1 name2 path2 ... - ]`. The references graph of each pathN will be stored in a text file - nameN in the temporary build directory. The text files have the - format used by `nix-store + ]`. The references graph of each *pathN* will be stored in a text + file *nameN* in the temporary build directory. The text files have + the format used by `nix-store --register-validity` (with the deriver fields left empty). For example, when the following derivation is built: @@ -204,9 +204,9 @@ Derivations can declare some infrequently used optional attributes. then when the builder runs, the environment variable `bigPath` will contain the absolute path to a temporary file containing `a very long - string`. That is, for any attribute x listed in `passAsFile`, Nix + string`. That is, for any attribute *x* listed in `passAsFile`, Nix will pass an environment variable `xPath` holding the path of the - file containing the value of attribute x. This is useful when you + file containing the value of attribute *x*. This is useful when you need to pass large strings to a builder, since most operating systems impose a limit on the size of the environment (typically, a few hundred kilobyte). diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md index 8faf4b939..8f19c692a 100644 --- a/doc/manual/src/expressions/builtins.md +++ b/doc/manual/src/expressions/builtins.md @@ -9,42 +9,42 @@ scope. Instead, you can access them through the `builtins` built-in value, which is a set that contains all built-in functions and values. For instance, `derivation` is also available as `builtins.derivation`. - - `abort` s; `builtins.abort` s - Abort Nix expression evaluation, print error message s. + - `abort` *s*; `builtins.abort` *s* + Abort Nix expression evaluation, print error message *s*. - - `builtins.add` e1 e2 - Return the sum of the numbers e1 and e2. + - `builtins.add` *e1* *e2* + Return the sum of the numbers *e1* and *e2*. - - `builtins.all` pred list - Return `true` if the function pred returns `true` for all elements - of list, and `false` otherwise. + - `builtins.all` *pred* *list* + Return `true` if the function *pred* returns `true` for all elements + of *list*, and `false` otherwise. - - `builtins.any` pred list - Return `true` if the function pred returns `true` for at least one - element of list, and `false` otherwise. + - `builtins.any` *pred* *list* + Return `true` if the function *pred* returns `true` for at least one + element of *list*, and `false` otherwise. - - `builtins.attrNames` set - Return the names of the attributes in the set set in an + - `builtins.attrNames` *set* + Return the names of the attributes in the set *set* in an alphabetically sorted list. For instance, `builtins.attrNames { y = 1; x = "foo"; }` evaluates to `[ "x" "y" ]`. - - `builtins.attrValues` set - Return the values of the attributes in the set set in the order + - `builtins.attrValues` *set* + Return the values of the attributes in the set *set* in the order corresponding to the sorted attribute names. - - `baseNameOf` s - Return the *base name* of the string s, that is, everything + - `baseNameOf` *s* + Return the *base name* of the string *s*, that is, everything following the final slash in the string. This is similar to the GNU `basename` command. - - `builtins.bitAnd` e1 e2 - Return the bitwise AND of the integers e1 and e2. + - `builtins.bitAnd` *e1* *e2* + Return the bitwise AND of the integers *e1* and *e2*. - - `builtins.bitOr` e1 e2 - Return the bitwise OR of the integers e1 and e2. + - `builtins.bitOr` *e1* *e2* + Return the bitwise OR of the integers *e1* and *e2*. - - `builtins.bitXor` e1 e2 - Return the bitwise XOR of the integers e1 and e2. + - `builtins.bitXor` *e1* *e2* + Return the bitwise XOR of the integers *e1* and *e2*. - `builtins` The set `builtins` contains all the built-in functions and values. @@ -56,17 +56,17 @@ For instance, `derivation` is also available as `builtins.derivation`. This allows a Nix expression to fall back gracefully on older Nix installations that don’t have the desired built-in function. - - `builtins.compareVersions` s1 s2 + - `builtins.compareVersions` *s1* *s2* Compare two strings representing versions and return `-1` if version - s1 is older than version s2, `0` if they are the same, and `1` if s1 - is newer than s2. The version comparison algorithm is the same as - the one used by [`nix-env + *s1* is older than version *s2*, `0` if they are the same, and `1` + if *s1* is newer than *s2*. The version comparison algorithm is the + same as the one used by [`nix-env -u`](#ssec-version-comparisons). - - `builtins.concatLists` lists + - `builtins.concatLists` *lists* Concatenate a list of lists into a single list. - - `builtins.concatStringsSep` separator list + - `builtins.concatStringsSep` *separator* *list* Concatenate a list of strings with a separator between each element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] == "usr/local/bin"` @@ -76,37 +76,37 @@ For instance, `derivation` is also available as `builtins.derivation`. identifier for the Nix installation on which the expression is being evaluated, such as `"i686-linux"` or `"x86_64-darwin"`. - - `builtins.deepSeq` e1 e2 + - `builtins.deepSeq` *e1* *e2* This is like `seq e1 - e2`, except that e1 is evaluated *deeply*: if it’s a list or set, + e2`, except that *e1* is evaluated *deeply*: if it’s a list or set, its elements or attributes are also evaluated recursively. - - `derivation` attrs; `builtins.derivation` attrs + - `derivation` *attrs*; `builtins.derivation` *attrs* `derivation` is described in [???](#ssec-derivation). - - `dirOf` s; `builtins.dirOf` s - Return the directory part of the string s, that is, everything + - `dirOf` *s*; `builtins.dirOf` *s* + Return the directory part of the string *s*, that is, everything before the final slash in the string. This is similar to the GNU `dirname` command. - - `builtins.div` e1 e2 - Return the quotient of the numbers e1 and e2. + - `builtins.div` *e1* *e2* + Return the quotient of the numbers *e1* and *e2*. - - `builtins.elem` x xs - Return `true` if a value equal to x occurs in the list xs, and + - `builtins.elem` *x* *xs* + Return `true` if a value equal to *x* occurs in the list *xs*, and `false` otherwise. - - `builtins.elemAt` xs n - Return element n from the list xs. Elements are counted starting + - `builtins.elemAt` *xs* *n* + Return element *n* from the list *xs*. Elements are counted starting from 0. A fatal error occurs if the index is out of bounds. - - `builtins.fetchurl` url + - `builtins.fetchurl` *url* Download the specified URL and return the path of the downloaded file. This function is not available if [restricted evaluation mode](#conf-restrict-eval) is enabled. - - `fetchTarball` url; `builtins.fetchTarball` url + - `fetchTarball` *url*; `builtins.fetchTarball` *url* Download the specified URL, unpack it and return the path of the unpacked tree. The file must be a tape archive (`.tar`) compressed with `gzip`, `bzip2` or `xz`. The top-level path component of the @@ -142,10 +142,10 @@ For instance, `derivation` is also available as `builtins.derivation`. This function is not available if [restricted evaluation mode](#conf-restrict-eval) is enabled. - - `builtins.fetchGit` args - Fetch a path from git. args can be a URL, in which case the HEAD of - the repo at that URL is fetched. Otherwise, it can be an attribute - with the following attributes (all except `url` optional): + - `builtins.fetchGit` *args* + Fetch a path from git. *args* can be a URL, in which case the HEAD + of the repo at that URL is fetched. Otherwise, it can be an + attribute with the following attributes (all except `url` optional): - url The URL of the repo. @@ -240,11 +240,11 @@ For instance, `derivation` is also available as `builtins.derivation`. > > This behavior is disabled in *Pure evaluation mode*. - - `builtins.filter` f xs - Return a list consisting of the elements of xs for which the - function f returns `true`. + - `builtins.filter` *f* *xs* + Return a list consisting of the elements of *xs* for which the + function *f* returns `true`. - - `builtins.filterSource` e1 e2 + - `builtins.filterSource` *e1* *e2* This function allows you to copy sources into the Nix store while filtering certain files. For instance, suppose that you want to use the directory `source-dir` as an input to a Nix expression, e.g. @@ -266,9 +266,9 @@ For instance, `derivation` is also available as `builtins.derivation`. ./source-dir; ``` - Thus, the first argument e1 must be a predicate function that is + Thus, the first argument *e1* must be a predicate function that is called for each regular file, directory or symlink in the source - tree e2. If the function returns `true`, the file is copied to the + tree *e2*. If the function returns `true`, the file is copied to the Nix store, otherwise it is omitted. The function is called with two arguments. The first is the full path of the file. The second is a string that identifies the type of the file, which is either @@ -276,19 +276,19 @@ For instance, `derivation` is also available as `builtins.derivation`. kinds of files such as device nodes or fifos — but note that those cannot be copied to the Nix store, so if the predicate returns `true` for them, the copy will fail). If you exclude a directory, - the entire corresponding subtree of e2 will be excluded. + the entire corresponding subtree of *e2* will be excluded. - - `builtins.foldl’` op nul list + - `builtins.foldl’` *op* *nul* *list* Reduce a list by applying a binary operator, from left to right, e.g. `foldl’ op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2) ...`. The operator is applied strictly, i.e., its arguments are evaluated first. For example, `foldl’ (x: y: x + y) 0 [1 2 3]` evaluates to 6. - - `builtins.functionArgs` f + - `builtins.functionArgs` *f* Return a set containing the names of the formal arguments expected - by the function f. The value of each attribute is a Boolean denoting - whether the corresponding argument has a default value. For + by the function *f*. The value of each attribute is a Boolean + denoting whether the corresponding argument has a default value. For instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }`. @@ -296,7 +296,7 @@ For instance, `derivation` is also available as `builtins.derivation`. the function. Plain lambdas are not included, e.g. `functionArgs (x: ...) = { }`. - - `builtins.fromJSON` e + - `builtins.fromJSON` *e* Convert a JSON string to a Nix value. For example, builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' @@ -304,21 +304,22 @@ For instance, `derivation` is also available as `builtins.derivation`. returns the value `{ x = [ 1 2 3 ]; y = null; }`. - - `builtins.genList` generator length - Generate list of size length, with each element i equal to the value - returned by generator `i`. For example, + - `builtins.genList` *generator* *length* + Generate list of size *length*, with each element *i* equal to the + value returned by *generator* `i`. For example, builtins.genList (x: x * x) 5 returns the list `[ 0 1 4 9 16 ]`. - - `builtins.getAttr` s set - `getAttr` returns the attribute named s from set. Evaluation aborts - if the attribute doesn’t exist. This is a dynamic version of the `.` - operator, since s is an expression rather than an identifier. + - `builtins.getAttr` *s* *set* + `getAttr` returns the attribute named *s* from *set*. Evaluation + aborts if the attribute doesn’t exist. This is a dynamic version of + the `.` operator, since *s* is an expression rather than an + identifier. - - `builtins.getEnv` s - `getEnv` returns the value of the environment variable s, or an + - `builtins.getEnv` *s* + `getEnv` returns the value of the environment variable *s*, or an empty string if the variable doesn’t exist. This function should be used with care, as it can introduce all sorts of nasty environment dependencies in your Nix expression. @@ -328,29 +329,29 @@ For instance, `derivation` is also available as `builtins.derivation`. Packages. (That is, it does a `getEnv "HOME"` to locate the user’s home directory.) - - `builtins.hasAttr` s set - `hasAttr` returns `true` if set has an attribute named s, and + - `builtins.hasAttr` *s* *set* + `hasAttr` returns `true` if *set* has an attribute named *s*, and `false` otherwise. This is a dynamic version of the `?` operator, - since s is an expression rather than an identifier. + since *s* is an expression rather than an identifier. - - `builtins.hashString` type s + - `builtins.hashString` *type* *s* Return a base-16 representation of the cryptographic hash of string - s. The hash algorithm specified by type must be one of `"md5"`, + *s*. The hash algorithm specified by *type* must be one of `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`. - - `builtins.hashFile` type p + - `builtins.hashFile` *type* *p* Return a base-16 representation of the cryptographic hash of the - file at path p. The hash algorithm specified by type must be one of - `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`. + file at path *p*. The hash algorithm specified by *type* must be one + of `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`. - - `builtins.head` list + - `builtins.head` *list* Return the first element of a list; abort evaluation if the argument isn’t a list or is an empty list. You can test whether a list is empty by comparing it with `[]`. - - `import` path; `builtins.import` path - Load, parse and return the Nix expression in the file path. If path - is a directory, the file ` default.nix + - `import` *path*; `builtins.import` *path* + Load, parse and return the Nix expression in the file *path*. If + *path* is a directory, the file ` default.nix ` in that directory is loaded. Evaluation aborts if the file doesn’t exist or contains an incorrect Nix expression. `import` implements Nix’s module system: you can put any Nix expression (such @@ -361,7 +362,8 @@ For instance, `derivation` is also available as `builtins.derivation`. > > Unlike some languages, `import` is a regular function in Nix. > Paths using the angle bracket syntax (e.g., ` - > > > > > import` \) are normal path values (see [???](#ssec-values)). + > > > > > import` *\*) are normal path values (see + > [???](#ssec-values)). A Nix expression loaded by `import` must not contain any *free variables* (identifiers that are not defined in the Nix expression @@ -393,50 +395,50 @@ For instance, `derivation` is also available as `builtins.derivation`. (The function argument doesn’t have to be called `x` in `foo.nix`; any name would work.) - - `builtins.intersectAttrs` e1 e2 - Return a set consisting of the attributes in the set e2 that also - exist in the set e1. + - `builtins.intersectAttrs` *e1* *e2* + Return a set consisting of the attributes in the set *e2* that also + exist in the set *e1*. - - `builtins.isAttrs` e - Return `true` if e evaluates to a set, and `false` otherwise. + - `builtins.isAttrs` *e* + Return `true` if *e* evaluates to a set, and `false` otherwise. - - `builtins.isList` e - Return `true` if e evaluates to a list, and `false` otherwise. + - `builtins.isList` *e* + Return `true` if *e* evaluates to a list, and `false` otherwise. - - `builtins.isFunction` e - Return `true` if e evaluates to a function, and `false` otherwise. + - `builtins.isFunction` *e* + Return `true` if *e* evaluates to a function, and `false` otherwise. - - `builtins.isString` e - Return `true` if e evaluates to a string, and `false` otherwise. + - `builtins.isString` *e* + Return `true` if *e* evaluates to a string, and `false` otherwise. - - `builtins.isInt` e - Return `true` if e evaluates to an int, and `false` otherwise. + - `builtins.isInt` *e* + Return `true` if *e* evaluates to an int, and `false` otherwise. - - `builtins.isFloat` e - Return `true` if e evaluates to a float, and `false` otherwise. + - `builtins.isFloat` *e* + Return `true` if *e* evaluates to a float, and `false` otherwise. - - `builtins.isBool` e - Return `true` if e evaluates to a bool, and `false` otherwise. + - `builtins.isBool` *e* + Return `true` if *e* evaluates to a bool, and `false` otherwise. - - `builtins.isPath` e - Return `true` if e evaluates to a path, and `false` otherwise. + - `builtins.isPath` *e* + Return `true` if *e* evaluates to a path, and `false` otherwise. - - `isNull` e; `builtins.isNull` e - Return `true` if e evaluates to `null`, and `false` otherwise. + - `isNull` *e*; `builtins.isNull` *e* + Return `true` if *e* evaluates to `null`, and `false` otherwise. > **Warning** > > This function is *deprecated*; just write `e == null` instead. - - `builtins.length` e - Return the length of the list e. + - `builtins.length` *e* + Return the length of the list *e*. - - `builtins.lessThan` e1 e2 - Return `true` if the number e1 is less than the number e2, and - `false` otherwise. Evaluation aborts if either e1 or e2 does not + - `builtins.lessThan` *e1* *e2* + Return `true` if the number *e1* is less than the number *e2*, and + `false` otherwise. Evaluation aborts if either *e1* or *e2* does not evaluate to a number. - - `builtins.listToAttrs` e + - `builtins.listToAttrs` *e* Construct a set from a list specifying the names and values of each attribute. Each element of the list should be a set consisting of a string-valued attribute `name` specifying the name of the attribute, @@ -451,19 +453,20 @@ For instance, `derivation` is also available as `builtins.derivation`. { foo = 123; bar = 456; } - - `map` f list; `builtins.map` f list - Apply the function f to each element in the list list. For example, + - `map` *f* *list*; `builtins.map` *f* *list* + Apply the function *f* to each element in the list *list*. For + example, map (x: "foo" + x) [ "bar" "bla" "abc" ] evaluates to `[ "foobar" "foobla" "fooabc" ]`. - - `builtins.match` regex str + - `builtins.match` *regex* *str* Returns a list if the [extended POSIX regular expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04) - regex matches str precisely, otherwise returns `null`. Each item in - the list is a regex group. + *regex* matches *str* precisely, otherwise returns `null`. Each item + in the list is a regex group. builtins.match "ab" "abc" @@ -481,21 +484,21 @@ For instance, `derivation` is also available as `builtins.derivation`. Evaluates to `[ "foo" ]`. - - `builtins.mul` e1 e2 - Return the product of the numbers e1 and e2. + - `builtins.mul` *e1* *e2* + Return the product of the numbers *e1* and *e2*. - - `builtins.parseDrvName` s - Split the string s into a package name and version. The package name - is everything up to but not including the first dash followed by a - digit, and the version is everything following that dash. The result - is returned in a set `{ name, version }`. Thus, + - `builtins.parseDrvName` *s* + Split the string *s* into a package name and version. The package + name is everything up to but not including the first dash followed + by a digit, and the version is everything following that dash. The + result is returned in a set `{ name, version }`. Thus, `builtins.parseDrvName "nix-0.12pre12876"` returns `{ name = "nix"; version = "0.12pre12876"; }`. - - `builtins.path` args + - `builtins.path` *args* An enrichment of the built-in path type, based on the attributes - present in args. All are optional except `path`: + present in *args*. All are optional except `path`: - path The underlying path. @@ -523,20 +526,20 @@ For instance, `derivation` is also available as `builtins.derivation`. providing a hash allows `builtins.path` to be used even when the `pure-eval` nix config option is on. - - `builtins.pathExists` path - Return `true` if the path path exists at evaluation time, and + - `builtins.pathExists` *path* + Return `true` if the path *path* exists at evaluation time, and `false` otherwise. - - `builtins.placeholder` output - Return a placeholder string for the specified output that will be + - `builtins.placeholder` *output* + Return a placeholder string for the specified *output* that will be substituted by the corresponding output path at build time. Typical outputs would be `"out"`, `"bin"` or `"dev"`. - - `builtins.readDir` path - Return the contents of the directory path as a set mapping directory - entries to the corresponding file type. For instance, if directory - `A` contains a regular file `B` and another directory `C`, then - `builtins.readDir + - `builtins.readDir` *path* + Return the contents of the directory *path* as a set mapping + directory entries to the corresponding file type. For instance, if + directory `A` contains a regular file `B` and another directory `C`, + then `builtins.readDir ./A` will return the set { B = "regular"; C = "directory"; } @@ -544,33 +547,33 @@ For instance, `derivation` is also available as `builtins.derivation`. The possible values for the file type are `"regular"`, `"directory"`, `"symlink"` and `"unknown"`. - - `builtins.readFile` path - Return the contents of the file path as a string. + - `builtins.readFile` *path* + Return the contents of the file *path* as a string. - - `removeAttrs` set list; `builtins.removeAttrs` set list - Remove the attributes listed in list from set. The attributes don’t - have to exist in set. For instance, + - `removeAttrs` *set* *list*; `builtins.removeAttrs` *set* *list* + Remove the attributes listed in *list* from *set*. The attributes + don’t have to exist in *set*. For instance, removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ] evaluates to `{ y = 2; }`. - - `builtins.replaceStrings` from to s - Given string s, replace every occurrence of the strings in from with - the corresponding string in to. For example, + - `builtins.replaceStrings` *from* *to* *s* + Given string *s*, replace every occurrence of the strings in *from* + with the corresponding string in *to*. For example, builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" evaluates to `"fabir"`. - - `builtins.seq` e1 e2 - Evaluate e1, then evaluate and return e2. This ensures that a - computation is strict in the value of e1. + - `builtins.seq` *e1* *e2* + Evaluate *e1*, then evaluate and return *e2*. This ensures that a + computation is strict in the value of *e1*. - - `builtins.sort` comparator list - Return list in sorted order. It repeatedly calls the function - comparator with two elements. The comparator should return `true` if - the first element is less than the second, and `false` otherwise. + - `builtins.sort` *comparator* *list* + Return *list* in sorted order. It repeatedly calls the function + *comparator* with two elements. The comparator should return `true` + if the first element is less than the second, and `false` otherwise. For example, builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] @@ -581,12 +584,12 @@ For instance, `derivation` is also available as `builtins.derivation`. This is a stable sort: it preserves the relative order of elements deemed equal by the comparator. - - `builtins.split` regex str + - `builtins.split` *regex* *str* Returns a list composed of non matched strings interleaved with the lists of the [extended POSIX regular expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04) - regex matches of str. Each item in the lists of matched sequences is - a regex group. + *regex* matches of *str*. Each item in the lists of matched + sequences is a regex group. builtins.split "(a)b" "abc" @@ -604,44 +607,44 @@ For instance, `derivation` is also available as `builtins.derivation`. Evaluates to `[ " " [ "FOO" ] " " ]`. - - `builtins.splitVersion` s + - `builtins.splitVersion` *s* Split a string representing a version into its components, by the same version splitting logic underlying the version comparison in [`nix-env -u`](#ssec-version-comparisons). - - `builtins.stringLength` e - Return the length of the string e. If e is not a string, evaluation - is aborted. + - `builtins.stringLength` *e* + Return the length of the string *e*. If *e* is not a string, + evaluation is aborted. - - `builtins.sub` e1 e2 - Return the difference between the numbers e1 and e2. + - `builtins.sub` *e1* *e2* + Return the difference between the numbers *e1* and *e2*. - - `builtins.substring` start len s - Return the substring of s from character position start (zero-based) - up to but not including start + len. If start is greater than the - length of the string, an empty string is returned, and if start + - len lies beyond the end of the string, only the substring up to the - end of the string is returned. start must be non-negative. For - example, + - `builtins.substring` *start* *len* *s* + Return the substring of *s* from character position *start* + (zero-based) up to but not including *start + len*. If *start* is + greater than the length of the string, an empty string is returned, + and if *start + len* lies beyond the end of the string, only the + substring up to the end of the string is returned. *start* must be + non-negative. For example, builtins.substring 0 3 "nixos" evaluates to `"nix"`. - - `builtins.tail` list + - `builtins.tail` *list* Return the second to last elements of a list; abort evaluation if the argument isn’t a list or is an empty list. - - `throw` s; `builtins.throw` s - Throw an error message s. This usually aborts Nix expression + - `throw` *s*; `builtins.throw` *s* + Throw an error message *s*. This usually aborts Nix expression evaluation, but in `nix-env -qa` and other commands that try to evaluate a set of derivations to get information about those derivations, a derivation that throws an error is silently skipped (which is not the case for `abort`). - - `builtins.toFile` name s - Store the string s in a file in the Nix store and return its path. - The file has suffix name. This file can be used as an input to + - `builtins.toFile` *name* *s* + Store the string *s* in a file in the Nix store and return its path. + The file has suffix *name*. This file can be used as an input to derivations. One application is to write builders “inline”. For instance, the following Nix expression combines [???](#ex-hello-nix) and [???](#ex-hello-builder) into one file: @@ -705,20 +708,20 @@ For instance, `derivation` is also available as `builtins.derivation`. you are using Nixpkgs, the `writeTextFile` function is able to do that. - - `builtins.toJSON` e - Return a string containing a JSON representation of e. Strings, + - `builtins.toJSON` *e* + Return a string containing a JSON representation of *e*. Strings, integers, floats, booleans, nulls and lists are mapped to their JSON equivalents. Sets (except derivations) are represented as objects. Derivations are translated to a JSON string containing the derivation’s output path. Paths are copied to the store and represented as a JSON string of the resulting store path. - - `builtins.toPath` s + - `builtins.toPath` *s* DEPRECATED. Use `/. + "/path"` to convert a string into an absolute path. For relative paths, use `./. + "/path"`. - - `toString` e; `builtins.toString` e - Convert the expression e to a string. e can be: + - `toString` *e*; `builtins.toString` *e* + Convert the expression *e* to a string. *e* can be: - A string (in which case the string is returned unmodified). @@ -735,8 +738,8 @@ For instance, `derivation` is also available as `builtins.derivation`. - `null`, which yields the empty string. - - `builtins.toXML` e - Return a string containing an XML representation of e. The main + - `builtins.toXML` *e* + Return a string containing an XML representation of *e*. The main application for `toXML` is to communicate information with the builder in a more structured format than plain environment variables. @@ -822,22 +825,23 @@ For instance, `derivation` is also available as `builtins.derivation`. of the stylesheet is spliced into the builder using the syntax `xsltproc ${stylesheet}`. - - `builtins.trace` e1 e2 - Evaluate e1 and print its abstract syntax representation on standard - error. Then return e2. This function is useful for debugging. + - `builtins.trace` *e1* *e2* + Evaluate *e1* and print its abstract syntax representation on + standard error. Then return *e2*. This function is useful for + debugging. - - `builtins.tryEval` e - Try to shallowly evaluate e. Return a set containing the attributes - `success` (`true` if e evaluated successfully, `false` if an error - was thrown) and `value`, equalling e if successful and `false` - otherwise. Note that this doesn't evaluate e deeply, so ` let e = { - x = throw ""; }; in (builtins.tryEval e).success + - `builtins.tryEval` *e* + Try to shallowly evaluate *e*. Return a set containing the + attributes `success` (`true` if *e* evaluated successfully, `false` + if an error was thrown) and `value`, equalling *e* if successful and + `false` otherwise. Note that this doesn't evaluate *e* deeply, so + ` let e = { x = throw ""; }; in (builtins.tryEval e).success ` will be `true`. Using ` builtins.deepSeq ` one can get the expected result: `let e = { x = throw ""; }; in (builtins.tryEval (builtins.deepSeq e e)).success` will be `false`. - - `builtins.typeOf` e - Return a string representing the type of the value e, namely + - `builtins.typeOf` *e* + Return a string representing the type of the value *e*, namely `"int"`, `"bool"`, `"string"`, `"path"`, `"null"`, `"set"`, `"list"`, `"lambda"` or `"float"`. diff --git a/doc/manual/src/expressions/expression-syntax.md b/doc/manual/src/expressions/expression-syntax.md index 9e99a1f60..2abe6ac6e 100644 --- a/doc/manual/src/expressions/expression-syntax.md +++ b/doc/manual/src/expressions/expression-syntax.md @@ -33,7 +33,7 @@ elements (referenced from the figure by number): Nix functions generally have the form `{ x, y, ..., z }: e` where `x`, `y`, etc. are the names of the expected - arguments, and where e is the body of the function. So here, the + arguments, and where *e* is the body of the function. So here, the entire remainder of the file is the body of the function; when given the required arguments, the body should describe how to build an instance of the Hello package. diff --git a/doc/manual/src/expressions/language-constructs.md b/doc/manual/src/expressions/language-constructs.md index 20d003348..2699d675f 100644 --- a/doc/manual/src/expressions/language-constructs.md +++ b/doc/manual/src/expressions/language-constructs.md @@ -147,7 +147,7 @@ three kinds of patterns: It is possible to provide *default values* for attributes, in which case they are allowed to be missing. A default value is specified by writing `name ? - e`, where e is an arbitrary expression. For example, + e`, where *e* is an arbitrary expression. For example, { x, y ? "foo", z ? "bar" }: z + y + x @@ -201,7 +201,7 @@ Conditionals look like this: if e1 then e2 else e3 -where e1 is an expression that should evaluate to a Boolean value +where *e1* is an expression that should evaluate to a Boolean value (`true` or `false`). ## Assertions @@ -211,9 +211,9 @@ between features and dependencies hold. They look like this: assert e1; e2 -where e1 is an expression that should evaluate to a Boolean value. If it -evaluates to `true`, e2 is returned; otherwise expression evaluation is -aborted and a backtrace is printed. +where *e1* is an expression that should evaluate to a Boolean value. If +it evaluates to `true`, *e2* is returned; otherwise expression +evaluation is aborted and a backtrace is printed. Here is a Nix expression for the Subversion package that shows how assertions can be used:. @@ -275,8 +275,8 @@ A *with-expression*, with e1; e2 -introduces the set e1 into the lexical scope of the expression e2. For -instance, +introduces the set *e1* into the lexical scope of the expression *e2*. +For instance, let as = { x = "foo"; y = "bar"; }; in with as; x + y diff --git a/doc/manual/src/expressions/language-operators.md b/doc/manual/src/expressions/language-operators.md index 4fa2eca37..b124a2417 100644 --- a/doc/manual/src/expressions/language-operators.md +++ b/doc/manual/src/expressions/language-operators.md @@ -4,29 +4,29 @@ expression language, in order of precedence (from strongest to weakest binding). -| Name | Syntax | Associativity | Description | Precedence | -| ------------------------ | ----------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -| Select | e `.` attrpath \[ `or` def \] | none | Select attribute denoted by the attribute path attrpath from set e. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return def if provided, otherwise abort evaluation. | 1 | -| Application | e1 e2 | left | Call function e1 with argument e2. | 2 | -| Arithmetic Negation | `-` e | none | Arithmetic negation. | 3 | -| Has Attribute | e `?` attrpath | none | Test whether set e contains the attribute denoted by attrpath; return `true` or `false`. | 4 | -| List Concatenation | e1 `++` e2 | right | List concatenation. | 5 | -| Multiplication | e1 `*` e2, | left | Arithmetic multiplication. | 6 | -| Division | e1 `/` e2 | left | Arithmetic division. | 6 | -| Addition | e1 `+` e2 | left | Arithmetic addition. | 7 | -| Subtraction | e1 `-` e2 | left | Arithmetic subtraction. | 7 | -| String Concatenation | string1 `+` string2 | left | String concatenation. | 7 | -| Not | `!` e | none | Boolean negation. | 8 | -| Update | e1 `//` e2 | right | Return a set consisting of the attributes in e1 and e2 (with the latter taking precedence over the former in case of equally named attributes). | 9 | -| Less Than | e1 `<` e2, | none | Arithmetic comparison. | 10 | -| Less Than or Equal To | e1 `<=` e2 | none | Arithmetic comparison. | 10 | -| Greater Than | e1 `>` e2 | none | Arithmetic comparison. | 10 | -| Greater Than or Equal To | e1 `>=` e2 | none | Arithmetic comparison. | 10 | -| Equality | e1 `==` e2 | none | Equality. | 11 | -| Inequality | e1 `!=` e2 | none | Inequality. | 11 | -| Logical AND | e1 `&&` e2 | left | Logical AND. | 12 | -| Logical OR | e1 `\|\|` e2 | left | Logical OR. | 13 | -| Logical Implication | e1 `->` e2 | none | Logical implication (equivalent to `!e1 \|\| - e2`). | 14 | +| Name | Syntax | Associativity | Description | Precedence | +| ------------------------ | ----------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | +| Select | *e* `.` *attrpath* \[ `or` *def* \] | none | Select attribute denoted by the attribute path *attrpath* from set *e*. (An attribute path is a dot-separated list of attribute names.) If the attribute doesn’t exist, return *def* if provided, otherwise abort evaluation. | 1 | +| Application | *e1* *e2* | left | Call function *e1* with argument *e2*. | 2 | +| Arithmetic Negation | `-` *e* | none | Arithmetic negation. | 3 | +| Has Attribute | *e* `?` *attrpath* | none | Test whether set *e* contains the attribute denoted by *attrpath*; return `true` or `false`. | 4 | +| List Concatenation | *e1* `++` *e2* | right | List concatenation. | 5 | +| Multiplication | *e1* `*` *e2*, | left | Arithmetic multiplication. | 6 | +| Division | *e1* `/` *e2* | left | Arithmetic division. | 6 | +| Addition | *e1* `+` *e2* | left | Arithmetic addition. | 7 | +| Subtraction | *e1* `-` *e2* | left | Arithmetic subtraction. | 7 | +| String Concatenation | *string1* `+` *string2* | left | String concatenation. | 7 | +| Not | `!` *e* | none | Boolean negation. | 8 | +| Update | *e1* `//` *e2* | right | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes). | 9 | +| Less Than | *e1* `<` *e2*, | none | Arithmetic comparison. | 10 | +| Less Than or Equal To | *e1* `<=` *e2* | none | Arithmetic comparison. | 10 | +| Greater Than | *e1* `>` *e2* | none | Arithmetic comparison. | 10 | +| Greater Than or Equal To | *e1* `>=` *e2* | none | Arithmetic comparison. | 10 | +| Equality | *e1* `==` *e2* | none | Equality. | 11 | +| Inequality | *e1* `!=` *e2* | none | Inequality. | 11 | +| Logical AND | *e1* `&&` *e2* | left | Logical AND. | 12 | +| Logical OR | *e1* `\|\|` *e2* | left | Logical OR. | 13 | +| Logical Implication | *e1* `->` *e2* | none | Logical implication (equivalent to `!e1 \|\| + e2`). | 14 | Operators diff --git a/doc/manual/src/installation/building-source.md b/doc/manual/src/installation/building-source.md index c498713de..35dbd5541 100644 --- a/doc/manual/src/installation/building-source.md +++ b/doc/manual/src/installation/building-source.md @@ -17,7 +17,7 @@ command: The installation path can be specified by passing the `--prefix=prefix` to `configure`. The default installation directory is `/usr/local`. You can change this to any location you like. You must have write permission -to the prefix path. +to the *prefix* path. Nix keeps its *store* (the place where packages are stored) in `/nix/store` by default. This can be changed using diff --git a/doc/manual/src/package-management/basic-package-mgmt.md b/doc/manual/src/package-management/basic-package-mgmt.md index 04dad3339..d9c34afc6 100644 --- a/doc/manual/src/package-management/basic-package-mgmt.md +++ b/doc/manual/src/package-management/basic-package-mgmt.md @@ -60,7 +60,8 @@ Nixpkgs tree using the `-f` flag: $ nix-env -qaf /path/to/nixpkgs -where /path/to/nixpkgs is where you’ve unpacked or checked out Nixpkgs. +where */path/to/nixpkgs* is where you’ve unpacked or checked out +Nixpkgs. You can select specific packages by name: diff --git a/doc/manual/src/release-notes/rl-0.10.md b/doc/manual/src/release-notes/rl-0.10.md index 07b19ff05..1301add26 100644 --- a/doc/manual/src/release-notes/rl-0.10.md +++ b/doc/manual/src/release-notes/rl-0.10.md @@ -34,7 +34,7 @@ - `nix-env -i pkgname` will now install the highest available version of - pkgname, rather than installing all available versions (which + *pkgname*, rather than installing all available versions (which would probably give collisions) (`NIX-31`). - `nix-env (-i|-u) --dry-run` now shows exactly which missing diff --git a/doc/manual/src/release-notes/rl-0.12.md b/doc/manual/src/release-notes/rl-0.12.md index aaecfbb70..3a4aba07d 100644 --- a/doc/manual/src/release-notes/rl-0.12.md +++ b/doc/manual/src/release-notes/rl-0.12.md @@ -41,10 +41,10 @@ - The garbage collector has a number of new options to allow only some of the garbage to be deleted. The option `--max-freed N` tells the - collector to stop after at least N bytes have been deleted. The + collector to stop after at least *N* bytes have been deleted. The option `--max-links N` tells it to stop after the link count on `/nix/store` has dropped - below N. This is useful for very large Nix stores on filesystems + below *N*. This is useful for very large Nix stores on filesystems with a 32000 subdirectories limit (like `ext3`). The option `--use-atime` causes store paths to be deleted in order of ascending last access time. This allows non-recently used stuff to be deleted. diff --git a/doc/manual/src/release-notes/rl-0.13.md b/doc/manual/src/release-notes/rl-0.13.md index 21f33e3db..13a60e01c 100644 --- a/doc/manual/src/release-notes/rl-0.13.md +++ b/doc/manual/src/release-notes/rl-0.13.md @@ -51,5 +51,5 @@ This is primarily a bug fix release. It has some new features: option is used. - The scoping rules for `inherit - (e) ...` in recursive attribute sets have changed. The expression e - can now refer to the attributes defined in the containing set. + (e) ...` in recursive attribute sets have changed. The expression + *e* can now refer to the attributes defined in the containing set. diff --git a/doc/manual/src/release-notes/rl-0.16.md b/doc/manual/src/release-notes/rl-0.16.md index 79074fcdc..23ac53786 100644 --- a/doc/manual/src/release-notes/rl-0.16.md +++ b/doc/manual/src/release-notes/rl-0.16.md @@ -15,7 +15,7 @@ This release has the following improvements: `--cores N` as well as a configuration setting `build-cores = N` that causes the environment variable `NIX_BUILD_CORES` to be set - to N when the builder is invoked. The builder can use this at its + to *N* when the builder is invoked. The builder can use this at its discretion to perform a parallel build, e.g., by calling `make -j N`. In Nixpkgs, this can be enabled on a per-package basis by setting the derivation attribute `enableParallelBuilding` to `true`. diff --git a/doc/manual/src/release-notes/rl-0.6.md b/doc/manual/src/release-notes/rl-0.6.md index c816c9851..ed2d21583 100644 --- a/doc/manual/src/release-notes/rl-0.6.md +++ b/doc/manual/src/release-notes/rl-0.6.md @@ -49,8 +49,8 @@ - New language construct: `with E1; - E2` brings all attributes defined in the attribute set E1 in - scope in E2. + E2` brings all attributes defined in the attribute set *E1* in + scope in *E2*. - Added a `map` function. diff --git a/doc/manual/src/release-notes/rl-1.11.md b/doc/manual/src/release-notes/rl-1.11.md index 381887bd8..fbabdaa2f 100644 --- a/doc/manual/src/release-notes/rl-1.11.md +++ b/doc/manual/src/release-notes/rl-1.11.md @@ -35,7 +35,7 @@ features: derivations, and in `builtins.hashString`. - The new flag `--option build-repeat - N` will cause every build to be executed N+1 times. If the build + N` will cause every build to be executed *N*+1 times. If the build output differs between any round, the build is rejected, and the output paths are not registered as valid. This is primarily useful to verify build determinism. (We already had a `--check` option to diff --git a/doc/manual/src/release-notes/rl-1.4.md b/doc/manual/src/release-notes/rl-1.4.md index d6d2227f8..d23de71ad 100644 --- a/doc/manual/src/release-notes/rl-1.4.md +++ b/doc/manual/src/release-notes/rl-1.4.md @@ -10,7 +10,7 @@ There are also the following improvements: - New built-in function: `builtins.hashString`. - - Build logs are now stored in `/nix/var/log/nix/drvs/XX/`, where XX + - Build logs are now stored in `/nix/var/log/nix/drvs/XX/`, where *XX* is the first two characters of the derivation. This is useful on machines that keep a lot of build logs (such as Hydra servers). diff --git a/doc/manual/src/release-notes/rl-1.6.1.md b/doc/manual/src/release-notes/rl-1.6.1.md index ed974fe0b..9bb9bb1f8 100644 --- a/doc/manual/src/release-notes/rl-1.6.1.md +++ b/doc/manual/src/release-notes/rl-1.6.1.md @@ -6,8 +6,8 @@ This is primarily a bug fix release. Changes of interest are: strings, such as `"${/foo}/bar"`. This release reverts to the Nix 1.5.3 behaviour. - - Previously, Nix optimised expressions such as `"${expr}"` to expr. - Thus it neither checked whether expr could be coerced to a string, + - Previously, Nix optimised expressions such as `"${expr}"` to *expr*. + Thus it neither checked whether *expr* could be coerced to a string, nor applied such coercions. This meant that `"${123}"` evaluatued to `123`, and `"${./foo}"` evaluated to `./foo` (even though `"${./foo} "` evaluates to `"/nix/store/hash-foo "`). Nix now checks the type diff --git a/doc/manual/src/release-notes/rl-1.7.md b/doc/manual/src/release-notes/rl-1.7.md index 71a327ed6..8d49ae54e 100644 --- a/doc/manual/src/release-notes/rl-1.7.md +++ b/doc/manual/src/release-notes/rl-1.7.md @@ -89,10 +89,10 @@ features: specifier. For example, `nix-store --gc --max-freed 1G` will free up to 1 gigabyte of disk space. - - `nix-collect-garbage` has a new flag `--delete-older-than` N`d`, - which deletes all user environment generations older than N days. + - `nix-collect-garbage` has a new flag `--delete-older-than` *N*`d`, + which deletes all user environment generations older than *N* days. Likewise, `nix-env - --delete-generations` accepts a N`d` age limit. + --delete-generations` accepts a *N*`d` age limit. - Nix now heuristically detects whether a build failure was due to a disk-full condition. In that case, the build is not flagged as