diff options
Diffstat (limited to 'doc/manual/writing-nix-expressions.xml')
| -rw-r--r-- | doc/manual/writing-nix-expressions.xml | 99 |
1 files changed, 77 insertions, 22 deletions
diff --git a/doc/manual/writing-nix-expressions.xml b/doc/manual/writing-nix-expressions.xml index 310dd5ae0..3c2d06eec 100644 --- a/doc/manual/writing-nix-expressions.xml +++ b/doc/manual/writing-nix-expressions.xml @@ -11,6 +11,13 @@ the things that tell Nix how to build packages. It starts with a simple example (a Nix expression for GNU Hello), and then moves on to a more in-depth look at the Nix expression language.</para> +<note><para>This chapter is mostly about the Nix expression language. +For more extensive information on adding packages to the Nix Packages +collection (such as functions in the standard environment and coding +conventions), please consult <link +xlink:href="http://hydra.nixos.org/job/nixpkgs/trunk/tarball/latest/download-by-type/doc/manual">its +manual</link>.</para></note> + <section><title>A simple Nix expression</title> @@ -315,15 +322,15 @@ error check.</para> rec { <co xml:id='ex-hello-composition-co-1' /> - hello = (import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' />) { <co xml:id='ex-hello-composition-co-3' /> + hello = import ../applications/misc/hello/ex-1 <co xml:id='ex-hello-composition-co-2' /> { <co xml:id='ex-hello-composition-co-3' /> inherit fetchurl stdenv perl; }; - perl = (import ../development/interpreters/perl) { <co xml:id='ex-hello-composition-co-4' /> + perl = import ../development/interpreters/perl { <co xml:id='ex-hello-composition-co-4' /> inherit fetchurl stdenv; }; - fetchurl = (import ../build-support/fetchurl) { + fetchurl = import ../build-support/fetchurl { inherit stdenv; ... }; @@ -390,6 +397,23 @@ some fragments of <varname>stdenv.mkDerivation</varname> in <xref linkend='ex-hello-nix' />).</para> + <note><para>Nixpkgs has a convenience function + <function>callPackage</function> that imports and calls a + function, filling in any missing arguments by passing the + corresponding attribute from the Nixpkgs set, like this: + +<programlisting> +hello = callPackage ../applications/misc/hello/ex-1 { }; +</programlisting> + + If necessary, you can set or override arguments: + +<programlisting> +hello = callPackage ../applications/misc/hello/ex-1 { stdenv = myStdenv; }; +</programlisting> + + </para></note> + </callout> <callout arearefs='ex-hello-composition-co-4'> @@ -813,7 +837,23 @@ occur once.</para> <programlisting> { a = "Foo"; b = "Bar"; }.a</programlisting> -evaluates to <literal>"Foo"</literal>.</para> +evaluates to <literal>"Foo"</literal>. It is possible to provide a +default value in an attribute selection using the +<literal>or</literal> keyword. For example, + +<programlisting> +{ a = "Foo"; b = "Bar"; }.c or "Xyzzy"</programlisting> + +will evaluate to <literal>"Xyzzy"</literal> because there is no +<varname>c</varname> attribute in the set.</para> + +<para>You can use arbitrary string constants as attribute names by +enclosing them in quotes: + +<programlisting> +{ "foo bar" = 123; "nix-1.0" = 456; }."foo bar" </programlisting> + +This will evaluate to <literal>123</literal>.</para> </simplesect> @@ -1189,12 +1229,17 @@ weakest binding).</para> </thead> <tbody> <row> - <entry><replaceable>e</replaceable> . - <replaceable>id</replaceable></entry> + <entry><replaceable>e</replaceable> <literal>.</literal> + <replaceable>attrpath</replaceable> + [ <literal>or</literal> <replaceable>def</replaceable> ] + </entry> <entry>none</entry> - <entry>Select attribute named <replaceable>id</replaceable> - from attribute set <replaceable>e</replaceable>. Abort - evaluation if the attribute doesn’t exist.</entry> + <entry>Select attribute denoted by the attribute path + <replaceable>attrpath</replaceable> from attribute set + <replaceable>e</replaceable>. (An attribute path is a + dot-separated list of attribute names.) If the attribute + doesn’t exist, return <replaceable>def</replaceable> if + provided, otherwise abort evaluation.</entry> </row> <row> <entry><replaceable>e1</replaceable> <replaceable>e2</replaceable></entry> @@ -1203,31 +1248,31 @@ weakest binding).</para> argument <replaceable>e2</replaceable>.</entry> </row> <row> - <entry><replaceable>e</replaceable> ? - <replaceable>id</replaceable></entry> + <entry><replaceable>e</replaceable> <literal>?</literal> + <replaceable>attrpath</replaceable></entry> <entry>none</entry> <entry>Test whether attribute set <replaceable>e</replaceable> - contains an attribute named <replaceable>id</replaceable>; + contains the attribute denoted by <replaceable>attrpath</replaceable>; return <literal>true</literal> or <literal>false</literal>.</entry> </row> <row> - <entry><replaceable>e1</replaceable> ++ <replaceable>e2</replaceable></entry> + <entry><replaceable>e1</replaceable> <literal>++</literal> <replaceable>e2</replaceable></entry> <entry>right</entry> <entry>List concatenation.</entry> </row> <row> - <entry><replaceable>e1</replaceable> + <replaceable>e2</replaceable></entry> + <entry><replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable></entry> <entry>left</entry> <entry>String or path concatenation.</entry> </row> <row> - <entry>! <replaceable>e</replaceable></entry> + <entry><literal>!</literal> <replaceable>e</replaceable></entry> <entry>left</entry> <entry>Boolean negation.</entry> </row> <row> - <entry><replaceable>e1</replaceable> // + <entry><replaceable>e1</replaceable> <literal>//</literal> <replaceable>e2</replaceable></entry> <entry>right</entry> <entry>Return an attribute set consisting of the attributes in @@ -1236,31 +1281,31 @@ weakest binding).</para> precedence over the former in case of equally named attributes).</entry> </row> <row> - <entry><replaceable>e1</replaceable> == + <entry><replaceable>e1</replaceable> <literal>==</literal> <replaceable>e2</replaceable></entry> <entry>none</entry> <entry>Equality.</entry> </row> <row> - <entry><replaceable>e1</replaceable> != + <entry><replaceable>e1</replaceable> <literal>!=</literal> <replaceable>e2</replaceable></entry> <entry>none</entry> <entry>Inequality.</entry> </row> <row> - <entry><replaceable>e1</replaceable> && + <entry><replaceable>e1</replaceable> <literal>&&</literal> <replaceable>e2</replaceable></entry> <entry>left</entry> <entry>Logical AND.</entry> </row> <row> - <entry><replaceable>e1</replaceable> || + <entry><replaceable>e1</replaceable> <literal>||</literal> <replaceable>e2</replaceable></entry> <entry>left</entry> <entry>Logical OR.</entry> </row> <row> - <entry><replaceable>e1</replaceable> -> + <entry><replaceable>e1</replaceable> <literal>-></literal> <replaceable>e2</replaceable></entry> <entry>none</entry> <entry>Logical implication (equivalent to @@ -1662,7 +1707,17 @@ impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; </varlistentry> - + <varlistentry><term><varname>preferLocalBuild</varname></term> + + <listitem><para>If this attribute is set to + <literal>true</literal> and <link + linkend="chap-distributed-builds">distributed building is + enabled</link>, then, if possible, perform this build locally + instead of forwarding it to a remote machine. This is appropriate + for trivial builders where the cost of doing a remote build would + exceed the cost of building locally.</para></listitem> + + </varlistentry> </variablelist> |