ref-manual: Updates to BB_NUMBER_THREADS and PARALLEL_MAKE

I added some more detail to these two variables.  The system sets
them according to the perceived number of cores.  These default
setting are cool for single socket systems.  However, if you
have some big system with a lot of physical CPUs, you might want
to cap off the values at 20.  This is according to Darren Hart.

I also put in some cross-references to the "Speeding Up the Build"
section.

(From yocto-docs rev: 69b931f019f7bec687a642d7fccd1172a9be1746)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 34 insertions, 3 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index c330fe0..ea5b9d8 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -872,8 +872,26 @@
                     The OpenEmbedded build system automatically configures
                     this variable to be equal to the number of cores on the
                     build system.
-                    To gain optimal parallelism, you should not have to
-                    override this variable.
+                    For example, a system with a dual core processor that
+                    also uses hyper-threading causes the
+                    <filename>BB_NUMBER_THREADS<filename> variable to default
+                    to "4".
+                </para>
+
+                <para>
+                    For single socket systems (i.e. one CPU), you should not
+                    have to override this variable to gain optimal parallelism
+                    during builds.
+                    However, if you have very large systems that employ
+                    multiple physical CPUs, you might want to make sure the
+                    <filename>BB_NUMBER_THREADS</filename> variable is not
+                    set higher than "20".
+                </para>
+
+                <para>
+                    For more information on speeding up builds, see the
+                    "<link linkend='speeding-up-the-build'>Speeding Up the Build</link>"
+                    section.
                 </para>
             </glossdef>
         </glossentry>
@@ -8499,7 +8517,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
                     task in order to specify parallel compilation on the local
                     build host.
-                    This variable is usually in the form "-j &lt;x&gt;",
+                    This variable is usually in the form "-j <replaceable>x</replaceable>",
                     where x represents the maximum number of parallel threads
                     <filename>make</filename> can run.
                 </para>
@@ -8513,6 +8531,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                         the software being built has problems running its
                         <filename>make</filename> process in parallel.
                     </note>
+                    For single socket systems (i.e. one CPU), you should not
+                    have to override this variable to gain optimal parallelism
+                    during builds.
+                    However, if you have very large systems that employ
+                    multiple physical CPUs, you might want to make sure the
+                    <filename>PARALLEL_MAKE</filename> variable is not
+                    set higher than "20".
+                </para>
+
+                <para>
+                    For more information on speeding up builds, see the
+                    "<link linkend='speeding-up-the-build'>Speeding Up the Build</link>"
+                    section.
                 </para>
             </glossdef>
         </glossentry>