about summary refs log tree commit diff
path: root/doc/manual/expressions
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual/expressions')
-rw-r--r--doc/manual/expressions/advanced-attributes.xml75
-rw-r--r--doc/manual/expressions/custom-builder.xml26
-rw-r--r--doc/manual/expressions/debug-build.xml17
-rw-r--r--doc/manual/expressions/derivations.xml14
-rw-r--r--doc/manual/expressions/generic-builder.xml4
-rw-r--r--doc/manual/expressions/language-values.xml9
-rw-r--r--doc/manual/expressions/simple-building-testing.xml4
-rw-r--r--doc/manual/expressions/simple-expression.xml4
-rw-r--r--doc/manual/expressions/standard-env.xml60
-rw-r--r--doc/manual/expressions/writing-nix-expressions.xml1
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>