diff options
Diffstat (limited to 'doc/manual/expressions')
-rw-r--r-- | doc/manual/expressions/advanced-attributes.xml | 75 | ||||
-rw-r--r-- | doc/manual/expressions/custom-builder.xml | 26 | ||||
-rw-r--r-- | doc/manual/expressions/debug-build.xml | 17 | ||||
-rw-r--r-- | doc/manual/expressions/derivations.xml | 14 | ||||
-rw-r--r-- | doc/manual/expressions/generic-builder.xml | 4 | ||||
-rw-r--r-- | doc/manual/expressions/language-values.xml | 9 | ||||
-rw-r--r-- | doc/manual/expressions/simple-building-testing.xml | 4 | ||||
-rw-r--r-- | doc/manual/expressions/simple-expression.xml | 4 | ||||
-rw-r--r-- | doc/manual/expressions/standard-env.xml | 60 | ||||
-rw-r--r-- | doc/manual/expressions/writing-nix-expressions.xml | 1 |
10 files changed, 82 insertions, 132 deletions
diff --git a/doc/manual/expressions/advanced-attributes.xml b/doc/manual/expressions/advanced-attributes.xml index f8b84b98cb82..83ad6eefc8b1 100644 --- a/doc/manual/expressions/advanced-attributes.xml +++ b/doc/manual/expressions/advanced-attributes.xml @@ -40,7 +40,7 @@ allowedReferences = []; recursively. For example, <programlisting> -allowedReferences = [ foobar ]; +allowedRequisites = [ foobar ]; </programlisting> enforces that the output of a derivation cannot have any other @@ -90,6 +90,33 @@ derivation { </varlistentry> + <varlistentry><term><varname>impureEnvVars</varname></term> + + <listitem><para>This attribute allows you to specify a list of + environment variables that should be passed from the environment + of the calling user to the builder. Usually, the environment is + cleared completely when the builder is executed, but with this + attribute you can allow specific environment variables to be + passed unmodified. For example, <function>fetchurl</function> in + Nixpkgs has the line + +<programlisting> +impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; +</programlisting> + + to make it use the proxy server configuration specified by the + user in the environment variables <envar>http_proxy</envar> and + friends.</para> + + <para>This attribute is only allowed in <link + linkend="fixed-output-drvs">fixed-output derivations</link>, where + impurities such as these are okay since (the hash of) the output + is known in advance. It is ignored for all other + derivations.</para></listitem> + + </varlistentry> + + <varlistentry xml:id="fixed-output-drvs"> <term><varname>outputHash</varname></term> <term><varname>outputHashAlgo</varname></term> @@ -215,29 +242,29 @@ stdenv.mkDerivation { </varlistentry> - <varlistentry><term><varname>impureEnvVars</varname></term> - - <listitem><para>This attribute allows you to specify a list of - environment variables that should be passed from the environment - of the calling user to the builder. Usually, the environment is - cleared completely when the builder is executed, but with this - attribute you can allow specific environment variables to be - passed unmodified. For example, <function>fetchurl</function> in - Nixpkgs has the line - -<programlisting> -impureEnvVars = [ "http_proxy" "https_proxy" <replaceable>...</replaceable> ]; -</programlisting> - - to make it use the proxy server configuration specified by the - user in the environment variables <envar>http_proxy</envar> and - friends.</para> - - <para>This attribute is only allowed in <link - linkend="fixed-output-drvs">fixed-output derivations</link>, where - impurities such as these are okay since (the hash of) the output - is known in advance. It is ignored for all other - derivations.</para></listitem> + <varlistentry><term><varname>passAsFile</varname></term> + + <listitem><para>A list of names of attributes that should be + passed via files rather than environment variables. For example, + if you have + + <programlisting> +passAsFile = ["big"]; +big = "a very long string"; + </programlisting> + + then when the builder runs, the environment variable + <envar>bigPath</envar> will contain the absolute path to a + temporary file containing <literal>a very long + string</literal>. That is, for any attribute + <replaceable>x</replaceable> listed in + <varname>passAsFile</varname>, Nix will pass an environment + variable <envar><replaceable>x</replaceable>Path</envar> holding + the path of the file containing the value of attribute + <replaceable>x</replaceable>. This is useful when you need to pass + large strings to a builder, since most operating systems impose a + limit on the size of the environment (typically, a few hundred + kilobyte).</para></listitem> </varlistentry> diff --git a/doc/manual/expressions/custom-builder.xml b/doc/manual/expressions/custom-builder.xml deleted file mode 100644 index c26deac40f4a..000000000000 --- a/doc/manual/expressions/custom-builder.xml +++ /dev/null @@ -1,26 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-custom-builder"> - -<title>Customizing the Generic Builder</title> - -<para>The operation of the generic builder can be modified in many -places by setting certain variables. These <emphasis>hook -variables</emphasis> are typically set to the name of some shell -function defined by you. For instance, to perform some additional -steps after <command>make install</command> you would set the -<varname>postInstall</varname> variable: - -<programlisting> -postInstall=myPostInstall - -myPostInstall() { - mkdir $out/share/extra - cp extrafiles/* $out/share/extra -}</programlisting> - -</para> - -</section> \ No newline at end of file diff --git a/doc/manual/expressions/debug-build.xml b/doc/manual/expressions/debug-build.xml index 508cb2c1930e..0c1f4e6719b2 100644 --- a/doc/manual/expressions/debug-build.xml +++ b/doc/manual/expressions/debug-build.xml @@ -6,13 +6,14 @@ <title>Debugging Build Failures</title> -<para>At the beginning of each phase, the set of all shell variables -is written to the file <filename>env-vars</filename> at the top-level -build directory. This is useful for debugging: it allows you to -recreate the environment in which a build was performed. For -instance, if a build fails, then assuming you used the -<option>-K</option> flag, you can go to the output directory and -<quote>switch</quote> to the environment of the builder: +<para>At the beginning of each phase of the build (such as unpacking, +building or installing), the set of all shell variables is written to +the file <filename>env-vars</filename> at the top-level build +directory. This is useful for debugging: it allows you to recreate +the environment in which a build was performed. For instance, if a +build fails, then assuming you used the <option>-K</option> flag, you +can go to the output directory and <quote>switch</quote> to the +environment of the builder: <screen> $ nix-build -K ./foo.nix @@ -30,4 +31,4 @@ $ make </para> -</section> \ No newline at end of file +</section> diff --git a/doc/manual/expressions/derivations.xml b/doc/manual/expressions/derivations.xml index b57c33f4e3a9..90e2786faaab 100644 --- a/doc/manual/expressions/derivations.xml +++ b/doc/manual/expressions/derivations.xml @@ -110,12 +110,12 @@ buildInputs = [ pkg pkg.headers ]; </itemizedlist> -<para>The function <function>mkDerivation</function> in the standard -environment is a wrapper around <function>derivation</function> that -adds a default value for <varname>system</varname> and always uses -Bash as the builder, to which the supplied builder is passed as a -command-line argument. See <xref linkend='sec-standard-environment' -/>.</para> +<para>The function <function>mkDerivation</function> in the Nixpkgs +standard environment is a wrapper around +<function>derivation</function> that adds a default value for +<varname>system</varname> and always uses Bash as the builder, to +which the supplied builder is passed as a command-line argument. See +the Nixpkgs manual for details.</para> <para>The builder is executed as follows: @@ -208,4 +208,4 @@ command-line argument. See <xref linkend='sec-standard-environment' <xi:include href="advanced-attributes.xml" /> -</section> \ No newline at end of file +</section> diff --git a/doc/manual/expressions/generic-builder.xml b/doc/manual/expressions/generic-builder.xml index f8567a042d47..db7ff405d8b1 100644 --- a/doc/manual/expressions/generic-builder.xml +++ b/doc/manual/expressions/generic-builder.xml @@ -71,7 +71,7 @@ genericBuild <co xml:id='ex-hello-builder2-co-3' /></programlisting> generic builder is smart enough to figure out whether to unpack the sources using <command>gzip</command>, <command>bzip2</command>, etc. It can be customised in many ways; - see <xref linkend='sec-standard-environment' />.</para> + see the Nixpkgs manual for details.</para> </callout> @@ -95,4 +95,4 @@ In fact, <varname>mkDerivation</varname> provides a default builder that looks exactly like that, so it is actually possible to omit the builder for Hello entirely.</para> -</section> \ No newline at end of file +</section> diff --git a/doc/manual/expressions/language-values.xml b/doc/manual/expressions/language-values.xml index c3514e58f0de..0bf6632d6e3a 100644 --- a/doc/manual/expressions/language-values.xml +++ b/doc/manual/expressions/language-values.xml @@ -155,7 +155,14 @@ stdenv.mkDerivation { 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 absolute path is - <filename>/foo/xyzzy/fnord.nix</filename>.</para></listitem> + <filename>/foo/xyzzy/fnord.nix</filename>.</para> + + <para>If the first component of a path is a <literal>~</literal>, + it is interpreted as if the rest of the path were relative to the + user's home directory. e.g. <filename>~/foo</filename> would be + equivalent to <filename>/home/edolstra/foo</filename> for a user + whose home directory is <filename>/home/edolstra</filename>. + </para></listitem> <listitem><para><emphasis>Booleans</emphasis> with values <literal>true</literal> and diff --git a/doc/manual/expressions/simple-building-testing.xml b/doc/manual/expressions/simple-building-testing.xml index cc90409b5e93..e0dd98b7e67e 100644 --- a/doc/manual/expressions/simple-building-testing.xml +++ b/doc/manual/expressions/simple-building-testing.xml @@ -83,4 +83,6 @@ Just pass the option <link linkend='opt-max-jobs'><option>-j in parallel, or set. Typically this should be the number of CPUs.</para> -</section> \ No newline at end of file +<xi:include href="debug-build.xml" /> + +</section> diff --git a/doc/manual/expressions/simple-expression.xml b/doc/manual/expressions/simple-expression.xml index a8eb96f5a8e2..29fd872eea19 100644 --- a/doc/manual/expressions/simple-expression.xml +++ b/doc/manual/expressions/simple-expression.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ch-simple-expression"> -<title>Simple Nix Expression Use-Case</title> +<title>A Simple Nix Expression</title> <para>This section shows how to add and test the <link xlink:href='http://www.gnu.org/software/hello/hello.html'>GNU Hello @@ -44,4 +44,4 @@ need to do three things: <xi:include href="simple-building-testing.xml" /> <xi:include href="generic-builder.xml" /> -</chapter> \ No newline at end of file +</chapter> diff --git a/doc/manual/expressions/standard-env.xml b/doc/manual/expressions/standard-env.xml deleted file mode 100644 index 2571f43fccba..000000000000 --- a/doc/manual/expressions/standard-env.xml +++ /dev/null @@ -1,60 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='sec-standard-environment'> - -<title>The Standard Environment</title> - - -<para>The standard environment is used by passing it as an input -called <envar>stdenv</envar> to the derivation, and then doing - -<programlisting> -source $stdenv/setup</programlisting> - -at the top of the builder.</para> - -<para>Apart from adding the aforementioned commands to the -<envar>PATH</envar>, <filename>setup</filename> also does the -following: - -<itemizedlist> - - <listitem><para>All input packages specified in the - <envar>buildInputs</envar> environment variable have their - <filename>/bin</filename> subdirectory added to <envar>PATH</envar>, - their <filename>/include</filename> subdirectory added to the C/C++ - header file search path, and their <filename>/lib</filename> - subdirectory added to the linker search path. This can be extended. - For instance, when the <command>pkgconfig</command> package is - used, the subdirectory <filename>/lib/pkgconfig</filename> of each - input is added to the <envar>PKG_CONFIG_PATH</envar> environment - variable.</para></listitem> - - <listitem><para>The environment variable - <envar>NIX_CFLAGS_STRIP</envar> is set so that the compiler strips - debug information from object files. This can be disabled by - setting <envar>NIX_STRIP_DEBUG</envar> to - <literal>0</literal>.</para></listitem> - -</itemizedlist> - -</para> - -<para>The <filename>setup</filename> script also exports a function -called <function>genericBuild</function> that knows how to build -typical Autoconf-style packages. It can be customised to perform -builds for any type of package. It is advisable to use -<function>genericBuild</function> since it provides facilities that -are almost always useful such as unpacking of sources, patching of -sources, nested logging, etc.</para> - -<para>The definitive, up-to-date documentation of the generic builder -is the source itself, which resides in -<filename>pkgs/stdenv/generic/setup.sh</filename>.</para> - -<xi:include href="custom-builder.xml" /> -<xi:include href="debug-build.xml" /> - -</chapter> \ No newline at end of file diff --git a/doc/manual/expressions/writing-nix-expressions.xml b/doc/manual/expressions/writing-nix-expressions.xml index 6b797c200992..6646dddf0842 100644 --- a/doc/manual/expressions/writing-nix-expressions.xml +++ b/doc/manual/expressions/writing-nix-expressions.xml @@ -22,6 +22,5 @@ manual</link>.</para></note> <xi:include href="simple-expression.xml" /> <xi:include href="expression-language.xml" /> -<xi:include href="standard-env.xml" /> </part> |