// Jest Snapshot v1, https://goo.gl/fbAQLP exports[`has not changed builtins data 1`] = ` [ { "category": "builtins", "description": [ "takes 1 arguments: __\`s\`__ ", "Abort Nix expression evaluation and print the error message *s*. ", ], "fn_type": "abort :: String", "id": "builtins.abort", "name": "abort", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return the sum of the numbers *e1* and *e2*. ", ], "fn_type": "add :: Number -> Number -> Number", "id": "builtins.add", "name": "add", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`pred\` \`list\`__ ", "Return \`true\` if the function *pred* returns \`true\` for all elements of *list*, and \`false\` otherwise. ", ], "fn_type": "all :: (a -> Bool) -> [a] -> Bool", "id": "builtins.all", "name": "all", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`pred\` \`list\`__ ", "Return \`true\` if the function *pred* returns \`true\` for at least one element of *list*, and \`false\` otherwise. ", ], "fn_type": null, "id": "builtins.any", "name": "any", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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" ]\`. ", ], "fn_type": "attrNames :: AttrSet -> [a]", "id": "builtins.attrNames", "name": "attrNames", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`set\`__ ", "Return the values of the attributes in the set *set* in the order corresponding to the sorted attribute names. ", ], "fn_type": "attrValues :: AttrSet -> [a]", "id": "builtins.attrValues", "name": "attrValues", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. ", ], "fn_type": "baseNameOf :: String -> String", "id": "builtins.baseNameOf", "name": "baseNameOf", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return the bitwise AND of the integers *e1* and *e2*. ", ], "fn_type": "bitAnd :: Int -> Int -> Int", "id": "builtins.bitAnd", "name": "bitAnd", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return the bitwise OR of the integers *e1* and *e2*. ", ], "fn_type": "bitOr :: Int -> Int -> Int", "id": "builtins.bitOr", "name": "bitOr", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return the bitwise XOR of the integers *e1* and *e2*. ", ], "fn_type": "bitXor :: Int -> Int -> Int", "id": "builtins.bitXor", "name": "bitXor", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`v\`__ ", "In debug mode (enabled using \`--debugger\`), pause Nix expression evaluation and enter the REPL. Otherwise, return the argument \`v\`. ", ], "fn_type": "break :: a -> a", "id": "builtins.break", "name": "break", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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, \`\`\`nix builtins.catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}] \`\`\` evaluates to \`[1 2]\`. ", ], "fn_type": "cattAtrs :: String -> [ { \${name} :: a } ] -> [a]", "id": "builtins.catAttrs", "name": "catAttrs", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. ", ], "fn_type": "ceil :: Float -> Int", "id": "builtins.ceil", "name": "ceil", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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). ", ], "fn_type": "compareVersions :: String -> String -> Int", "id": "builtins.compareVersions", "name": "compareVersions", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`lists\`__ ", "Concatenate a list of lists into a single list. ", ], "fn_type": "concatLists :: [List] -> []", "id": "builtins.concatLists", "name": "concatLists", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`f\` \`list\`__ ", "This function is equivalent to \`builtins.concatLists (map f list)\` but is more efficient. ", ], "fn_type": "concatMap :: (a -> b) -> [a] -> [b]", "id": "builtins.concatMap", "name": "concatMap", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`separator\` \`list\`__ ", "Concatenate a list of strings with a separator between each element, e.g. \`concatStringsSep "/" ["usr" "local" "bin"] == "usr/local/bin"\`. ", ], "fn_type": "concatStringsSep :: String -> [String] -> String", "id": "builtins.concatStringsSep", "name": "concatStringsSep", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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. ", ], "fn_type": "deepSeq :: a -> b -> b", "id": "builtins.deepSeq", "name": "deepSeq", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. ", ], "fn_type": "dirOf :: String -> String", "id": "builtins.dirOf", "name": "dirOf", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return the quotient of the numbers *e1* and *e2*. ", ], "fn_type": "div :: Number -> Number -> Number", "id": "builtins.div", "name": "div", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`x\` \`xs\`__ ", "Return \`true\` if a value equal to *x* occurs in the list *xs*, and \`false\` otherwise. ", ], "fn_type": "elem :: a -> [b] -> Bool", "id": "builtins.elem", "name": "elem", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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. ", ], "fn_type": "elemAt :: [a] -> Int -> b", "id": "builtins.elemAt", "name": "elemAt", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`args\`__ ", "Fetch a Nix store closure from a binary cache, rewriting it into content-addressed form. For example, \`\`\`nix 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 \`fromPath\` is already content-addressed, or if you are allowing impure evaluation (\`--impure\`), then \`toPath\` may be omitted. To find out the correct value for \`toPath\` given a \`fromPath\`, you can use \`nix store make-content-addressed\`: \`\`\`console # 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.storePath\` in 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\`. ", ], "fn_type": "fetchClosure :: AttrSet -> AttrSet", "id": "builtins.fetchClosure", "name": "fetchClosure", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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\`. - shallow\\ A Boolean parameter that specifies whether fetching a shallow clone is allowed. Defaults to \`false\`. - allRefs\\ Whether to fetch all refs of the repository. With this argument being true, it's possible to load a \`rev\` from *any* \`ref\` (by default only \`rev\`s from the specified \`ref\` are supported). 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*. ", ], "fn_type": "fetchgit :: AttrSet -> AttrSet", "id": "builtins.fetchGit", "name": "fetchGit", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`args\`__ ", "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 \`--tarball-ttl\` *number-of-seconds* or in the Nix configuration file by adding the line \`tarball-ttl = \` *number-of-seconds*. 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. ", ], "fn_type": "fetchTarball :: AttrSet -> AttrSet", "id": "builtins.fetchTarball", "name": "fetchTarball", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. ", ], "fn_type": "fetchurl :: String -> AttrSet", "id": "builtins.fetchurl", "name": "fetchurl", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`f\` \`list\`__ ", "Return a list consisting of the elements of *list* for which the function *f* returns \`true\`. ", ], "fn_type": "filter :: (a -> Bool) -> [a] -> [b]", "id": "builtins.filter", "name": "filter", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "> **Warning** > > \`filterSource\` should not be used to filter store paths. Since > \`filterSource\` uses the name of the input directory while naming > the output directory, doing so will produce a directory name in > the form of \`--\`, where \`-\` is > the name of the input directory. Since \`\` 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. Use \`builtins.path\` instead, 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-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. ", ], "fn_type": "filterSource :: (Path -> String -> Bool) -> Path -> StorePath", "id": "builtins.filterSource", "name": "filterSource", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. ", ], "fn_type": "floor :: Float -> Int", "id": "builtins.floor", "name": "floor", }, { "category": "builtins", "description": [ "takes 3 arguments: __\`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. ", ], "fn_type": "foldl' :: (a -> b -> c) -> a -> [b] -> c", "id": "builtins.foldl'", "name": "foldl'", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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; }\`. ", ], "fn_type": "fromJSON :: String -> a", "id": "builtins.fromJSON", "name": "fromJSON", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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: ...) = { }\`. ", ], "fn_type": "functionArgs :: (a) -> AttrSet", "id": "builtins.functionArgs", "name": "functionArgs", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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 ]\`. ", ], "fn_type": "genList :: (a -> b) -> a -> [b]", "id": "builtins.genList", "name": "genList", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`attrset\`__ ", "Take an *attrset* with values named \`startSet\` and \`operator\` in order to return a *list of attrsets* by starting with the \`startSet\`, recursively applying the \`operator\` function to each element. The *attrsets* in the \`startSet\` and produced by the \`operator\` must each contain value named \`key\` which 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; } ] \`\`\` ", ], "fn_type": "genericClosure :: AttrSet -> [AttrSet]", "id": "builtins.genericClosure", "name": "genericClosure", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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. ", ], "fn_type": "getAttr :: String -> AttrSet -> a", "id": "builtins.getAttr", "name": "getAttr", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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.) ", ], "fn_type": "getEnv :: String -> String", "id": "builtins.getEnv", "name": "getEnv", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`args\`__ ", "Fetch a flake from a flake reference, and return its output attributes and some metadata. For example: \`\`\`nix (builtins.getFlake "nix/55bc52401966fbffa525c574c14f67b00bc4fb3a").packages.x86_64-linux.nix \`\`\` Unless 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: \`\`\`nix (builtins.getFlake "github:edolstra/dwarffs").rev \`\`\` This function is only available if you enable the experimental feature \`flakes\`. ", ], "fn_type": "getFlake :: AttrSet -> AttrSet", "id": "builtins.getFlake", "name": "getFlake", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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, \`\`\`nix builtins.groupBy (builtins.substring 0 1) ["foo" "bar" "baz"] \`\`\` evaluates to \`\`\`nix { b = [ "bar" "baz" ]; f = [ "foo" ]; } \`\`\` ", ], "fn_type": "groupBy :: (a -> b) -> [a] -> AttrSet", "id": "builtins.groupBy", "name": "groupBy", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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. ", ], "fn_type": "hasAttr :: String -> AttrSet -> Bool", "id": "builtins.hasAttr", "name": "hasAttr", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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"\`. ", ], "fn_type": "hashFile :: String -> Path -> String", "id": "builtins.hashFile", "name": "hashFile", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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"\`. ", ], "fn_type": "hashString :: String -> String -> String", "id": "builtins.hashString", "name": "hashString", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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 \`[]\`. ", ], "fn_type": "head :: [a] -> a", "id": "builtins.head", "name": "head", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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 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\` *\\*) > 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.) ", ], "fn_type": "import :: Path -> a", "id": "builtins.import", "name": "import", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return a set consisting of the attributes in the set *e2* that also exist in the set *e1*. ", ], "fn_type": "intersectAttrs :: AttrSet -> AttrSet -> AttrSet", "id": "builtins.intersectAttrs", "name": "intersectAttrs", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to a set, and \`false\` otherwise. ", ], "fn_type": "isAttrs :: a -> Bool", "id": "builtins.isAttrs", "name": "isAttrs", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to a bool, and \`false\` otherwise. ", ], "fn_type": "isBool :: a -> Bool", "id": "builtins.isBool", "name": "isBool", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to a float, and \`false\` otherwise. ", ], "fn_type": "isFloat :: a -> Bool", "id": "builtins.isFloat", "name": "isFloat", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to a function, and \`false\` otherwise. ", ], "fn_type": "isFunction :: a -> Bool", "id": "builtins.isFunction", "name": "isFunction", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to an integer, and \`false\` otherwise. ", ], "fn_type": "isInt :: a -> Bool", "id": "builtins.isInt", "name": "isInt", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to a list, and \`false\` otherwise. ", ], "fn_type": "isList :: a -> Bool", "id": "builtins.isList", "name": "isList", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to \`null\`, and \`false\` otherwise. > **Warning** > > This function is *deprecated*; just write \`e == null\` instead. ", ], "fn_type": "isNull :: a -> Bool", "id": "builtins.isNull", "name": "isNull", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to a path, and \`false\` otherwise. ", ], "fn_type": "isPath :: a -> Bool", "id": "builtins.isPath", "name": "isPath", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return \`true\` if *e* evaluates to a string, and \`false\` otherwise. ", ], "fn_type": "isString :: a -> Bool", "id": "builtins.isString", "name": "isString", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return the length of the list *e*. ", ], "fn_type": "length :: [a] -> Int", "id": "builtins.length", "name": "length", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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. ", ], "fn_type": "lessThan :: Number -> Number -> Bool", "id": "builtins.lessThan", "name": "lessThan", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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; } \`\`\` ", ], "fn_type": "listToAttrs :: [{name :: String; value :: a}] -> AttrSet", "id": "builtins.listToAttrs", "name": "listToAttrs", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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" ]\`. ", ], "fn_type": "map :: (a -> b) -> [a] -> [b]", "id": "builtins.map", "name": "map", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`f\` \`attrset\`__ ", "Apply function *f* to every element of *attrset*. For example, \`\`\`nix builtins.mapAttrs (name: value: value * 10) { a = 1; b = 2; } \`\`\` evaluates to \`{ a = 10; b = 20; }\`. ", ], "fn_type": "mapAttrs :: (a -> b -> c) -> AttrSet -> AttrSet", "id": "builtins.mapAttrs", "name": "mapAttrs", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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" ]\`. ", ], "fn_type": "match :: String -> String -> Bool", "id": "builtins.match", "name": "match", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return the product of the numbers *e1* and *e2*. ", ], "fn_type": "mul :: Number -> Number -> Number", "id": "builtins.mul", "name": "mul", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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"; }\`. ", ], "fn_type": "parseDrvName :: String -> AttrSet", "id": "builtins.parseDrvName", "name": "parseDrvName", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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* returned \`true\`, and a list named \`wrong\`, containing the elements for which it returned \`false\`. For example, \`\`\`nix builtins.partition (x: x > 10) [1 23 9 3 42] \`\`\` evaluates to \`\`\`nix { right = [ 23 42 ]; wrong = [ 1 9 3 ]; } \`\`\` ", ], "fn_type": "partition :: (a -> Bool) -> [a] -> AttrSet", "id": "builtins.partition", "name": "partition", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. ", ], "fn_type": null, "id": "builtins.path", "name": "path", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`path\`__ ", "Return \`true\` if the path *path* exists at evaluation time, and \`false\` otherwise. ", ], "fn_type": "pathExists :: Path -> Bool", "id": "builtins.pathExists", "name": "pathExists", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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"\`. ", ], "fn_type": "placeholder :: String -> String", "id": "builtins.placeholder", "name": "placeholder", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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"\`. ", ], "fn_type": "readDir :: Path -> AttrSet", "id": "builtins.readDir", "name": "readDir", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`path\`__ ", "Return the contents of the file *path* as a string. ", ], "fn_type": "readFile :: Path -> String", "id": "builtins.readFile", "name": "readFile", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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; }\`. ", ], "fn_type": "removeAttrs :: AttrSet -> [a] -> AttrSet", "id": "builtins.removeAttrs", "name": "removeAttrs", }, { "category": "builtins", "description": [ "takes 3 arguments: __\`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"\`. ", ], "fn_type": "replaceStrings :: [String] -> [String] -> String -> String", "id": "builtins.replaceStrings", "name": "replaceStrings", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Evaluate *e1*, then evaluate and return *e2*. This ensures that a computation is strict in the value of *e1*. ", ], "fn_type": "seq :: a -> b -> b", "id": "builtins.seq", "name": "seq", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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. ", ], "fn_type": "sort :: (a -> b -> Bool) -> [a] -> [b]", "id": "builtins.sort", "name": "sort", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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" ] " " ]\`. ", ], "fn_type": "split :: String -> String -> [String]", "id": "builtins.split", "name": "split", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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). ", ], "fn_type": "splitVersion :: String -> [String]", "id": "builtins.splitVersion", "name": "splitVersion", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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…-source\` causes 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. ", ], "fn_type": null, "id": "builtins.storePath", "name": "storePath", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return the length of the string *e*. If *e* is not a string, evaluation is aborted. ", ], "fn_type": "stringLength :: String -> Int", "id": "builtins.stringLength", "name": "stringLength", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Return the difference between the numbers *e1* and *e2*. ", ], "fn_type": "sub :: Number -> Number -> Number", "id": "builtins.sub", "name": "sub", }, { "category": "builtins", "description": [ "takes 3 arguments: __\`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"\`. ", ], "fn_type": "substring :: Int -> Int -> String -> String", "id": "builtins.substring", "name": "substring", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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 calling \`tail\` takes O(n^2) time. ", ], "fn_type": "tail :: [a] -> a", "id": "builtins.tail", "name": "tail", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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\`). ", ], "fn_type": "throw :: String", "id": "builtins.throw", "name": "throw", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`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. ", ], "fn_type": "toFile :: Path -> String -> StorePath ", "id": "builtins.toFile", "name": "toFile", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. ", ], "fn_type": "toJSON :: a -> String", "id": "builtins.toJSON", "name": "toJSON", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`s\`__ ", "**DEPRECATED.** Use \`/. + "/path"\` to convert a string into an absolute path. For relative paths, use \`./. + "/path"\`. ", ], "fn_type": "toPath :: String -> Path", "id": "builtins.toPath", "name": "toPath", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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: ...; }\` or \`{ outPath = ...; }\`. - 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. ", ], "fn_type": "toString :: a -> String", "id": "builtins.toString", "name": "toString", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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" ② " "; 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 \`\`\` 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}\`. ", ], "fn_type": "toXML :: a -> String", "id": "builtins.toXML", "name": "toXML", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Evaluate *e1* and print its abstract syntax representation on standard error. Then return *e2*. This function is useful for debugging. ", ], "fn_type": "trace :: a -> b -> b", "id": "builtins.trace", "name": "trace", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`e1\` \`e2\`__ ", "Evaluate *e1* and print its abstract syntax representation on standard error if \`--trace-verbose\` is enabled. Then return *e2*. This function is useful for debugging. ", ], "fn_type": "traceVerbose :: a -> b -> b", "id": "builtins.traceVerbose", "name": "traceVerbose", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`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. \`tryEval\` will only prevent errors created by \`throw\` or \`assert\` from being thrown. Errors \`tryEval\` will not catch are for example those created by \`abort\` and type errors generated by builtins. Also 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\`. ", ], "fn_type": "tryEval :: a", "id": "builtins.tryEval", "name": "tryEval", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`e\`__ ", "Return a string representing the type of the value *e*, namely \`"int"\`, \`"bool"\`, \`"string"\`, \`"path"\`, \`"null"\`, \`"set"\`, \`"list"\`, \`"lambda"\` or \`"float"\`. ", ], "fn_type": "typeOf :: a -> String", "id": "builtins.typeOf", "name": "typeOf", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`f\` \`list\`__ ", "Transpose a list of attribute sets into an attribute set of lists, then apply \`mapAttrs\`. \`f\` receives 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 of \`f\`. \`\`\`nix 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" ]; }; } \`\`\` ", ], "fn_type": "zipAttrsWith :: (String -> [a] ) -> [a] -> AttrSet", "id": "builtins.zipAttrsWith", "name": "zipAttrsWith", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`s\`__ ", "# Derivations The most important built-in function is \`derivation\`, which is used to describe a single derivation (a build task). It takes as input a set, the attributes of which specify the inputs of the build. - There must be an attribute named [\`system\`]{#attr-system} whose value must be a string specifying a Nix system type, such as \`"i686-linux"\` or \`"x86_64-darwin"\`. (To figure out your system type, run \`nix -vv --version\`.) The build can only be performed on a machine and operating system matching the system type. (Nix can automatically [forward builds for other platforms](../advanced-topics/distributed-builds.md) by forwarding them to other machines.) - There must be an attribute named \`name\` whose value must be a string. This is used as a symbolic name for the package by \`nix-env\`, and it is appended to the output paths of the derivation. - There must be an attribute named \`builder\` that identifies the program that is executed to perform the build. It can be either a derivation or a source (a local file reference, e.g., \`./builder.sh\`). - Every attribute is passed as an environment variable to the builder. Attribute values are translated to environment variables as follows: - Strings and numbers are just passed verbatim. - A *path* (e.g., \`../foo/sources.tar\`) causes the referenced file to be copied to the store; its location in the store is put in the environment variable. The idea is that all sources should reside in the Nix store, since all inputs to a derivation should reside in the Nix store. - A *derivation* causes that derivation to be built prior to the present derivation; its default output path is put in the environment variable. - Lists of the previous types are also allowed. They are simply concatenated, separated by spaces. - \`true\` is passed as the string \`1\`, \`false\` and \`null\` are passed as an empty string. - The optional attribute \`args\` specifies command-line arguments to be passed to the builder. It should be a list. - The optional attribute \`outputs\` specifies a list of symbolic outputs of the derivation. By default, a derivation produces a single output path, denoted as \`out\`. However, derivations can produce multiple output paths. This is useful because it allows outputs to be downloaded or garbage-collected separately. For instance, imagine a library package that provides a dynamic library, header files, and documentation. A program that links against the library doesn’t need the header files and documentation at runtime, and it doesn’t need the documentation at build time. Thus, the library package could specify: \`\`\`nix outputs = [ "lib" "headers" "doc" ]; \`\`\` This will cause Nix to pass environment variables \`lib\`, \`headers\` and \`doc\` to the builder containing the intended store paths of each output. The builder would typically do something like \`\`\`bash ./configure \\n --libdir=$lib/lib \\n --includedir=$headers/include \\n --docdir=$doc/share/doc \`\`\` for an Autoconf-style package. You can refer to each output of a derivation by selecting it as an attribute, e.g. \`\`\`nix buildInputs = [ pkg.lib pkg.headers ]; \`\`\` The first element of \`outputs\` determines the *default output*. Thus, you could also write \`\`\`nix buildInputs = [ pkg pkg.headers ]; \`\`\` since \`pkg\` is equivalent to \`pkg.lib\`. The function \`mkDerivation\` in the Nixpkgs standard environment is a wrapper around \`derivation\` that adds a default value for \`system\` and always uses Bash as the builder, to which the supplied builder is passed as a command-line argument. See the Nixpkgs manual for details. The builder is executed as follows: - A temporary directory is created under the directory specified by \`TMPDIR\` (default \`/tmp\`) where the build will take place. The current directory is changed to this directory. - The environment is cleared and set to the derivation attributes, as specified above. - In addition, the following variables are set: - \`NIX_BUILD_TOP\` contains the path of the temporary directory for this build. - Also, \`TMPDIR\`, \`TEMPDIR\`, \`TMP\`, \`TEMP\` are set to point to the temporary directory. This is to prevent the builder from accidentally writing temporary files anywhere else. Doing so might cause interference by other processes. - \`PATH\` is set to \`/path-not-set\` to prevent shells from initialising it to their built-in default value. - \`HOME\` is set to \`/homeless-shelter\` to prevent programs from using \`/etc/passwd\` or the like to find the user's home directory, which could cause impurity. Usually, when \`HOME\` is set, it is used as the location of the home directory, even if it points to a non-existent path. - \`NIX_STORE\` is set to the path of the top-level Nix store directory (typically, \`/nix/store\`). - For each output declared in \`outputs\`, the corresponding environment variable is set to point to the intended path in the Nix store for that output. Each output path is a concatenation of the cryptographic hash of all build inputs, the \`name\` attribute and the output name. (The output name is omitted if it’s \`out\`.) - If an output path already exists, it is removed. Also, locks are acquired to prevent multiple Nix instances from performing the same build at the same time. - A log of the combined standard output and error is written to \`/nix/var/log/nix\`. - The builder is executed with the arguments specified by the attribute \`args\`. If it exits with exit code 0, it is considered to have succeeded. - The temporary directory is removed (unless the \`-K\` option was specified). - If the build was successful, Nix scans each output path for references to input paths by looking for the hash parts of the input paths. Since these are potential runtime dependencies, Nix registers them as dependencies of the output paths. - After the build, Nix sets the last-modified timestamp on all files in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to the default group, and sets the mode of the file to 0444 or 0555 (i.e., read-only, with execute permission enabled if the file was originally executable). Note that possible \`setuid\` and \`setgid\` bits are cleared. Setuid and setgid programs are not currently supported by Nix. This is because the Nix archives used in deployment have no concept of ownership information, and because it makes the build result dependent on the user performing the build. ", ], "fn_type": "let Derivation :: { all :: [ Derivation ]; builder :: String; drvAttrs :: { builder = String; name = String; outputs = [ output :: String ]; system = String; \${additionalArgs} :: String; } drvPath :: String; name :: String; outPath :: String; outputName :: String; outputs :: [ output :: String ]; system :: String; type :: "derivation"; \${output} :: Derivation; \${additionalArgs} :: String; }; in builtins.derivation :: { name :: String; outputs :: [ output :: String ] ? [ "out" ]; builder :: String; system :: String; \${additionalArgs} :: String; } -> Derivation", "id": "builtins.derivation", "name": "derivation", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`s\` \`c\`__ ", " ", ], "fn_type": null, "id": "builtins.addErrorContext", "name": "addErrorContext", }, { "category": "builtins", "description": [ "takes 2 arguments: __\`s\` \`c\`__ ", " ", ], "fn_type": null, "id": "builtins.appendContext", "name": "appendContext", }, { "category": "builtins", "description": [ "", "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. ", ], "fn_type": null, "id": "builtins.builtins", "name": "builtins", }, { "category": "builtins", "description": [ "", "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"\`. ", ], "fn_type": null, "id": "builtins.currentSystem", "name": "currentSystem", }, { "category": "builtins", "description": [ "", "The built-in value \`currentSystem\` evaluates to the current seconds since Jan 01 1970. (UTC). ", ], "fn_type": null, "id": "builtins.currentTime", "name": "currentTime", }, { "category": "builtins", "description": [ "", "The built-in boolean value \`false\`. ", ], "fn_type": null, "id": "builtins.false", "name": "false", }, { "category": "builtins", "description": [ "", "The built-in boolean value \`true\`. ", ], "fn_type": null, "id": "builtins.true", "name": "true", }, { "category": "builtins", "description": [ "", "The built-in value \`null\`. ", ], "fn_type": null, "id": "builtins.null", "name": "null", }, { "category": "builtins", "description": [ "takes 1 arguments: __\`s\`__ ", "# Parse a TOML-configuration from String \`\`\` builtins.fromTOML '' # Toplevel foo = "bar" # Simple Attrset [set] info = "foobar" # Nested Attrset [set.nested] meta = 42 '' -> { foo = "bar"; set = { info = "foobar"; nested = { meta = 42; }; }; } \`\`\` Also works nicely with \`readFile\`: \`\`\` builtins.fromTOML (builtins.readFile ./config.toml) \`\`\` ", ], "fn_type": "fromTOML :: String -> { Any }", "id": "builtins.fromTOML", "name": "fromTOML", }, ] `; exports[`has not changed lib data 1`] = ` [ { "category": "./lib/versions.nix", "description": "Break a version string into its component parts.", "example": "splitVersion "1.2.3" => ["1" "2" "3"]", "fn_type": null, "id": "lib.versions.splitVersion", "line": 12, "name": "splitVersion", }, { "category": "./lib/versions.nix", "description": "Get the major version string from a string.", "example": "major "1.2.3" => "1"", "fn_type": null, "id": "lib.versions.major", "line": 20, "name": "major", }, { "category": "./lib/versions.nix", "description": "Get the minor version string from a string.", "example": "minor "1.2.3" => "2"", "fn_type": null, "id": "lib.versions.minor", "line": 28, "name": "minor", }, { "category": "./lib/versions.nix", "description": "Get the patch version string from a string.", "example": "patch "1.2.3" => "3"", "fn_type": null, "id": "lib.versions.patch", "line": 36, "name": "patch", }, { "category": "./lib/versions.nix", "description": "Get string of the first two parts (major and minor) of a version string.", "example": "majorMinor "1.2.3" => "1.2"", "fn_type": null, "id": "lib.versions.majorMinor", "line": 45, "name": "majorMinor", }, { "category": "./lib/versions.nix", "description": "Pad a version string with zeros to match the given number of components.", "example": "pad 3 "1.2" => "1.2.0" pad 3 "1.3-rc1" => "1.3.0-rc1" pad 3 "1.2.3.4" => "1.2.3"", "fn_type": null, "id": "lib.versions.pad", "line": 59, "name": "pad", }, { "category": "./lib/trivial.nix", "description": "The identity function For when you need a function that does “nothing”.", "example": null, "fn_type": "id :: a -> a", "id": "lib.trivial.id", "line": 13, "name": "id", }, { "category": "./lib/trivial.nix", "description": "The constant function Ignores the second argument. If called with only one argument, constructs a function that always returns a static value.", "example": "let f = const 5; in f 10 => 5", "fn_type": "const :: a -> b -> a", "id": "lib.trivial.const", "line": 26, "name": "const", }, { "category": "./lib/trivial.nix", "description": "Pipes a value through a list of functions, left to right.", "example": "pipe 2 [ (x: x + 2) # 2 + 2 = 4 (x: x * 2) # 4 * 2 = 8 ] => 8 # ideal to do text transformations pipe [ "a/b" "a/c" ] [ # create the cp command (map (file: ''cp "\${src}/\${file}" $out\\n'')) # concatenate all commands into one string lib.concatStrings # make that string into a nix derivation (pkgs.runCommand "copy-to-out" {}) ] => The output type of each function has to be the input type of the next function, and the last function returns the final value.", "fn_type": "pipe :: a -> [] -> ", "id": "lib.trivial.pipe", "line": 61, "name": "pipe", }, { "category": "./lib/trivial.nix", "description": "Concatenate two lists", "example": "concat [ 1 2 ] [ 3 4 ] => [ 1 2 3 4 ]", "fn_type": "concat :: [a] -> [a] -> [a]", "id": "lib.trivial.concat", "line": 80, "name": "concat", }, { "category": "./lib/trivial.nix", "description": "boolean “or”", "example": null, "fn_type": null, "id": "lib.trivial.or", "line": 83, "name": "or", }, { "category": "./lib/trivial.nix", "description": "boolean “and”", "example": null, "fn_type": null, "id": "lib.trivial.and", "line": 86, "name": "and", }, { "category": "./lib/trivial.nix", "description": "bitwise “and”", "example": null, "fn_type": null, "id": "lib.trivial.bitAnd", "line": 89, "name": "bitAnd", }, { "category": "./lib/trivial.nix", "description": "bitwise “or”", "example": null, "fn_type": null, "id": "lib.trivial.bitOr", "line": 95, "name": "bitOr", }, { "category": "./lib/trivial.nix", "description": "bitwise “xor”", "example": null, "fn_type": null, "id": "lib.trivial.bitXor", "line": 100, "name": "bitXor", }, { "category": "./lib/trivial.nix", "description": "bitwise “not”", "example": null, "fn_type": null, "id": "lib.trivial.bitNot", "line": 106, "name": "bitNot", }, { "category": "./lib/trivial.nix", "description": "Convert a boolean to a string. This function uses the strings "true" and "false" to represent boolean values. Calling \`toString\` on a bool instead returns "1" and "" (sic!).", "example": null, "fn_type": "boolToString :: bool -> string", "id": "lib.trivial.boolToString", "line": 114, "name": "boolToString", }, { "category": "./lib/trivial.nix", "description": "Merge two attribute sets shallowly, right side trumps left mergeAttrs :: attrs -> attrs -> attrs", "example": "mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; } => { a = 1; b = 3; c = 4; }", "fn_type": null, "id": "lib.trivial.mergeAttrs", "line": 125, "name": "mergeAttrs", }, { "category": "./lib/trivial.nix", "description": "Flip the order of the arguments of a binary function.", "example": "flip concat [1] [2] => [ 2 1 ]", "fn_type": "flip :: (a -> b -> c) -> (b -> a -> c)", "id": "lib.trivial.flip", "line": 140, "name": "flip", }, { "category": "./lib/trivial.nix", "description": "Apply function if the supplied argument is non-null.", "example": "mapNullable (x: x+1) null => null mapNullable (x: x+1) 22 => 23", "fn_type": null, "id": "lib.trivial.mapNullable", "line": 149, "name": "mapNullable", }, { "category": "./lib/trivial.nix", "description": "Returns the current full nixpkgs version number.", "example": null, "fn_type": null, "id": "lib.trivial.version", "line": 164, "name": "version", }, { "category": "./lib/trivial.nix", "description": "Returns the current nixpkgs release number as string.", "example": null, "fn_type": null, "id": "lib.trivial.release", "line": 167, "name": "release", }, { "category": "./lib/trivial.nix", "description": "The latest release that is supported, at the time of release branch-off, if applicable. Ideally, out-of-tree modules should be able to evaluate cleanly with all supported Nixpkgs versions (master, release and old release until EOL). So if possible, deprecation warnings should take effect only when all out-of-tree expressions/libs/modules can upgrade to the new way without losing support for supported Nixpkgs versions. This release number allows deprecation warnings to be implemented such that they take effect as soon as the oldest release reaches end of life.", "example": null, "fn_type": null, "id": "lib.trivial.oldestSupportedRelease", "line": 181, "name": "oldestSupportedRelease", }, { "category": "./lib/trivial.nix", "description": "Whether a feature is supported in all supported releases (at the time of release branch-off, if applicable). See \`oldestSupportedRelease\`.", "example": null, "fn_type": null, "id": "lib.trivial.isInOldestRelease", "line": 187, "name": "isInOldestRelease", }, { "category": "./lib/trivial.nix", "description": "Returns the current nixpkgs release code name. On each release the first letter is bumped and a new animal is chosen starting with that new letter.", "example": null, "fn_type": null, "id": "lib.trivial.codeName", "line": 200, "name": "codeName", }, { "category": "./lib/trivial.nix", "description": "Returns the current nixpkgs version suffix as string.", "example": null, "fn_type": null, "id": "lib.trivial.versionSuffix", "line": 202, "name": "versionSuffix", }, { "category": "./lib/trivial.nix", "description": "Attempts to return the the current revision of nixpkgs and returns the supplied default value otherwise.", "example": null, "fn_type": "revisionWithDefault :: string -> string", "id": "lib.trivial.revisionWithDefault", "line": 213, "name": "revisionWithDefault", }, { "category": "./lib/trivial.nix", "description": "Determine whether the function is being called from inside a Nix shell.", "example": null, "fn_type": "inNixShell :: bool", "id": "lib.trivial.inNixShell", "line": 230, "name": "inNixShell", }, { "category": "./lib/trivial.nix", "description": "Determine whether the function is being called from inside pure-eval mode by seeing whether \`builtins\` contains \`currentSystem\`. If not, we must be in pure-eval mode.", "example": null, "fn_type": "inPureEvalMode :: bool", "id": "lib.trivial.inPureEvalMode", "line": 238, "name": "inPureEvalMode", }, { "category": "./lib/trivial.nix", "description": "Return minimum of two numbers.", "example": null, "fn_type": null, "id": "lib.trivial.min", "line": 243, "name": "min", }, { "category": "./lib/trivial.nix", "description": "Return maximum of two numbers.", "example": null, "fn_type": null, "id": "lib.trivial.max", "line": 246, "name": "max", }, { "category": "./lib/trivial.nix", "description": "Integer modulus", "example": "mod 11 10 => 1 mod 1 10 => 1", "fn_type": null, "id": "lib.trivial.mod", "line": 256, "name": "mod", }, { "category": "./lib/trivial.nix", "description": "C-style comparisons a < b, compare a b => -1 a == b, compare a b => 0 a > b, compare a b => 1", "example": null, "fn_type": null, "id": "lib.trivial.compare", "line": 269, "name": "compare", }, { "category": "./lib/trivial.nix", "description": "Split type into two subtypes by predicate \`p\`, take all elements of the first subtype to be less than all the elements of the second subtype, compare elements of a single subtype with \`yes\` and \`no\` respectively.", "example": "let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in cmp "a" "z" => -1 cmp "fooa" "fooz" => -1 cmp "f" "a" => 1 cmp "fooa" "a" => -1 # while compare "fooa" "a" => 1", "fn_type": "(a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int)", "id": "lib.trivial.splitByAndCompare", "line": 293, "name": "splitByAndCompare", }, { "category": "./lib/trivial.nix", "description": "Reads a JSON file. Type :: path -> any", "example": null, "fn_type": null, "id": "lib.trivial.importJSON", "line": 313, "name": "importJSON", }, { "category": "./lib/trivial.nix", "description": "Reads a TOML file. Type :: path -> any", "example": null, "fn_type": null, "id": "lib.trivial.importTOML", "line": 320, "name": "importTOML", }, { "category": "./lib/trivial.nix", "description": "Print a warning before returning the second argument. This function behaves like \`builtins.trace\`, but requires a string message and formats it as a warning, including the \`warning: \` prefix. To get a call stack trace and abort evaluation, set the environment variable \`NIX_ABORT_ON_WARN=true\` and set the Nix options \`--option pure-eval false --show-trace\`", "example": null, "fn_type": "string -> a -> a", "id": "lib.trivial.warn", "line": 348, "name": "warn", }, { "category": "./lib/trivial.nix", "description": "Like warn, but only warn when the first argument is \`true\`.", "example": null, "fn_type": "bool -> string -> a -> a", "id": "lib.trivial.warnIf", "line": 357, "name": "warnIf", }, { "category": "./lib/trivial.nix", "description": "Like warnIf, but negated (warn if the first argument is \`false\`).", "example": null, "fn_type": "bool -> string -> a -> a", "id": "lib.trivial.warnIfNot", "line": 364, "name": "warnIfNot", }, { "category": "./lib/trivial.nix", "description": "Like the \`assert b; e\` expression, but with a custom error message and without the semicolon. If true, return the identity function, \`r: r\`. If false, throw the error message. Calls can be juxtaposed using function application, as \`(r: r) a = a\`, so \`(r: r) (r: r) a = a\`, and so forth.", "example": "throwIfNot (lib.isList overlays) "The overlays argument to nixpkgs must be a list." lib.foldr (x: throwIfNot (lib.isFunction x) "All overlays passed to nixpkgs must be functions.") (r: r) overlays pkgs", "fn_type": "bool -> string -> a -> a", "id": "lib.trivial.throwIfNot", "line": 386, "name": "throwIfNot", }, { "category": "./lib/trivial.nix", "description": "Like throwIfNot, but negated (throw if the first argument is \`true\`).", "example": null, "fn_type": "bool -> string -> a -> a", "id": "lib.trivial.throwIf", "line": 393, "name": "throwIf", }, { "category": "./lib/trivial.nix", "description": "Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise.", "example": "let colorVariants = ["bright" "dark" "black"] in checkListOfEnum "color variants" [ "standard" "light" "dark" ] colorVariants; => error: color variants: bright, black unexpected; valid ones: standard, light, dark", "fn_type": "String -> List ComparableVal -> List ComparableVal -> a -> a", "id": "lib.trivial.checkListOfEnum", "line": 405, "name": "checkListOfEnum", }, { "category": "./lib/trivial.nix", "description": "Add metadata about expected function arguments to a function. The metadata should match the format given by builtins.functionArgs, i.e. a set from expected argument to a bool representing whether that argument has a default or not. setFunctionArgs : (a → b) → Map String Bool → (a → b) This function is necessary because you can't dynamically create a function of the { a, b ? foo, ... }: format, but some facilities like callPackage expect to be able to query expected arguments.", "example": null, "fn_type": null, "id": "lib.trivial.setFunctionArgs", "line": 429, "name": "setFunctionArgs", }, { "category": "./lib/trivial.nix", "description": "Extract the expected function arguments from a function. This works both with nix-native { a, b ? foo, ... }: style functions and functions with args set with 'setFunctionArgs'. It has the same return type and semantics as builtins.functionArgs. setFunctionArgs : (a → b) → Map String Bool.", "example": null, "fn_type": null, "id": "lib.trivial.functionArgs", "line": 442, "name": "functionArgs", }, { "category": "./lib/trivial.nix", "description": "Check whether something is a function or something annotated with function args.", "example": null, "fn_type": null, "id": "lib.trivial.isFunction", "line": 449, "name": "isFunction", }, { "category": "./lib/trivial.nix", "description": "Turns any non-callable values into constant functions. Returns callable values as is.", "example": "nix-repl> lib.toFunction 1 2 1 nix-repl> lib.toFunction (x: x + 1) 2 3", "fn_type": null, "id": "lib.trivial.toFunction", "line": 466, "name": "toFunction", }, { "category": "./lib/trivial.nix", "description": "Convert the given positive integer to a string of its hexadecimal representation. For example: toHexString 0 => "0" toHexString 16 => "10" toHexString 250 => "FA"", "example": null, "fn_type": null, "id": "lib.trivial.toHexString", "line": 481, "name": "toHexString", }, { "category": "./lib/trivial.nix", "description": "\`toBaseDigits base i\` converts the positive integer i to a list of its digits in the given base. For example: toBaseDigits 10 123 => [ 1 2 3 ] toBaseDigits 2 6 => [ 1 1 0 ] toBaseDigits 16 250 => [ 15 10 ]", "example": null, "fn_type": null, "id": "lib.trivial.toBaseDigits", "line": 507, "name": "toBaseDigits", }, { "category": "./lib/strings.nix", "description": "Concatenate a list of strings.", "example": "concatStrings ["foo" "bar"] => "foobar"", "fn_type": "concatStrings :: [string] -> string", "id": "lib.strings.concatStrings", "line": 45, "name": "concatStrings", }, { "category": "./lib/strings.nix", "description": "Map a function over a list and concatenate the resulting strings.", "example": "concatMapStrings (x: "a" + x) ["foo" "bar"] => "afooabar"", "fn_type": "concatMapStrings :: (a -> string) -> [a] -> string", "id": "lib.strings.concatMapStrings", "line": 55, "name": "concatMapStrings", }, { "category": "./lib/strings.nix", "description": "Like \`concatMapStrings\` except that the f functions also gets the position as a parameter.", "example": "concatImapStrings (pos: x: "\${toString pos}-\${x}") ["foo" "bar"] => "1-foo2-bar"", "fn_type": "concatImapStrings :: (int -> a -> string) -> [a] -> string", "id": "lib.strings.concatImapStrings", "line": 66, "name": "concatImapStrings", }, { "category": "./lib/strings.nix", "description": "Place an element between each element of a list", "example": "intersperse "/" ["usr" "local" "bin"] => ["usr" "/" "local" "/" "bin"].", "fn_type": "intersperse :: a -> [a] -> [a]", "id": "lib.strings.intersperse", "line": 76, "name": "intersperse", }, { "category": "./lib/strings.nix", "description": "Concatenate a list of strings with a separator between each element", "example": "concatStringsSep "/" ["usr" "local" "bin"] => "usr/local/bin"", "fn_type": "concatStringsSep :: string -> [string] -> string", "id": "lib.strings.concatStringsSep", "line": 93, "name": "concatStringsSep", }, { "category": "./lib/strings.nix", "description": "Maps a function over a list of strings and then concatenates the result with the specified separator interspersed between elements.", "example": "concatMapStringsSep "-" (x: toUpper x) ["foo" "bar" "baz"] => "FOO-BAR-BAZ"", "fn_type": "concatMapStringsSep :: string -> (a -> string) -> [a] -> string", "id": "lib.strings.concatMapStringsSep", "line": 106, "name": "concatMapStringsSep", }, { "category": "./lib/strings.nix", "description": "Same as \`concatMapStringsSep\`, but the mapping function additionally receives the position of its argument.", "example": "concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ] => "6-3-2"", "fn_type": "concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string", "id": "lib.strings.concatImapStringsSep", "line": 123, "name": "concatImapStringsSep", }, { "category": "./lib/strings.nix", "description": "Concatenate a list of strings, adding a newline at the end of each one. Defined as \`concatMapStrings (s: s + "\\n")\`.", "example": "concatLines [ "foo" "bar" ] => "foo\\nbar\\n"", "fn_type": "concatLines :: [string] -> string", "id": "lib.strings.concatLines", "line": 140, "name": "concatLines", }, { "category": "./lib/strings.nix", "description": "Construct a Unix-style, colon-separated search path consisting of the given \`subDir\` appended to each of the given paths.", "example": "makeSearchPath "bin" ["/root" "/usr" "/usr/local"] => "/root/bin:/usr/bin:/usr/local/bin" makeSearchPath "bin" [""] => "/bin"", "fn_type": "makeSearchPath :: string -> [string] -> string", "id": "lib.strings.makeSearchPath", "line": 153, "name": "makeSearchPath", }, { "category": "./lib/strings.nix", "description": "Construct a Unix-style search path by appending the given \`subDir\` to the specified \`output\` of each of the packages. If no output by the given name is found, fallback to \`.out\` and then to the default.", "example": "makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ] => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin"", "fn_type": "string -> string -> [package] -> string", "id": "lib.strings.makeSearchPathOutput", "line": 171, "name": "makeSearchPathOutput", }, { "category": "./lib/strings.nix", "description": "Construct a library search path (such as RPATH) containing the libraries for a set of packages", "example": "makeLibraryPath [ "/usr" "/usr/local" ] => "/usr/lib:/usr/local/lib" pkgs = import { } makeLibraryPath [ pkgs.openssl pkgs.zlib ] => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib"", "fn_type": null, "id": "lib.strings.makeLibraryPath", "line": 189, "name": "makeLibraryPath", }, { "category": "./lib/strings.nix", "description": "Construct a binary search path (such as $PATH) containing the binaries for a set of packages.", "example": "makeBinPath ["/root" "/usr" "/usr/local"] => "/root/bin:/usr/bin:/usr/local/bin"", "fn_type": null, "id": "lib.strings.makeBinPath", "line": 198, "name": "makeBinPath", }, { "category": "./lib/strings.nix", "description": "Normalize path, removing extraneous /s", "example": "normalizePath "/a//b///c/" => "/a/b/c/"", "fn_type": "normalizePath :: string -> string", "id": "lib.strings.normalizePath", "line": 208, "name": "normalizePath", }, { "category": "./lib/strings.nix", "description": "Depending on the boolean \`cond', return either the given string or the empty string. Useful to concatenate against a bigger string.", "example": "optionalString true "some-string" => "some-string" optionalString false "some-string" => """, "fn_type": "optionalString :: bool -> string -> string", "id": "lib.strings.optionalString", "line": 221, "name": "optionalString", }, { "category": "./lib/strings.nix", "description": "Determine whether a string has given prefix.", "example": "hasPrefix "foo" "foobar" => true hasPrefix "foo" "barfoo" => false", "fn_type": "hasPrefix :: string -> string -> bool", "id": "lib.strings.hasPrefix", "line": 237, "name": "hasPrefix", }, { "category": "./lib/strings.nix", "description": "Determine whether a string has given suffix.", "example": "hasSuffix "foo" "foobar" => false hasSuffix "foo" "barfoo" => true", "fn_type": "hasSuffix :: string -> string -> bool", "id": "lib.strings.hasSuffix", "line": 253, "name": "hasSuffix", }, { "category": "./lib/strings.nix", "description": "Determine whether a string contains the given infix", "example": "hasInfix "bc" "abcd" => true hasInfix "ab" "abcd" => true hasInfix "cd" "abcd" => true hasInfix "foo" "abcd" => false", "fn_type": "hasInfix :: string -> string -> bool", "id": "lib.strings.hasInfix", "line": 278, "name": "hasInfix", }, { "category": "./lib/strings.nix", "description": "Convert a string to a list of characters (i.e. singleton strings). This allows you to, e.g., map a function over each character. However, note that this will likely be horribly inefficient; Nix is not a general purpose programming language. Complex string manipulations should, if appropriate, be done in a derivation. Also note that Nix treats strings as a list of bytes and thus doesn't handle unicode.", "example": "stringToCharacters "" => [ ] stringToCharacters "abc" => [ "a" "b" "c" ] stringToCharacters "🦄" => [ "�" "�" "�" "�" ]", "fn_type": "stringToCharacters :: string -> [string]", "id": "lib.strings.stringToCharacters", "line": 299, "name": "stringToCharacters", }, { "category": "./lib/strings.nix", "description": "Manipulate a string character by character and replace them by strings before concatenating the results.", "example": "stringAsChars (x: if x == "a" then "i" else x) "nax" => "nix"", "fn_type": "stringAsChars :: (string -> string) -> string -> string", "id": "lib.strings.stringAsChars", "line": 311, "name": "stringAsChars", }, { "category": "./lib/strings.nix", "description": "Convert char to ascii value, must be in printable range", "example": "charToInt "A" => 65 charToInt "(" => 40", "fn_type": "charToInt :: string -> int", "id": "lib.strings.charToInt", "line": 330, "name": "charToInt", }, { "category": "./lib/strings.nix", "description": "Escape occurrence of the elements of \`list\` in \`string\` by prefixing it with a backslash.", "example": "escape ["(" ")"] "(foo)" => "\\\\(foo\\\\)"", "fn_type": "escape :: [string] -> string -> string", "id": "lib.strings.escape", "line": 343, "name": "escape", }, { "category": "./lib/strings.nix", "description": "Escape occurrence of the element of \`list\` in \`string\` by converting to its ASCII value and prefixing it with \\\\x. Only works for printable ascii characters.", "example": "escapeC [" "] "foo bar" => "foo\\\\x20bar"", "fn_type": "escapeC = [string] -> string -> string", "id": "lib.strings.escapeC", "line": 356, "name": "escapeC", }, { "category": "./lib/strings.nix", "description": "Quote string to be used safely within the Bourne shell.", "example": "escapeShellArg "esc'ape\\nme" => "'esc'\\\\''ape\\nme'"", "fn_type": "escapeShellArg :: string -> string", "id": "lib.strings.escapeShellArg", "line": 366, "name": "escapeShellArg", }, { "category": "./lib/strings.nix", "description": "Quote all arguments to be safely passed to the Bourne shell.", "example": "escapeShellArgs ["one" "two three" "four'five"] => "'one' 'two three' 'four'\\\\''five'"", "fn_type": "escapeShellArgs :: [string] -> string", "id": "lib.strings.escapeShellArgs", "line": 376, "name": "escapeShellArgs", }, { "category": "./lib/strings.nix", "description": "Test whether the given name is a valid POSIX shell variable name.", "example": "isValidPosixName "foo_bar000" => true isValidPosixName "0-bad.jpg" => false", "fn_type": "string -> bool", "id": "lib.strings.isValidPosixName", "line": 388, "name": "isValidPosixName", }, { "category": "./lib/strings.nix", "description": "Translate a Nix value into a shell variable declaration, with proper escaping. The value can be a string (mapped to a regular variable), a list of strings (mapped to a Bash-style array) or an attribute set of strings (mapped to a Bash-style associative array). Note that "string" includes string-coercible values like paths or derivations. Strings are translated into POSIX sh-compatible code; lists and attribute sets assume a shell that understands Bash syntax (e.g. Bash or ZSH).", "example": "'' \${toShellVar "foo" "some string"} [[ "$foo" == "some string" ]] ''", "fn_type": "string -> (string | listOf string | attrsOf string) -> string", "id": "lib.strings.toShellVar", "line": 408, "name": "toShellVar", }, { "category": "./lib/strings.nix", "description": "Translate an attribute set into corresponding shell variable declarations using \`toShellVar\`.", "example": "let foo = "value"; bar = foo; in '' \${toShellVars { inherit foo bar; }} [[ "$foo" == "$bar" ]] ''", "fn_type": "attrsOf (string | listOf string | attrsOf string) -> string", "id": "lib.strings.toShellVars", "line": 436, "name": "toShellVars", }, { "category": "./lib/strings.nix", "description": "Turn a string into a Nix expression representing that string", "example": "escapeNixString "hello\\\${}\\n" => "\\"hello\\\\\\\${}\\\\n\\""", "fn_type": "string -> string", "id": "lib.strings.escapeNixString", "line": 446, "name": "escapeNixString", }, { "category": "./lib/strings.nix", "description": "Turn a string into an exact regular expression", "example": "escapeRegex "[^a-z]*" => "\\\\[\\\\^a-z]\\\\*"", "fn_type": "string -> string", "id": "lib.strings.escapeRegex", "line": 456, "name": "escapeRegex", }, { "category": "./lib/strings.nix", "description": "Quotes a string if it can't be used as an identifier directly.", "example": "escapeNixIdentifier "hello" => "hello" escapeNixIdentifier "0abc" => "\\"0abc\\""", "fn_type": "string -> string", "id": "lib.strings.escapeNixIdentifier", "line": 468, "name": "escapeNixIdentifier", }, { "category": "./lib/strings.nix", "description": "Escapes a string such that it is safe to include verbatim in an XML document.", "example": "escapeXML ''"test" 'test' < & >'' => ""test" 'test' < & >"", "fn_type": "string -> string", "id": "lib.strings.escapeXML", "line": 482, "name": "escapeXML", }, { "category": "./lib/strings.nix", "description": "Converts an ASCII string to lower-case.", "example": "toLower "HOME" => "home"", "fn_type": "toLower :: string -> string", "id": "lib.strings.toLower", "line": 501, "name": "toLower", }, { "category": "./lib/strings.nix", "description": "Converts an ASCII string to upper-case.", "example": "toUpper "home" => "HOME"", "fn_type": "toUpper :: string -> string", "id": "lib.strings.toUpper", "line": 511, "name": "toUpper", }, { "category": "./lib/strings.nix", "description": "Appends string context from another string. This is an implementation detail of Nix and should be used carefully. Strings in Nix carry an invisible \`context\` which is a list of strings representing store paths. If the string is later used in a derivation attribute, the derivation will properly populate the inputDrvs and inputSrcs.", "example": "pkgs = import { }; addContextFrom pkgs.coreutils "bar" => "bar"", "fn_type": null, "id": "lib.strings.addContextFrom", "line": 526, "name": "addContextFrom", }, { "category": "./lib/strings.nix", "description": "Cut a string with a separator and produces a list of strings which were separated by this separator.", "example": "splitString "." "foo.bar.baz" => [ "foo" "bar" "baz" ] splitString "/" "/usr/local/bin" => [ "" "usr" "local" "bin" ]", "fn_type": null, "id": "lib.strings.splitString", "line": 537, "name": "splitString", }, { "category": "./lib/strings.nix", "description": "Return a string without the specified prefix, if the prefix matches.", "example": "removePrefix "foo." "foo.bar.baz" => "bar.baz" removePrefix "xxx" "foo.bar.baz" => "foo.bar.baz"", "fn_type": "string -> string -> string", "id": "lib.strings.removePrefix", "line": 553, "name": "removePrefix", }, { "category": "./lib/strings.nix", "description": "Return a string without the specified suffix, if the suffix matches.", "example": "removeSuffix "front" "homefront" => "home" removeSuffix "xxx" "homefront" => "homefront"", "fn_type": "string -> string -> string", "id": "lib.strings.removeSuffix", "line": 577, "name": "removeSuffix", }, { "category": "./lib/strings.nix", "description": "Return true if string v1 denotes a version older than v2.", "example": "versionOlder "1.1" "1.2" => true versionOlder "1.1" "1.1" => false", "fn_type": null, "id": "lib.strings.versionOlder", "line": 599, "name": "versionOlder", }, { "category": "./lib/strings.nix", "description": "Return true if string v1 denotes a version equal to or newer than v2.", "example": "versionAtLeast "1.1" "1.0" => true versionAtLeast "1.1" "1.1" => true versionAtLeast "1.1" "1.2" => false", "fn_type": null, "id": "lib.strings.versionAtLeast", "line": 611, "name": "versionAtLeast", }, { "category": "./lib/strings.nix", "description": "This function takes an argument that's either a derivation or a derivation's "name" attribute and extracts the name part from that argument.", "example": "getName "youtube-dl-2016.01.01" => "youtube-dl" getName pkgs.youtube-dl => "youtube-dl"", "fn_type": null, "id": "lib.strings.getName", "line": 623, "name": "getName", }, { "category": "./lib/strings.nix", "description": "This function takes an argument that's either a derivation or a derivation's "name" attribute and extracts the version part from that argument.", "example": "getVersion "youtube-dl-2016.01.01" => "2016.01.01" getVersion pkgs.youtube-dl => "2016.01.01"", "fn_type": null, "id": "lib.strings.getVersion", "line": 640, "name": "getVersion", }, { "category": "./lib/strings.nix", "description": "Extract name with version from URL. Ask for separator which is supposed to start extension.", "example": "nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "-" => "nix" nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "_" => "nix-1.7-x86"", "fn_type": null, "id": "lib.strings.nameFromURL", "line": 656, "name": "nameFromURL", }, { "category": "./lib/strings.nix", "description": "Create a -D= string that can be passed to typical Meson invocations.", "example": "mesonOption "engine" "opengl" => "-Dengine=opengl"", "fn_type": "mesonOption :: string -> string -> string @param feature The feature to be set @param value The desired value", "id": "lib.strings.mesonOption", "line": 675, "name": "mesonOption", }, { "category": "./lib/strings.nix", "description": "Create a -D={true,false} string that can be passed to typical Meson invocations.", "example": "mesonBool "hardened" true => "-Dhardened=true" mesonBool "static" false => "-Dstatic=false"", "fn_type": "mesonBool :: string -> bool -> string @param condition The condition to be made true or false @param flag The controlling flag of the condition", "id": "lib.strings.mesonBool", "line": 694, "name": "mesonBool", }, { "category": "./lib/strings.nix", "description": "Create a -D={enabled,disabled} string that can be passed to typical Meson invocations.", "example": "mesonEnable "docs" true => "-Ddocs=enabled" mesonEnable "savage" false => "-Dsavage=disabled"", "fn_type": "mesonEnable :: string -> bool -> string @param feature The feature to be enabled or disabled @param flag The controlling flag", "id": "lib.strings.mesonEnable", "line": 713, "name": "mesonEnable", }, { "category": "./lib/strings.nix", "description": "Create an --{enable,disable}- string that can be passed to standard GNU Autoconf scripts.", "example": "enableFeature true "shared" => "--enable-shared" enableFeature false "shared" => "--disable-shared"", "fn_type": null, "id": "lib.strings.enableFeature", "line": 727, "name": "enableFeature", }, { "category": "./lib/strings.nix", "description": "Create an --{enable-=,disable-} string that can be passed to standard GNU Autoconf scripts.", "example": "enableFeatureAs true "shared" "foo" => "--enable-shared=foo" enableFeatureAs false "shared" (throw "ignored") => "--disable-shared"", "fn_type": null, "id": "lib.strings.enableFeatureAs", "line": 740, "name": "enableFeatureAs", }, { "category": "./lib/strings.nix", "description": "Create an --{with,without}- string that can be passed to standard GNU Autoconf scripts.", "example": "withFeature true "shared" => "--with-shared" withFeature false "shared" => "--without-shared"", "fn_type": null, "id": "lib.strings.withFeature", "line": 751, "name": "withFeature", }, { "category": "./lib/strings.nix", "description": "Create an --{with-=,without-} string that can be passed to standard GNU Autoconf scripts.", "example": "withFeatureAs true "shared" "foo" => "--with-shared=foo" withFeatureAs false "shared" (throw "ignored") => "--without-shared"", "fn_type": null, "id": "lib.strings.withFeatureAs", "line": 764, "name": "withFeatureAs", }, { "category": "./lib/strings.nix", "description": "Create a fixed width string with additional prefix to match required width. This function will fail if the input string is longer than the requested length.", "example": "fixedWidthString 5 "0" (toString 15) => "00015"", "fn_type": "fixedWidthString :: int -> string -> string -> string", "id": "lib.strings.fixedWidthString", "line": 778, "name": "fixedWidthString", }, { "category": "./lib/strings.nix", "description": "Format a number adding leading zeroes up to fixed width.", "example": "fixedWidthNumber 5 15 => "00015"", "fn_type": null, "id": "lib.strings.fixedWidthNumber", "line": 795, "name": "fixedWidthNumber", }, { "category": "./lib/strings.nix", "description": "Convert a float to a string, but emit a warning when precision is lost during the conversion", "example": "floatToString 0.000001 => "0.000001" floatToString 0.0000001 => trace: warning: Imprecise conversion from float to string 0.000000 "0.000000"", "fn_type": null, "id": "lib.strings.floatToString", "line": 807, "name": "floatToString", }, { "category": "./lib/strings.nix", "description": "Soft-deprecated function. While the original implementation is available as isConvertibleWithToString, consider using isStringLike instead, if suitable.", "example": null, "fn_type": null, "id": "lib.strings.isCoercibleToString", "line": 815, "name": "isCoercibleToString", }, { "category": "./lib/strings.nix", "description": "Check whether a list or other value can be passed to toString. Many types of value are coercible to string this way, including int, float, null, bool, list of similarly coercible values.", "example": null, "fn_type": null, "id": "lib.strings.isConvertibleWithToString", "line": 824, "name": "isConvertibleWithToString", }, { "category": "./lib/strings.nix", "description": "Check whether a value can be coerced to a string. The value must be a string, path, or attribute set. String-like values can be used without explicit conversion in string interpolations and in most functions that expect a string.", "example": null, "fn_type": null, "id": "lib.strings.isStringLike", "line": 835, "name": "isStringLike", }, { "category": "./lib/strings.nix", "description": "Check whether a value is a store path.", "example": "isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11/bin/python" => false isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11" => true isStorePath pkgs.python => true isStorePath [] || isStorePath 42 || isStorePath {} || … => false", "fn_type": null, "id": "lib.strings.isStorePath", "line": 853, "name": "isStorePath", }, { "category": "./lib/strings.nix", "description": "Parse a string as an int. Does not support parsing of integers with preceding zero due to ambiguity between zero-padded and octal numbers. See toIntBase10.", "example": "toInt "1337" => 1337 toInt "-4" => -4 toInt " 123 " => 123 toInt "00024" => error: Ambiguity in interpretation of 00024 between octal and zero padded integer. toInt "3.14" => error: floating point JSON numbers are not supported", "fn_type": "string -> int", "id": "lib.strings.toInt", "line": 884, "name": "toInt", }, { "category": "./lib/strings.nix", "description": "Parse a string as a base 10 int. This supports parsing of zero-padded integers.", "example": "toIntBase10 "1337" => 1337 toIntBase10 "-4" => -4 toIntBase10 " 123 " => 123 toIntBase10 "00024" => 24 toIntBase10 "3.14" => error: floating point JSON numbers are not supported", "fn_type": "string -> int", "id": "lib.strings.toIntBase10", "line": 934, "name": "toIntBase10", }, { "category": "./lib/strings.nix", "description": "Read a list of paths from \`file\`, relative to the \`rootPath\`. Lines beginning with \`#\` are treated as comments and ignored. Whitespace is significant. NOTE: This function is not performant and should be avoided.", "example": "readPathsFromFile /prefix ./pkgs/development/libraries/qt-5/5.4/qtbase/series => [ "/prefix/dlopen-resolv.patch" "/prefix/tzdir.patch" "/prefix/dlopen-libXcursor.patch" "/prefix/dlopen-openssl.patch" "/prefix/dlopen-dbus.patch" "/prefix/xdg-config-dirs.patch" "/prefix/nix-profiles-library-paths.patch" "/prefix/compose-search-path.patch" ]", "fn_type": null, "id": "lib.strings.readPathsFromFile", "line": 977, "name": "readPathsFromFile", }, { "category": "./lib/strings.nix", "description": "Read the contents of a file removing the trailing \\n", "example": "$ echo "1.0" > ./version fileContents ./version => "1.0"", "fn_type": "fileContents :: path -> string", "id": "lib.strings.fileContents", "line": 997, "name": "fileContents", }, { "category": "./lib/strings.nix", "description": "Creates a valid derivation name from a potentially invalid one.", "example": "sanitizeDerivationName "../hello.bar # foo" => "-hello.bar-foo" sanitizeDerivationName "" => "unknown" sanitizeDerivationName pkgs.hello => "-nix-store-2g75chlbpxlrqn15zlby2dfh8hr9qwbk-hello-2.10"", "fn_type": "sanitizeDerivationName :: String -> String", "id": "lib.strings.sanitizeDerivationName", "line": 1012, "name": "sanitizeDerivationName", }, { "category": "./lib/strings.nix", "description": "Computes the Levenshtein distance between two strings. Complexity O(n*m) where n and m are the lengths of the strings. Algorithm adjusted from https://stackoverflow.com/a/9750974/6605742", "example": "levenshtein "foo" "foo" => 0 levenshtein "book" "hook" => 1 levenshtein "hello" "Heyo" => 3", "fn_type": "levenshtein :: string -> string -> int", "id": "lib.strings.levenshtein", "line": 1051, "name": "levenshtein", }, { "category": "./lib/strings.nix", "description": "Returns the length of the prefix common to both strings.", "example": null, "fn_type": null, "id": "lib.strings.commonPrefixLength", "line": 1072, "name": "commonPrefixLength", }, { "category": "./lib/strings.nix", "description": "Returns the length of the suffix common to both strings.", "example": null, "fn_type": null, "id": "lib.strings.commonSuffixLength", "line": 1080, "name": "commonSuffixLength", }, { "category": "./lib/strings.nix", "description": "Returns whether the levenshtein distance between two strings is at most some value Complexity is O(min(n,m)) for k <= 2 and O(n*m) otherwise", "example": "levenshteinAtMost 0 "foo" "foo" => true levenshteinAtMost 1 "foo" "boa" => false levenshteinAtMost 2 "foo" "boa" => true levenshteinAtMost 2 "This is a sentence" "this is a sentense." => false levenshteinAtMost 3 "This is a sentence" "this is a sentense." => true", "fn_type": "levenshteinAtMost :: int -> string -> string -> bool", "id": "lib.strings.levenshteinAtMost", "line": 1104, "name": "levenshteinAtMost", }, { "category": "./lib/strings-with-deps.nix", "description": "!!! The interface of this function is kind of messed up, since it's way too overloaded and almost but not quite computes a topological sort of the depstrings.", "example": null, "fn_type": null, "id": "lib.strings-with-deps.textClosureList", "line": 59, "name": "textClosureList", }, { "category": "./lib/sources.nix", "description": "Returns the type of a path: regular (for file), symlink, or directory.", "example": null, "fn_type": null, "id": "lib.sources.pathType", "line": 25, "name": "pathType", }, { "category": "./lib/sources.nix", "description": "Returns true if the path exists and is a directory, false otherwise.", "example": null, "fn_type": null, "id": "lib.sources.pathIsDirectory", "line": 30, "name": "pathIsDirectory", }, { "category": "./lib/sources.nix", "description": "Returns true if the path exists and is a regular file, false otherwise.", "example": null, "fn_type": null, "id": "lib.sources.pathIsRegularFile", "line": 35, "name": "pathIsRegularFile", }, { "category": "./lib/sources.nix", "description": "A basic filter for \`cleanSourceWith\` that removes directories of version control system, backup files (*~) and some generated files.", "example": null, "fn_type": null, "id": "lib.sources.cleanSourceFilter", "line": 42, "name": "cleanSourceFilter", }, { "category": "./lib/sources.nix", "description": "Filters a source tree removing version control files and directories using cleanSourceFilter.", "example": "cleanSource ./.", "fn_type": null, "id": "lib.sources.cleanSource", "line": 65, "name": "cleanSource", }, { "category": "./lib/sources.nix", "description": "Like \`builtins.filterSource\`, except it will compose with itself, allowing you to chain multiple calls together without any intermediate copies being put in the nix store.", "example": "lib.cleanSourceWith { filter = f; src = lib.cleanSourceWith { filter = g; src = ./.; }; } # Succeeds! builtins.filterSource f (builtins.filterSource g ./.) # Fails!", "fn_type": null, "id": "lib.sources.cleanSourceWith", "line": 86, "name": "cleanSourceWith", }, { "category": "./lib/sources.nix", "description": "Add logging to a source, for troubleshooting the filtering behavior.", "example": null, "fn_type": "sources.trace :: sourceLike -> Source", "id": "lib.sources.trace", "line": 114, "name": "trace", }, { "category": "./lib/sources.nix", "description": "Filter sources by a list of regular expressions.", "example": "src = sourceByRegex ./my-subproject [".*\\.py$" "^database.sql$"]", "fn_type": null, "id": "lib.sources.sourceByRegex", "line": 137, "name": "sourceByRegex", }, { "category": "./lib/sources.nix", "description": "Get all files ending with the specified suffices from the given source directory or its descendants, omitting files that do not match any suffix. The result of the example below will include files like \`./dir/module.c\` and \`./dir/subdir/doc.xml\` if present.", "example": "sourceFilesBySuffices ./. [ ".xml" ".c" ]", "fn_type": "sourceLike -> [String] -> Source", "id": "lib.sources.sourceFilesBySuffices", "line": 159, "name": "sourceFilesBySuffices", }, { "category": "./lib/sources.nix", "description": "Get the commit id of a git repo.", "example": "commitIdFromGitRepo ", "fn_type": null, "id": "lib.sources.commitIdFromGitRepo", "line": 176, "name": "commitIdFromGitRepo", }, { "category": "./lib/options.nix", "description": "Returns true when the given argument is an option", "example": "isOption 1 // => false isOption (mkOption {}) // => true", "fn_type": "isOption :: a -> bool", "id": "lib.options.isOption", "line": 56, "name": "isOption", }, { "category": "./lib/options.nix", "description": "Creates an Option attribute set. mkOption accepts an attribute set with the following keys: All keys default to \`null\` when not given.", "example": "mkOption { } // => { _type = "option"; } mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; }", "fn_type": null, "id": "lib.options.mkOption", "line": 66, "name": "mkOption", }, { "category": "./lib/options.nix", "description": "Creates an Option attribute set for a boolean value option i.e an option to be toggled on or off:", "example": "mkEnableOption "foo" => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }", "fn_type": null, "id": "lib.options.mkEnableOption", "line": 98, "name": "mkEnableOption", }, { "category": "./lib/options.nix", "description": "Creates an Option attribute set for an option that specifies the package a module should use for some purpose.", "example": "mkPackageOption pkgs "hello" { } => { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; } mkPackageOption pkgs "GHC" { default = [ "ghc" ]; example = "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])"; } => { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; } mkPackageOption pkgs [ "python39Packages" "pytorch" ] { extraDescription = "This is an example and doesn't actually do anything."; } => { _type = "option"; default = «derivation /nix/store/gvqgsnc4fif9whvwd9ppa568yxbkmvk8-python3.9-pytorch-1.10.2.drv»; defaultText = { ... }; description = "The pytorch package to use. This is an example and doesn't actually do anything."; type = { ... }; }", "fn_type": "mkPackageOption :: pkgs -> (string|[string]) -> { default? :: [string], example? :: null|string|[string], extraDescription? :: string } -> option The package is specified in the third argument under \`default\` as a list of strings representing its attribute path in nixpkgs (or another package set). Because of this, you need to pass nixpkgs itself (or a subset) as the first argument. The second argument may be either a string or a list of strings. It provides the display name of the package in the description of the generated option (using only the last element if the passed value is a list) and serves as the fallback value for the \`default\` argument. To include extra information in the description, pass \`extraDescription\` to append arbitrary text to the generated description. You can also pass an \`example\` value, either a literal string or an attribute path. The default argument can be omitted if the provided name is an attribute of pkgs (if name is a string) or a valid attribute path in pkgs (if name is a list). If you wish to explicitly provide no default, pass \`null\` as \`default\`.", "id": "lib.options.mkPackageOption", "line": 154, "name": "mkPackageOption", }, { "category": "./lib/options.nix", "description": "Like mkPackageOption, but emit an mdDoc description instead of DocBook.", "example": null, "fn_type": null, "id": "lib.options.mkPackageOptionMD", "line": 184, "name": "mkPackageOptionMD", }, { "category": "./lib/options.nix", "description": "This option accepts anything, but it does not produce any result. This is useful for sharing a module across different module sets without having to implement similar features as long as the values of the options are not accessed.", "example": null, "fn_type": null, "id": "lib.options.mkSinkUndeclaredOptions", "line": 193, "name": "mkSinkUndeclaredOptions", }, { "category": "./lib/options.nix", "description": ""Merge" option definitions by checking that they all have the same value.", "example": null, "fn_type": null, "id": "lib.options.mergeEqualOption", "line": 226, "name": "mergeEqualOption", }, { "category": "./lib/options.nix", "description": "Extracts values of all "value" keys of the given list.", "example": "getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ] getValues [ ] // => [ ]", "fn_type": "getValues :: [ { value :: a; } ] -> [a]", "id": "lib.options.getValues", "line": 246, "name": "getValues", }, { "category": "./lib/options.nix", "description": "Extracts values of all "file" keys of the given list", "example": "getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ] getFiles [ ] // => [ ]", "fn_type": "getFiles :: [ { file :: a; } ] -> [a]", "id": "lib.options.getFiles", "line": 256, "name": "getFiles", }, { "category": "./lib/options.nix", "description": "This function recursively removes all derivation attributes from \`x\` except for the \`name\` attribute. This is to make the generation of \`options.xml\` much more efficient: the XML representation of derivations is very large (on the order of megabytes) and is not actually used by the manual generator. This function was made obsolete by renderOptionValue and is kept for compatibility with out-of-tree code.", "example": null, "fn_type": null, "id": "lib.options.scrubOptionValue", "line": 314, "name": "scrubOptionValue", }, { "category": "./lib/options.nix", "description": "Ensures that the given option value (default or example) is a \`_type\`d string by rendering Nix values to \`literalExpression\`s.", "example": null, "fn_type": null, "id": "lib.options.renderOptionValue", "line": 325, "name": "renderOptionValue", }, { "category": "./lib/options.nix", "description": "For use in the \`defaultText\` and \`example\` option attributes. Causes the given string to be rendered verbatim in the documentation as Nix code. This is necessary for complex values, e.g. functions, or values that depend on other values or packages.", "example": null, "fn_type": null, "id": "lib.options.literalExpression", "line": 338, "name": "literalExpression", }, { "category": "./lib/options.nix", "description": "For use in the \`defaultText\` and \`example\` option attributes. Causes the given DocBook text to be inserted verbatim in the documentation, for when a \`literalExpression\` would be too hard to read.", "example": null, "fn_type": null, "id": "lib.options.literalDocBook", "line": 349, "name": "literalDocBook", }, { "category": "./lib/options.nix", "description": "Transition marker for documentation that's already migrated to markdown syntax.", "example": null, "fn_type": null, "id": "lib.options.mdDoc", "line": 359, "name": "mdDoc", }, { "category": "./lib/options.nix", "description": "For use in the \`defaultText\` and \`example\` option attributes. Causes the given MD text to be inserted verbatim in the documentation, for when a \`literalExpression\` would be too hard to read.", "example": null, "fn_type": null, "id": "lib.options.literalMD", "line": 367, "name": "literalMD", }, { "category": "./lib/options.nix", "description": "Convert an option, described as a list of the option parts to a human-readable version.", "example": "(showOption ["foo" "bar" "baz"]) == "foo.bar.baz" (showOption ["foo" "bar.baz" "tux"]) == "foo.\\"bar.baz\\".tux" (showOption ["windowManager" "2bwm" "enable"]) == "windowManager.\\"2bwm\\".enable" Placeholders will not be quoted as they are not actual values: (showOption ["foo" "*" "bar"]) == "foo.*.bar" (showOption ["foo" "" "bar"]) == "foo..bar"", "fn_type": null, "id": "lib.options.showOption", "line": 385, "name": "showOption", }, { "category": "./lib/modules.nix", "description": "Evaluate a set of modules. The result is a set with the attributes: ‘options’: The nested set of all option declarations, ‘config’: The nested set of all option values. ‘type’: A module system type representing the module set as a submodule, to be extended by configuration from the containing module set. This is also available as the module argument ‘moduleType’. ‘extendModules’: A function similar to ‘evalModules’ but building on top of the module set. Its arguments, ‘modules’ and ‘specialArgs’ are added to the existing values. Using ‘extendModules’ a few times has no performance impact as long as you only reference the final ‘options’ and ‘config’. If you do reference multiple ‘config’ (or ‘options’) from before and after ‘extendModules’, performance is the same as with multiple ‘evalModules’ invocations, because the new modules' ability to override existing configuration fundamentally requires a new fixpoint to be constructed. This is also available as a module argument. ‘_module’: A portion of the configuration tree which is elided from ‘config’. It contains some values that are mostly internal to the module system implementation. !!! Please think twice before adding to this argument list! The more that is specified here instead of in the modules themselves the harder it is to transparently move a set of modules to be a submodule of another config (as the proper arguments need to be replicated at each call to evalModules) and the less declarative the module set is.", "example": null, "fn_type": null, "id": "lib.modules.evalModules", "line": 103, "name": "evalModules", }, { "category": "./lib/modules.nix", "description": "Collects all modules recursively into the form { disabled = [ ]; # All modules of the main module list modules = [ { key = ; module = ; # All modules imported by the module for key1 modules = [ { key = ; module = ; # All modules imported by the module for key1-1 modules = [ ... ]; } ... ]; } ... ]; }", "example": null, "fn_type": null, "id": "lib.modules.collectStructuredModules", "line": 394, "name": "collectStructuredModules", }, { "category": "./lib/modules.nix", "description": "Wrap a module with a default location for reporting errors.", "example": null, "fn_type": null, "id": "lib.modules.setDefaultModuleLocation", "line": 430, "name": "setDefaultModuleLocation", }, { "category": "./lib/modules.nix", "description": "Massage a module into canonical form, that is, a set consisting of ‘options’, ‘config’ and ‘imports’ attributes.", "example": null, "fn_type": null, "id": "lib.modules.unifyModuleSyntax", "line": 437, "name": "unifyModuleSyntax", }, { "category": "./lib/modules.nix", "description": "Merge a list of modules. This will recurse over the option declarations in all modules, combining them into a single set. At the same time, for each option declaration, it will merge the corresponding option definitions in all machines, returning them in the ‘value’ attribute of each option. This returns a set like { # A recursive set of options along with their final values matchedOptions = { foo = { _type = "option"; value = "option value of foo"; ... }; bar.baz = { _type = "option"; value = "option value of bar.baz"; ... }; ... }; # A list of definitions that weren't matched by any option unmatchedDefns = [ { file = "file.nix"; prefix = [ "qux" ]; value = "qux"; } ... ]; }", "example": null, "fn_type": null, "id": "lib.modules.mergeModules", "line": 517, "name": "mergeModules", }, { "category": "./lib/modules.nix", "description": "byName is like foldAttrs, but will look for attributes to merge in the specified attribute name. byName "foo" (module: value: ["module.hidden=\${module.hidden},value=\${value}"]) [ { hidden="baz"; foo={qux="bar"; gla="flop";}; } { hidden="fli"; foo={qux="gne"; gli="flip";}; } ] ===> { gla = [ "module.hidden=baz,value=flop" ]; gli = [ "module.hidden=fli,value=flip" ]; qux = [ "module.hidden=baz,value=bar" "module.hidden=fli,value=gne" ]; }", "example": null, "fn_type": null, "id": "lib.modules.byName", "line": 544, "name": "byName", }, { "category": "./lib/modules.nix", "description": "Merge multiple option declarations into a single declaration. In general, there should be only one declaration of each option. The exception is the ‘options’ attribute, which specifies sub-options. These can be specified multiple times to allow one module to add sub-options to an option declared somewhere else (e.g. multiple modules define sub-options for ‘fileSystems’). 'loc' is the list of attribute names where the option is located. 'opts' is a list of modules. Each module has an options attribute which correspond to the definition of 'loc' in 'opt.file'.", "example": null, "fn_type": null, "id": "lib.modules.mergeOptionDecls", "line": 670, "name": "mergeOptionDecls", }, { "category": "./lib/modules.nix", "description": "Merge all the definitions of an option to produce the final config value.", "example": null, "fn_type": null, "id": "lib.modules.evalOptionValue", "line": 702, "name": "evalOptionValue", }, { "category": "./lib/modules.nix", "description": "Given a config set, expand mkMerge properties, and push down the other properties into the children. The result is a list of config sets that do not have properties at top-level. For example, mkMerge [ { boot = set1; } (mkIf cond { boot = set2; services = set3; }) ] is transformed into [ { boot = set1; } { boot = mkIf cond set2; services = mkIf cond set3; } ]. This transform is the critical step that allows mkIf conditions to refer to the full configuration without creating an infinite recursion.", "example": null, "fn_type": null, "id": "lib.modules.pushDownProperties", "line": 797, "name": "pushDownProperties", }, { "category": "./lib/modules.nix", "description": "Given a config value, expand mkMerge properties, and discharge any mkIf conditions. That is, this is the place where mkIf conditions are actually evaluated. The result is a list of config values. For example, ‘mkIf false x’ yields ‘[]’, ‘mkIf true x’ yields ‘[x]’, and mkMerge [ 1 (mkIf true 2) (mkIf true (mkIf false 3)) ] yields ‘[ 1 2 ]’.", "example": null, "fn_type": null, "id": "lib.modules.dischargeProperties", "line": 818, "name": "dischargeProperties", }, { "category": "./lib/modules.nix", "description": "Given a list of config values, process the mkOverride properties, that is, return the values that have the highest (that is, numerically lowest) priority, and strip the mkOverride properties. For example, [ { file = "/1"; value = mkOverride 10 "a"; } { file = "/2"; value = mkOverride 20 "b"; } { file = "/3"; value = "z"; } { file = "/4"; value = mkOverride 10 "d"; } ] yields [ { file = "/1"; value = "a"; } { file = "/4"; value = "d"; } ] Note that "z" has the default priority 100.", "example": null, "fn_type": null, "id": "lib.modules.filterOverrides", "line": 852, "name": "filterOverrides", }, { "category": "./lib/modules.nix", "description": "Sort a list of properties. The sort priority of a property is defaultOrderPriority by default, but can be overridden by wrapping the property using mkOrder.", "example": null, "fn_type": null, "id": "lib.modules.sortProperties", "line": 867, "name": "sortProperties", }, { "category": "./lib/modules.nix", "description": "Properties.", "example": null, "fn_type": null, "id": "lib.modules.mkIf", "line": 889, "name": "mkIf", }, { "category": "./lib/modules.nix", "description": "Compatibility.", "example": null, "fn_type": null, "id": "lib.modules.fixMergeModules", "line": 964, "name": "fixMergeModules", }, { "category": "./lib/modules.nix", "description": "Return a module that causes a warning to be shown if the specified option is defined. For example, mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "" causes a assertion if the user defines boot.loader.grub.bootDevice. replacementInstructions is a string that provides instructions on how to achieve the same functionality without the removed option, or alternatively a reasoning why the functionality is not needed. replacementInstructions SHOULD be provided!", "example": null, "fn_type": null, "id": "lib.modules.mkRemovedOptionModule", "line": 978, "name": "mkRemovedOptionModule", }, { "category": "./lib/modules.nix", "description": "Return a module that causes a warning to be shown if the specified "from" option is defined; the defined value is however forwarded to the "to" option. This can be used to rename options while providing backward compatibility. For example, mkRenamedOptionModule [ "boot" "copyKernels" ] [ "boot" "loader" "grub" "copyKernels" ] forwards any definitions of boot.copyKernels to boot.loader.grub.copyKernels while printing a warning. This also copies over the priority from the aliased option to the non-aliased option.", "example": null, "fn_type": null, "id": "lib.modules.mkRenamedOptionModule", "line": 1009, "name": "mkRenamedOptionModule", }, { "category": "./lib/modules.nix", "description": "Return a module that causes a warning to be shown if any of the "from" option is defined; the defined values can be used in the "mergeFn" to set the "to" value. This function can be used to merge multiple options into one that has a different type. "mergeFn" takes the module "config" as a parameter and must return a value of "to" option type. mkMergedOptionModule [ [ "a" "b" "c" ] [ "d" "e" "f" ] ] [ "x" "y" "z" ] (config: let value = p: getAttrFromPath p config; in if (value [ "a" "b" "c" ]) == true then "foo" else if (value [ "d" "e" "f" ]) == true then "bar" else "baz") - options.a.b.c is a removed boolean option - options.d.e.f is a removed boolean option - options.x.y.z is a new str option that combines a.b.c and d.e.f functionality This show a warning if any a.b.c or d.e.f is set, and set the value of x.y.z to the result of the merge function", "example": null, "fn_type": null, "id": "lib.modules.mkMergedOptionModule", "line": 1063, "name": "mkMergedOptionModule", }, { "category": "./lib/modules.nix", "description": "Single "from" version of mkMergedOptionModule. Return a module that causes a warning to be shown if the "from" option is defined; the defined value can be used in the "mergeFn" to set the "to" value. This function can be used to change an option into another that has a different type. "mergeFn" takes the module "config" as a parameter and must return a value of "to" option type. mkChangedOptionModule [ "a" "b" "c" ] [ "x" "y" "z" ] (config: let value = getAttrFromPath [ "a" "b" "c" ] config; in if value > 100 then "high" else "normal") - options.a.b.c is a removed int option - options.x.y.z is a new str option that supersedes a.b.c This show a warning if a.b.c is set, and set the value of x.y.z to the result of the change function", "example": null, "fn_type": null, "id": "lib.modules.mkChangedOptionModule", "line": 1110, "name": "mkChangedOptionModule", }, { "category": "./lib/modules.nix", "description": "Like ‘mkRenamedOptionModule’, but doesn't show a warning.", "example": null, "fn_type": null, "id": "lib.modules.mkAliasOptionModule", "line": 1118, "name": "mkAliasOptionModule", }, { "category": "./lib/modules.nix", "description": "Transitional version of mkAliasOptionModule that uses MD docs.", "example": null, "fn_type": null, "id": "lib.modules.mkAliasOptionModuleMD", "line": 1124, "name": "mkAliasOptionModuleMD", }, { "category": "./lib/modules.nix", "description": "mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b Create config definitions with the same priority as the definition of another option. This should be used for option definitions where one option sets the value of another as a convenience. For instance a config file could be set with a \`text\` or \`source\` option, where text translates to a \`source\` value using \`mkDerivedConfig options.text (pkgs.writeText "filename.conf")\`. It takes care of setting the right priority using \`mkOverride\`.", "example": null, "fn_type": null, "id": "lib.modules.mkDerivedConfig", "line": 1147, "name": "mkDerivedConfig", }, { "category": "./lib/modules.nix", "description": "Use this function to import a JSON file as NixOS configuration. modules.importJSON :: path -> attrs", "example": null, "fn_type": null, "id": "lib.modules.importJSON", "line": 1185, "name": "importJSON", }, { "category": "./lib/modules.nix", "description": "Use this function to import a TOML file as NixOS configuration. modules.importTOML :: path -> attrs", "example": null, "fn_type": null, "id": "lib.modules.importTOML", "line": null, "name": "importTOML", }, { "category": "./lib/meta.nix", "description": "Add to or override the meta attributes of the given derivation.", "example": "addMetaAttrs {description = "Bla blah";} somePkg", "fn_type": null, "id": "lib.meta.addMetaAttrs", "line": 15, "name": "addMetaAttrs", }, { "category": "./lib/meta.nix", "description": "Disable Hydra builds of given derivation.", "example": null, "fn_type": null, "id": "lib.meta.dontDistribute", "line": 21, "name": "dontDistribute", }, { "category": "./lib/meta.nix", "description": "Change the symbolic name of a package for presentation purposes (i.e., so that nix-env users can tell them apart).", "example": null, "fn_type": null, "id": "lib.meta.setName", "line": 27, "name": "setName", }, { "category": "./lib/meta.nix", "description": "Like \`setName\`, but takes the previous name as an argument.", "example": "updateName (oldName: oldName + "-experimental") somePkg", "fn_type": null, "id": "lib.meta.updateName", "line": 35, "name": "updateName", }, { "category": "./lib/meta.nix", "description": "Append a suffix to the name of a package (before the version part).", "example": null, "fn_type": null, "id": "lib.meta.appendToName", "line": 40, "name": "appendToName", }, { "category": "./lib/meta.nix", "description": "Apply a function to each derivation and only to derivations in an attrset.", "example": null, "fn_type": null, "id": "lib.meta.mapDerivationAttrset", "line": 46, "name": "mapDerivationAttrset", }, { "category": "./lib/meta.nix", "description": "Set the nix-env priority of the package.", "example": null, "fn_type": null, "id": "lib.meta.setPrio", "line": 50, "name": "setPrio", }, { "category": "./lib/meta.nix", "description": "Decrease the nix-env priority of the package, i.e., other versions/variants of the package will be preferred.", "example": null, "fn_type": null, "id": "lib.meta.lowPrio", "line": 55, "name": "lowPrio", }, { "category": "./lib/meta.nix", "description": "Apply lowPrio to an attrset with derivations", "example": null, "fn_type": null, "id": "lib.meta.lowPrioSet", "line": 59, "name": "lowPrioSet", }, { "category": "./lib/meta.nix", "description": "Increase the nix-env priority of the package, i.e., this version/variant of the package will be preferred.", "example": null, "fn_type": null, "id": "lib.meta.hiPrio", "line": 65, "name": "hiPrio", }, { "category": "./lib/meta.nix", "description": "Apply hiPrio to an attrset with derivations", "example": null, "fn_type": null, "id": "lib.meta.hiPrioSet", "line": 69, "name": "hiPrioSet", }, { "category": "./lib/meta.nix", "description": "Check to see if a platform is matched by the given \`meta.platforms\` element. A \`meta.platform\` pattern is either 1. (legacy) a system string. 2. (modern) a pattern for the entire platform structure (see \`lib.systems.inspect.platformPatterns\`). 3. (modern) a pattern for the platform \`parsed\` field (see \`lib.systems.inspect.patterns\`). We can inject these into a pattern for the whole of a structured platform, and then match that.", "example": null, "fn_type": null, "id": "lib.meta.platformMatch", "line": 86, "name": "platformMatch", }, { "category": "./lib/meta.nix", "description": "Check if a package is available on a given platform. A package is available on a platform if both 1. One of \`meta.platforms\` pattern matches the given platform, or \`meta.platforms\` is not present. 2. None of \`meta.badPlatforms\` pattern matches the given platform.", "example": null, "fn_type": null, "id": "lib.meta.availableOn", "line": 104, "name": "availableOn", }, { "category": "./lib/meta.nix", "description": "Get the corresponding attribute in lib.licenses from the SPDX ID. For SPDX IDs, see https://spdx.org/licenses", "example": "lib.getLicenseFromSpdxId "MIT" == lib.licenses.mit => true lib.getLicenseFromSpdxId "mIt" == lib.licenses.mit => true lib.getLicenseFromSpdxId "MY LICENSE" => trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE => { shortName = "MY LICENSE"; }", "fn_type": "getLicenseFromSpdxId :: str -> AttrSet", "id": "lib.meta.getLicenseFromSpdxId", "line": 125, "name": "getLicenseFromSpdxId", }, { "category": "./lib/meta.nix", "description": "Get the path to the main program of a derivation with either meta.mainProgram or pname or name", "example": "getExe pkgs.hello => "/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello" getExe pkgs.mustache-go => "/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache"", "fn_type": "getExe :: derivation -> string", "id": "lib.meta.getExe", "line": 146, "name": "getExe", }, { "category": "./lib/lists.nix", "description": "Create a list consisting of a single element. \`singleton x\` is sometimes more convenient with respect to indentation than \`[x]\` when x spans multiple lines.", "example": "singleton "foo" => [ "foo" ]", "fn_type": "singleton :: a -> [a]", "id": "lib.lists.singleton", "line": 23, "name": "singleton", }, { "category": "./lib/lists.nix", "description": "Apply the function to each element in the list. Same as \`map\`, but arguments flipped.", "example": "forEach [ 1 2 ] (x: toString x ) => [ "1" "2" ]", "fn_type": "forEach :: [a] -> (a -> b) -> [b]", "id": "lib.lists.forEach", "line": 36, "name": "forEach", }, { "category": "./lib/lists.nix", "description": "“right fold” a binary function \`op\` between successive elements of \`list\` with \`nul\` as the starting value, i.e., \`foldr op nul [x_1 x_2 ... x_n] == op x_1 (op x_2 ... (op x_n nul))\`.", "example": "concat = foldr (a: b: a + b) "z" concat [ "a" "b" "c" ] => "abcz" # different types strange = foldr (int: str: toString (int + 1) + str) "a" strange [ 1 2 3 4 ] => "2345a"", "fn_type": "foldr :: (a -> b -> b) -> b -> [a] -> b", "id": "lib.lists.foldr", "line": 53, "name": "foldr", }, { "category": "./lib/lists.nix", "description": "\`fold\` is an alias of \`foldr\` for historic reasons", "example": null, "fn_type": null, "id": "lib.lists.fold", "line": 64, "name": "fold", }, { "category": "./lib/lists.nix", "description": "“left fold”, like \`foldr\`, but from the left: \`foldl op nul [x_1 x_2 ... x_n] == op (... (op (op nul x_1) x_2) ... x_n)\`.", "example": "lconcat = foldl (a: b: a + b) "z" lconcat [ "a" "b" "c" ] => "zabc" # different types lstrange = foldl (str: int: str + toString (int + 1)) "a" lstrange [ 1 2 3 4 ] => "a2345"", "fn_type": "foldl :: (b -> a -> b) -> b -> [a] -> b", "id": "lib.lists.foldl", "line": 81, "name": "foldl", }, { "category": "./lib/lists.nix", "description": "Strict version of \`foldl\`. The difference is that evaluation is forced upon access. Usually used with small whole results (in contrast with lazily-generated list or large lists where only a part is consumed.)", "example": null, "fn_type": "foldl' :: (b -> a -> b) -> b -> [a] -> b", "id": "lib.lists.foldl'", "line": 97, "name": "foldl'", }, { "category": "./lib/lists.nix", "description": "Map with index starting from 0", "example": "imap0 (i: v: "\${v}-\${toString i}") ["a" "b"] => [ "a-0" "b-1" ]", "fn_type": "imap0 :: (int -> a -> b) -> [a] -> [b]", "id": "lib.lists.imap0", "line": 107, "name": "imap0", }, { "category": "./lib/lists.nix", "description": "Map with index starting from 1", "example": "imap1 (i: v: "\${v}-\${toString i}") ["a" "b"] => [ "a-1" "b-2" ]", "fn_type": "imap1 :: (int -> a -> b) -> [a] -> [b]", "id": "lib.lists.imap1", "line": 117, "name": "imap1", }, { "category": "./lib/lists.nix", "description": "Map and concatenate the result.", "example": "concatMap (x: [x] ++ ["z"]) ["a" "b"] => [ "a" "z" "b" "z" ]", "fn_type": "concatMap :: (a -> [b]) -> [a] -> [b]", "id": "lib.lists.concatMap", "line": 127, "name": "concatMap", }, { "category": "./lib/lists.nix", "description": "Flatten the argument into a single list; that is, nested lists are spliced into the top-level lists.", "example": "flatten [1 [2 [3] 4] 5] => [1 2 3 4 5] flatten 1 => [1]", "fn_type": null, "id": "lib.lists.flatten", "line": 138, "name": "flatten", }, { "category": "./lib/lists.nix", "description": "Remove elements equal to 'e' from a list. Useful for buildInputs.", "example": "remove 3 [ 1 3 4 3 ] => [ 1 4 ]", "fn_type": "remove :: a -> [a] -> [a]", "id": "lib.lists.remove", "line": 152, "name": "remove", }, { "category": "./lib/lists.nix", "description": "Find the sole element in the list matching the specified predicate, returns \`default\` if no such element exists, or \`multiple\` if there are multiple matching elements.", "example": "findSingle (x: x == 3) "none" "multiple" [ 1 3 3 ] => "multiple" findSingle (x: x == 3) "none" "multiple" [ 1 3 ] => 3 findSingle (x: x == 3) "none" "multiple" [ 1 9 ] => "none"", "fn_type": "findSingle :: (a -> bool) -> a -> a -> [a] -> a", "id": "lib.lists.findSingle", "line": 169, "name": "findSingle", }, { "category": "./lib/lists.nix", "description": "Find the first element in the list matching the specified predicate or return \`default\` if no such element exists.", "example": "findFirst (x: x > 3) 7 [ 1 6 4 ] => 6 findFirst (x: x > 9) 7 [ 1 6 4 ] => 7", "fn_type": "findFirst :: (a -> bool) -> a -> [a] -> a", "id": "lib.lists.findFirst", "line": 194, "name": "findFirst", }, { "category": "./lib/lists.nix", "description": "Return true if function \`pred\` returns true for at least one element of \`list\`.", "example": "any isString [ 1 "a" { } ] => true any isString [ 1 { } ] => false", "fn_type": "any :: (a -> bool) -> [a] -> bool", "id": "lib.lists.any", "line": 215, "name": "any", }, { "category": "./lib/lists.nix", "description": "Return true if function \`pred\` returns true for all elements of \`list\`.", "example": "all (x: x < 3) [ 1 2 ] => true all (x: x < 3) [ 1 2 3 ] => false", "fn_type": "all :: (a -> bool) -> [a] -> bool", "id": "lib.lists.all", "line": 228, "name": "all", }, { "category": "./lib/lists.nix", "description": "Count how many elements of \`list\` match the supplied predicate function.", "example": "count (x: x == 3) [ 3 2 3 4 6 ] => 2", "fn_type": "count :: (a -> bool) -> [a] -> int", "id": "lib.lists.count", "line": 240, "name": "count", }, { "category": "./lib/lists.nix", "description": "Return a singleton list or an empty list, depending on a boolean value. Useful when building lists with optional elements (e.g. \`++ optional (system == "i686-linux") firefox\`).", "example": "optional true "foo" => [ "foo" ] optional false "foo" => [ ]", "fn_type": "optional :: bool -> a -> [a]", "id": "lib.lists.optional", "line": 255, "name": "optional", }, { "category": "./lib/lists.nix", "description": "Return a list or an empty list, depending on a boolean value.", "example": "optionals true [ 2 3 ] => [ 2 3 ] optionals false [ 2 3 ] => [ ]", "fn_type": "optionals :: bool -> [a] -> [a]", "id": "lib.lists.optionals", "line": 267, "name": "optionals", }, { "category": "./lib/lists.nix", "description": "If argument is a list, return it; else, wrap it in a singleton list. If you're using this, you should almost certainly reconsider if there isn't a more "well-typed" approach.", "example": "toList [ 1 2 ] => [ 1 2 ] toList "hi" => [ "hi "]", "fn_type": null, "id": "lib.lists.toList", "line": 284, "name": "toList", }, { "category": "./lib/lists.nix", "description": "Return a list of integers from \`first\` up to and including \`last\`.", "example": "range 2 4 => [ 2 3 4 ] range 3 2 => [ ]", "fn_type": "range :: int -> int -> [int]", "id": "lib.lists.range", "line": 297, "name": "range", }, { "category": "./lib/lists.nix", "description": "Return a list with \`n\` copies of an element.", "example": "replicate 3 "a" => [ "a" "a" "a" ] replicate 2 true => [ true true ]", "fn_type": "replicate :: int -> a -> [a]", "id": "lib.lists.replicate", "line": 316, "name": "replicate", }, { "category": "./lib/lists.nix", "description": "Splits the elements of a list in two lists, \`right\` and \`wrong\`, depending on the evaluation of a predicate.", "example": "partition (x: x > 2) [ 5 1 2 3 4 ] => { right = [ 5 3 4 ]; wrong = [ 1 2 ]; }", "fn_type": "(a -> bool) -> [a] -> { right :: [a]; wrong :: [a]; }", "id": "lib.lists.partition", "line": 327, "name": "partition", }, { "category": "./lib/lists.nix", "description": "Splits the elements of a list into many lists, using the return value of a predicate. Predicate should return a string which becomes keys of attrset \`groupBy\` returns. \`groupBy'\` allows to customise the combining function and initial value", "example": "groupBy (x: boolToString (x > 2)) [ 5 1 2 3 4 ] => { true = [ 5 3 4 ]; false = [ 1 2 ]; } groupBy (x: x.name) [ {name = "icewm"; script = "icewm &";} {name = "xfce"; script = "xfce4-session &";} {name = "icewm"; script = "icewmbg &";} {name = "mate"; script = "gnome-session &";} ] => { icewm = [ { name = "icewm"; script = "icewm &"; } { name = "icewm"; script = "icewmbg &"; } ]; mate = [ { name = "mate"; script = "gnome-session &"; } ]; xfce = [ { name = "xfce"; script = "xfce4-session &"; } ]; } groupBy' builtins.add 0 (x: boolToString (x > 2)) [ 5 1 2 3 4 ] => { true = 12; false = 3; }", "fn_type": null, "id": "lib.lists.groupBy'", "line": 356, "name": "groupBy'", }, { "category": "./lib/lists.nix", "description": "Merges two lists of the same size together. If the sizes aren't the same the merging stops at the shortest. How both lists are merged is defined by the first argument.", "example": "zipListsWith (a: b: a + b) ["h" "l"] ["e" "o"] => ["he" "lo"]", "fn_type": "zipListsWith :: (a -> b -> c) -> [a] -> [b] -> [c]", "id": "lib.lists.zipListsWith", "line": 376, "name": "zipListsWith", }, { "category": "./lib/lists.nix", "description": "Merges two lists of the same size together. If the sizes aren't the same the merging stops at the shortest.", "example": "zipLists [ 1 2 ] [ "a" "b" ] => [ { fst = 1; snd = "a"; } { fst = 2; snd = "b"; } ]", "fn_type": "zipLists :: [a] -> [b] -> [{ fst :: a; snd :: b; }]", "id": "lib.lists.zipLists", "line": 395, "name": "zipLists", }, { "category": "./lib/lists.nix", "description": "Reverse the order of the elements of a list.", "example": "reverseList [ "b" "o" "j" ] => [ "j" "o" "b" ]", "fn_type": "reverseList :: [a] -> [a]", "id": "lib.lists.reverseList", "line": 406, "name": "reverseList", }, { "category": "./lib/lists.nix", "description": "Depth-First Search (DFS) for lists \`list != []\`. \`before a b == true\` means that \`b\` depends on \`a\` (there's an edge from \`b\` to \`a\`).", "example": "listDfs true hasPrefix [ "/home/user" "other" "/" "/home" ] == { minimal = "/"; # minimal element visited = [ "/home/user" ]; # seen elements (in reverse order) rest = [ "/home" "other" ]; # everything else } listDfs true hasPrefix [ "/home/user" "other" "/" "/home" "/" ] == { cycle = "/"; # cycle encountered at this element loops = [ "/" ]; # and continues to these elements visited = [ "/" "/home/user" ]; # elements leading to the cycle (in reverse order) rest = [ "/home" "other" ]; # everything else", "fn_type": null, "id": "lib.lists.listDfs", "line": 428, "name": "listDfs", }, { "category": "./lib/lists.nix", "description": "Sort a list based on a partial ordering using DFS. This implementation is O(N^2), if your ordering is linear, use \`sort\` instead. \`before a b == true\` means that \`b\` should be after \`a\` in the result.", "example": "toposort hasPrefix [ "/home/user" "other" "/" "/home" ] == { result = [ "/" "/home" "/home/user" "other" ]; } toposort hasPrefix [ "/home/user" "other" "/" "/home" "/" ] == { cycle = [ "/home/user" "/" "/" ]; # path leading to a cycle loops = [ "/" ]; } # loops back to these elements toposort hasPrefix [ "other" "/home/user" "/home" "/" ] == { result = [ "other" "/" "/home" "/home/user" ]; } toposort (a: b: a < b) [ 3 2 1 ] == { result = [ 1 2 3 ]; }", "fn_type": null, "id": "lib.lists.toposort", "line": 467, "name": "toposort", }, { "category": "./lib/lists.nix", "description": "Sort a list based on a comparator function which compares two elements and returns true if the first argument is strictly below the second argument. The returned list is sorted in an increasing order. The implementation does a quick-sort.", "example": "sort (a: b: a < b) [ 5 3 7 ] => [ 3 5 7 ]", "fn_type": null, "id": "lib.lists.sort", "line": 495, "name": "sort", }, { "category": "./lib/lists.nix", "description": "Compare two lists element-by-element.", "example": "compareLists compare [] [] => 0 compareLists compare [] [ "a" ] => -1 compareLists compare [ "a" ] [] => 1 compareLists compare [ "a" "b" ] [ "a" "c" ] => -1", "fn_type": null, "id": "lib.lists.compareLists", "line": 524, "name": "compareLists", }, { "category": "./lib/lists.nix", "description": "Sort list using "Natural sorting". Numeric portions of strings are sorted in numeric order.", "example": "naturalSort ["disk11" "disk8" "disk100" "disk9"] => ["disk8" "disk9" "disk11" "disk100"] naturalSort ["10.46.133.149" "10.5.16.62" "10.54.16.25"] => ["10.5.16.62" "10.46.133.149" "10.54.16.25"] naturalSort ["v0.2" "v0.15" "v0.0.9"] => [ "v0.0.9" "v0.2" "v0.15" ]", "fn_type": null, "id": "lib.lists.naturalSort", "line": 547, "name": "naturalSort", }, { "category": "./lib/lists.nix", "description": "Return the first (at most) N elements of a list.", "example": "take 2 [ "a" "b" "c" "d" ] => [ "a" "b" ] take 2 [ ] => [ ]", "fn_type": "take :: int -> [a] -> [a]", "id": "lib.lists.take", "line": 566, "name": "take", }, { "category": "./lib/lists.nix", "description": "Remove the first (at most) N elements of a list.", "example": "drop 2 [ "a" "b" "c" "d" ] => [ "c" "d" ] drop 2 [ ] => [ ]", "fn_type": "drop :: int -> [a] -> [a]", "id": "lib.lists.drop", "line": 580, "name": "drop", }, { "category": "./lib/lists.nix", "description": "Return a list consisting of at most \`count\` elements of \`list\`, starting at index \`start\`.", "example": "sublist 1 3 [ "a" "b" "c" "d" "e" ] => [ "b" "c" "d" ] sublist 1 3 [ ] => [ ]", "fn_type": "sublist :: int -> int -> [a] -> [a]", "id": "lib.lists.sublist", "line": 596, "name": "sublist", }, { "category": "./lib/lists.nix", "description": "Return the last element of a list. This function throws an error if the list is empty.", "example": "last [ 1 2 3 ] => 3", "fn_type": "last :: [a] -> a", "id": "lib.lists.last", "line": 620, "name": "last", }, { "category": "./lib/lists.nix", "description": "Return all elements but the last. This function throws an error if the list is empty.", "example": "init [ 1 2 3 ] => [ 1 2 ]", "fn_type": "init :: [a] -> [a]", "id": "lib.lists.init", "line": 634, "name": "init", }, { "category": "./lib/lists.nix", "description": "Return the image of the cross product of some lists by a function.", "example": "crossLists (x:y: "\${toString x}\${toString y}") [[1 2] [3 4]] => [ "13" "14" "23" "24" ]", "fn_type": null, "id": "lib.lists.crossLists", "line": 645, "name": "crossLists", }, { "category": "./lib/lists.nix", "description": "Remove duplicate elements from the list. O(n^2) complexity.", "example": "unique [ 3 2 3 4 ] => [ 3 2 4 ]", "fn_type": "unique :: [a] -> [a]", "id": "lib.lists.unique", "line": 658, "name": "unique", }, { "category": "./lib/lists.nix", "description": "Intersects list 'e' and another list. O(nm) complexity.", "example": "intersectLists [ 1 2 3 ] [ 6 3 2 ] => [ 3 2 ]", "fn_type": null, "id": "lib.lists.intersectLists", "line": 666, "name": "intersectLists", }, { "category": "./lib/lists.nix", "description": "Subtracts list 'e' from another list. O(nm) complexity.", "example": "subtractLists [ 3 2 ] [ 1 2 3 4 5 3 ] => [ 1 4 5 ]", "fn_type": null, "id": "lib.lists.subtractLists", "line": 674, "name": "subtractLists", }, { "category": "./lib/lists.nix", "description": "Test if two lists have no common element. It should be slightly more efficient than (intersectLists a b == [])", "example": null, "fn_type": null, "id": "lib.lists.mutuallyExclusive", "line": 679, "name": "mutuallyExclusive", }, { "category": "./lib/licenses.nix", "description": "License identifiers from spdx.org where possible. * If you cannot find your license here, then look for a similar license or * add it to this list. The URL mentioned above is a good source for inspiration.", "example": null, "fn_type": null, "id": "lib.licenses.abstyles", "line": 28, "name": "abstyles", }, { "category": "./lib/kernel.nix", "description": "Common patterns/legacy used in common-config/hardened/config.nix", "example": null, "fn_type": null, "id": "lib.kernel.whenHelpers", "line": 19, "name": "whenHelpers", }, { "category": "./lib/generators.nix", "description": "Convert a value to a sensible default string representation. * The builtin \`toString\` function has some strange defaults, * suitable for bash scripts but not much else.", "example": null, "fn_type": null, "id": "lib.generators.mkValueStringDefault", "line": 33, "name": "mkValueStringDefault", }, { "category": "./lib/generators.nix", "description": "Generate a line of key k and value v, separated by * character sep. If sep appears in k, it is escaped. * Helper for synaxes with different separators. * * mkValueString specifies how values should be formatted. * * mkKeyValueDefault {} ":" "f:oo" "bar" * > "f\\:oo:bar"", "example": null, "fn_type": null, "id": "lib.generators.mkKeyValueDefault", "line": 69, "name": "mkKeyValueDefault", }, { "category": "./lib/generators.nix", "description": "Generate a key-value-style config file from an attrset. * * mkKeyValue is the same as in toINI.", "example": null, "fn_type": null, "id": "lib.generators.toKeyValue", "line": 82, "name": "toKeyValue", }, { "category": "./lib/generators.nix", "description": "Generate an INI-style config file from an * attrset of sections to an attrset of key-value pairs. * * generators.toINI {} { * foo = { hi = "\${pkgs.hello}"; ciao = "bar"; }; * baz = { "also, integers" = 42; }; * } * *> [baz] *> also, integers=42 *> *> [foo] *> ciao=bar *> hi=/nix/store/y93qql1p5ggfnaqjjqhxcw0vqw95rlz0-hello-2.10 * * The mk* configuration attributes can generically change * the way sections and key-value strings are generated. * * For more examples see the test cases in ./tests/misc.nix.", "example": null, "fn_type": null, "id": "lib.generators.toINI", "line": 113, "name": "toINI", }, { "category": "./lib/generators.nix", "description": "Generate an INI-style config file from an attrset * specifying the global section (no header), and an * attrset of sections to an attrset of key-value pairs. * * generators.toINIWithGlobalSection {} { * globalSection = { * someGlobalKey = "hi"; * }; * sections = { * foo = { hi = "\${pkgs.hello}"; ciao = "bar"; }; * baz = { "also, integers" = 42; }; * } * *> someGlobalKey=hi *> *> [baz] *> also, integers=42 *> *> [foo] *> ciao=bar *> hi=/nix/store/y93qql1p5ggfnaqjjqhxcw0vqw95rlz0-hello-2.10 * * The mk* configuration attributes can generically change * the way sections and key-value strings are generated. * * For more examples see the test cases in ./tests/misc.nix. * * If you don’t need a global section, you can also use * \`generators.toINI\` directly, which only takes * the part in \`sections\`.", "example": null, "fn_type": null, "id": "lib.generators.toINIWithGlobalSection", "line": 164, "name": "toINIWithGlobalSection", }, { "category": "./lib/generators.nix", "description": "Generate a git-config file from an attrset. * * It has two major differences from the regular INI format: * * 1. values are indented with tabs * 2. sections can have sub-sections * * generators.toGitINI { * url."ssh://git@github.com/".insteadOf = "https://github.com"; * user.name = "edolstra"; * } * *> [url "ssh://git@github.com/"] *> insteadOf = https://github.com/ *> *> [user] *> name = edolstra", "example": null, "fn_type": null, "id": "lib.generators.toGitINI", "line": 196, "name": "toGitINI", }, { "category": "./lib/generators.nix", "description": "Generates JSON from an arbitrary (non-function) value. * For more information see the documentation of the builtin.", "example": null, "fn_type": null, "id": "lib.generators.toJSON", "line": 235, "name": "toJSON", }, { "category": "./lib/generators.nix", "description": "YAML has been a strict superset of JSON since 1.2, so we * use toJSON. Before it only had a few differences referring * to implicit typing rules, so it should work with older * parsers as well.", "example": null, "fn_type": null, "id": "lib.generators.toYAML", "line": 243, "name": "toYAML", }, { "category": "./lib/generators.nix", "description": "Pretty print a value, akin to \`builtins.trace\`. * Should probably be a builtin as well. * The pretty-printed string should be suitable for rendering default values * in the NixOS manual. In particular, it should be as close to a valid Nix expression * as possible.", "example": null, "fn_type": null, "id": "lib.generators.toPretty", "line": 286, "name": "toPretty", }, { "category": "./lib/generators.nix", "description": "Translate a simple Nix expression to Dhall notation. * Note that integers are translated to Integer and never * the Natural type.", "example": null, "fn_type": null, "id": "lib.generators.toDhall", "line": 409, "name": "toDhall", }, { "category": "./lib/filesystem.nix", "description": "A map of all haskell packages defined in the given path, identified by having a cabal file with the same name as the directory itself.", "example": null, "fn_type": "Path -> Map String Path", "id": "lib.filesystem.haskellPathsInDir", "line": 18, "name": "haskellPathsInDir", }, { "category": "./lib/filesystem.nix", "description": "Find the first directory containing a file matching 'pattern' upward from a given 'file'. Returns 'null' if no directories contain a file matching 'pattern'.", "example": null, "fn_type": "RegExp -> Path -> Nullable { path : Path; matches : [ MatchResults ]; }", "id": "lib.filesystem.locateDominatingFile", "line": 41, "name": "locateDominatingFile", }, { "category": "./lib/filesystem.nix", "description": "Given a directory, return a flattened list of all files within it recursively.", "example": null, "fn_type": "Path -> [ Path ]", "id": "lib.filesystem.listFilesRecursive", "line": 69, "name": "listFilesRecursive", }, { "category": "./lib/derivations.nix", "description": "Restrict a derivation to a predictable set of attribute names, so that the returned attrset is not strict in the actual derivation, saving a lot of computation when the derivation is non-trivial. This is useful in situations where a derivation might only be used for its passthru attributes, improving evaluation performance. The returned attribute set is lazy in \`derivation\`. Specifically, this means that the derivation will not be evaluated in at least the situations below. For illustration and/or testing, we define derivation such that its evaluation is very noticeable. let derivation = throw "This won't be evaluated."; In the following expressions, \`derivation\` will _not_ be evaluated: (lazyDerivation { inherit derivation; }).type attrNames (lazyDerivation { inherit derivation; }) (lazyDerivation { inherit derivation; } // { foo = true; }).foo (lazyDerivation { inherit derivation; meta.foo = true; }).meta In these expressions, it \`derivation\` _will_ be evaluated: "\${lazyDerivation { inherit derivation }}" (lazyDerivation { inherit derivation }).outPath (lazyDerivation { inherit derivation }).meta And the following expressions are not valid, because the refer to implementation details and/or attributes that may not be present on some derivations: (lazyDerivation { inherit derivation }).buildInputs (lazyDerivation { inherit derivation }).passthru (lazyDerivation { inherit derivation }).pythonPath", "example": null, "fn_type": null, "id": "lib.derivations.lazyDerivation", "line": 53, "name": "lazyDerivation", }, { "category": "./lib/deprecated.nix", "description": "deprecated: For historical reasons, imap has an index starting at 1. But for consistency with the rest of the library we want an index starting at zero.", "example": null, "fn_type": null, "id": "lib.deprecated.imap", "line": 301, "name": "imap", }, { "category": "./lib/debug.nix", "description": "Conditionally trace the supplied message, based on a predicate.", "example": "traceIf true "hello" 3 trace: hello => 3", "fn_type": "traceIf :: bool -> string -> a -> a", "id": "lib.debug.traceIf", "line": 51, "name": "traceIf", }, { "category": "./lib/debug.nix", "description": "Trace the supplied value after applying a function to it, and return the original value.", "example": "traceValFn (v: "mystring \${v}") "foo" trace: mystring foo => "foo"", "fn_type": "traceValFn :: (a -> b) -> a -> a", "id": "lib.debug.traceValFn", "line": 69, "name": "traceValFn", }, { "category": "./lib/debug.nix", "description": "Trace the supplied value and return it.", "example": "traceVal 42 # trace: 42 => 42", "fn_type": "traceVal :: a -> a", "id": "lib.debug.traceVal", "line": 84, "name": "traceVal", }, { "category": "./lib/debug.nix", "description": "\`builtins.trace\`, but the value is \`builtins.deepSeq\`ed first.", "example": "trace { a.b.c = 3; } null trace: { a = ; } => null traceSeq { a.b.c = 3; } null trace: { a = { b = { c = 3; }; }; } => null", "fn_type": "traceSeq :: a -> b -> b", "id": "lib.debug.traceSeq", "line": 98, "name": "traceSeq", }, { "category": "./lib/debug.nix", "description": "Like \`traceSeq\`, but only evaluate down to depth n. This is very useful because lots of \`traceSeq\` usages lead to an infinite recursion.", "example": "traceSeqN 2 { a.b.c = 3; } null trace: { a = { b = {…}; }; } => null", "fn_type": "traceSeqN :: Int -> a -> b -> b", "id": "lib.debug.traceSeqN", "line": 115, "name": "traceSeqN", }, { "category": "./lib/debug.nix", "description": "A combination of \`traceVal\` and \`traceSeq\` that applies a provided function to the value to be traced after \`deepSeq\`ing it.", "example": null, "fn_type": null, "id": "lib.debug.traceValSeqFn", "line": 132, "name": "traceValSeqFn", }, { "category": "./lib/debug.nix", "description": "A combination of \`traceVal\` and \`traceSeq\`.", "example": null, "fn_type": null, "id": "lib.debug.traceValSeq", "line": 139, "name": "traceValSeq", }, { "category": "./lib/debug.nix", "description": "A combination of \`traceVal\` and \`traceSeqN\` that applies a provided function to the value to be traced.", "example": null, "fn_type": null, "id": "lib.debug.traceValSeqNFn", "line": 143, "name": "traceValSeqNFn", }, { "category": "./lib/debug.nix", "description": "A combination of \`traceVal\` and \`traceSeqN\`.", "example": null, "fn_type": null, "id": "lib.debug.traceValSeqN", "line": 151, "name": "traceValSeqN", }, { "category": "./lib/debug.nix", "description": "Trace the input and output of a function \`f\` named \`name\`, both down to \`depth\`. This is useful for adding around a function call, to see the before/after of values as they are transformed.", "example": "traceFnSeqN 2 "id" (x: x) { a.b.c = 3; } trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; } => { a.b.c = 3; }", "fn_type": null, "id": "lib.debug.traceFnSeqN", "line": 164, "name": "traceFnSeqN", }, { "category": "./lib/debug.nix", "description": "Evaluates a set of tests. A test is an attribute set \`{expr, expected}\`, denoting an expression and its expected result. The result is a \`list\` of __failed tests__, each represented as \`{name, expected, result}\`, - expected - What was passed as \`expected\` - result - The actual \`result\` of the test Used for regression testing of the functions in lib; see tests.nix for more examples. Important: Only attributes that start with \`test\` are executed. - If you want to run only a subset of the tests add the attribute \`tests = ["testName"];\`", "example": "runTests { testAndOk = { expr = lib.and true false; expected = false; }; testAndFail = { expr = lib.and true false; expected = true; }; } -> [ { name = "testAndFail"; expected = true; result = false; } ]", "fn_type": "runTests :: { tests = [ String ]; \${testName} :: { expr :: a; expected :: a; }; } -> [ { name :: String; expected :: a; result :: a; } ]", "id": "lib.debug.runTests", "line": 237, "name": "runTests", }, { "category": "./lib/debug.nix", "description": "Create a test assuming that list elements are \`true\`.", "example": "{ testX = allTrue [ true ]; }", "fn_type": null, "id": "lib.debug.testAllTrue", "line": 252, "name": "testAllTrue", }, { "category": "./lib/customisation.nix", "description": "\`overrideDerivation drv f\` takes a derivation (i.e., the result of a call to the builtin function \`derivation\`) and returns a new derivation in which the attributes of the original are overridden according to the function \`f\`. The function \`f\` is called with the original derivation attributes. \`overrideDerivation\` allows certain "ad-hoc" customisation scenarios (e.g. in ~/.config/nixpkgs/config.nix). For instance, if you want to "patch" the derivation returned by a package function in Nixpkgs to build another version than what the function itself provides, you can do something like this: mySed = overrideDerivation pkgs.gnused (oldAttrs: { name = "sed-4.2.2-pre"; src = fetchurl { url = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2; sha256 = "11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k"; }; patches = []; }); For another application, see build-support/vm, where this function is used to build arbitrary derivations inside a QEMU virtual machine. Note that in order to preserve evaluation errors, the new derivation's outPath depends on the old one's, which means that this function cannot be used in circular situations when the old derivation also depends on the new one. You should in general prefer \`drv.overrideAttrs\` over this function; see the nixpkgs manual for more information on overriding.", "example": null, "fn_type": null, "id": "lib.customisation.overrideDerivation", "line": 39, "name": "overrideDerivation", }, { "category": "./lib/customisation.nix", "description": "\`makeOverridable\` takes a function from attribute set to attribute set and injects \`override\` attribute which can be used to override arguments of the function. nix-repl> x = {a, b}: { result = a + b; } nix-repl> y = lib.makeOverridable x { a = 1; b = 2; } nix-repl> y { override = «lambda»; overrideDerivation = «lambda»; result = 3; } nix-repl> y.override { a = 10; } { override = «lambda»; overrideDerivation = «lambda»; result = 12; } Please refer to "Nixpkgs Contributors Guide" section ".overrideDerivation" to learn about \`overrideDerivation\` and caveats related to its use.", "example": null, "fn_type": null, "id": "lib.customisation.makeOverridable", "line": 78, "name": "makeOverridable", }, { "category": "./lib/customisation.nix", "description": "Call the package function in the file \`fn\` with the required arguments automatically. The function is called with the arguments \`args\`, but any missing arguments are obtained from \`autoArgs\`. This function is intended to be partially parameterised, e.g., callPackage = callPackageWith pkgs; pkgs = { libfoo = callPackage ./foo.nix { }; libbar = callPackage ./bar.nix { }; }; If the \`libbar\` function expects an argument named \`libfoo\`, it is automatically passed as an argument. Overrides or missing arguments can be supplied in \`args\`, e.g. libbar = callPackage ./bar.nix { libfoo = null; enableX11 = true; };", "example": null, "fn_type": null, "id": "lib.customisation.callPackageWith", "line": 128, "name": "callPackageWith", }, { "category": "./lib/customisation.nix", "description": "Like callPackage, but for a function that returns an attribute set of derivations. The override function is added to the individual attributes.", "example": null, "fn_type": null, "id": "lib.customisation.callPackagesWith", "line": 185, "name": "callPackagesWith", }, { "category": "./lib/customisation.nix", "description": "Add attributes to each output of a derivation without changing the derivation itself and check a given condition when evaluating.", "example": null, "fn_type": null, "id": "lib.customisation.extendDerivation", "line": 202, "name": "extendDerivation", }, { "category": "./lib/customisation.nix", "description": "Strip a derivation of all non-essential attributes, returning only those needed by hydra-eval-jobs. Also strictly evaluate the result to ensure that there are no thunks kept alive to prevent garbage collection.", "example": null, "fn_type": null, "id": "lib.customisation.hydraJob", "line": 236, "name": "hydraJob", }, { "category": "./lib/customisation.nix", "description": "Make a set of packages with a common scope. All packages called with the provided \`callPackage\` will be evaluated with the same arguments. Any package in the set may depend on any other. The \`overrideScope'\` function allows subsequent modification of the package set in a consistent way, i.e. all packages in the set will be called with the overridden packages. The package sets may be hierarchical: the packages in the set are called with the scope provided by \`newScope\` and the set provides a \`newScope\` attribute which can form the parent scope for later package sets.", "example": null, "fn_type": null, "id": "lib.customisation.makeScope", "line": 274, "name": "makeScope", }, { "category": "./lib/customisation.nix", "description": "Like the above, but aims to support cross compilation. It's still ugly, but hopefully it helps a little bit.", "example": null, "fn_type": null, "id": "lib.customisation.makeScopeWithSplicing", "line": 288, "name": "makeScopeWithSplicing", }, { "category": "./lib/cli.nix", "description": "Automatically convert an attribute set to command-line options. This helps protect against malformed command lines and also to reduce boilerplate related to command-line construction for simple use cases. \`toGNUCommandLine\` returns a list of nix strings. \`toGNUCommandLineShell\` returns an escaped shell string.", "example": "cli.toGNUCommandLine {} { data = builtins.toJSON { id = 0; }; X = "PUT"; retry = 3; retry-delay = null; url = [ "https://example.com/foo" "https://example.com/bar" ]; silent = false; verbose = true; } => [ "-X" "PUT" "--data" "{\\"id\\":0}" "--retry" "3" "--url" "https://example.com/foo" "--url" "https://example.com/bar" "--verbose" ] cli.toGNUCommandLineShell {} { data = builtins.toJSON { id = 0; }; X = "PUT"; retry = 3; retry-delay = null; url = [ "https://example.com/foo" "https://example.com/bar" ]; silent = false; verbose = true; } => "'-X' 'PUT' '--data' '{\\"id\\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";", "fn_type": null, "id": "lib.cli.toGNUCommandLineShell", "line": 42, "name": "toGNUCommandLineShell", }, { "category": "./lib/attrsets.nix", "description": "Return an attribute from nested attribute sets.", "example": "x = { a = { b = 3; }; } # ["a" "b"] is equivalent to x.a.b # 6 is a default value to return if the path does not exist in attrset attrByPath ["a" "b"] 6 x => 3 attrByPath ["z" "z"] 6 x => 6", "fn_type": "attrByPath :: [String] -> Any -> AttrSet -> Any", "id": "lib.attrsets.attrByPath", "line": 30, "name": "attrByPath", }, { "category": "./lib/attrsets.nix", "description": "Return if an attribute from nested attribute set exists.", "example": "x = { a = { b = 3; }; } hasAttrByPath ["a" "b"] x => true hasAttrByPath ["z" "z"] x => false", "fn_type": "hasAttrByPath :: [String] -> AttrSet -> Bool", "id": "lib.attrsets.hasAttrByPath", "line": 56, "name": "hasAttrByPath", }, { "category": "./lib/attrsets.nix", "description": "Create a new attribute set with \`value\` set at the nested attribute location specified in \`attrPath\`.", "example": "setAttrByPath ["a" "b"] 3 => { a = { b = 3; }; }", "fn_type": "setAttrByPath :: [String] -> Any -> AttrSet", "id": "lib.attrsets.setAttrByPath", "line": 78, "name": "setAttrByPath", }, { "category": "./lib/attrsets.nix", "description": "Like \`attrByPath\`, but without a default value. If it doesn't find the path it will throw an error.", "example": "x = { a = { b = 3; }; } getAttrFromPath ["a" "b"] x => 3 getAttrFromPath ["z" "z"] x => error: cannot find attribute \`z.z'", "fn_type": "getAttrFromPath :: [String] -> AttrSet -> Any", "id": "lib.attrsets.getAttrFromPath", "line": 104, "name": "getAttrFromPath", }, { "category": "./lib/attrsets.nix", "description": "Map each attribute in the given set and merge them into a new attribute set.", "example": "concatMapAttrs (name: value: { \${name} = value; \${name + value} = value; }) { x = "a"; y = "b"; } => { x = "a"; xa = "a"; y = "b"; yb = "b"; }", "fn_type": "concatMapAttrs :: (String -> a -> AttrSet) -> AttrSet -> AttrSet", "id": "lib.attrsets.concatMapAttrs", "line": 126, "name": "concatMapAttrs", }, { "category": "./lib/attrsets.nix", "description": "Update or set specific paths of an attribute set. Takes a list of updates to apply and an attribute set to apply them to, and returns the attribute set with the updates applied. Updates are represented as \`{ path = ...; update = ...; }\` values, where \`path\` is a list of strings representing the attribute path that should be updated, and \`update\` is a function that takes the old value at that attribute path as an argument and returns the new value it should be. Properties: - Updates to deeper attribute paths are applied before updates to more shallow attribute paths - Multiple updates to the same attribute path are applied in the order they appear in the update list - If any but the last \`path\` element leads into a value that is not an attribute set, an error is thrown - If there is an update for an attribute path that doesn't exist, accessing the argument in the update function causes an error, but intermediate attribute sets are implicitly created as needed", "example": "updateManyAttrsByPath [ { path = [ "a" "b" ]; update = old: { d = old.c; }; } { path = [ "a" "b" "c" ]; update = old: old + 1; } { path = [ "x" "y" ]; update = old: "xy"; } ] { a.b.c = 0; } => { a = { b = { d = 1; }; }; x = { y = "xy"; }; }", "fn_type": "updateManyAttrsByPath :: [{ path :: [String]; update :: (Any -> Any); }] -> AttrSet -> AttrSet", "id": "lib.attrsets.updateManyAttrsByPath", "line": 173, "name": "updateManyAttrsByPath", }, { "category": "./lib/attrsets.nix", "description": "Return the specified attributes from a set.", "example": "attrVals ["a" "b" "c"] as => [as.a as.b as.c]", "fn_type": "attrVals :: [String] -> AttrSet -> [Any]", "id": "lib.attrsets.attrVals", "line": 241, "name": "attrVals", }, { "category": "./lib/attrsets.nix", "description": "Return the values of all attributes in the given set, sorted by attribute name.", "example": "attrValues {c = 3; a = 1; b = 2;} => [1 2 3]", "fn_type": "attrValues :: AttrSet -> [Any]", "id": "lib.attrsets.attrValues", "line": 258, "name": "attrValues", }, { "category": "./lib/attrsets.nix", "description": "Given a set of attribute names, return the set of the corresponding attributes from the given set.", "example": "getAttrs [ "a" "b" ] { a = 1; b = 2; c = 3; } => { a = 1; b = 2; }", "fn_type": "getAttrs :: [String] -> AttrSet -> AttrSet", "id": "lib.attrsets.getAttrs", "line": 271, "name": "getAttrs", }, { "category": "./lib/attrsets.nix", "description": "Collect each attribute named \`attr\` from a list of attribute sets. Sets that don't contain the named attribute are ignored.", "example": "catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}] => [1 2]", "fn_type": "catAttrs :: String -> [AttrSet] -> [Any]", "id": "lib.attrsets.catAttrs", "line": 287, "name": "catAttrs", }, { "category": "./lib/attrsets.nix", "description": "Filter an attribute set by removing all attributes for which the given predicate return false.", "example": "filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; } => { foo = 1; }", "fn_type": "filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet", "id": "lib.attrsets.filterAttrs", "line": 301, "name": "filterAttrs", }, { "category": "./lib/attrsets.nix", "description": "Filter an attribute set recursively by removing all attributes for which the given predicate return false.", "example": "filterAttrsRecursive (n: v: v != null) { foo = { bar = null; }; } => { foo = {}; }", "fn_type": "filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet", "id": "lib.attrsets.filterAttrsRecursive", "line": 319, "name": "filterAttrsRecursive", }, { "category": "./lib/attrsets.nix", "description": "Apply fold functions to values grouped by key.", "example": "foldAttrs (item: acc: [item] ++ acc) [] [{ a = 2; } { a = 3; }] => { a = [ 2 3 ]; }", "fn_type": "foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any", "id": "lib.attrsets.foldAttrs", "line": 346, "name": "foldAttrs", }, { "category": "./lib/attrsets.nix", "description": "Recursively collect sets that verify a given predicate named \`pred\` from the set \`attrs\`. The recursion is stopped when the predicate is verified.", "example": "collect isList { a = { b = ["b"]; }; c = [1]; } => [["b"] [1]] collect (x: x ? outPath) { a = { outPath = "a/"; }; b = { outPath = "b/"; }; } => [{ outPath = "a/"; } { outPath = "b/"; }]", "fn_type": "collect :: (AttrSet -> Bool) -> AttrSet -> [x]", "id": "lib.attrsets.collect", "line": 375, "name": "collect", }, { "category": "./lib/attrsets.nix", "description": "Return the cartesian product of attribute set value combinations.", "example": "cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; } => [ { a = 1; b = 10; } { a = 1; b = 20; } { a = 2; b = 10; } { a = 2; b = 20; } ]", "fn_type": "cartesianProductOfSets :: AttrSet -> [AttrSet]", "id": "lib.attrsets.cartesianProductOfSets", "line": 400, "name": "cartesianProductOfSets", }, { "category": "./lib/attrsets.nix", "description": "Utility function that creates a \`{name, value}\` pair as expected by \`builtins.listToAttrs\`.", "example": "nameValuePair "some" 6 => { name = "some"; value = 6; }", "fn_type": "nameValuePair :: String -> Any -> { name :: String; value :: Any; }", "id": "lib.attrsets.nameValuePair", "line": 419, "name": "nameValuePair", }, { "category": "./lib/attrsets.nix", "description": "Apply a function to each element in an attribute set, creating a new attribute set.", "example": "mapAttrs (name: value: name + "-" + value) { x = "foo"; y = "bar"; } => { x = "x-foo"; y = "y-bar"; }", "fn_type": "mapAttrs :: (String -> Any -> Any) -> AttrSet -> AttrSet", "id": "lib.attrsets.mapAttrs", "line": 437, "name": "mapAttrs", }, { "category": "./lib/attrsets.nix", "description": "Like \`mapAttrs\`, but allows the name of each attribute to be changed in addition to the value. The applied function should return both the new name and value as a \`nameValuePair\`.", "example": "mapAttrs' (name: value: nameValuePair ("foo_" + name) ("bar-" + value)) { x = "a"; y = "b"; } => { foo_x = "bar-a"; foo_y = "bar-b"; }", "fn_type": "mapAttrs' :: (String -> Any -> { name :: String; value :: Any; }) -> AttrSet -> AttrSet", "id": "lib.attrsets.mapAttrs'", "line": 454, "name": "mapAttrs'", }, { "category": "./lib/attrsets.nix", "description": "Call a function for each attribute in the given set and return the result in a list.", "example": "mapAttrsToList (name: value: name + value) { x = "a"; y = "b"; } => [ "xa" "yb" ]", "fn_type": "mapAttrsToList :: (String -> a -> b) -> AttrSet -> [b]", "id": "lib.attrsets.mapAttrsToList", "line": 474, "name": "mapAttrsToList", }, { "category": "./lib/attrsets.nix", "description": "Like \`mapAttrs\`, except that it recursively applies itself to the *leaf* attributes of a potentially-nested attribute set: the second argument of the function will never be an attrset. Also, the first argument of the argument function is a *list* of the attribute names that form the path to the leaf attribute. For a function that gives you control over what counts as a leaf, see \`mapAttrsRecursiveCond\`.", "example": "mapAttrsRecursive (path: value: concatStringsSep "-" (path ++ [value])) { n = { a = "A"; m = { b = "B"; c = "C"; }; }; d = "D"; } => { n = { a = "n-a-A"; m = { b = "n-m-b-B"; c = "n-m-c-C"; }; }; d = "d-D"; }", "fn_type": "mapAttrsRecursive :: ([String] -> a -> b) -> AttrSet -> AttrSet", "id": "lib.attrsets.mapAttrsRecursive", "line": 499, "name": "mapAttrsRecursive", }, { "category": "./lib/attrsets.nix", "description": "Like \`mapAttrsRecursive\`, but it takes an additional predicate function that tells it whether to recurse into an attribute set. If it returns false, \`mapAttrsRecursiveCond\` does not recurse, but does apply the map function. If it returns true, it does recurse, and does not apply the map function.", "example": "# To prevent recursing into derivations (which are attribute # sets with the attribute "type" equal to "derivation"): mapAttrsRecursiveCond (as: !(as ? "type" && as.type == "derivation")) (x: ... do something ...) attrs", "fn_type": "mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([String] -> a -> b) -> AttrSet -> AttrSet", "id": "lib.attrsets.mapAttrsRecursiveCond", "line": 524, "name": "mapAttrsRecursiveCond", }, { "category": "./lib/attrsets.nix", "description": "Generate an attribute set by mapping a function over a list of attribute names.", "example": "genAttrs [ "foo" "bar" ] (name: "x_" + name) => { foo = "x_foo"; bar = "x_bar"; }", "fn_type": "genAttrs :: [ String ] -> (String -> Any) -> AttrSet", "id": "lib.attrsets.genAttrs", "line": 553, "name": "genAttrs", }, { "category": "./lib/attrsets.nix", "description": "Check whether the argument is a derivation. Any set with \`{ type = "derivation"; }\` counts as a derivation.", "example": "nixpkgs = import {} isDerivation nixpkgs.ruby => true isDerivation "foobar" => false", "fn_type": "isDerivation :: Any -> Bool", "id": "lib.attrsets.isDerivation", "line": 574, "name": "isDerivation", }, { "category": "./lib/attrsets.nix", "description": "Converts a store path to a fake derivation.", "example": null, "fn_type": "toDerivation :: Path -> Derivation", "id": "lib.attrsets.toDerivation", "line": 583, "name": "toDerivation", }, { "category": "./lib/attrsets.nix", "description": "If \`cond\` is true, return the attribute set \`as\`, otherwise an empty attribute set.", "example": "optionalAttrs (true) { my = "set"; } => { my = "set"; } optionalAttrs (false) { my = "set"; } => { }", "fn_type": "optionalAttrs :: Bool -> AttrSet -> AttrSet", "id": "lib.attrsets.optionalAttrs", "line": 611, "name": "optionalAttrs", }, { "category": "./lib/attrsets.nix", "description": "Merge sets of attributes and use the function \`f\` to merge attributes values.", "example": "zipAttrsWithNames ["a"] (name: vs: vs) [{a = "x";} {a = "y"; b = "z";}] => { a = ["x" "y"]; }", "fn_type": "zipAttrsWithNames :: [ String ] -> (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet", "id": "lib.attrsets.zipAttrsWithNames", "line": 629, "name": "zipAttrsWithNames", }, { "category": "./lib/attrsets.nix", "description": "Merge sets of attributes and use the function f to merge attribute values. Like \`lib.attrsets.zipAttrsWithNames\` with all key names are passed for \`names\`. Implementation note: Common names appear multiple times in the list of names, hopefully this does not affect the system because the maximal laziness avoid computing twice the same expression and \`listToAttrs\` does not care about duplicated attribute names.", "example": "zipAttrsWith (name: values: values) [{a = "x";} {a = "y"; b = "z";}] => { a = ["x" "y"]; b = ["z"]; }", "fn_type": "zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet", "id": "lib.attrsets.zipAttrsWith", "line": 657, "name": "zipAttrsWith", }, { "category": "./lib/attrsets.nix", "description": "Merge sets of attributes and combine each attribute value in to a list. Like \`lib.attrsets.zipAttrsWith\` with \`(name: values: values)\` as the function.", "example": "zipAttrs [{a = "x";} {a = "y"; b = "z";}] => { a = ["x" "y"]; b = ["z"]; }", "fn_type": "zipAttrs :: [ AttrSet ] -> AttrSet", "id": "lib.attrsets.zipAttrs", "line": 672, "name": "zipAttrs", }, { "category": "./lib/attrsets.nix", "description": "Does the same as the update operator '//' except that attributes are merged until the given predicate is verified. The predicate should accept 3 arguments which are the path to reach the attribute, a part of the first attribute set and a part of the second attribute set. When the predicate is satisfied, the value of the first attribute set is replaced by the value of the second attribute set.", "example": "recursiveUpdateUntil (path: l: r: path == ["foo"]) { # first attribute set foo.bar = 1; foo.baz = 2; bar = 3; } { #second attribute set foo.bar = 1; foo.quz = 2; baz = 4; } => { foo.bar = 1; # 'foo.*' from the second set foo.quz = 2; # bar = 3; # 'bar' from the first set baz = 4; # 'baz' from the second set }", "fn_type": "recursiveUpdateUntil :: ( [ String ] -> AttrSet -> AttrSet -> Bool ) -> AttrSet -> AttrSet -> AttrSet", "id": "lib.attrsets.recursiveUpdateUntil", "line": 708, "name": "recursiveUpdateUntil", }, { "category": "./lib/attrsets.nix", "description": "A recursive variant of the update operator ‘//’. The recursion stops when one of the attribute values is not an attribute set, in which case the right hand side value takes precedence over the left hand side value.", "example": "recursiveUpdate { boot.loader.grub.enable = true; boot.loader.grub.device = "/dev/hda"; } { boot.loader.grub.device = ""; } returns: { boot.loader.grub.enable = true; boot.loader.grub.device = ""; }", "fn_type": "recursiveUpdate :: AttrSet -> AttrSet -> AttrSet", "id": "lib.attrsets.recursiveUpdate", "line": 748, "name": "recursiveUpdate", }, { "category": "./lib/attrsets.nix", "description": "Returns true if the pattern is contained in the set. False otherwise.", "example": "matchAttrs { cpu = {}; } { cpu = { bits = 64; }; } => true", "fn_type": "matchAttrs :: AttrSet -> AttrSet -> Bool", "id": "lib.attrsets.matchAttrs", "line": 765, "name": "matchAttrs", }, { "category": "./lib/attrsets.nix", "description": "Override only the attributes that are already present in the old set useful for deep-overriding.", "example": "overrideExisting {} { a = 1; } => {} overrideExisting { b = 2; } { a = 1; } => { b = 2; } overrideExisting { a = 3; b = 2; } { a = 1; } => { a = 1; b = 2; }", "fn_type": "overrideExisting :: AttrSet -> AttrSet -> AttrSet", "id": "lib.attrsets.overrideExisting", "line": 793, "name": "overrideExisting", }, { "category": "./lib/attrsets.nix", "description": "Turns a list of strings into a human-readable description of those strings represented as an attribute path. The result of this function is not intended to be machine-readable. Create a new attribute set with \`value\` set at the nested attribute location specified in \`attrPath\`.", "example": "showAttrPath [ "foo" "10" "bar" ] => "foo.\\"10\\".bar" showAttrPath [] => """, "fn_type": "showAttrPath :: [String] -> String", "id": "lib.attrsets.showAttrPath", "line": 815, "name": "showAttrPath", }, { "category": "./lib/attrsets.nix", "description": "Get a package output. If no output is found, fallback to \`.out\` and then to the default.", "example": "getOutput "dev" pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev"", "fn_type": "getOutput :: String -> Derivation -> String", "id": "lib.attrsets.getOutput", "line": 832, "name": "getOutput", }, { "category": "./lib/attrsets.nix", "description": "Get a package's \`bin\` output. If the output does not exist, fallback to \`.out\` and then to the default.", "example": "getBin pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r"", "fn_type": "getBin :: Derivation -> String", "id": "lib.attrsets.getBin", "line": 847, "name": "getBin", }, { "category": "./lib/attrsets.nix", "description": "Get a package's \`lib\` output. If the output does not exist, fallback to \`.out\` and then to the default.", "example": "getLib pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-lib"", "fn_type": "getLib :: Derivation -> String", "id": "lib.attrsets.getLib", "line": 860, "name": "getLib", }, { "category": "./lib/attrsets.nix", "description": "Get a package's \`dev\` output. If the output does not exist, fallback to \`.out\` and then to the default.", "example": "getDev pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev"", "fn_type": "getDev :: Derivation -> String", "id": "lib.attrsets.getDev", "line": 873, "name": "getDev", }, { "category": "./lib/attrsets.nix", "description": "Get a package's \`man\` output. If the output does not exist, fallback to \`.out\` and then to the default.", "example": "getMan pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-man"", "fn_type": "getMan :: Derivation -> String", "id": "lib.attrsets.getMan", "line": 886, "name": "getMan", }, { "category": "./lib/attrsets.nix", "description": "Pick the outputs of packages to place in \`buildInputs\`", "example": null, "fn_type": "chooseDevOutputs :: [Derivation] -> [String]", "id": "lib.attrsets.chooseDevOutputs", "line": 893, "name": "chooseDevOutputs", }, { "category": "./lib/attrsets.nix", "description": "Make various Nix tools consider the contents of the resulting attribute set when looking for what to build, find, etc. This function only affects a single attribute set; it does not apply itself recursively for nested attribute sets.", "example": "{ pkgs ? import {} }: { myTools = pkgs.lib.recurseIntoAttrs { inherit (pkgs) hello figlet; }; }", "fn_type": "recurseIntoAttrs :: AttrSet -> AttrSet", "id": "lib.attrsets.recurseIntoAttrs", "line": 916, "name": "recurseIntoAttrs", }, { "category": "./lib/attrsets.nix", "description": "Undo the effect of recurseIntoAttrs.", "example": null, "fn_type": "dontRecurseIntoAttrs :: AttrSet -> AttrSet", "id": "lib.attrsets.dontRecurseIntoAttrs", "line": 926, "name": "dontRecurseIntoAttrs", }, { "category": "./lib/attrsets.nix", "description": "\`unionOfDisjoint x y\` is equal to \`x // y // z\` where the attrnames in \`z\` are the intersection of the attrnames in \`x\` and \`y\`, and all values \`assert\` with an error message. This operator is commutative, unlike (//).", "example": null, "fn_type": "unionOfDisjoint :: AttrSet -> AttrSet -> AttrSet", "id": "lib.attrsets.unionOfDisjoint", "line": 938, "name": "unionOfDisjoint", }, { "category": "./lib/asserts.nix", "description": "Throw if pred is false, else return pred. Intended to be used to augment asserts with helpful error messages.", "example": "assertMsg false "nope" stderr> error: nope assert assertMsg ("foo" == "bar") "foo is not bar, silly"; "" stderr> error: foo is not bar, silly", "fn_type": "assertMsg :: Bool -> String -> Bool", "id": "lib.asserts.assertMsg", "line": 19, "name": "assertMsg", }, { "category": "./lib/asserts.nix", "description": "Specialized \`assertMsg\` for checking if \`val\` is one of the elements of the list \`xs\`. Useful for checking enums.", "example": "let sslLibrary = "libressl"; in assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ] stderr> error: sslLibrary must be one of [ stderr> "openssl" stderr> "bearssl" stderr> ], but is: "libressl"", "fn_type": "assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool", "id": "lib.asserts.assertOneOf", "line": 40, "name": "assertOneOf", }, ] `; exports[`has not changed trivial-builders data 1`] = ` [ { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Run the shell command \`buildCommand' to produce a store path named \`name'. The attributes in \`env' are added to the environment prior to running the command. By default \`runCommand\` runs in a stdenv with no compiler environment. \`runCommandCC\` uses the default stdenv, \`pkgs.stdenv\`.", "example": "runCommand "name" {envVariable = true;} ''echo hello > $out'' runCommandCC "name" {} ''gcc -o myfile myfile.c; cp myfile $out''; The \`*Local\` variants force a derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network roundrip and can speed up a build. It is the same as adding the special fields \`preferLocalBuild = true;\` \`allowSubstitutes = false;\` to a derivation’s attributes.", "fn_type": null, "id": "build-support.trivial-builders.runCommand", "line": 38, "name": "runCommand", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Generalized version of the \`runCommand\`-variants which does customized behavior via a single attribute set passed as the first argument instead of having a lot of variants like \`runCommand*\`. Additionally it allows changing the used \`stdenv\` freely and has a more explicit approach to changing the arguments passed to \`stdenv.mkDerivation\`.", "example": null, "fn_type": null, "id": "build-support.trivial-builders.runCommandWith", "line": 69, "name": "runCommandWith", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Writes a text file to the nix store. The contents of text is added to the file in the store.", "example": "# Writes my-file to /nix/store/ writeTextFile { name = "my-file"; text = '' Contents of File ''; } See also the \`writeText\` helper function below. # Writes executable my-file to /nix/store//bin/my-file writeTextFile { name = "my-file"; text = '' Contents of File ''; executable = true; destination = "/bin/my-file"; }", "fn_type": null, "id": "build-support.trivial-builders.writeTextFile", "line": 128, "name": "writeTextFile", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Writes a text file to nix store with no optional parameters available.", "example": "# Writes contents of file to /nix/store/ writeText "my-file" '' Contents of File '';", "fn_type": null, "id": "build-support.trivial-builders.writeText", "line": 172, "name": "writeText", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Writes a text file to nix store in a specific directory with no optional parameters available.", "example": "# Writes contents of file to /nix/store//share/my-file writeTextDir "share/my-file" '' Contents of File '';", "fn_type": null, "id": "build-support.trivial-builders.writeTextDir", "line": 189, "name": "writeTextDir", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Writes a text file to /nix/store/ and marks the file as executable. If passed as a build input, will be used as a setup hook. This makes setup hooks more efficient to create: you don't need a derivation that copies them to $out/nix-support/setup-hook, instead you can use the file as is.", "example": "# Writes my-file to /nix/store/ and makes executable writeScript "my-file" '' Contents of File '';", "fn_type": null, "id": "build-support.trivial-builders.writeScript", "line": 214, "name": "writeScript", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Writes a text file to /nix/store//bin/ and marks the file as executable.", "example": "# Writes my-file to /nix/store//bin/my-file and makes executable. writeScriptBin "my-file" '' Contents of File '';", "fn_type": null, "id": "build-support.trivial-builders.writeScriptBin", "line": 232, "name": "writeScriptBin", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Similar to writeScript. Writes a Shell script and checks its syntax. Automatically includes interpreter above the contents passed.", "example": "# Writes my-file to /nix/store/ and makes executable. writeShellScript "my-file" '' Contents of File '';", "fn_type": null, "id": "build-support.trivial-builders.writeShellScript", "line": 249, "name": "writeShellScript", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Similar to writeShellScript and writeScriptBin. Writes an executable Shell script to /nix/store//bin/ and checks its syntax. Automatically includes interpreter above the contents passed.", "example": "# Writes my-file to /nix/store//bin/my-file and makes executable. writeShellScriptBin "my-file" '' Contents of File '';", "fn_type": null, "id": "build-support.trivial-builders.writeShellScriptBin", "line": 278, "name": "writeShellScriptBin", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Similar to writeShellScriptBin and writeScriptBin. Writes an executable Shell script to /nix/store//bin/ and checks its syntax with shellcheck and the shell's -n option. Automatically includes sane set of shellopts (errexit, nounset, pipefail) and handles creation of PATH based on runtimeInputs Note that the checkPhase uses stdenv.shell for the test run of the script, while the generated shebang uses runtimeShell. If, for whatever reason, those were to mismatch you might lose fidelity in the default checks.", "example": "Writes my-file to /nix/store//bin/my-file and makes executable. writeShellApplication { name = "my-file"; runtimeInputs = [ curl w3m ]; text = '' curl -s 'https://nixos.org' | w3m -dump -T text/html ''; }", "fn_type": null, "id": "build-support.trivial-builders.writeShellApplication", "line": 317, "name": "writeShellApplication", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "concat a list of files to the nix store. The contents of files are added to the file in the store.", "example": "# Writes my-file to /nix/store/ concatTextFile { name = "my-file"; files = [ drv1 "\${drv2}/path/to/file" ]; } See also the \`concatText\` helper function below. # Writes executable my-file to /nix/store//bin/my-file concatTextFile { name = "my-file"; files = [ drv1 "\${drv2}/path/to/file" ]; executable = true; destination = "/bin/my-file"; }", "fn_type": null, "id": "build-support.trivial-builders.concatTextFile", "line": 397, "name": "concatTextFile", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Writes a text file to nix store with no optional parameters available.", "example": "# Writes contents of files to /nix/store/ concatText "my-file" [ file1 file2 ]", "fn_type": null, "id": "build-support.trivial-builders.concatText", "line": 428, "name": "concatText", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Writes a text file to nix store with and mark it as executable.", "example": "# Writes contents of files to /nix/store/ concatScript "my-file" [ file1 file2 ]", "fn_type": null, "id": "build-support.trivial-builders.concatScript", "line": 438, "name": "concatScript", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Create a forest of symlinks to the files in \`paths'. This creates a single derivation that replicates the directory structure of all the input paths. BEWARE: it may not "work right" when the passed paths contain symlinks to directories.", "example": "# adds symlinks of hello to current build. symlinkJoin { name = "myhello"; paths = [ pkgs.hello ]; } # adds symlinks of hello and stack to current build and prints "links added" symlinkJoin { name = "myexample"; paths = [ pkgs.hello pkgs.stack ]; postBuild = "echo links added"; } This creates a derivation with a directory structure like the following: /nix/store/sglsr5g079a5235hy29da3mq3hv8sjmm-myexample |-- bin | |-- hello -> /nix/store/qy93dp4a3rqyn2mz63fbxjg228hffwyw-hello-2.10/bin/hello | \`-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/bin/stack \`-- share |-- bash-completion | \`-- completions | \`-- stack -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/bash-completion/completions/stack |-- fish | \`-- vendor_completions.d | \`-- stack.fish -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1/share/fish/vendor_completions.d/stack.fish ... symlinkJoin and linkFarm are similar functions, but they output derivations with different structure. symlinkJoin is used to create a derivation with a familiar directory structure (top-level bin/, share/, etc), but with all actual files being symlinks to the files in the input derivations. symlinkJoin is used many places in nixpkgs to create a single derivation that appears to contain binaries, libraries, documentation, etc from multiple input derivations. linkFarm is instead used to create a simple derivation with symlinks to other derivations. A derivation created with linkFarm is often used in CI as a easy way to build multiple derivations at once.", "fn_type": null, "id": "build-support.trivial-builders.symlinkJoin", "line": 494, "name": "symlinkJoin", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Quickly create a set of symlinks to derivations. This creates a simple derivation with symlinks to all inputs. entries can be a list of attribute sets like [ { name = "name" ; path = "/nix/store/..."; } ] or an attribute set name -> path like: { name = "/nix/store/..."; other = "/nix/store/..."; }", "example": "# Symlinks hello and stack paths in store to current $out/hello-test and # $out/foobar. linkFarm "myexample" [ { name = "hello-test"; path = pkgs.hello; } { name = "foobar"; path = pkgs.stack; } ] This creates a derivation with a directory structure like the following: /nix/store/qc5728m4sa344mbks99r3q05mymwm4rw-myexample |-- foobar -> /nix/store/6lzdpxshx78281vy056lbk553ijsdr44-stack-2.1.3.1 \`-- hello-test -> /nix/store/qy93dp4a3rqyn2mz63fbxjg228hffwyw-hello-2.10 See the note on symlinkJoin for the difference between linkFarm and symlinkJoin.", "fn_type": null, "id": "build-support.trivial-builders.linkFarm", "line": 547, "name": "linkFarm", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Easily create a linkFarm from a set of derivations. This calls linkFarm with a list of entries created from the list of input derivations. It turns each input derivation into an attribute set like { name = drv.name ; path = drv }, and passes this to linkFarm.", "example": "# Symlinks the hello, gcc, and ghc derivations in $out linkFarmFromDrvs "myexample" [ pkgs.hello pkgs.gcc pkgs.ghc ] This creates a derivation with a directory structure like the following: /nix/store/m3s6wkjy9c3wy830201bqsb91nk2yj8c-myexample |-- gcc-wrapper-9.2.0 -> /nix/store/fqhjxf9ii4w4gqcsx59fyw2vvj91486a-gcc-wrapper-9.2.0 |-- ghc-8.6.5 -> /nix/store/gnf3s07bglhbbk4y6m76sbh42siym0s6-ghc-8.6.5 \`-- hello-2.10 -> /nix/store/k0ll91c4npk4lg8lqhx00glg2m735g74-hello-2.10", "fn_type": null, "id": "build-support.trivial-builders.linkFarmFromDrvs", "line": 591, "name": "linkFarmFromDrvs", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Write the set of references to a file, that is, their immediate dependencies. This produces the equivalent of \`nix-store -q --references\`.", "example": null, "fn_type": null, "id": "build-support.trivial-builders.writeDirectReferencesToFile", "line": 655, "name": "writeDirectReferencesToFile", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Extract a string's references to derivations and paths (its context) and write them to a text file, removing the input string itself from the dependency graph. This is useful when you want to make a derivation depend on the string's references, but not its contents (to avoid unnecessary rebuilds, for example). Note that this only works as intended on Nix >= 2.3.", "example": null, "fn_type": null, "id": "build-support.trivial-builders.writeStringReferencesToFile", "line": 689, "name": "writeStringReferencesToFile", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Print an error message if the file with the specified name and hash doesn't exist in the Nix store. This function should only be used by non-redistributable software with an unfree license that we need to require the user to download manually. It produces packages that cannot be built automatically.", "example": "requireFile { name = "my-file"; url = "http://example.com/download/"; sha256 = "ffffffffffffffffffffffffffffffffffffffffffffffffffff"; }", "fn_type": null, "id": "build-support.trivial-builders.requireFile", "line": 777, "name": "requireFile", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Copy a path to the Nix store. Nix automatically copies files to the store before stringifying paths. If you need the store path of a file, \${copyPathToStore } can be shortened to \${}.", "example": null, "fn_type": null, "id": "build-support.trivial-builders.copyPathToStore", "line": 828, "name": "copyPathToStore", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Copy a list of paths to the Nix store.", "example": null, "fn_type": null, "id": "build-support.trivial-builders.copyPathsToStore", "line": 834, "name": "copyPathsToStore", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "Applies a list of patches to a source directory.", "example": "# Patching nixpkgs: applyPatches { src = pkgs.path; patches = [ (pkgs.fetchpatch { url = "https://github.com/NixOS/nixpkgs/commit/1f770d20550a413e508e081ddc08464e9d08ba3d.patch"; sha256 = "1nlzx171y3r3jbk0qhvnl711kmdk57jlq4na8f8bs8wz2pbffymr"; }) ]; }", "fn_type": null, "id": "build-support.trivial-builders.applyPatches", "line": 853, "name": "applyPatches", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "An immutable file in the store with a length of 0 bytes.", "example": null, "fn_type": null, "id": "build-support.trivial-builders.emptyFile", "line": 873, "name": "emptyFile", }, { "category": "./pkgs/build-support/trivial-builders.nix", "description": "An immutable empty directory in the store.", "example": null, "fn_type": null, "id": "build-support.trivial-builders.emptyDirectory", "line": 881, "name": "emptyDirectory", }, { "category": "./pkgs/build-support/plugins.nix", "description": "Takes a list of expected plugin names * and compares it to the found plugins given in the file, * one plugin per line. * If the lists differ, the build fails with a nice message. * * This is helpful to ensure maintainers don’t miss * the addition or removal of a plugin.", "example": null, "fn_type": null, "id": "build-support.plugins.diffPlugins", "line": 13, "name": "diffPlugins", }, ] `;