Built-in Functions
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.
derivation attrs;builtins.derivation attrsderivation is described in its own section.
abort s-
Abort Nix expression evaluation and print the error message s.
add e1 e2-
Return the sum of the numbers e1 and e2.
all pred list-
Return
trueif the function pred returnstruefor all elements of list, andfalseotherwise. any pred list-
Return
trueif the function pred returnstruefor at least one element of list, andfalseotherwise. 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" ]. 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
basenamecommand. bitAnd e1 e2-
Return the bitwise AND of the integers e1 and e2.
bitOr e1 e2-
Return the bitwise OR of the integers e1 and e2.
bitXor e1 e2-
Return the bitwise XOR of the integers e1 and e2.
catAttrs attr list-
Collect each attribute named attr from a list of attribute sets. Attrsets that don't contain the named attribute are ignored. For example,
builtins.catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]evaluates to
[1 2]. ceil double-
Converts an IEEE-754 double-precision floating-point number (double) to the next higher integer.
If the datatype is neither an integer nor a "float", an evaluation error will be thrown.
compareVersions s1 s2-
Compare two strings representing versions and return
-1if version s1 is older than version s2,0if they are the same, and1if s1 is newer than s2. The version comparison algorithm is the same as the one used bynix-env -u. concatLists lists-
Concatenate a list of lists into a single list.
concatMap f list-
This function is equivalent to
builtins.concatLists (map f list)but is more efficient. concatStringsSep separator list-
Concatenate a list of strings with a separator between each element, e.g.
concatStringsSep "/" ["usr" "local" "bin"] == "usr/local/bin". 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. 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
dirnamecommand. div e1 e2-
Return the quotient of the numbers e1 and e2.
elem x xs-
Return
trueif a value equal to x occurs in the list xs, andfalseotherwise. 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.
fetchClosure args-
Fetch a Nix store closure from a binary cache, rewriting it into content-addressed form. For example,
builtins.fetchClosure { fromStore = "https://cache.nixos.org"; fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1; toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1; }fetches
/nix/store/r2jd...from the specified binary cache, and rewrites it into the content-addressed store path/nix/store/ldbh....If
fromPathis already content-addressed, or if you are allowing impure evaluation (--impure), thentoPathmay be omitted.To find out the correct value for
toPathgiven afromPath, you can usenix store make-content-addressed:# nix store make-content-addressed --from https://cache.nixos.org /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1 rewrote '/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1' to '/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1'This function is similar to
builtins.storePathin that it allows you to use a previously built store path in a Nix expression. However, it is more reproducible because it requires specifying a binary cache from which the path can be fetched. Also, requiring a content-addressed final store path avoids the need for users to configure binary cache public keys.This function is only available if you enable the experimental feature
fetch-closure. 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
urloptional):-
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 ofref. -
ref
The git ref to look for the requested revision under. This is often a branch or tag name. Defaults toHEAD.By default, the
refvalue is prefixed withrefs/heads/. As of Nix 2.3.0 Nix will not prefixrefs/heads/ifrefstarts withrefs/. -
submodules
A Boolean parameter that specifies whether submodules should be checked out. Defaults tofalse. -
allRefs
Whether to fetch all refs of the repository. With this argument being true, it's possible to load arevfrom anyref(by default onlyrevs from the specifiedrefare supported).
Here are some examples of how to use
fetchGit.-
To fetch a private repository over SSH:
builtins.fetchGit { url = "git@github.com:my-secret/repository.git"; ref = "master"; rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; } -
To fetch an arbitrary reference:
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
refattribute.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
refattribute as well.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
refattribute.builtins.fetchGit { url = "https://github.com/nixos/nix.git"; rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; } -
To fetch a specific tag:
builtins.fetchGit { url = "https://github.com/nixos/nix.git"; ref = "refs/tags/1.9"; } -
To fetch the latest version of a remote branch:
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.
-
fetchTarball args-
Download the specified URL, unpack it and return the path of the unpacked tree. The file must be a tape archive (
.tar) compressed withgzip,bzip2orxz. 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.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--tarball-ttlnumber-of-seconds or in the Nix configuration file by adding the linetarball-ttl =number-of-seconds.Note that when obtaining the hash with
nix-prefetch-urlthe option--unpackis 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
urland the attributesha256, e.g.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 is enabled.
fetchurl url-
Download the specified URL and return the path of the downloaded file. This function is not available if restricted evaluation mode is enabled.
filter f list-
Return a list consisting of the elements of list for which the function f returns
true. filterSource e1 e2-
Warning
filterSourceshould not be used to filter store paths. SincefilterSourceuses the name of the input directory while naming the output directory, doing so will produce a directory name in the form of<hash2>-<hash>-<name>, where<hash>-<name>is the name of the input directory. Since<hash>depends on the unfiltered directory, the name of the output directory will indirectly depend on files that are filtered out by the function. This will trigger a rebuild even when a filtered out file is changed. Usebuiltins.pathinstead, which allows specifying the name of the output directory.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-diras an input to a Nix expression, e.g.stdenv.mkDerivation { ... src = ./source-dir; }However, if
source-diris a Subversion working copy, then all those annoying.svnsubdirectories will also be copied to the store. Worse, the contents of those directories may change a lot, causing lots of spurious rebuilds. WithfilterSourceyou can filter out the.svndirectories: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 returnstruefor them, the copy will fail). If you exclude a directory, the entire corresponding subtree of e2 will be excluded. floor double-
Converts an IEEE-754 double-precision floating-point number (double) to the next lower integer.
If the datatype is neither an integer nor a "float", an evaluation error will be thrown.
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. fromJSON e-
Convert a JSON string to a Nix value. For example,
builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''returns the value
{ x = [ 1 2 3 ]; y = null; }. 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: ...) = { }. 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) 5returns the list
[ 0 1 4 9 16 ]. genericClosure attrset-
Take an attrset with values named
startSetandoperatorin order to return a list of attrsets by starting with thestartSet, recursively applying theoperatorfunction to each element. The attrsets in thestartSetand produced by theoperatormust each contain value namedkeywhich are comparable to each other. The result is produced by repeatedly calling the operator for each element encountered with a unique key, terminating when no new elements are produced. For example,builtins.genericClosure { startSet = [ {key = 5;} ]; operator = item: [{ key = if (item.key / 2 ) * 2 == item.key then item.key / 2 else 3 * item.key + 1; }]; }evaluates to
[ { key = 5; } { key = 16; } { key = 8; } { key = 4; } { key = 2; } { key = 1; } ] getAttr s set-
getAttrreturns 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. getEnv s-
getEnvreturns 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.getEnvis used in Nix Packages to locate the file~/.nixpkgs/config.nix, which contains user-local settings for Nix Packages. (That is, it does agetEnv "HOME"to locate the user’s home directory.) getFlake args-
Fetch a flake from a flake reference, and return its output attributes and some metadata. For example:
(builtins.getFlake "nix/55bc52401966fbffa525c574c14f67b00bc4fb3a").packages.x86_64-linux.nixUnless impure evaluation is allowed (
--impure), the flake reference must be "locked", e.g. contain a Git revision or content hash. An example of an unlocked usage is:(builtins.getFlake "github:edolstra/dwarffs").revThis function is only available if you enable the experimental feature
flakes. groupBy f list-
Groups elements of list together by the string returned from the function f called on each element. It returns an attribute set where each attribute value contains the elements of list that are mapped to the same corresponding attribute name returned by f.
For example,
builtins.groupBy (builtins.substring 0 1) ["foo" "bar" "baz"]evaluates to
{ b = [ "bar" "baz" ]; f = [ "foo" ]; } hasAttr s set-
hasAttrreturnstrueif set has an attribute named s, andfalseotherwise. This is a dynamic version of the?operator, since s is an expression rather than an identifier. 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". 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". 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-
Load, parse and return the Nix expression in the file path. If path is a directory, the file
default.nixin that directory is loaded. Evaluation aborts if the file doesn’t exist or contains an incorrect Nix expression.importimplements Nix’s module 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,
importis a regular function in Nix. Paths using the angle bracket syntax (e.g.,import<foo>) are normal path values.A Nix expression loaded by
importmust 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 expressionrec { x = 123; y = import ./foo.nix; }then the following
foo.nixwill give an error:x + 456since
xis not in scope infoo.nix. If you wantxto be available infoo.nix, you should pass it as a function argument:rec { x = 123; y = import ./foo.nix x; }and
x: x + 456(The function argument doesn’t have to be called
xinfoo.nix; any name would work.) intersectAttrs e1 e2-
Return a set consisting of the attributes in the set e2 that also exist in the set e1.
isAttrs e-
Return
trueif e evaluates to a set, andfalseotherwise. isBool e-
Return
trueif e evaluates to a bool, andfalseotherwise. isFloat e-
Return
trueif e evaluates to a float, andfalseotherwise. isFunction e-
Return
trueif e evaluates to a function, andfalseotherwise. isInt e-
Return
trueif e evaluates to an integer, andfalseotherwise. isList e-
Return
trueif e evaluates to a list, andfalseotherwise. isNull e-
Return
trueif e evaluates tonull, andfalseotherwise.Warning
This function is deprecated; just write
e == nullinstead. isPath e-
Return
trueif e evaluates to a path, andfalseotherwise. isString e-
Return
trueif e evaluates to a string, andfalseotherwise. length e-
Return the length of the list e.
lessThan e1 e2-
Return
trueif the number e1 is less than the number e2, andfalseotherwise. Evaluation aborts if either e1 or e2 does not evaluate to a number. 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
namespecifying the name of the attribute, and an attributevaluespecifying its value. Example:builtins.listToAttrs [ { name = "foo"; value = 123; } { name = "bar"; value = 456; } ]evaluates to
{ foo = 123; bar = 456; } 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" ]. mapAttrs f attrset-
Apply function f to every element of attrset. For example,
builtins.mapAttrs (name: value: value * 10) { a = 1; b = 2; }evaluates to
{ a = 10; b = 20; }. match regex str-
Returns a list if the extended POSIX regular expression regex matches str precisely, otherwise returns
null. Each item in the list is a regex group.builtins.match "ab" "abc"Evaluates to
null.builtins.match "abc" "abc"Evaluates to
[ ].builtins.match "a(b)(c)" "abc"Evaluates to
[ "b" "c" ].builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO "Evaluates to
[ "foo" ]. mul e1 e2-
Return the product of the numbers e1 and e2.
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"; }. partition pred list-
Given a predicate function pred, this function returns an attrset containing a list named
right, containing the elements in list for which pred returnedtrue, and a list namedwrong, containing the elements for which it returnedfalse. For example,builtins.partition (x: x > 10) [1 23 9 3 42]evaluates to
{ right = [ 23 42 ]; wrong = [ 1 9 3 ]; } 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 bybuiltins.filterSource, with the same semantics. -
recursive
Whenfalse, whenpathis added to the store it is with a flat hash, rather than a hash of the NAR serialization of the file. Thus,pathmust refer to a regular file, not a directory. This allows similar behavior tofetchurl. Defaults totrue. -
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 allowsbuiltins.pathto be used even when thepure-evalnix config option is on.
-
pathExists path-
Return
trueif the path path exists at evaluation time, andfalseotherwise. 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". readDir path-
Return the contents of the directory path as a set mapping directory entries to the corresponding file type. For instance, if directory
Acontains a regular fileBand another directoryC, thenbuiltins.readDir ./Awill return the set{ B = "regular"; C = "directory"; }The possible values for the file type are
"regular","directory","symlink"and"unknown". readFile path-
Return the contents of the file path as a string.
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; }. 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". seq e1 e2-
Evaluate e1, then evaluate and return e2. This ensures that a computation is strict in the value of e1.
sort comparator list-
Return list in sorted order. It repeatedly calls the function comparator with two elements. The comparator should return
trueif the first element is less than the second, andfalseotherwise. For example,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.
split 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 sequences is a regex group.
builtins.split "(a)b" "abc"Evaluates to
[ "" [ "a" ] "c" ].builtins.split "([ac])" "abc"Evaluates to
[ "" [ "a" ] "b" [ "c" ] "" ].builtins.split "(a)|(c)" "abc"Evaluates to
[ "" [ "a" null ] "b" [ null "c" ] "" ].builtins.split "([[:upper:]]+)" " FOO "Evaluates to
[ " " [ "FOO" ] " " ]. 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. storePath path-
This function allows you to define a dependency on an already existing store path. For example, the derivation attribute
src = builtins.storePath /nix/store/f1d18v1y…-sourcecauses the derivation to depend on the specified path, which must exist or be substitutable. Note that this differs from a plain path (e.g.src = /nix/store/f1d18v1y…-source) in that the latter causes the path to be copied again to the Nix store, resulting in a new path (e.g./nix/store/ld01dnzc…-source-source).This function is not available in pure evaluation mode.
stringLength e-
Return the length of the string e. If e is not a string, evaluation is aborted.
sub e1 e2-
Return the difference between the numbers e1 and e2.
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". 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.
Warning
This function should generally be avoided since it's inefficient: unlike Haskell's
tail, it takes O(n) time, so recursing over a list by repeatedly callingtailtakes O(n^2) time. throw s-
Throw an error message s. This usually aborts Nix expression evaluation, but in
nix-env -qaand 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 forabort). 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 and its build script into one file:
{ 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.,
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, so the result of the expressionconfigFile(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:
let foo = builtins.toFile "foo" "...${bar}..."; bar = builtins.toFile "bar" "...${foo}..."; in fooThis is not allowed because it would cause a cyclic dependency in the computation of the cryptographic hashes for
fooandbar.It is also not possible to reference the result of a derivation. If you are using Nixpkgs, the
writeTextFilefunction is able to do that. 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.
toPath s-
DEPRECATED. Use
/. + "/path"to convert a string into an absolute path. For relative paths, use./. + "/path". 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/baryields"/foo/bar". -
A set containing
{ __toString = self: ...; }or{ outPath = ...; }. -
An integer.
-
A list, in which case the string representations of its elements are joined with spaces.
-
A Boolean (
falseyields"",trueyields"1"). -
null, which yields the empty string.
-
toXML e-
Return a string containing an XML representation of e. The main application for
toXMLis to communicate information with the builder in a more structured format than plain environment variables.Here is an example where this is the case:
{ 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. A servlet container contains a number of servlets (
*.warfiles) each exported under a specific URI prefix. So the servlet configuration is a list of sets containing thepathandwarof 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 withtoXML, 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 ③ bytoXMLis as follows:<?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
toFilebuilt-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 syntaxxsltproc ${stylesheet}. trace e1 e2-
Evaluate e1 and print its abstract syntax representation on standard error. Then return e2. This function is useful for debugging.
tryEval e-
Try to shallowly evaluate e. Return a set containing the attributes
success(trueif e evaluated successfully,falseif an error was thrown) andvalue, equalling e if successful andfalseotherwise.tryEvalwill only prevent errors created bythroworassertfrom being thrown. ErrorstryEvalwill not catch are for example those created byabortand type errors generated by builtins. Also note that this doesn't evaluate e deeply, solet e = { x = throw ""; }; in (builtins.tryEval e).successwill betrue. Usingbuiltins.deepSeqone can get the expected result:let e = { x = throw ""; }; in (builtins.tryEval (builtins.deepSeq e e)).successwill befalse. typeOf e-
Return a string representing the type of the value e, namely
"int","bool","string","path","null","set","list","lambda"or"float". zipAttrsWith f list-
Transpose a list of attribute sets into an attribute set of lists, then apply
mapAttrs.freceives two arguments: the attribute name and a non-empty list of all values encountered for that attribute name.The result is an attribute set where the attribute names are the union of the attribute names in each element of
list. The attribute values are the return values off.builtins.zipAttrsWith (name: values: { inherit name values; }) [ { a = "x"; } { a = "y"; b = "z"; } ]evaluates to
{ a = { name = "a"; values = [ "x" "y" ]; }; b = { name = "b"; values = [ "z" ]; }; }