hsjobeki/noogle
1
1
Fork 0
mirror of https://github.com/hsjobeki/noogle.git synced 2024-12-28 00:12:44 +03:00
Code Issues Projects Releases Wiki Activity
23d3efa2c7
noogle/tests/__snapshots__/data.test.js.snap
hsjobeki 23d3efa2c7 chore: sync docs with master 
confirm updated:
- trivial-builders.makeSetupHook
- lib.options.mkPackageOption
2023-02-27 12:25:37 +01:00

6903 lines
212 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// 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 \`<hash2>-<hash>-<name>\`, where \`<hash>-<name>\` is
> the name of the input directory. Since \`<hash>\` depends on the
> unfiltered directory, the name of the output directory will
> indirectly depend on files that are filtered out by the
> function. This will trigger a rebuild even when a filtered out
> file is changed. 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\` *\\<foo\\>*)
> are [normal path values](language-values.md).
A Nix expression loaded by \`import\` must not contain any *free
variables* (identifiers that are not defined in the Nix expression
itself and are not built-in). Therefore, it cannot refer to
variables that are in scope at the call site. For instance, if you
have a calling expression
\`\`\`nix
rec {
x = 123;
y = import ./foo.nix;
}
\`\`\`
then the following \`foo.nix\` will give an error:
\`\`\`nix
x + 456
\`\`\`
since \`x\` is not in scope in \`foo.nix\`. If you want \`x\` to be
available in \`foo.nix\`, you should pass it as a function argument:
\`\`\`nix
rec {
x = 123;
y = import ./foo.nix x;
}
\`\`\`
and
\`\`\`nix
x: x + 456
\`\`\`
(The function argument doesn’t have to be called \`x\` in \`foo.nix\`;
any name would work.)
",
],
"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" ②
"<?xml version='1.0' encoding='UTF-8'?>
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
<xsl:template match='/'>
<Configure>
<xsl:for-each select='/expr/list/attrs'>
<Call name='addWebApplication'>
<Arg><xsl:value-of select=\\"attr[@name = 'path']/string/@value\\" /></Arg>
<Arg><xsl:value-of select=\\"attr[@name = 'war']/path/@value\\" /></Arg>
</Call>
</xsl:for-each>
</Configure>
</xsl:template>
</xsl:stylesheet>
";
servlets = builtins.toXML [ ③
{ path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; }
{ path = "/wiki"; war = uberwiki + "/uberwiki.war"; }
];
})
\`\`\`
The builder is supposed to generate the configuration file for a
[Jetty servlet container](http://jetty.mortbay.org/). A servlet
container contains a number of servlets (\`*.war\` files) each
exported under a specific URI prefix. So the servlet configuration
is a list of sets containing the \`path\` and \`war\` of the servlet
(①). This kind of information is difficult to communicate with the
normal method of passing information through an environment
variable, which just concatenates everything together into a
string (which might just work in this case, but wouldn’t work if
fields are optional or contain lists themselves). Instead the Nix
expression is converted to an XML representation with \`toXML\`,
which is unambiguous and can easily be processed with the
appropriate tools. For instance, in the example an XSLT stylesheet
(at point ②) is applied to it (at point ①) to generate the XML
configuration file for the Jetty server. The XML representation
produced at point ③ by \`toXML\` is as follows:
\`\`\`xml
<?xml version='1.0' encoding='utf-8'?>
<expr>
<list>
<attrs>
<attr name="path">
<string value="/bugtracker" />
</attr>
<attr name="war">
<path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" />
</attr>
</attrs>
<attrs>
<attr name="path">
<string value="/wiki" />
</attr>
<attr name="war">
<path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" />
</attr>
</attrs>
</list>
</expr>
\`\`\`
Note that we used the \`toFile\` built-in to write the builder and
the stylesheet “inline” in the Nix expression. The path of the
stylesheet is spliced into the builder using the syntax \`xsltproc
\${stylesheet}\`.
",
],
"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" {})
]
=> <drv which copies all files 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 -> [<functions>] -> <return type of last function>",
"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 <nixpkgs> { }
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 "🦄"
=> [ "<22>" "<22>" "<22>" "<22>" ]",
"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' < & >''
=> "&quot;test&quot; &apos;test&apos; &lt; &amp; &gt;"",
"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 <nixpkgs> { };
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<feature>=<value> 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<condition>={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<feature>={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}-<feat> 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-<feat>=<value>,disable-<feat>} 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}-<feat> 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-<feat>=<value>,without-<feat>} 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 <nixpkgs/.git>",
"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" "<name>" "bar"]) == "foo.<name>.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 = [ <list of disabled modules> ];
# All modules of the main module list
modules = [
{
key = <key1>;
module = <module for key1>;
# All modules imported by the module for key1
modules = [
{
key = <key1-1>;
module = <module for key1-1>;
# 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" ] "<replacement instructions>"
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 = <CODE>; }
=> 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
"<pkg>.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 <nixpkgs> {}
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 []
=> "<root attribute path>"",
"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 <nixpkgs> {} }:
{
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/<store path>
writeTextFile {
name = "my-file";
text = ''
Contents of File
'';
}
See also the \`writeText\` helper function below.
# Writes executable my-file to /nix/store/<store path>/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/<store path>
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/<store path>/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/<store path> 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/<store path> 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/<store path>/bin/<name> and
marks the file as executable.",
"example": "# Writes my-file to /nix/store/<store path>/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/<store path> 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/<store path>/bin/<name> and checks its syntax.
Automatically includes interpreter above the contents passed.",
"example": "# Writes my-file to /nix/store/<store path>/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/<store path>/bin/<name> 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/<store path>/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/<store path>
concatTextFile {
name = "my-file";
files = [ drv1 "\${drv2}/path/to/file" ];
}
See also the \`concatText\` helper function below.
# Writes executable my-file to /nix/store/<store path>/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/<store path>
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/<store path>
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 <path>} can be
shortened to \${<path>}.",
"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",
},
]
`;
Reference in New Issue View Git Blame Copy Permalink