From 55b35d6d776e6f204d446fdadf9e30ed712f0899 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Sun, 7 Nov 2004 13:53:07 +0000 Subject: [PATCH] * Lets, inheritance, assertions. --- doc/manual/writing-nix-expressions.xml | 181 +++++++++++++++++++++++-- 1 file changed, 171 insertions(+), 10 deletions(-) diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index b11f6debeb..d81d741a88 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -638,6 +638,10 @@ language. /foo/bar/bla.nix refers to ../xyzzy/fnord.nix, the absolutised path is /foo/xyzzy/fnord.nix. + + Booleans with values + true and + false. @@ -733,23 +737,85 @@ encountered).. - - Let expressions -TODO +A let expression is a simple short-hand for a +rec expression followed by an attribute selection: +let { attrs } translates +to rec { attrs +}.body. + +For instance, + + +let { + x = "foo"; + y = "bar"; + body = x + y; +} + +is equivalent to + + +rec { + x = "foo"; + y = "bar"; + body = x + y; +}.body + +and evaluates to "foobar". + + Inheriting attributes -TODO +When defining an attribute set itt is often convenient to copy +variables from the surrounding lexical scope (e.g., when you want to +propagate attributes). This can be shortened using the +inherit keyword. For instance, + + +let { + x = 123; + body = { + inherit x; + y = 456; + }; +} + +evaluates to {x = 123; y = 456;}. (Note that this +works because x is added to the lexical scope by +the let construct.) It is also possible to inherit +attributes from another attribute set. For instance, in this fragment +from all-packages-generic.nix, + + + graphviz = (import ../tools/graphics/graphviz) { + inherit fetchurl stdenv libpng libjpeg expat x11 yacc; + inherit (xlibs) libXaw; + }; + + xlibs = { + libX11 = ...; + libXaw = ...; + ... + } + + libpng = ...; + libjpg = ...; + ... + +the attribute set used in the function call to the function defined in +../tools/graphics/graphviz inherits a number of +variables from the surrounding scope (fetchurl +... yacc), but also inherits +libXaw (the X Athena Widgets) from the +xlibs (X11 client-side libraries) attribute +set. @@ -765,11 +831,106 @@ shortened using the inherit keyword. For instance, Conditionals -TODO +Conditionals look like this: + + +if e1 then e2 else e3 + +where e1 is an expression that should +evaluate to a boolean value (true or +false). +Assertions + +Assertions are generally used to check that certain requirements +on or between features and dependencies hold. They look like this: + + +assert e1; e2 + +where e1 is an expression that should +evaluate to a boolean value. If it evaluates to +true, e2 is returned; +otherwise expression evaluation is aborted and a backtrace is printed. + +Nix expression for Subversion + +{ localServer ? false +, httpServer ? false +, sslSupport ? false +, pythonBindings ? false +, javaSwigBindings ? false +, javahlBindings ? false +, stdenv, fetchurl +, openssl ? null, httpd ? null, db4 ? null, expat, swig ? null, j2sdk ? null +}: + +assert localServer -> db4 != null; +assert httpServer -> httpd != null && httpd.expat == expat; +assert sslSupport -> openssl != null && (httpServer -> httpd.openssl == openssl); +assert pythonBindings -> swig != null && swig.pythonSupport; +assert javaSwigBindings -> swig != null && swig.javaSupport; +assert javahlBindings -> j2sdk != null; + +stdenv.mkDerivation { + name = "subversion-1.1.1"; + ... + openssl = if sslSupport then openssl else null; + ... +} + + + show how assertions are +used in the Nix expression for Subversion. + + + + + This assertion states that if Subversion is to have support + for local repositories, then Berkeley DB is needed. So if the + Subversion function is called with the + localServer argument set to + true but the db4 argument + set to null, then the evaluation fails. + + + + This is a more subtle condition: if Subversion is built with + Apache (httpServer) support, then the Expat + library (an XML library) used by Subversion should be same as the + one used by Apache. This is because in this configuration + Subversion code ends up being linked with Apache code, and if the + Expat libraries do not match, a build- or runtime link error or + incompatibility might occur. + + + + This assertion says that in order for Subversion to have SSL + support (so that it can access https URLs), an + OpenSSL library must be passed. Additionally, it says + if Apache support is enabled, then Apache's + OpenSSL should much Subversion's. (Note that if Apache support is + not enabled, we don't care about Apache's OpenSSL.) + + + + The conditional here is not really related to assertions, + but is worth pointing out: it ensures that if SSL support is + disabled, then the Subversion derivation is not dependent on + OpenSSL, even if a non-null value was passed. + This prevents an unnecessary rebuild of Subversion if OpenSSL + changes. + + + + + + + + With expressions TODO @@ -791,7 +952,7 @@ shortened using the inherit keyword. For instance, -Miscelleneous built-in functions +Other built-in functions TODO