From 612b3e8fa35dde4893f92b4d0a5cfb5aa040f551 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Mon, 22 Oct 2007 15:28:32 +0000 Subject: [PATCH] * Document the new primops in Nix 0.11. --- doc/manual/builtins.xml | 165 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 164 insertions(+), 1 deletion(-) diff --git a/doc/manual/builtins.xml b/doc/manual/builtins.xml index 8f9272505c..1ce40a6076 100644 --- a/doc/manual/builtins.xml +++ b/doc/manual/builtins.xml @@ -1,5 +1,6 @@
+ xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id='ssec-builtins'> Built-in functions @@ -145,6 +146,58 @@ if builtins ? getEnv then __getEnv "PATH" else "" + 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. + + +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: + + + 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). + + + + + + builtins.getAttr s attrs @@ -254,6 +307,16 @@ x: x + 456 + builtins.isAttrs + e + + Return true if + e evaluates to an attribute set, and + false otherwise. + + + + builtins.isList e @@ -264,6 +327,16 @@ x: x + 456 + builtins.isFunction + e + + Return true if + e evaluates to a function, and + false otherwise. + + + + isNull e @@ -292,6 +365,33 @@ x: x + 456 + builtins.listToAttrs + e + + Construct an attribute set from a list specifying + the names and values of each attribute. Each element of the list + should be an attribute set consisting of a string-valued attribute + name specifying the name of the attribute, and + an attribute value specifying its value. + Example: + + +builtins.listToAttrs [ + {name = "foo"; value = 123;} + {name = "bar"; value = 456;} +] + + + evaluates to + + +{ foo = 123; bar = 456; } + + + + + + map f list @@ -357,6 +457,44 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"] + 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 integers + e1 and + e2. + + + + + builtins.substr + 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. + + + + builtins.tail list @@ -367,6 +505,20 @@ removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"] + 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 @@ -582,6 +734,17 @@ stdenv.mkDerivation (rec { + builtins.trace + e1 e2 + + Evaluate e1 and print its + abstract syntax representation on standard error. Then return + e2. This function is useful for + debugging. + + + +