dev-manual, ref-manual, yocto-project-qs: Updates to parallelism variables

The way the old manual set had worded the use of the
BB_NUMBER_THREADS, PARALLEL_MAKE, and BB_NUMBER_PARSE_THREADS
had become depricated.  It suggested a lot of user intervention
to get these variables set to have the build system utilize
optimal parallelism.  The change a while back to the build system
where the variables are set to the number of build host cores
now makes the variables automatically be set to their best
values.  I have gone through the manual set and changed wordings
appropriately to reflect this.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
(From yocto-docs rev: 3a27b1792c92a2f22173315e2732f672cdad2c78)

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

5 files changed, 33 insertions, 50 deletions

diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index df29302fdb..c3206b86f8 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -297,10 +297,9 @@
                 This file defines many aspects of the build environment including
                 the target machine architecture through the
                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
-                the development machine's processor use through the
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
-                a centralized tarball download directory through the
+                the packaging format used during the build
+                (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
+                and a centralized tarball download directory through the
                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
             <listitem><para>
                 Build the image using the <filename>bitbake</filename> command.
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index c0c0d619a4..eaf07d665f 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -162,9 +162,10 @@
             <itemizedlist>
                 <listitem><para><emphasis>Parallelism Options:</emphasis>
                     Controlled by the
-                    <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
+                    <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>,
+                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>,
                     and
-                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
+                    <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
                     variables.</para></listitem>
                 <listitem><para><emphasis>Target Machine Selection:</emphasis>
                     Controlled by the
@@ -216,12 +217,10 @@
                     For example, suppose you had several build environments and
                     they shared some common features.
                     You can set these default build properties here.
-                    A good example is perhaps the level of parallelism you want
-                    to use through the
-                    <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
-                    and
-                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
-                    variables.</para>
+                    A good example is perhaps the packaging format to use
+                    through the
+                    <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+                    variable.</para>
                     <para>One useful scenario for using the
                     <filename>conf/site.conf</filename> file is to extend your
                     <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 14419d3a84..1098006c73 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -467,12 +467,8 @@
             <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
             for which you want to build, which package types you wish to use
             (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
-            the location from which you want to access downloaded files
-            (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
-            and how you want your host machine to use resources
-            (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
-            and
-            <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
+            and the location from which you want to access downloaded files
+            (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>).
         </para>
 
         <para>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 7abad0460a..281c4e3e2d 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -729,20 +729,17 @@
 
         <glossentry id='var-BB_NUMBER_THREADS'><glossterm><imagedata fileref="figures/define-generic.png" />BB_NUMBER_THREADS</glossterm>
             <info>
-                BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. A good rule of thumb is for this variable to be twice the number of cores."
+                BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. This variable is automatically configured to be equal to the number of build system cores."
             </info>
             <glossdef>
                 <para>
                     The maximum number of tasks BitBake should run in parallel
                     at any one time.
-                    If your host development system supports multiple cores,
-                    a good rule of thumb is to have this variable be twice the
-                    number of cores.
-                </para>
-
-                <para>
-                    The default value for <filename>BB_NUMBER_THREADS</filename>
-                    is equal to the number of cores your build system has.
+                    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.
                 </para>
             </glossdef>
         </glossentry>
@@ -7380,11 +7377,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                 </para>
 
                 <para>
-                    If your development host supports multiple cores, a good
-                    rule of thumb is to set this variable to twice the number
-                    of cores on the host.
-                    If you do not set <filename>PARALLEL_MAKE</filename>, it
-                    defaults to the number of cores your build system has.
+                    The OpenEmbedded build system automatically sets this
+                    variable to be equal to the number of cores the build
+                    system uses.
                     <note>
                         Individual recipes might clear out this variable if
                         the software being built has problems running its
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index 8fe9b766e6..f21558ebbd 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -509,15 +509,17 @@
          </para>
 
          <para>
-             Another couple of variables of interest are the
-             <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink> and the
-             <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> variables.
-             By default, these variables are set to the number of processor
-             cores your build host uses.
-             However, if your build host uses multiple processor cores,
-             you should increase these settings to twice the number of
-             cores used.
-             Doing so can significantly shorten your build time.
+             Another three variables of interest are the
+             <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>,
+             <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>,
+             and
+             <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink>
+             variables.
+             By default, these variables are optimally set based on the
+             number of processor cores your build host uses.
+             Although it is possible to override these variables, the
+             default values the OpenEmbedded build system derives provide you
+             with parallelism during the build.
          </para>
 
         <para>
@@ -898,18 +900,10 @@
             <filename>conf/local.conf</filename> configuration file
             in the Build Directory.
             You need to manually edit this file to specify the machine you
-            are building and to optimize your build time.
-            Here are the minimal changes to make:
+            are building:
             <literallayout class='monospaced'>
-     BB_NUMBER_THREADS = "8"
-     PARALLEL_MAKE = "-j 8"
      MACHINE ?= "beaglebone"
             </literallayout>
-            Briefly, set
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>
-            and
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> to
-            twice your host processor's number of cores.
         </para>
 
         <para>