From 86f65edf4e519224eaa35ebc6bcf98bffe04b3d6 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Tue, 17 Aug 2010 07:22:05 +0000
Subject: [PATCH] * Document --cores in the manual.

---
 doc/manual/conf-file.xml      | 19 +++++++++++++++++++
 doc/manual/opt-common-syn.xml |  4 ++++
 doc/manual/opt-common.xml     | 20 +++++++++++++++++++-
 doc/manual/release-notes.xml  |  6 +++---
 nix.conf.example              |  2 +-
 5 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml
index 2ee2680970..ec64e8b114 100644
--- a/doc/manual/conf-file.xml
+++ b/doc/manual/conf-file.xml
@@ -97,6 +97,25 @@ env-keep-derivations = false
   </varlistentry>
 
 
+  <varlistentry xml:id="conf-build-cores"><term><literal>build-cores</literal></term>
+
+    <listitem><para>Sets the value of the
+    <envar>NIX_BUILD_CORES</envar> environment variable in the
+    invocation of builders.  Builders can use this variable at their
+    discretion to control the maximum amount of parallelism.  For
+    instance, in Nixpkgs, if the derivation attribute
+    <varname>enableParallelBuilding</varname> is set to
+    <literal>true</literal>, the builder passes the
+    <option>-j<replaceable>N</replaceable></option> flag to GNU Make.
+    It can be overriden using the <option
+    linkend='opt-cores'>--cores</option> command line switch and
+    defaults to <literal>1</literal>.  The value <literal>0</literal>
+    means that the builder should use all available CPU cores in the
+    system.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry xml:id="conf-build-max-silent-time"><term><literal>build-max-silent-time</literal></term>
 
     <listitem>
diff --git a/doc/manual/opt-common-syn.xml b/doc/manual/opt-common-syn.xml
index 0412fcb6ab..da60288b2a 100644
--- a/doc/manual/opt-common-syn.xml
+++ b/doc/manual/opt-common-syn.xml
@@ -13,6 +13,10 @@
   </group>
   <replaceable>number</replaceable>
 </arg>
+<arg>
+  <arg><option>--cores</option></arg>
+  <replaceable>number</replaceable>
+</arg>
 <arg>
   <arg><option>--max-silent-time</option></arg>
   <replaceable>number</replaceable>
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index 3be9f5dd5f..2d67162d7c 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -98,7 +98,25 @@
   linkend='conf-build-max-jobs'><literal>build-max-jobs</literal></link>
   configuration setting, which itself defaults to
   <literal>1</literal>.  A higher value is useful on SMP systems or to
-  exploit I/O latency.  </para></listitem>
+  exploit I/O latency.</para></listitem>
+  
+</varlistentry>
+
+
+<varlistentry xml:id="opt-cores"><term><option>--cores</option></term>
+
+  <listitem><para>Sets the value of the <envar>NIX_BUILD_CORES</envar>
+  environment variable in the invocation of builders.  Builders can
+  use this variable at their discretion to control the maximum amount
+  of parallelism.  For instance, in Nixpkgs, if the derivation
+  attribute <varname>enableParallelBuilding</varname> is set to
+  <literal>true</literal>, the builder passes the
+  <option>-j<replaceable>N</replaceable></option> flag to GNU Make.
+  It defaults to the value of the <link
+  linkend='conf-build-cores'><literal>build-cores</literal></link>
+  configuration setting, if set, or <literal>1</literal> otherwise.
+  The value <literal>0</literal> means that the builder should use all
+  available CPU cores in the system.</para></listitem>
   
 </varlistentry>
 
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index b3a324c97b..5b1c30bf82 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -8,7 +8,7 @@
 
 <!--==================================================================-->
 
-<section xml:id="ssec-relnotes-0.16"><title>Release 0.16 (August 16, 2010)</title>
+<section xml:id="ssec-relnotes-0.16"><title>Release 0.16 (August 17, 2010)</title>
 
 <para>This release has the following improvements:</para>
 
@@ -39,8 +39,8 @@
       builder can use this at its discretion to perform a parallel
       build, e.g., by calling <command>make -j
       <replaceable>N</replaceable></command>.  In Nixpkgs, this can be
-      enabled on a per-package basis by setting
-      <varname>enableParallelBuilding</varname> to
+      enabled on a per-package basis by setting the derivation
+      attribute <varname>enableParallelBuilding</varname> to
       <literal>true</literal>.
     </para>
   </listitem>
diff --git a/nix.conf.example b/nix.conf.example
index 7063bed54c..3c55b570e6 100644
--- a/nix.conf.example
+++ b/nix.conf.example
@@ -63,7 +63,7 @@
 #
 # This option defines the number of CPU cores to utilize in parallel
 # within a build job, i.e. by passing an appropriate `-jN' flag to GNU
-# make. The default is 1, meaning that parallel building within jobs
+# Make. The default is 1, meaning that parallel building within jobs
 # is disabled.  Passing the special value `0' causes Nix to try and
 # auto-detect the number of available cores on the local host.  This
 # setting can be overridden using the `--cores' command line switch.