diff options
| -rw-r--r-- | doc/manual/writing-nix-expressions.xml | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index d3514b625997..b6f426d663a7 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -499,6 +499,234 @@ run in parallel. Typically this should be the number of CPUs.</para> </sect2> +<sect2><title>The generic builder</title> + +<para>TODO</para> + +</sect2> + + +</sect1> + + + +<sect1><title>The Nix expression language</title> + +<para>The Nix expression language is a pure, lazy, functional +language. Purity means that operations in the language don't have +side-effects (for instance, there is no variable assignment). +Laziness means that arguments to functions are evaluated only when +they are needed. Functional means that functions are +<quote>normal</quote> values that can be passed around and +manipulated in interesting ways.</para> + +<para>The language is not a full-featured, general purpose language. +It's main job is to describe components, compositions of components, +and the variability within components. For this a functional language +is perfectly suited.</para> + +<para>This section presents the various features of the +language.</para> + + +<simplesect><title>Simple values</title> + +<para>Nix has the following basic datatypes: + +<itemizedlist> + + <listitem><para><emphasis>Strings</emphasis>, enclosed between + double quotes, e.g., <literal>"foo bar"</literal>.</para></listitem> + + <listitem><para><emphasis>Integers</emphasis>, e.g., + <literal>123</literal>.</para></listitem> + + <listitem><para><emphasis>URIs</emphasis> as defined in appendix B + of <ulink url='http://www.ietf.org/rfc/rfc2396.txt'>RFC + 2396</ulink>, e.g., + <literal>https://svn.cs.uu.nl:12443/dist/trace/trace-nix-trunk.tar.bz2</literal>.</para></listitem> + + <listitem><para><emphasis>Paths</emphasis>, e.g., + <filename>/bin/sh</filename> or <filename>./builder.sh</filename>. + A path must contain at least one slash to be recognised as such; for + instance, <filename>builder.sh</filename> is not a + path<footnote><para>It's parsed as an expression that selects the + attribute <varname>sh</varname> from the variable + <varname>builder</varname>.</para></footnote>. If the filename is + relative, i.e., if it does not begin with a slash, it is made + absolute at parse time relative to the directory of the Nix + expression that contained it. For instance, if a Nix expression in + <filename>/foo/bar/bla.nix</filename> refers to + <filename>../xyzzy/fnord.nix</filename>, the absolutised path is + <filename>/foo/xyzzy/fnord.nix</filename>.</para></listitem> + +</itemizedlist> + +</para> + +</simplesect> + + +<simplesect><title>Lists</title> + +<para>Lists are formed by enclosing a whitespace-separated list of +values between square bracktes. For example, + +<programlisting> +[ 123 ./foo.nix "abc" (f {x=y;}) ]</programlisting> + +defines a list of four elements, the last being the result of a call +to the function <varname>f</varname>. Note that function calls have +to be enclosed in parentheses. If they had been omitted, e.g., + +<programlisting> +[ 123 ./foo.nix "abc" f {x=y;} ]</programlisting> + +the result would be a list of five elements, the fourth one being a +function and the fifth being an attribute set.</para> + +</simplesect> + + +<simplesect><title>Attribute sets</title> + +<para>Attribute sets are really the core of the language, since +ultimately it's all about creating derivations, which are really just +sets of attributes to be passed to build scripts.</para> + +<para>Attribute sets are just a list of name/value pairs enclosed in +curly brackets, where each value is an arbitrary expression terminated +by a semicolon. For example: + +<programlisting> +{ x = 123; + text = "Hello"; + y = f { bla = 456; }; +}</programlisting> + +This defines an attribute set with attributes named +<varname>x</varname>, <varname>test</varname>, <varname>y</varname>. +The order of the attributes is irrelevant. An attribute name may only +occur once.</para> + +<para>Attributes can be selected from an attribute set using the +<literal>.</literal> operator. For instance, + +<programlisting> +{ a = "Foo"; b = "Bar"; }.a</programlisting> + +evaluates to <literal>"Foo"</literal>.</para> + +</simplesect> + + +<simplesect><title>Recursive attribute sets</title> + +<para>Recursive attribute sets are just normal attribute sets, but the +attributes can refer to each other. For example, + +<programlisting> +rec { + x = y; + y = 123; +}.x +</programlisting> + +evaluates to <literal>123</literal>. Note that without +<literal>rec</literal> the binding <literal>x = y;</literal> would +refer to the variable <varname>y</varname> in the surrounding scope, +if one exists, and would be invalid if no such variable exists. That +is, in a normal (non-recursive) attribute set, attributes are not +added to the lexical scope; in a recursive set, they are.</para> + +<para>Recursive attribute sets of course introduce the danger of +infinite recursion. For example, + +<programlisting> +rec { + x = y; + y = x; +}.x</programlisting> + +does not terminate<footnote><para>Actually, Nix detects infinite +recursion in this case and aborts (<quote>infinite recursion +encountered</quote>).</para></footnote>.</para> + +</simplesect> + +<!-- +<para>It is often convenient to copy variables from the surrounding +scope (e.g., when you want to propagate attributes). This can be +shortened using the <literal>inherit</literal> keyword. For instance, +--> + + +<simplesect><title>Lets</title> + +<para>TODO</para> + +</simplesect> + + +<simplesect><title>Inheriting attributes</title> + +<para>TODO</para> + +</simplesect> + + +<simplesect><title>Functions</title> + +<para>TODO</para> + +<para>Higher-order functions; map</para> + +</simplesect> + + +<simplesect><title>Conditionals</title> + +<para>TODO</para> + +</simplesect> + + +<simplesect><title><quote>With</quote> expressions</title> + +<para>TODO</para> + +</simplesect> + + +<simplesect><title>Operators</title> + +<para>TODO</para> + +</simplesect> + + +<simplesect><title>Derivations</title> + +<para>TODO</para> + +</simplesect> + + +<simplesect><title>Miscelleneous built-in functions</title> + +<para>TODO</para> + +</simplesect> + + +</sect1> + + + +<sect1><title>The standard environment</title> + +<para>TODO</para> + </sect1> |