forked from lix-project/lix
Move primop docs inline
This makes them available to 'nix repl'.
This commit is contained in:
Eelco Dolstra
parent
33b1679d75
commit
a990f063ff
|
|
@ -38,6 +38,7 @@
|
||||||
- [Operators](expressions/language-operators.md)
|
- [Operators](expressions/language-operators.md)
|
||||||
- [Derivations](expressions/derivations.md)
|
- [Derivations](expressions/derivations.md)
|
||||||
- [Advanced Attributes](expressions/advanced-attributes.md)
|
- [Advanced Attributes](expressions/advanced-attributes.md)
|
||||||
|
- [Built-in Constants](expressions/builtin-constants.md)
|
||||||
- [Built-in Functions](expressions/builtins.md)
|
- [Built-in Functions](expressions/builtins.md)
|
||||||
- [Advanced Topics](advanced-topics/advanced-topics.md)
|
- [Advanced Topics](advanced-topics/advanced-topics.md)
|
||||||
- [Remote Builds](advanced-topics/distributed-builds.md)
|
- [Remote Builds](advanced-topics/distributed-builds.md)
|
||||||
|
|
|
||||||
20
doc/manual/src/expressions/builtin-constants.md
Normal file
20
doc/manual/src/expressions/builtin-constants.md
Normal file
|
|
@ -0,0 +1,20 @@
|
||||||
|
# Built-in Constants
|
||||||
|
|
||||||
|
Here are the constants built into the Nix expression evaluator:
|
||||||
|
|
||||||
|
- `builtins`
|
||||||
|
The set `builtins` contains all the built-in functions and values.
|
||||||
|
You can use `builtins` to test for the availability of features in
|
||||||
|
the Nix installation, e.g.,
|
||||||
|
|
||||||
|
```nix
|
||||||
|
if builtins ? getEnv then builtins.getEnv "PATH" else ""
|
||||||
|
```
|
||||||
|
|
||||||
|
This allows a Nix expression to fall back gracefully on older Nix
|
||||||
|
installations that don’t have the desired built-in function.
|
||||||
|
|
||||||
|
- `builtins.currentSystem`
|
||||||
|
The built-in value `currentSystem` evaluates to the Nix platform
|
||||||
|
identifier for the Nix installation on which the expression is being
|
||||||
|
evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
|
||||||
|
|
@ -1,374 +1,20 @@
|
||||||
# Built-in Functions
|
# Built-in Functions
|
||||||
|
|
||||||
This section lists the functions and constants built into the Nix
|
This section lists the functions built into the Nix expression
|
||||||
expression evaluator. (The built-in function `derivation` is discussed
|
evaluator. (The built-in function `derivation` is discussed above.)
|
||||||
above.) Some built-ins, such as `derivation`, are always in scope of
|
Some built-ins, such as `derivation`, are always in scope of every Nix
|
||||||
every Nix expression; you can just access them right away. But to
|
expression; you can just access them right away. But to prevent
|
||||||
prevent polluting the namespace too much, most built-ins are not in
|
polluting the namespace too much, most built-ins are not in
|
||||||
scope. Instead, you can access them through the `builtins` built-in
|
scope. Instead, you can access them through the `builtins` built-in
|
||||||
value, which is a set that contains all built-in functions and values.
|
value, which is a set that contains all built-in functions and values.
|
||||||
For instance, `derivation` is also available as `builtins.derivation`.
|
For instance, `derivation` is also available as `builtins.derivation`.
|
||||||
|
|
||||||
- `builtins.add` *e1* *e2*
|
|
||||||
Return the sum of the numbers *e1* and *e2*.
|
|
||||||
|
|
||||||
- `builtins.all` *pred* *list*
|
|
||||||
Return `true` if the function *pred* returns `true` for all elements
|
|
||||||
of *list*, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.any` *pred* *list*
|
|
||||||
Return `true` if the function *pred* returns `true` for at least one
|
|
||||||
element of *list*, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.attrNames` *set*
|
|
||||||
Return the names of the attributes in the set *set* in an
|
|
||||||
alphabetically sorted list. For instance, `builtins.attrNames { y
|
|
||||||
= 1; x = "foo"; }` evaluates to `[ "x" "y" ]`.
|
|
||||||
|
|
||||||
- `builtins.attrValues` *set*
|
|
||||||
Return the values of the attributes in the set *set* in the order
|
|
||||||
corresponding to the sorted attribute names.
|
|
||||||
|
|
||||||
- `baseNameOf` *s*
|
|
||||||
Return the *base name* of the string *s*, that is, everything
|
|
||||||
following the final slash in the string. This is similar to the GNU
|
|
||||||
`basename` command.
|
|
||||||
|
|
||||||
- `builtins.bitAnd` *e1* *e2*
|
|
||||||
Return the bitwise AND of the integers *e1* and *e2*.
|
|
||||||
|
|
||||||
- `builtins.bitOr` *e1* *e2*
|
|
||||||
Return the bitwise OR of the integers *e1* and *e2*.
|
|
||||||
|
|
||||||
- `builtins.bitXor` *e1* *e2*
|
|
||||||
Return the bitwise XOR of the integers *e1* and *e2*.
|
|
||||||
|
|
||||||
- `builtins`
|
|
||||||
The set `builtins` contains all the built-in functions and values.
|
|
||||||
You can use `builtins` to test for the availability of features in
|
|
||||||
the Nix installation, e.g.,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
if builtins ? getEnv then builtins.getEnv "PATH" else ""
|
|
||||||
```
|
|
||||||
|
|
||||||
This allows a Nix expression to fall back gracefully on older Nix
|
|
||||||
installations that don’t have the desired built-in function.
|
|
||||||
|
|
||||||
- `builtins.compareVersions` *s1* *s2*
|
|
||||||
Compare two strings representing versions and return `-1` if
|
|
||||||
version *s1* is older than version *s2*, `0` if they are the same,
|
|
||||||
and `1` if *s1* is newer than *s2*. The version comparison
|
|
||||||
algorithm is the same as the one used by [`nix-env
|
|
||||||
-u`](../command-ref/nix-env.md#operation---upgrade).
|
|
||||||
|
|
||||||
- `builtins.concatLists` *lists*
|
|
||||||
Concatenate a list of lists into a single list.
|
|
||||||
|
|
||||||
- `builtins.concatStringsSep` *separator* *list*
|
|
||||||
Concatenate a list of strings with a separator between each
|
|
||||||
element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] ==
|
|
||||||
"usr/local/bin"`
|
|
||||||
|
|
||||||
- `builtins.currentSystem`
|
|
||||||
The built-in value `currentSystem` evaluates to the Nix platform
|
|
||||||
identifier for the Nix installation on which the expression is being
|
|
||||||
evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
|
|
||||||
|
|
||||||
- `builtins.deepSeq` *e1* *e2*
|
|
||||||
This is like `seq e1 e2`, except that *e1* is evaluated *deeply*:
|
|
||||||
if it’s a list or set, its elements or attributes are also
|
|
||||||
evaluated recursively.
|
|
||||||
|
|
||||||
- `derivation` *attrs*; `builtins.derivation` *attrs*
|
- `derivation` *attrs*; `builtins.derivation` *attrs*
|
||||||
|
|
||||||
`derivation` is described in [its own section](derivations.md).
|
`derivation` is described in [its own section](derivations.md).
|
||||||
|
|
||||||
- `dirOf` *s*; `builtins.dirOf` *s*
|
|
||||||
Return the directory part of the string *s*, that is, everything
|
|
||||||
before the final slash in the string. This is similar to the GNU
|
|
||||||
`dirname` command.
|
|
||||||
|
|
||||||
- `builtins.div` *e1* *e2*
|
|
||||||
Return the quotient of the numbers *e1* and *e2*.
|
|
||||||
|
|
||||||
- `builtins.elem` *x* *xs*
|
|
||||||
Return `true` if a value equal to *x* occurs in the list *xs*, and
|
|
||||||
`false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.elemAt` *xs* *n*
|
|
||||||
Return element *n* from the list *xs*. Elements are counted starting
|
|
||||||
from 0. A fatal error occurs if the index is out of bounds.
|
|
||||||
|
|
||||||
- `builtins.fetchurl` *url*
|
|
||||||
Download the specified URL and return the path of the downloaded
|
|
||||||
file. This function is not available if [restricted evaluation
|
|
||||||
mode](../command-ref/conf-file.md) is enabled.
|
|
||||||
|
|
||||||
- `fetchTarball` *url*; `builtins.fetchTarball` *url*
|
|
||||||
Download the specified URL, unpack it and return the path of the
|
|
||||||
unpacked tree. The file must be a tape archive (`.tar`) compressed
|
|
||||||
with `gzip`, `bzip2` or `xz`. The top-level path component of the
|
|
||||||
files in the tarball is removed, so it is best if the tarball
|
|
||||||
contains a single directory at top level. The typical use of the
|
|
||||||
function is to obtain external Nix expression dependencies, such as
|
|
||||||
a particular version of Nixpkgs, e.g.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {};
|
|
||||||
|
|
||||||
stdenv.mkDerivation { … }
|
|
||||||
```
|
|
||||||
|
|
||||||
The fetched tarball is cached for a certain amount of time (1 hour
|
|
||||||
by default) in `~/.cache/nix/tarballs/`. You can change the cache
|
|
||||||
timeout either on the command line with `--option tarball-ttl number
|
|
||||||
of seconds` or in the Nix configuration file with this option: `
|
|
||||||
number of seconds to cache `.
|
|
||||||
|
|
||||||
Note that when obtaining the hash with ` nix-prefetch-url ` the
|
|
||||||
option `--unpack` is required.
|
|
||||||
|
|
||||||
This function can also verify the contents against a hash. In that
|
|
||||||
case, the function takes a set instead of a URL. The set requires
|
|
||||||
the attribute `url` and the attribute `sha256`, e.g.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
with import (fetchTarball {
|
|
||||||
url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz";
|
|
||||||
sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
|
|
||||||
}) {};
|
|
||||||
|
|
||||||
stdenv.mkDerivation { … }
|
|
||||||
```
|
|
||||||
|
|
||||||
This function is not available if [restricted evaluation
|
|
||||||
mode](../command-ref/conf-file.md) is enabled.
|
|
||||||
|
|
||||||
- `builtins.fetchGit` *args*
|
|
||||||
Fetch a path from git. *args* can be a URL, in which case the HEAD
|
|
||||||
of the repo at that URL is fetched. Otherwise, it can be an
|
|
||||||
attribute with the following attributes (all except `url` optional):
|
|
||||||
|
|
||||||
- url
|
|
||||||
The URL of the repo.
|
|
||||||
|
|
||||||
- name
|
|
||||||
The name of the directory the repo should be exported to in the
|
|
||||||
store. Defaults to the basename of the URL.
|
|
||||||
|
|
||||||
- rev
|
|
||||||
The git revision to fetch. Defaults to the tip of `ref`.
|
|
||||||
|
|
||||||
- ref
|
|
||||||
The git ref to look for the requested revision under. This is
|
|
||||||
often a branch or tag name. Defaults to `HEAD`.
|
|
||||||
|
|
||||||
By default, the `ref` value is prefixed with `refs/heads/`. As
|
|
||||||
of Nix 2.3.0 Nix will not prefix `refs/heads/` if `ref` starts
|
|
||||||
with `refs/`.
|
|
||||||
|
|
||||||
- submodules
|
|
||||||
A Boolean parameter that specifies whether submodules should be
|
|
||||||
checked out. Defaults to `false`.
|
|
||||||
|
|
||||||
Here are some examples of how to use `fetchGit`.
|
|
||||||
|
|
||||||
- To fetch a private repository over SSH:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.fetchGit {
|
|
||||||
url = "git@github.com:my-secret/repository.git";
|
|
||||||
ref = "master";
|
|
||||||
rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- To fetch an arbitrary reference:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.fetchGit {
|
|
||||||
url = "https://github.com/NixOS/nix.git";
|
|
||||||
ref = "refs/heads/0.5-release";
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- If the revision you're looking for is in the default branch of
|
|
||||||
the git repository you don't strictly need to specify the branch
|
|
||||||
name in the `ref` attribute.
|
|
||||||
|
|
||||||
However, if the revision you're looking for is in a future
|
|
||||||
branch for the non-default branch you will need to specify the
|
|
||||||
the `ref` attribute as well.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.fetchGit {
|
|
||||||
url = "https://github.com/nixos/nix.git";
|
|
||||||
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
|
|
||||||
ref = "1.11-maintenance";
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note**
|
|
||||||
>
|
|
||||||
> It is nice to always specify the branch which a revision
|
|
||||||
> belongs to. Without the branch being specified, the fetcher
|
|
||||||
> might fail if the default branch changes. Additionally, it can
|
|
||||||
> be confusing to try a commit from a non-default branch and see
|
|
||||||
> the fetch fail. If the branch is specified the fault is much
|
|
||||||
> more obvious.
|
|
||||||
|
|
||||||
- If the revision you're looking for is in the default branch of
|
|
||||||
the git repository you may omit the `ref` attribute.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.fetchGit {
|
|
||||||
url = "https://github.com/nixos/nix.git";
|
|
||||||
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- To fetch a specific tag:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.fetchGit {
|
|
||||||
url = "https://github.com/nixos/nix.git";
|
|
||||||
ref = "refs/tags/1.9";
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- To fetch the latest version of a remote branch:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.fetchGit {
|
|
||||||
url = "ssh://git@github.com/nixos/nix.git";
|
|
||||||
ref = "master";
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> **Note**
|
|
||||||
>
|
|
||||||
> Nix will refetch the branch in accordance with
|
|
||||||
> the option `tarball-ttl`.
|
|
||||||
|
|
||||||
> **Note**
|
|
||||||
>
|
|
||||||
> This behavior is disabled in *Pure evaluation mode*.
|
|
||||||
|
|
||||||
- `builtins.filter` *f* *xs*
|
|
||||||
Return a list consisting of the elements of *xs* for which the
|
|
||||||
function *f* returns `true`.
|
|
||||||
|
|
||||||
- `builtins.filterSource` *e1* *e2*
|
|
||||||
This function allows you to copy sources into the Nix store while
|
|
||||||
filtering certain files. For instance, suppose that you want to use
|
|
||||||
the directory `source-dir` as an input to a Nix expression, e.g.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
stdenv.mkDerivation {
|
|
||||||
...
|
|
||||||
src = ./source-dir;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
However, if `source-dir` is a Subversion working copy, then all
|
|
||||||
those annoying `.svn` subdirectories will also be copied to the
|
|
||||||
store. Worse, the contents of those directories may change a lot,
|
|
||||||
causing lots of spurious rebuilds. With `filterSource` you can
|
|
||||||
filter out the `.svn` directories:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
src = builtins.filterSource
|
|
||||||
(path: type: type != "directory" || baseNameOf path != ".svn")
|
|
||||||
./source-dir;
|
|
||||||
```
|
|
||||||
|
|
||||||
Thus, the first argument *e1* must be a predicate function that is
|
|
||||||
called for each regular file, directory or symlink in the source
|
|
||||||
tree *e2*. If the function returns `true`, the file is copied to the
|
|
||||||
Nix store, otherwise it is omitted. The function is called with two
|
|
||||||
arguments. The first is the full path of the file. The second is a
|
|
||||||
string that identifies the type of the file, which is either
|
|
||||||
`"regular"`, `"directory"`, `"symlink"` or `"unknown"` (for other
|
|
||||||
kinds of files such as device nodes or fifos — but note that those
|
|
||||||
cannot be copied to the Nix store, so if the predicate returns
|
|
||||||
`true` for them, the copy will fail). If you exclude a directory,
|
|
||||||
the entire corresponding subtree of *e2* will be excluded.
|
|
||||||
|
|
||||||
- `builtins.foldl’` *op* *nul* *list*
|
|
||||||
Reduce a list by applying a binary operator, from left to right,
|
|
||||||
e.g. `foldl’ op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2)
|
|
||||||
...`. The operator is applied strictly, i.e., its arguments are
|
|
||||||
evaluated first. For example, `foldl’ (x: y: x + y) 0 [1 2 3]`
|
|
||||||
evaluates to 6.
|
|
||||||
|
|
||||||
- `builtins.functionArgs` *f*
|
|
||||||
Return a set containing the names of the formal arguments expected
|
|
||||||
by the function *f*. The value of each attribute is a Boolean
|
|
||||||
denoting whether the corresponding argument has a default value. For
|
|
||||||
instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y =
|
|
||||||
true; }`.
|
|
||||||
|
|
||||||
"Formal argument" here refers to the attributes pattern-matched by
|
|
||||||
the function. Plain lambdas are not included, e.g. `functionArgs (x:
|
|
||||||
...) = { }`.
|
|
||||||
|
|
||||||
- `builtins.fromJSON` *e*
|
|
||||||
Convert a JSON string to a Nix value. For example,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
|
|
||||||
```
|
|
||||||
|
|
||||||
returns the value `{ x = [ 1 2 3 ]; y = null; }`.
|
|
||||||
|
|
||||||
- `builtins.genList` *generator* *length*
|
|
||||||
Generate list of size *length*, with each element *i* equal to the
|
|
||||||
value returned by *generator* `i`. For example,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.genList (x: x * x) 5
|
|
||||||
```
|
|
||||||
|
|
||||||
returns the list `[ 0 1 4 9 16 ]`.
|
|
||||||
|
|
||||||
- `builtins.getAttr` *s* *set*
|
|
||||||
`getAttr` returns the attribute named *s* from *set*. Evaluation
|
|
||||||
aborts if the attribute doesn’t exist. This is a dynamic version of
|
|
||||||
the `.` operator, since *s* is an expression rather than an
|
|
||||||
identifier.
|
|
||||||
|
|
||||||
- `builtins.getEnv` *s*
|
|
||||||
`getEnv` returns the value of the environment variable *s*, or an
|
|
||||||
empty string if the variable doesn’t exist. This function should be
|
|
||||||
used with care, as it can introduce all sorts of nasty environment
|
|
||||||
dependencies in your Nix expression.
|
|
||||||
|
|
||||||
`getEnv` is used in Nix Packages to locate the file
|
|
||||||
`~/.nixpkgs/config.nix`, which contains user-local settings for Nix
|
|
||||||
Packages. (That is, it does a `getEnv "HOME"` to locate the user’s
|
|
||||||
home directory.)
|
|
||||||
|
|
||||||
- `builtins.hasAttr` *s* *set*
|
|
||||||
`hasAttr` returns `true` if *set* has an attribute named *s*, and
|
|
||||||
`false` otherwise. This is a dynamic version of the `?` operator,
|
|
||||||
since *s* is an expression rather than an identifier.
|
|
||||||
|
|
||||||
- `builtins.hashString` *type* *s*
|
|
||||||
Return a base-16 representation of the cryptographic hash of string
|
|
||||||
*s*. The hash algorithm specified by *type* must be one of `"md5"`,
|
|
||||||
`"sha1"`, `"sha256"` or `"sha512"`.
|
|
||||||
|
|
||||||
- `builtins.hashFile` *type* *p*
|
|
||||||
Return a base-16 representation of the cryptographic hash of the
|
|
||||||
file at path *p*. The hash algorithm specified by *type* must be one
|
|
||||||
of `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`.
|
|
||||||
|
|
||||||
- `builtins.head` *list*
|
|
||||||
Return the first element of a list; abort evaluation if the argument
|
|
||||||
isn’t a list or is an empty list. You can test whether a list is
|
|
||||||
empty by comparing it with `[]`.
|
|
||||||
|
|
||||||
- `import` *path*; `builtins.import` *path*
|
- `import` *path*; `builtins.import` *path*
|
||||||
|
|
||||||
Load, parse and return the Nix expression in the file *path*. If
|
Load, parse and return the Nix expression in the file *path*. If
|
||||||
*path* is a directory, the file ` default.nix ` in that directory
|
*path* is a directory, the file ` default.nix ` in that directory
|
||||||
is loaded. Evaluation aborts if the file doesn’t exist or contains
|
is loaded. Evaluation aborts if the file doesn’t exist or contains
|
||||||
|
|
@ -420,491 +66,3 @@ For instance, `derivation` is also available as `builtins.derivation`.
|
||||||
|
|
||||||
(The function argument doesn’t have to be called `x` in `foo.nix`;
|
(The function argument doesn’t have to be called `x` in `foo.nix`;
|
||||||
any name would work.)
|
any name would work.)
|
||||||
|
|
||||||
- `builtins.intersectAttrs` *e1* *e2*
|
|
||||||
Return a set consisting of the attributes in the set *e2* that also
|
|
||||||
exist in the set *e1*.
|
|
||||||
|
|
||||||
- `builtins.isAttrs` *e*
|
|
||||||
Return `true` if *e* evaluates to a set, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.isList` *e*
|
|
||||||
Return `true` if *e* evaluates to a list, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.isFunction` *e*
|
|
||||||
Return `true` if *e* evaluates to a function, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.isString` *e*
|
|
||||||
Return `true` if *e* evaluates to a string, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.isInt` *e*
|
|
||||||
Return `true` if *e* evaluates to an int, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.isFloat` *e*
|
|
||||||
Return `true` if *e* evaluates to a float, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.isBool` *e*
|
|
||||||
Return `true` if *e* evaluates to a bool, and `false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.isPath` *e*
|
|
||||||
Return `true` if *e* evaluates to a path, and `false` otherwise.
|
|
||||||
|
|
||||||
- `isNull` *e*; `builtins.isNull` *e*
|
|
||||||
Return `true` if *e* evaluates to `null`, and `false` otherwise.
|
|
||||||
|
|
||||||
> **Warning**
|
|
||||||
>
|
|
||||||
> This function is *deprecated*; just write `e == null` instead.
|
|
||||||
|
|
||||||
- `builtins.length` *e*
|
|
||||||
Return the length of the list *e*.
|
|
||||||
|
|
||||||
- `builtins.lessThan` *e1* *e2*
|
|
||||||
Return `true` if the number *e1* is less than the number *e2*, and
|
|
||||||
`false` otherwise. Evaluation aborts if either *e1* or *e2* does not
|
|
||||||
evaluate to a number.
|
|
||||||
|
|
||||||
- `builtins.listToAttrs` *e*
|
|
||||||
Construct a set from a list specifying the names and values of each
|
|
||||||
attribute. Each element of the list should be a set consisting of a
|
|
||||||
string-valued attribute `name` specifying the name of the attribute,
|
|
||||||
and an attribute `value` specifying its value. Example:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.listToAttrs
|
|
||||||
[ { name = "foo"; value = 123; }
|
|
||||||
{ name = "bar"; value = 456; }
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
evaluates to
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ foo = 123; bar = 456; }
|
|
||||||
```
|
|
||||||
|
|
||||||
- `map` *f* *list*; `builtins.map` *f* *list*
|
|
||||||
Apply the function *f* to each element in the list *list*. For
|
|
||||||
example,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
map (x: "foo" + x) [ "bar" "bla" "abc" ]
|
|
||||||
```
|
|
||||||
|
|
||||||
evaluates to `[ "foobar" "foobla" "fooabc" ]`.
|
|
||||||
|
|
||||||
- `builtins.match` *regex* *str*
|
|
||||||
Returns a list if the [extended POSIX regular
|
|
||||||
expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
|
|
||||||
*regex* matches *str* precisely, otherwise returns `null`. Each item
|
|
||||||
in the list is a regex group.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.match "ab" "abc"
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `null`.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.match "abc" "abc"
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `[ ]`.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.match "a(b)(c)" "abc"
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `[ "b" "c" ]`.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO "
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `[ "foo" ]`.
|
|
||||||
|
|
||||||
- `builtins.mul` *e1* *e2*
|
|
||||||
Return the product of the numbers *e1* and *e2*.
|
|
||||||
|
|
||||||
- `builtins.parseDrvName` *s*
|
|
||||||
Split the string *s* into a package name and version. The package
|
|
||||||
name is everything up to but not including the first dash followed
|
|
||||||
by a digit, and the version is everything following that dash. The
|
|
||||||
result is returned in a set `{ name, version }`. Thus,
|
|
||||||
`builtins.parseDrvName "nix-0.12pre12876"` returns `{ name =
|
|
||||||
"nix"; version = "0.12pre12876"; }`.
|
|
||||||
|
|
||||||
- `builtins.path` *args*
|
|
||||||
An enrichment of the built-in path type, based on the attributes
|
|
||||||
present in *args*. All are optional except `path`:
|
|
||||||
|
|
||||||
- path
|
|
||||||
The underlying path.
|
|
||||||
|
|
||||||
- name
|
|
||||||
The name of the path when added to the store. This can used to
|
|
||||||
reference paths that have nix-illegal characters in their names,
|
|
||||||
like `@`.
|
|
||||||
|
|
||||||
- filter
|
|
||||||
A function of the type expected by `builtins.filterSource`,
|
|
||||||
with the same semantics.
|
|
||||||
|
|
||||||
- recursive
|
|
||||||
When `false`, when `path` is added to the store it is with a
|
|
||||||
flat hash, rather than a hash of the NAR serialization of the
|
|
||||||
file. Thus, `path` must refer to a regular file, not a
|
|
||||||
directory. This allows similar behavior to `fetchurl`. Defaults
|
|
||||||
to `true`.
|
|
||||||
|
|
||||||
- sha256
|
|
||||||
When provided, this is the expected hash of the file at the
|
|
||||||
path. Evaluation will fail if the hash is incorrect, and
|
|
||||||
providing a hash allows `builtins.path` to be used even when the
|
|
||||||
`pure-eval` nix config option is on.
|
|
||||||
|
|
||||||
- `builtins.pathExists` *path*
|
|
||||||
Return `true` if the path *path* exists at evaluation time, and
|
|
||||||
`false` otherwise.
|
|
||||||
|
|
||||||
- `builtins.placeholder` *output*
|
|
||||||
Return a placeholder string for the specified *output* that will be
|
|
||||||
substituted by the corresponding output path at build time. Typical
|
|
||||||
outputs would be `"out"`, `"bin"` or `"dev"`.
|
|
||||||
|
|
||||||
- `builtins.readDir` *path*
|
|
||||||
Return the contents of the directory *path* as a set mapping
|
|
||||||
directory entries to the corresponding file type. For instance, if
|
|
||||||
directory `A` contains a regular file `B` and another directory
|
|
||||||
`C`, then `builtins.readDir ./A` will return the set
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ B = "regular"; C = "directory"; }
|
|
||||||
```
|
|
||||||
|
|
||||||
The possible values for the file type are `"regular"`,
|
|
||||||
`"directory"`, `"symlink"` and `"unknown"`.
|
|
||||||
|
|
||||||
- `builtins.readFile` *path*
|
|
||||||
Return the contents of the file *path* as a string.
|
|
||||||
|
|
||||||
- `removeAttrs` *set* *list*; `builtins.removeAttrs` *set* *list*
|
|
||||||
Remove the attributes listed in *list* from *set*. The attributes
|
|
||||||
don’t have to exist in *set*. For instance,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]
|
|
||||||
```
|
|
||||||
|
|
||||||
evaluates to `{ y = 2; }`.
|
|
||||||
|
|
||||||
- `builtins.replaceStrings` *from* *to* *s*
|
|
||||||
Given string *s*, replace every occurrence of the strings in *from*
|
|
||||||
with the corresponding string in *to*. For example,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
|
|
||||||
```
|
|
||||||
|
|
||||||
evaluates to `"fabir"`.
|
|
||||||
|
|
||||||
- `builtins.seq` *e1* *e2*
|
|
||||||
Evaluate *e1*, then evaluate and return *e2*. This ensures that a
|
|
||||||
computation is strict in the value of *e1*.
|
|
||||||
|
|
||||||
- `builtins.sort` *comparator* *list*
|
|
||||||
Return *list* in sorted order. It repeatedly calls the function
|
|
||||||
*comparator* with two elements. The comparator should return `true`
|
|
||||||
if the first element is less than the second, and `false` otherwise.
|
|
||||||
For example,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
|
|
||||||
```
|
|
||||||
|
|
||||||
produces the list `[ 42 77 147 249 483 526 ]`.
|
|
||||||
|
|
||||||
This is a stable sort: it preserves the relative order of elements
|
|
||||||
deemed equal by the comparator.
|
|
||||||
|
|
||||||
- `builtins.split` *regex* *str*
|
|
||||||
Returns a list composed of non matched strings interleaved with the
|
|
||||||
lists of the [extended POSIX regular
|
|
||||||
expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
|
|
||||||
*regex* matches of *str*. Each item in the lists of matched
|
|
||||||
sequences is a regex group.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.split "(a)b" "abc"
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `[ "" [ "a" ] "c" ]`.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.split "([ac])" "abc"
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `[ "" [ "a" ] "b" [ "c" ] "" ]`.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.split "(a)|(c)" "abc"
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `[ "" [ "a" null ] "b" [ null "c" ] "" ]`.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.split "([[:upper:]]+)" " FOO "
|
|
||||||
```
|
|
||||||
|
|
||||||
Evaluates to `[ " " [ "FOO" ] " " ]`.
|
|
||||||
|
|
||||||
- `builtins.splitVersion` *s*
|
|
||||||
Split a string representing a version into its components, by the
|
|
||||||
same version splitting logic underlying the version comparison in
|
|
||||||
[`nix-env -u`](../command-ref/nix-env.md#operation---upgrade).
|
|
||||||
|
|
||||||
- `builtins.stringLength` *e*
|
|
||||||
Return the length of the string *e*. If *e* is not a string,
|
|
||||||
evaluation is aborted.
|
|
||||||
|
|
||||||
- `builtins.sub` *e1* *e2*
|
|
||||||
Return the difference between the numbers *e1* and *e2*.
|
|
||||||
|
|
||||||
- `builtins.substring` *start* *len* *s*
|
|
||||||
Return the substring of *s* from character position *start*
|
|
||||||
(zero-based) up to but not including *start + len*. If *start* is
|
|
||||||
greater than the length of the string, an empty string is returned,
|
|
||||||
and if *start + len* lies beyond the end of the string, only the
|
|
||||||
substring up to the end of the string is returned. *start* must be
|
|
||||||
non-negative. For example,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builtins.substring 0 3 "nixos"
|
|
||||||
```
|
|
||||||
|
|
||||||
evaluates to `"nix"`.
|
|
||||||
|
|
||||||
- `builtins.tail` *list*
|
|
||||||
Return the second to last elements of a list; abort evaluation if
|
|
||||||
the argument isn’t a list or is an empty list.
|
|
||||||
|
|
||||||
- `throw` *s*; `builtins.throw` *s*
|
|
||||||
Throw an error message *s*. This usually aborts Nix expression
|
|
||||||
evaluation, but in `nix-env -qa` and other commands that try to
|
|
||||||
evaluate a set of derivations to get information about those
|
|
||||||
derivations, a derivation that throws an error is silently skipped
|
|
||||||
(which is not the case for `abort`).
|
|
||||||
|
|
||||||
- `builtins.toFile` *name* *s*
|
|
||||||
Store the string *s* in a file in the Nix store and return its
|
|
||||||
path. The file has suffix *name*. This file can be used as an
|
|
||||||
input to derivations. One application is to write builders
|
|
||||||
“inline”. For instance, the following Nix expression combines the
|
|
||||||
[Nix expression for GNU Hello](expression-syntax.md) and its
|
|
||||||
[build script](build-script.md) into one file:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ stdenv, fetchurl, perl }:
|
|
||||||
|
|
||||||
stdenv.mkDerivation {
|
|
||||||
name = "hello-2.1.1";
|
|
||||||
|
|
||||||
builder = builtins.toFile "builder.sh" "
|
|
||||||
source $stdenv/setup
|
|
||||||
|
|
||||||
PATH=$perl/bin:$PATH
|
|
||||||
|
|
||||||
tar xvfz $src
|
|
||||||
cd hello-*
|
|
||||||
./configure --prefix=$out
|
|
||||||
make
|
|
||||||
make install
|
|
||||||
";
|
|
||||||
|
|
||||||
src = fetchurl {
|
|
||||||
url = "http://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
|
|
||||||
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
|
|
||||||
};
|
|
||||||
inherit perl;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
It is even possible for one file to refer to another, e.g.,
|
|
||||||
|
|
||||||
```nix
|
|
||||||
builder = let
|
|
||||||
configFile = builtins.toFile "foo.conf" "
|
|
||||||
# This is some dummy configuration file.
|
|
||||||
...
|
|
||||||
";
|
|
||||||
in builtins.toFile "builder.sh" "
|
|
||||||
source $stdenv/setup
|
|
||||||
...
|
|
||||||
cp ${configFile} $out/etc/foo.conf
|
|
||||||
";
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that `${configFile}` is an
|
|
||||||
[antiquotation](language-values.md), so the result of the
|
|
||||||
expression `configFile`
|
|
||||||
(i.e., a path like `/nix/store/m7p7jfny445k...-foo.conf`) will be
|
|
||||||
spliced into the resulting string.
|
|
||||||
|
|
||||||
It is however *not* allowed to have files mutually referring to each
|
|
||||||
other, like so:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
let
|
|
||||||
foo = builtins.toFile "foo" "...${bar}...";
|
|
||||||
bar = builtins.toFile "bar" "...${foo}...";
|
|
||||||
in foo
|
|
||||||
```
|
|
||||||
|
|
||||||
This is not allowed because it would cause a cyclic dependency in
|
|
||||||
the computation of the cryptographic hashes for `foo` and `bar`.
|
|
||||||
|
|
||||||
It is also not possible to reference the result of a derivation. If
|
|
||||||
you are using Nixpkgs, the `writeTextFile` function is able to do
|
|
||||||
that.
|
|
||||||
|
|
||||||
- `builtins.toJSON` *e*
|
|
||||||
Return a string containing a JSON representation of *e*. Strings,
|
|
||||||
integers, floats, booleans, nulls and lists are mapped to their JSON
|
|
||||||
equivalents. Sets (except derivations) are represented as objects.
|
|
||||||
Derivations are translated to a JSON string containing the
|
|
||||||
derivation’s output path. Paths are copied to the store and
|
|
||||||
represented as a JSON string of the resulting store path.
|
|
||||||
|
|
||||||
- `builtins.toPath` *s*
|
|
||||||
DEPRECATED. Use `/. + "/path"` to convert a string into an absolute
|
|
||||||
path. For relative paths, use `./. + "/path"`.
|
|
||||||
|
|
||||||
- `toString` *e*; `builtins.toString` *e*
|
|
||||||
Convert the expression *e* to a string. *e* can be:
|
|
||||||
|
|
||||||
- A string (in which case the string is returned unmodified).
|
|
||||||
|
|
||||||
- A path (e.g., `toString /foo/bar` yields `"/foo/bar"`.
|
|
||||||
|
|
||||||
- A set containing `{ __toString = self: ...; }`.
|
|
||||||
|
|
||||||
- An integer.
|
|
||||||
|
|
||||||
- A list, in which case the string representations of its elements
|
|
||||||
are joined with spaces.
|
|
||||||
|
|
||||||
- A Boolean (`false` yields `""`, `true` yields `"1"`).
|
|
||||||
|
|
||||||
- `null`, which yields the empty string.
|
|
||||||
|
|
||||||
- `builtins.toXML` *e*
|
|
||||||
Return a string containing an XML representation of *e*. The main
|
|
||||||
application for `toXML` is to communicate information with the
|
|
||||||
builder in a more structured format than plain environment
|
|
||||||
variables.
|
|
||||||
|
|
||||||
Here is an example where this is the case:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ stdenv, fetchurl, libxslt, jira, uberwiki }:
|
|
||||||
|
|
||||||
stdenv.mkDerivation (rec {
|
|
||||||
name = "web-server";
|
|
||||||
|
|
||||||
buildInputs = [ libxslt ];
|
|
||||||
|
|
||||||
builder = builtins.toFile "builder.sh" "
|
|
||||||
source $stdenv/setup
|
|
||||||
mkdir $out
|
|
||||||
echo "$servlets" | xsltproc ${stylesheet} - > $out/server-conf.xml ①
|
|
||||||
";
|
|
||||||
|
|
||||||
stylesheet = builtins.toFile "stylesheet.xsl" ②
|
|
||||||
"<?xml version='1.0' encoding='UTF-8'?>
|
|
||||||
<xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' version='1.0'>
|
|
||||||
<xsl:template match='/'>
|
|
||||||
<Configure>
|
|
||||||
<xsl:for-each select='/expr/list/attrs'>
|
|
||||||
<Call name='addWebApplication'>
|
|
||||||
<Arg><xsl:value-of select=\"attr[@name = 'path']/string/@value\" /></Arg>
|
|
||||||
<Arg><xsl:value-of select=\"attr[@name = 'war']/path/@value\" /></Arg>
|
|
||||||
</Call>
|
|
||||||
</xsl:for-each>
|
|
||||||
</Configure>
|
|
||||||
</xsl:template>
|
|
||||||
</xsl:stylesheet>
|
|
||||||
";
|
|
||||||
|
|
||||||
servlets = builtins.toXML [ ③
|
|
||||||
{ path = "/bugtracker"; war = jira + "/lib/atlassian-jira.war"; }
|
|
||||||
{ path = "/wiki"; war = uberwiki + "/uberwiki.war"; }
|
|
||||||
];
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
The builder is supposed to generate the configuration file for a
|
|
||||||
[Jetty servlet container](http://jetty.mortbay.org/). A servlet
|
|
||||||
container contains a number of servlets (`*.war` files) each
|
|
||||||
exported under a specific URI prefix. So the servlet configuration
|
|
||||||
is a list of sets containing the `path` and `war` of the servlet
|
|
||||||
(①). This kind of information is difficult to communicate with the
|
|
||||||
normal method of passing information through an environment
|
|
||||||
variable, which just concatenates everything together into a
|
|
||||||
string (which might just work in this case, but wouldn’t work if
|
|
||||||
fields are optional or contain lists themselves). Instead the Nix
|
|
||||||
expression is converted to an XML representation with `toXML`,
|
|
||||||
which is unambiguous and can easily be processed with the
|
|
||||||
appropriate tools. For instance, in the example an XSLT stylesheet
|
|
||||||
(at point ②) is applied to it (at point ①) to generate the XML
|
|
||||||
configuration file for the Jetty server. The XML representation
|
|
||||||
produced at point ③ by `toXML` is as follows:
|
|
||||||
|
|
||||||
```xml
|
|
||||||
<?xml version='1.0' encoding='utf-8'?>
|
|
||||||
<expr>
|
|
||||||
<list>
|
|
||||||
<attrs>
|
|
||||||
<attr name="path">
|
|
||||||
<string value="/bugtracker" />
|
|
||||||
</attr>
|
|
||||||
<attr name="war">
|
|
||||||
<path value="/nix/store/d1jh9pasa7k2...-jira/lib/atlassian-jira.war" />
|
|
||||||
</attr>
|
|
||||||
</attrs>
|
|
||||||
<attrs>
|
|
||||||
<attr name="path">
|
|
||||||
<string value="/wiki" />
|
|
||||||
</attr>
|
|
||||||
<attr name="war">
|
|
||||||
<path value="/nix/store/y6423b1yi4sx...-uberwiki/uberwiki.war" />
|
|
||||||
</attr>
|
|
||||||
</attrs>
|
|
||||||
</list>
|
|
||||||
</expr>
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that we used the `toFile` built-in to write the builder and
|
|
||||||
the stylesheet “inline” in the Nix expression. The path of the
|
|
||||||
stylesheet is spliced into the builder using the syntax `xsltproc
|
|
||||||
${stylesheet}`.
|
|
||||||
|
|
||||||
- `builtins.trace` *e1* *e2*
|
|
||||||
Evaluate *e1* and print its abstract syntax representation on
|
|
||||||
standard error. Then return *e2*. This function is useful for
|
|
||||||
debugging.
|
|
||||||
|
|
||||||
- `builtins.tryEval` *e*
|
|
||||||
Try to shallowly evaluate *e*. Return a set containing the
|
|
||||||
attributes `success` (`true` if *e* evaluated successfully,
|
|
||||||
`false` if an error was thrown) and `value`, equalling *e* if
|
|
||||||
successful and `false` otherwise. Note that this doesn't evaluate
|
|
||||||
*e* deeply, so ` let e = { x = throw ""; }; in (builtins.tryEval
|
|
||||||
e).success ` will be `true`. Using ` builtins.deepSeq ` one can
|
|
||||||
get the expected result: `let e = { x = throw ""; }; in
|
|
||||||
(builtins.tryEval (builtins.deepSeq e e)).success` will be
|
|
||||||
`false`.
|
|
||||||
|
|
||||||
- `builtins.typeOf` *e*
|
|
||||||
Return a string representing the type of the value *e*, namely
|
|
||||||
`"int"`, `"bool"`, `"string"`, `"path"`, `"null"`, `"set"`,
|
|
||||||
`"list"`, `"lambda"` or `"float"`.
|
|
||||||
|
|
|
||||||
File diff suppressed because it is too large
Load diff
|
|
@ -226,18 +226,187 @@ static void prim_fetchurl(EvalState & state, const Pos & pos, Value * * args, Va
|
||||||
fetch(state, pos, args, v, "fetchurl", false, "");
|
fetch(state, pos, args, v, "fetchurl", false, "");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
static RegisterPrimOp primop_fetchurl({
|
||||||
|
.name = "__fetchurl",
|
||||||
|
.args = {"url"},
|
||||||
|
.doc = R"(
|
||||||
|
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.
|
||||||
|
)",
|
||||||
|
.fun = prim_fetchurl,
|
||||||
|
});
|
||||||
|
|
||||||
static void prim_fetchTarball(EvalState & state, const Pos & pos, Value * * args, Value & v)
|
static void prim_fetchTarball(EvalState & state, const Pos & pos, Value * * args, Value & v)
|
||||||
{
|
{
|
||||||
fetch(state, pos, args, v, "fetchTarball", true, "source");
|
fetch(state, pos, args, v, "fetchTarball", true, "source");
|
||||||
}
|
}
|
||||||
|
|
||||||
|
static RegisterPrimOp primop_fetchTarball({
|
||||||
|
.name = "fetchTarball",
|
||||||
|
.args = {"args"},
|
||||||
|
.doc = R"(
|
||||||
|
Download the specified URL, unpack it and return the path of the
|
||||||
|
unpacked tree. The file must be a tape archive (`.tar`) compressed
|
||||||
|
with `gzip`, `bzip2` or `xz`. The top-level path component of the
|
||||||
|
files in the tarball is removed, so it is best if the tarball
|
||||||
|
contains a single directory at top level. The typical use of the
|
||||||
|
function is to obtain external Nix expression dependencies, such as
|
||||||
|
a particular version of Nixpkgs, e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz) {};
|
||||||
|
|
||||||
|
stdenv.mkDerivation { … }
|
||||||
|
```
|
||||||
|
|
||||||
|
The fetched tarball is cached for a certain amount of time (1 hour
|
||||||
|
by default) in `~/.cache/nix/tarballs/`. You can change the cache
|
||||||
|
timeout either on the command line with `--option tarball-ttl number
|
||||||
|
of seconds` or in the Nix configuration file with this option: `
|
||||||
|
number of seconds to cache `.
|
||||||
|
|
||||||
|
Note that when obtaining the hash with ` nix-prefetch-url ` the
|
||||||
|
option `--unpack` is required.
|
||||||
|
|
||||||
|
This function can also verify the contents against a hash. In that
|
||||||
|
case, the function takes a set instead of a URL. The set requires
|
||||||
|
the attribute `url` and the attribute `sha256`, e.g.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
with import (fetchTarball {
|
||||||
|
url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz";
|
||||||
|
sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
|
||||||
|
}) {};
|
||||||
|
|
||||||
|
stdenv.mkDerivation { … }
|
||||||
|
```
|
||||||
|
|
||||||
|
This function is not available if [restricted evaluation
|
||||||
|
mode](../command-ref/conf-file.md) is enabled.
|
||||||
|
)",
|
||||||
|
.fun = prim_fetchTarball,
|
||||||
|
});
|
||||||
|
|
||||||
static void prim_fetchGit(EvalState &state, const Pos &pos, Value **args, Value &v)
|
static void prim_fetchGit(EvalState &state, const Pos &pos, Value **args, Value &v)
|
||||||
{
|
{
|
||||||
fetchTree(state, pos, args, v, "git", true);
|
fetchTree(state, pos, args, v, "git", true);
|
||||||
}
|
}
|
||||||
|
|
||||||
static RegisterPrimOp r2("__fetchurl", 1, prim_fetchurl);
|
static RegisterPrimOp primop_fetchGit({
|
||||||
static RegisterPrimOp r3("fetchTarball", 1, prim_fetchTarball);
|
.name = "fetchGit",
|
||||||
static RegisterPrimOp r4("fetchGit", 1, prim_fetchGit);
|
.args = {"args"},
|
||||||
|
.doc = R"(
|
||||||
|
Fetch a path from git. *args* can be a URL, in which case the HEAD
|
||||||
|
of the repo at that URL is fetched. Otherwise, it can be an
|
||||||
|
attribute with the following attributes (all except `url` optional):
|
||||||
|
|
||||||
|
- url
|
||||||
|
The URL of the repo.
|
||||||
|
|
||||||
|
- name
|
||||||
|
The name of the directory the repo should be exported to in the
|
||||||
|
store. Defaults to the basename of the URL.
|
||||||
|
|
||||||
|
- rev
|
||||||
|
The git revision to fetch. Defaults to the tip of `ref`.
|
||||||
|
|
||||||
|
- ref
|
||||||
|
The git ref to look for the requested revision under. This is
|
||||||
|
often a branch or tag name. Defaults to `HEAD`.
|
||||||
|
|
||||||
|
By default, the `ref` value is prefixed with `refs/heads/`. As
|
||||||
|
of Nix 2.3.0 Nix will not prefix `refs/heads/` if `ref` starts
|
||||||
|
with `refs/`.
|
||||||
|
|
||||||
|
- submodules
|
||||||
|
A Boolean parameter that specifies whether submodules should be
|
||||||
|
checked out. Defaults to `false`.
|
||||||
|
|
||||||
|
Here are some examples of how to use `fetchGit`.
|
||||||
|
|
||||||
|
- To fetch a private repository over SSH:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
builtins.fetchGit {
|
||||||
|
url = "git@github.com:my-secret/repository.git";
|
||||||
|
ref = "master";
|
||||||
|
rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- To fetch an arbitrary reference:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
builtins.fetchGit {
|
||||||
|
url = "https://github.com/NixOS/nix.git";
|
||||||
|
ref = "refs/heads/0.5-release";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- If the revision you're looking for is in the default branch of
|
||||||
|
the git repository you don't strictly need to specify the branch
|
||||||
|
name in the `ref` attribute.
|
||||||
|
|
||||||
|
However, if the revision you're looking for is in a future
|
||||||
|
branch for the non-default branch you will need to specify the
|
||||||
|
the `ref` attribute as well.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
builtins.fetchGit {
|
||||||
|
url = "https://github.com/nixos/nix.git";
|
||||||
|
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
|
||||||
|
ref = "1.11-maintenance";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
>
|
||||||
|
> It is nice to always specify the branch which a revision
|
||||||
|
> belongs to. Without the branch being specified, the fetcher
|
||||||
|
> might fail if the default branch changes. Additionally, it can
|
||||||
|
> be confusing to try a commit from a non-default branch and see
|
||||||
|
> the fetch fail. If the branch is specified the fault is much
|
||||||
|
> more obvious.
|
||||||
|
|
||||||
|
- If the revision you're looking for is in the default branch of
|
||||||
|
the git repository you may omit the `ref` attribute.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
builtins.fetchGit {
|
||||||
|
url = "https://github.com/nixos/nix.git";
|
||||||
|
rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- To fetch a specific tag:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
builtins.fetchGit {
|
||||||
|
url = "https://github.com/nixos/nix.git";
|
||||||
|
ref = "refs/tags/1.9";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- To fetch the latest version of a remote branch:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
builtins.fetchGit {
|
||||||
|
url = "ssh://git@github.com/nixos/nix.git";
|
||||||
|
ref = "master";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
>
|
||||||
|
> Nix will refetch the branch in accordance with
|
||||||
|
> the option `tarball-ttl`.
|
||||||
|
|
||||||
|
> **Note**
|
||||||
|
>
|
||||||
|
> This behavior is disabled in *Pure evaluation mode*.
|
||||||
|
)",
|
||||||
|
.fun = prim_fetchGit,
|
||||||
|
});
|
||||||
|
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue