@@ -22,6 +22,7 @@ Yocto Project Development Tasks Manual
building
multiconfig
speeding-up-build
+ limiting-resources
libraries
prebuilt-libraries
devtool
new file mode 100644
@@ -0,0 +1,120 @@
+.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
+
+Limiting the Host Resources Usage
+*********************************
+
+While you sometimes need to :doc:`speed up a build
+</dev-manual/speeding-up-build>`, you may also need to limit the resources used
+by the :term:`OpenEmbedded Build System`, especially on shared infrastructures
+where multiple users start heavy-load builds, or when building on low-power
+machines.
+
+This document aims at giving the different configuration variables available to
+limit the resources used by the build system. These variables should be set from
+a :term:`configuration file` and thus take effect over the entire build environment.
+For each variable, also see the variable description in the glossary for more
+details.
+
+- :term:`BB_NUMBER_THREADS`:
+
+ This sets a hard limit on the number of threads :term:`BitBake` can run at the
+ same time. Lowering this value will set a limit to the number of
+ :term:`BitBake` threads, but will not prevent a single task from starting more
+ compilation threads (see :term:`PARALLEL_MAKE`).
+
+- :term:`BB_NUMBER_PARSE_THREADS`:
+
+ Like :term:`BB_NUMBER_THREADS`, but this variable sets a limit on the number
+ of threads during the parsing of the environment (before executing tasks).
+
+- :term:`PARALLEL_MAKE`:
+
+ This variable should be set in the form of ``-jN``, where ``N`` is a positive
+ integer. This integer controls the number of threads used when starting
+ ``make``. Note that this variable is not limited to the usage of ``make``,
+ but extends to the compilation (:ref:`ref-tasks-compile` task) commands
+ defined by the :ref:`ref-classes-meson`, :ref:`ref-classes-cmake` and such
+ classes.
+
+ If you want to have a different limit from the rest of the build for a
+ recipe, it is also possible to achieve with the following line added to your
+ ``local.conf`` :term:`configuration file`::
+
+ PARALLEL_MAKE:pn-linux-yocto = "-j4"
+
+ The above example will limit the number of threads used by ``make`` for the
+ ``linux-yocto`` recipe to 4.
+
+- :term:`PARALLEL_MAKEINST`:
+
+ Like :term:`PARALLEL_MAKE`, but this variable controls the number of threads
+ used during the :ref:`ref-tasks-install` task.
+
+ The default value of :term:`PARALLEL_MAKEINST` is the value of
+ :term:`PARALLEL_MAKE`.
+
+- :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` and
+ :term:`BB_PRESSURE_MAX_MEMORY`:
+
+ These variables control the limit of pressure (PSI as defined by
+ https://docs.kernel.org/accounting/psi.html) on the system, and will
+ limit the number of :term:`BitBake` threads dynamically depending on the
+ current pressure of the system. This also means that your host must support
+ the PSI kernel feature (otherwise see :term:`BB_LOADFACTOR_MAX` below).
+
+ These variables take a positive integer between 1 (extremely low limit) and
+ 1000000 (value unlikely ever reached). Setting an extremely low value, such
+ as 2, is not desirable as it will result in :term:`BitBake` limiting the
+ number of threads to 1 most of the time.
+
+ To determine a reasonable value to set for your host, follow these steps
+ below:
+
+ #. Start by setting the maximum value for the CPU pressure::
+
+ BB_PRESSURE_MAX_CPU = "1000000"
+
+ #. Then, start a heavy-load build and redirect the CPU pressure information
+ in a file::
+
+ bitbake -DDD core-image-minimal | grep "Current CPU pressure:" > cpu_pressure.txt
+
+ You can stop the build at anytime with Control + C.
+
+ #. Next, sort the CPU pressure by highest from ``cpu_pressure.txt`` into
+ ``cpu_pressure_sorted.txt``::
+
+ sort -r -n -t ' ' -k 5 < cpu_pressure.txt > cpu_pressure_sorted.txt
+
+ #. Finally, open the ``cpu_pressure_sorted.txt`` file and inspect the
+ highest values. These should indicate a value reached by your host
+ system. You can set a value below the highest number in that file.
+
+ The steps above are applicable for the I/O and Memory pressure
+ (:term:`BitBake` prints ``Current IO pressure:`` or ``Current Memory
+ pressure:`` messages).
+
+ After setting initial values, :term:`BitBake` will print messages on the
+ console in the following format each time the current pressure exceeds of the
+ limit set by the above variables::
+
+ Pressure status changed to CPU: True, IO: False, Mem: False (CPU: 1105.9/2.0, IO: 0.0/2.0, Mem: 0.0/2.0) - using 1/64 bitbake threads
+
+ Take a look at the value between parenthesis: ``CPU: 1105.9/2.0, IO: 0.0/2.0,
+ Mem: 0.0/2.0``. They correspond to the current pressure value for the CPU, IO
+ and memory respectively. If :term:`BitBake` prints these messages a lot, it
+ is likely that your pressure limit is too low, and thus can be raised to a
+ higher value.
+
+- :term:`BB_LOADFACTOR_MAX`:
+
+ This variable will limit the number of threads :term:`BitBake` will start
+ by monitoring the current CPU load of the host system. :term:`BitBake` will
+ print the following when the limit set by :term:`BB_LOADFACTOR_MAX` is
+ reached::
+
+ Load average limiting set to True as load average: 0.7188262939453125 - using 37/64 bitbake threads
+
+ This variable has no effect when any of :term:`BB_PRESSURE_MAX_CPU`,
+ :term:`BB_PRESSURE_MAX_IO` or :term:`BB_PRESSURE_MAX_MEMORY` is set, as it
+ was designed for systems that do not have pressure information available.
Add a "Limiting the Host Resources Usage" document to share the different techniques that can be used to limit the host resources usage. We do have a document to document how to speed up a build, so this document comes right after. [YOCTO #15111] Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/dev-manual/index.rst | 1 + documentation/dev-manual/limiting-resources.rst | 120 ++++++++++++++++++++++++ 2 files changed, 121 insertions(+)