From 3837fb233cccc8f65629749f07820afba04952a0 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Tue, 3 Oct 2006 15:19:05 +0000 Subject: [PATCH] * Document the built-in functions. --- doc/manual/opt-common.xml | 6 +- doc/manual/style.css | 21 +- doc/manual/writing-nix-expressions.xml | 510 ++++++++++++++++++++++++- 3 files changed, 504 insertions(+), 33 deletions(-) diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml index 2c514cad25..fcfeca858f 100644 --- a/doc/manual/opt-common.xml +++ b/doc/manual/opt-common.xml @@ -190,9 +190,9 @@ escapes Indicate nesting using escape codes that can be - interpreted by the log2xml tool in the Nix - source distribution. The resulting XML file can be fed into the - log2html.xsl stylesheet to create an HTML + interpreted by the nix-log2xml tool in the + Nix source distribution. The resulting XML file can be fed into + the log2html.xsl stylesheet to create an HTML file that can be browsed interactively, using Javascript to expand and collapse parts of the output. diff --git a/doc/manual/style.css b/doc/manual/style.css index 103086de1f..93ab65c4d1 100644 --- a/doc/manual/style.css +++ b/doc/manual/style.css @@ -41,17 +41,6 @@ div.section > div.titlepage h2 /* sections */ margin-top: 1.5em; } -div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ -{ - margin-top: 1.4em; - font-size: 125%; -} - -div.refsection h3 -{ - font-size: 110%; -} - h3 /* subsections */ { font-size: 125%; @@ -63,6 +52,16 @@ div.appendix h3 margin-top: 1.5em; } +div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ +{ + margin-top: 1.4em; + font-size: 125%; +} + +div.refsection h3 +{ + font-size: 110%; +} /*************************************************************************** diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 74ef3a868e..9f7fed8fde 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -586,14 +586,18 @@ components. language. +
Values + + Simple values Nix has the following basic datatypes: - Strings, enclosed between - double quotes, e.g., "foo bar". + Strings, + enclosed between double quotes, e.g., "foo bar". + TODO: antiquotations, escaping. Integers, e.g., 123. @@ -681,6 +685,12 @@ evaluates to "Foo". +
+ + +
Language constructs + + Recursive attribute sets Recursive attribute sets are just normal attribute sets, but the @@ -836,7 +846,7 @@ allows partial parameterisation (i.e., only filling some of the arguments of a function); e.g., -map (concat "foo") ["bar", "bla", "abc"] +map (concat "foo") ["bar" "bla" "abc"] evaluates to ["foobar" "foobla" "fooabc"]. @@ -977,7 +987,19 @@ locally in a rec-expression. -Operators +Comments + +Comments can be single-line, started with a # +character, or inline/multi-line, enclosed within /* +... */. + + + + +
+ + +
Operators lists the operators in the Nix expression language, in order of precedence (from strongest to @@ -994,13 +1016,28 @@ weakest binding). + + e . + id + none + Select attribute named id + from attribute set e. Abort + evaluation if the attribute doesn’t exist. + + + e1 e2 + left + Call function e1 with + argument e2. + e ? id none Test whether attribute set e - contains an attribute named - id. + contains an attribute named id; + return true or + false. e1 ++ e2 @@ -1062,10 +1099,10 @@ weakest binding). - +
-Derivations +
Derivations The most important built-in function is derivation, which is used to describe a @@ -1230,23 +1267,457 @@ command-line argument. See - +
-Other built-in functions +
Built-in functions TODO - + + + + abort s + + Abort Nix expression evaluation, print error + message s. + + + + + builtins.add + e1 e2 + + Add integers e1 and + e2.. + + + + + 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 + + The attribute 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., + + +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. + However, in that case you should not write + + +if builtins ? getEnv then __getEnv "PATH" else "" + + This Nix expression will trigger an “undefined variable” error on + older Nix versions since __getEnv doesn’t + exist. builtins.getEnv, on the other hand, is + safe since builtins always exists and attribute + selection is lazy, so it’s only performed if the test + succeeds. + + + + + 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 + "powerpc-darwin". + + -Comments + + + + + + + derivation + attrs + + derivation is described in + . + + + + + 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.getAttr + s attrs + + getAttr returns the attribute + named s from the attribute set + attrs. 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 attrs + + hasAttr returns + true if the attribute set + attrs 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.head + list + + Return the first element of a list; abort + evaluation if the argument isn’t a list or is an empty list. You + can test whether a list is empty by comparing it with + []. + + + + + import + path + + Load, parse and return the Nix expression in the + file path. 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 an attribute set + or a function) in a separate file, and use it from Nix expressions + in other files. + + 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 + + +rec { + x = 123; + y = import ./foo.nix; +} + + then the following foo.nix will give an + error: + + +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: + + +rec { + x = 123; + y = import ./foo.nix x; +} + + and + + +x: x + 456 + + (The function argument doesn’t have to be called + x in foo.nix; any name + would work.) + + + + + builtins.isList + e + + Return true if + e evaluates to a list, and + false otherwise. + + + + + isNull + e + + Return true if + e evaluates to null, + and false otherwise. + + This function is deprecated; + just write e == null instead. + + + + + + + builtins.lessThan + e1 e2 + + Return true if the integer + e1 is less than the integer + e2, and false + otherwise. Evaluation aborts if either + e1 or e2 + does not evaluate to an integer. + + + + + map + f list + + Apply the function f to + each element in the list list. For + example, + + +map (x: "foo" + x) ["bar" "bla" "abc"] + + evaluates to ["foobar" "foobla" + "fooabc"]. + + + + + builtins.pathExists + path + + Return true if the path + path exists, and + false otherwise. One application of this + function is to conditionally include a Nix expression containing + user configuration: + + +let + fileName = builtins.getEnv "CONFIG_FILE"; + config = + if fileName != "" && builtins.pathExists (builtins.toPath fileName) + then import (builtins.toPath fileName) + else { someSetting = false; }; # default configuration +in config.someSetting + + (Note that CONFIG_FILE must be an absolute path for + this to work.) + + + + + + + + removeAttrs + attrs list + + Remove the attributes listed in + list from the attribute set + attrs. The attributes don’t have to + exist in attrs. For instance, + + +removeAttrs { x = 1; y = 2; z = 3; } ["a" "x" "z"] + + evaluates to {y = 2;}. + + + + + 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. + + + + + 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 + and into one file: + + +{stdenv, fetchurl, perl}: + +stdenv.mkDerivation { + name = "hello-2.1.1"; + + builder = builtins.toFile "builder.sh" " + source $stdenv/setup + + PATH=$perl/bin:$PATH + + tar xvfz $src + cd hello-* + ./configure --prefix=$out + make + make install + "; + + src = fetchurl { + url = http://nix.cs.uu.nl/dist/tarballs/hello-2.1.1.tar.gz; + md5 = "70c9ccf9fac07f762c24f2df2290784d"; + }; + inherit perl; +} + + + + It is even possible for one file to refer to another, e.g., + + + builder = let + configFile = builtins.toFile "foo.conf" " + # This is some dummy configuration file. + ... + "; + in builtins.toFile "builder.sh" " + source $stdenv/setup + ... + cp ${configFile} $out/etc/foo.conf + "; + + Note that ${configFile} is an antiquotation + (see ), 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: + + +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. + + + + + builtins.toPath s + + Convert the string value + s into a path value. The string + s must represent an absolute path + (i.e., must start with /). The path need not + exist. The resulting path is canonicalised, e.g., + builtins.toPath "//foo/xyzzy/../bar/" returns + /foo/bar. + + + + + toString e + + Convert the expression + e to a string. + e can be a string (in which case + toString is a no-op) or a path (e.g., + toString /foo/bar yields + "/foo/bar". + + + + + 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. + + + + + + +
@@ -1294,9 +1765,10 @@ of the following components: GNU Make. It has been patched to provide nested output that can be fed into the - log2xml command and log2html - stylesheet to create a structured, readable output of the build - steps performed by Make. + nix-log2xml command and + log2html stylesheet to create a structured, + readable output of the build steps performed by + Make. Bash. This is the shell used for all builders in the Nix Packages collection. Not using /bin/sh