[PATCH 1/2] ref-manual/variables.rst: expand BB_NUMBER_THREADS description

[PATCH 1/2] ref-manual/variables.rst: expand BB_NUMBER_THREADS description

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Explain that reducing its value to reduce system load
is not sufficient if PARALLEL_MAKE is not reduced as well.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 27 ++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 9909622d7a..147679400f 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -530,6 +530,33 @@ system and gives an overview of their function and contents.
       ":ref:`dev-manual/common-tasks:speeding up a build`"
       section in the Yocto Project Development Tasks Manual.
 
+      On the other hand, if your goal is to limit the amount of system
+      resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS`
+      to a number lower than the number of CPU threads in your machine
+      won't be sufficient. That's because each package will still be built
+      and installed through a number of parallel jobs specified by the
+      :term:`PARALLEL_MAKE` variable, which is by default the number of CPU
+      threads in your system, and is not impacted by the
+      :term:`BB_NUMBER_THREADS` value.
+
+      So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set
+      :term:`PARALLEL_MAKE`, most of your system resources will be consumed
+      anyway.
+
+      Therefore, if you intend to reduce the load of your build system by
+      setting :term:`BB_NUMBER_THREADS` to a relatively low value compared
+      to the number of CPU threads on your system, you should also set
+      :term:`PARALLEL_MAKE` to a similarly low value.
+
+      An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage
+      of build system resources under control is to use the smarter
+      :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or
+      :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake
+      from starting new tasks as long as thresholds are exceeded. Anyway,
+      as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the
+      tasks already being run from using all CPU threads on the system
+      if :term:`PARALLEL_MAKE` is not set to a low value.
+
    :term:`BB_SERVER_TIMEOUT`
       Specifies the time (in seconds) after which to unload the BitBake
       server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how
-- 
2.34.1

[PATCH 2/2] ref-manual/variables.rst: expand PARALLEL_MAKE description

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Explain that this variable apply not only to make, but also
to ninja, and to other build tools which support parallel jobs.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/ref-manual/variables.rst | 28 +++++++++++++++-----------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 147679400f..d3aae63308 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5818,17 +5818,20 @@ system and gives an overview of their function and contents.
       desired splitting.
 
    :term:`PARALLEL_MAKE`
-      Extra options passed to the ``make`` command during the
-      :ref:`ref-tasks-compile` task in order to specify
-      parallel compilation on the local build host. This variable is
-      usually in the form "-j x", where x represents the maximum number of
-      parallel threads ``make`` can run.
+
+      Extra options passed to the build tool command (``make``,
+      ``ninja`` or more specific build engines, like the Go language one)
+      during the :ref:`ref-tasks-compile` task, to specify parallel compilation
+      on the local build host. This variable is usually in the form "-j x",
+      where x represents the maximum number of parallel threads such engines
+      can run.
 
       .. note::
 
-         In order for :term:`PARALLEL_MAKE` to be effective, ``make`` must be
-         called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy way to ensure
-         this is to use the ``oe_runmake`` function.
+         For software compiled by ``make``, in order for :term:`PARALLEL_MAKE`
+         to be effective, ``make`` must be called with
+         ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
+         way to ensure this is to use the ``oe_runmake`` function.
 
       By default, the OpenEmbedded build system automatically sets this
       variable to be equal to the number of cores the build system uses.
@@ -5853,15 +5856,16 @@ system and gives an overview of their function and contents.
       section in the Yocto Project Development Tasks Manual.
 
    :term:`PARALLEL_MAKEINST`
-      Extra options passed to the ``make install`` command during the
-      :ref:`ref-tasks-install` task in order to specify
+      Extra options passed to the build tool install command
+      (``make install``, ``ninja install`` or more specific ones)
+      during the :ref:`ref-tasks-install` task in order to specify
       parallel installation. This variable defaults to the value of
       :term:`PARALLEL_MAKE`.
 
       .. note::
 
-         In order for :term:`PARALLEL_MAKEINST` to be effective, ``make`` must
-         be called with
+         For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST`
+         to be effective, ``make`` must be called with
          ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
          way to ensure this is to use the ``oe_runmake`` function.
 
-- 
2.34.1