Restructuring the Nix manual

1 files changed, 60 insertions, 0 deletions

diff --git a/doc/manual/expressions/standard-env.xml b/doc/manual/expressions/standard-env.xml
new file mode 100644
index 000000000000..2571f43fccba
--- /dev/null
+++ b/doc/manual/expressions/standard-env.xml
@@ -0,0 +1,60 @@
+<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