diff options
author | Eelco Dolstra <edolstra@gmail.com> | 2020-08-24 14:31:10 +0200 |
---|---|---|
committer | Eelco Dolstra <edolstra@gmail.com> | 2020-08-24 14:31:10 +0200 |
commit | a990f063ff7afc6028ab430170ad23e1285d1a6d (patch) | |
tree | fe58e282a6a402c95ce2d023c2fa884915ecf287 /doc | |
parent | 33b1679d75f2a3a5dac053431a41897ebf96a3f3 (diff) |
Move primop docs inline
This makes them available to 'nix repl'.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/manual/src/SUMMARY.md | 1 | ||||
-rw-r--r-- | doc/manual/src/expressions/builtin-constants.md | 20 | ||||
-rw-r--r-- | doc/manual/src/expressions/builtins.md | 878 |
3 files changed, 39 insertions, 860 deletions
diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md index 4089caf8a..8281f683f 100644 --- a/doc/manual/src/SUMMARY.md +++ b/doc/manual/src/SUMMARY.md @@ -38,6 +38,7 @@ - [Operators](expressions/language-operators.md) - [Derivations](expressions/derivations.md) - [Advanced Attributes](expressions/advanced-attributes.md) + - [Built-in Constants](expressions/builtin-constants.md) - [Built-in Functions](expressions/builtins.md) - [Advanced Topics](advanced-topics/advanced-topics.md) - [Remote Builds](advanced-topics/distributed-builds.md) diff --git a/doc/manual/src/expressions/builtin-constants.md b/doc/manual/src/expressions/builtin-constants.md new file mode 100644 index 000000000..3345a715b --- /dev/null +++ b/doc/manual/src/expressions/builtin-constants.md @@ -0,0 +1,20 @@ +# Built-in Constants + +Here are the constants built into the Nix expression evaluator: + + - `builtins` + The set `builtins` contains all the built-in functions and values. + You can use `builtins` to test for the availability of features in + the Nix installation, e.g., + + ```nix + if builtins ? getEnv then builtins.getEnv "PATH" else "" + ``` + + This allows a Nix expression to fall back gracefully on older Nix + installations that don’t have the desired built-in function. + + - `builtins.currentSystem` + The built-in value `currentSystem` evaluates to the Nix platform + identifier for the Nix installation on which the expression is being + evaluated, such as `"i686-linux"` or `"x86_64-darwin"`. diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md index c258fb3b3..ae3bb150c 100644 --- a/doc/manual/src/expressions/builtins.md +++ b/doc/manual/src/expressions/builtins.md @@ -1,374 +1,20 @@ # Built-in Functions -This section lists the functions and constants built into the Nix -expression evaluator. (The built-in function `derivation` is discussed -above.) Some built-ins, such as `derivation`, are always in scope of -every Nix expression; you can just access them right away. But to -prevent polluting the namespace too much, most built-ins are not in +This section lists the functions built into the Nix expression +evaluator. (The built-in function `derivation` is discussed above.) +Some built-ins, such as `derivation`, are always in scope of every Nix +expression; you can just access them right away. But to prevent +polluting the namespace too much, most built-ins are not in 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`. - - `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.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 - 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 - corresponding to the sorted attribute names. - - - `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.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` - The set `builtins` contains all the built-in functions and values. - You can use `builtins` to test for the availability of features in - the Nix installation, e.g., - - ```nix - if builtins ? getEnv then builtins.getEnv "PATH" else "" - ``` - - 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* - 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 - -u`](../command-ref/nix-env.md#operation---upgrade). - - - `builtins.concatLists` *lists* - Concatenate a list of lists into a single 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"` - - - `builtins.currentSystem` - The built-in value `currentSystem` evaluates to the Nix platform - identifier for the Nix installation on which the expression is being - evaluated, such as `"i686-linux"` or `"x86_64-darwin"`. - - - `builtins.deepSeq` *e1* *e2* - This is like `seq e1 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` is described in [its own section](derivations.md). - - - `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.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 - from 0. A fatal error occurs if the index is out of bounds. - - - `builtins.fetchurl` *url* - Download the specified URL and return the path of the downloaded - file. This function is not available if [restricted evaluation - mode](../command-ref/conf-file.md) is enabled. - - - `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 - files in the tarball is removed, so it is best if the tarball - contains a single directory at top level. The typical use of the - function is to obtain external Nix expression dependencies, such as - a particular version of Nixpkgs, e.g. - - ```nix - with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {}; - - 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 `--option tarball-ttl number - of seconds` or in the Nix configuration file with this option: ` - number of seconds to cache `. - - Note that when obtaining the hash with ` nix-prefetch-url ` the - option `--unpack` is required. - - This function can also verify the contents against a hash. In that - case, the function takes a set instead of a URL. The set requires - the attribute `url` and the attribute `sha256`, e.g. - - ```nix - with import (fetchTarball { - url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz"; - sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2"; - }) {}; - - stdenv.mkDerivation { … } - ``` - - This function is not available if [restricted evaluation - mode](../command-ref/conf-file.md) 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): - - - url - The URL of the repo. - - - name - The name of the directory the repo should be exported to in the - store. Defaults to the basename of the URL. - - - rev - The git revision to fetch. Defaults to the tip of `ref`. - - - ref - The git ref to look for the requested revision under. This is - often a branch or tag name. Defaults to `HEAD`. - - By default, the `ref` value is prefixed with `refs/heads/`. As - of Nix 2.3.0 Nix will not prefix `refs/heads/` if `ref` starts - with `refs/`. - - - submodules - A Boolean parameter that specifies whether submodules should be - checked out. Defaults to `false`. - - Here are some examples of how to use `fetchGit`. - - - To fetch a private repository over SSH: - - ```nix - builtins.fetchGit { - url = "git@github.com:my-secret/repository.git"; - ref = "master"; - rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; - } - ``` - - - To fetch an arbitrary reference: - - ```nix - builtins.fetchGit { - url = "https://github.com/NixOS/nix.git"; - ref = "refs/heads/0.5-release"; - } - ``` - - - If the revision you're looking for is in the default branch of - the git repository you don't strictly need to specify the branch - name in the `ref` attribute. - - However, if the revision you're looking for is in a future - branch for the non-default branch you will need to specify the - the `ref` attribute as well. - - ```nix - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; - ref = "1.11-maintenance"; - } - ``` - - > **Note** - > - > It is nice to always specify the branch which a revision - > belongs to. Without the branch being specified, the fetcher - > might fail if the default branch changes. Additionally, it can - > be confusing to try a commit from a non-default branch and see - > the fetch fail. If the branch is specified the fault is much - > more obvious. - - - If the revision you're looking for is in the default branch of - the git repository you may omit the `ref` attribute. - - ```nix - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; - } - ``` - - - To fetch a specific tag: - - ```nix - builtins.fetchGit { - url = "https://github.com/nixos/nix.git"; - ref = "refs/tags/1.9"; - } - ``` - - - To fetch the latest version of a remote branch: - - ```nix - builtins.fetchGit { - url = "ssh://git@github.com/nixos/nix.git"; - ref = "master"; - } - ``` - - > **Note** - > - > Nix will refetch the branch in accordance with - > the option `tarball-ttl`. - - > **Note** - > - > 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.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. - - ```nix - stdenv.mkDerivation { - ... - src = ./source-dir; - } - ``` - - However, if `source-dir` is a Subversion working copy, then all - those annoying `.svn` subdirectories will also be copied to the - store. Worse, the contents of those directories may change a lot, - causing lots of spurious rebuilds. With `filterSource` you can - filter out the `.svn` directories: - - ```nix - src = builtins.filterSource - (path: type: type != "directory" || baseNameOf path != ".svn") - ./source-dir; - ``` - - 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 - 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 - `"regular"`, `"directory"`, `"symlink"` or `"unknown"` (for other - 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. - - - `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* - 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 - instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y = - true; }`. - - "Formal argument" here refers to the attributes pattern-matched by - the function. Plain lambdas are not included, e.g. `functionArgs (x: - ...) = { }`. - - - `builtins.fromJSON` *e* - Convert a JSON string to a Nix value. For example, - - ```nix - builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' - ``` - - 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, - - ```nix - 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.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. - - `getEnv` is used in Nix Packages to locate the file - `~/.nixpkgs/config.nix`, which contains user-local settings for Nix - 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 - `false` otherwise. This is a dynamic version of the `?` operator, - since *s* is an expression rather than an identifier. - - - `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"`, - `"sha1"`, `"sha256"` or `"sha512"`. - - - `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"`. - - - `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 `[]`. + `derivation` is described in [its own section](derivations.md). - `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 @@ -376,535 +22,47 @@ For instance, `derivation` is also available as `builtins.derivation`. system: you can put any Nix expression (such as a set or a function) in a separate file, and use it from Nix expressions in other files. - + > **Note** - > + > > Unlike some languages, `import` is a regular function in Nix. > Paths using the angle bracket syntax (e.g., `import` *\<foo\>*) > are [normal path values](language-values.md). - + A Nix expression loaded by `import` must not contain any *free variables* (identifiers that are not defined in the Nix expression itself and are not built-in). Therefore, it cannot refer to variables that are in scope at the call site. For instance, if you have a calling expression - + ```nix rec { x = 123; y = import ./foo.nix; } ``` - + then the following `foo.nix` will give an error: - + ```nix x + 456 ``` - + since `x` is not in scope in `foo.nix`. If you want `x` to be available in `foo.nix`, you should pass it as a function argument: - + ```nix rec { x = 123; y = import ./foo.nix x; } ``` - + and - + ```nix x: x + 456 ``` - + (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.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.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.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.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. - - - `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.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* - 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, - and an attribute `value` specifying its value. Example: - - ```nix - builtins.listToAttrs - [ { name = "foo"; value = 123; } - { name = "bar"; value = 456; } - ] - ``` - - evaluates to - - ```nix - { foo = 123; bar = 456; } - ``` - - - `map` *f* *list*; `builtins.map` *f* *list* - Apply the function *f* to each element in the list *list*. For - example, - - ```nix - map (x: "foo" + x) [ "bar" "bla" "abc" ] - ``` - - evaluates to `[ "foobar" "foobla" "fooabc" ]`. - - - `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. - - ```nix - builtins.match "ab" "abc" - ``` - - Evaluates to `null`. - - ```nix - builtins.match "abc" "abc" - ``` - - Evaluates to `[ ]`. - - ```nix - builtins.match "a(b)(c)" "abc" - ``` - - Evaluates to `[ "b" "c" ]`. - - ```nix - builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO " - ``` - - Evaluates to `[ "foo" ]`. - - - `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 "nix-0.12pre12876"` returns `{ name = - "nix"; version = "0.12pre12876"; }`. - - - `builtins.path` *args* - An enrichment of the built-in path type, based on the attributes - present in *args*. All are optional except `path`: - - - path - The underlying path. - - - name - The name of the path when added to the store. This can used to - reference paths that have nix-illegal characters in their names, - like `@`. - - - filter - A function of the type expected by `builtins.filterSource`, - with the same semantics. - - - recursive - When `false`, when `path` is added to the store it is with a - flat hash, rather than a hash of the NAR serialization of the - file. Thus, `path` must refer to a regular file, not a - directory. This allows similar behavior to `fetchurl`. Defaults - to `true`. - - - sha256 - When provided, this is the expected hash of the file at the - path. Evaluation will fail if the hash is incorrect, and - 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 - `false` otherwise. - - - `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 ./A` will return the set - - ```nix - { B = "regular"; C = "directory"; } - ``` - - 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. - - - `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, - - ```nix - 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, - - ```nix - 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.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, - - ```nix - builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] - ``` - - produces the list `[ 42 77 147 249 483 526 ]`. - - This is a stable sort: it preserves the relative order of elements - deemed equal by the comparator. - - - `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. - - ```nix - builtins.split "(a)b" "abc" - ``` - - Evaluates to `[ "" [ "a" ] "c" ]`. - - ```nix - builtins.split "([ac])" "abc" - ``` - - Evaluates to `[ "" [ "a" ] "b" [ "c" ] "" ]`. - - ```nix - builtins.split "(a)|(c)" "abc" - ``` - - Evaluates to `[ "" [ "a" null ] "b" [ null "c" ] "" ]`. - - ```nix - builtins.split "([[:upper:]]+)" " FOO " - ``` - - Evaluates to `[ " " [ "FOO" ] " " ]`. - - - `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`](../command-ref/nix-env.md#operation---upgrade). - - - `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.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, - - ```nix - builtins.substring 0 3 "nixos" - ``` - - evaluates to `"nix"`. - - - `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 - 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 derivations. One application is to write builders - “inline”. For instance, the following Nix expression combines the - [Nix expression for GNU Hello](expression-syntax.md) and its - [build script](build-script.md) into one file: - - ```nix - { stdenv, fetchurl, perl }: - - stdenv.mkDerivation { - name = "hello-2.1.1"; - - builder = builtins.toFile "builder.sh" " - source $stdenv/setup - - PATH=$perl/bin:$PATH - - tar xvfz $src - cd hello-* - ./configure --prefix=$out - make - make install - "; - - src = fetchurl { - url = "http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; - sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; - }; - inherit perl; - } - ``` - - It is even possible for one file to refer to another, e.g., - - ```nix - builder = let - configFile = builtins.toFile "foo.conf" " - # This is some dummy configuration file. - ... - "; - in builtins.toFile "builder.sh" " - source $stdenv/setup - ... - cp ${configFile} $out/etc/foo.conf - "; - ``` - - Note that `${configFile}` is an - [antiquotation](language-values.md), so the result of the - expression `configFile` - (i.e., a path like `/nix/store/m7p7jfny445k...-foo.conf`) will be - spliced into the resulting string. - - It is however *not* allowed to have files mutually referring to each - other, like so: - - ```nix - let - foo = builtins.toFile "foo" "...${bar}..."; - bar = builtins.toFile "bar" "...${foo}..."; - in foo - ``` - - This is not allowed because it would cause a cyclic dependency in - the computation of the cryptographic hashes for `foo` and `bar`. - - It is also not possible to reference the result of a derivation. If - 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, - 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* - 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: - - - A string (in which case the string is returned unmodified). - - - A path (e.g., `toString /foo/bar` yields `"/foo/bar"`. - - - A set containing `{ __toString = self: ...; }`. - - - An integer. - - - A list, in which case the string representations of its elements - are joined with spaces. - - - A Boolean (`false` yields `""`, `true` yields `"1"`). - - - `null`, which yields the empty string. - - - `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. - - Here is an example where this is the case: - - ```nix - { stdenv, fetchurl, libxslt, jira, uberwiki }: - - stdenv.mkDerivation (rec { - name = "web-server"; - - buildInputs = [ libxslt ]; - - builder = builtins.toFile "builder.sh" " - source $stdenv/setup - mkdir $out - echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml ① - "; - - stylesheet = builtins.toFile "stylesheet.xsl" ② - "<?xml version='1.0' encoding='UTF-8'?> - <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'> - <xsl:template match='/'> - <Configure> - <xsl:for-each select='/expr/list/attrs'> - <Call name='addWebApplication'> - <Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg> - <Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg> - </Call> - </xsl:for-each> - </Configure> - </xsl:template> - </xsl:stylesheet> - "; - - servlets = builtins.toXML [ ③ - { path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; } - { path = "/wiki"; war = uberwiki + "/uberwiki.war"; } - ]; - }) - ``` - - The builder is supposed to generate the configuration file for a - [Jetty servlet container](http://jetty.mortbay.org/). A servlet - container contains a number of servlets (`*.war` files) each - exported under a specific URI prefix. So the servlet configuration - is a list of sets containing the `path` and `war` of the servlet - (①). This kind of information is difficult to communicate with the - normal method of passing information through an environment - variable, which just concatenates everything together into a - string (which might just work in this case, but wouldn’t work if - fields are optional or contain lists themselves). Instead the Nix - expression is converted to an XML representation with `toXML`, - which is unambiguous and can easily be processed with the - appropriate tools. For instance, in the example an XSLT stylesheet - (at point ②) is applied to it (at point ①) to generate the XML - configuration file for the Jetty server. The XML representation - produced at point ③ by `toXML` is as follows: - - ```xml - <?xml version='1.0' encoding='utf-8'?> - <expr> - <list> - <attrs> - <attr name="path"> - <string value="/bugtracker" /> - </attr> - <attr name="war"> - <path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" /> - </attr> - </attrs> - <attrs> - <attr name="path"> - <string value="/wiki" /> - </attr> - <attr name="war"> - <path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" /> - </attr> - </attrs> - </list> - </expr> - ``` - - Note that we used the `toFile` built-in to write the builder and - the stylesheet “inline” in the Nix expression. The path 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.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 - `"int"`, `"bool"`, `"string"`, `"path"`, `"null"`, `"set"`, - `"list"`, `"lambda"` or `"float"`. |