Cap the maximum number of build jobs (#11373)

* config:build_jobs now controls the number of parallel jobs to spawn during
builds, but cannot ever exceed the number of cores on the machine.

* The default is set to 16 or the number of available cores, whatever
is lowest.

* Updated docs to reflect the changes done to limit parallel builds

1 files changed, 11 insertions, 4 deletions

diff --git a/lib/spack/docs/config_yaml.rst b/lib/spack/docs/config_yaml.rst
index 54a793b53f..7e2759349b 100644
--- a/lib/spack/docs/config_yaml.rst
+++ b/lib/spack/docs/config_yaml.rst
@@ -178,16 +178,23 @@ set ``dirty`` to ``true`` to skip the cleaning step and make all builds
 "dirty" by default.  Be aware that this will reduce the reproducibility
 of builds.
 
+.. _build-jobs:
+
 --------------
 ``build_jobs``
 --------------
 
 Unless overridden in a package or on the command line, Spack builds all
-packages in parallel. For a build system that uses Makefiles, this means
-running ``make -j<build_jobs>``, where ``build_jobs`` is the number of
-threads to use.
+packages in parallel. The default parallelism is equal to the number of
+cores on your machine, up to 16. Parallelism cannot exceed the number of
+cores available on the host. For a build system that uses Makefiles, this
+means running:
+
+- ``make -j<build_jobs>``, when ``build_jobs`` is less than the number of
+  cores on the machine
+- ``make -j<ncores>``, when ``build_jobs`` is greater or equal to the
+  number of cores on the machine
 
-The default parallelism is equal to the number of cores on your machine.
 If you work on a shared login node or have a strict ulimit, it may be
 necessary to set the default to a lower value. By setting ``build_jobs``
 to 4, for example, commands like ``spack install`` will run ``make -j4``