Ensure make -j uses a reasonable argument (#1541)

``make -j`` means no limit on the number of concurrent jobs, rather than
a sensible number constrained by the system's resources. When building
with LTO, it is easy to run out of memory when too many jobs run at the same time.

Co-authored-by: Thomas Wouters <thomas@python.org>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Author: 3 people

developer-workflow/extension-modules.rst

@@ -547,8 +547,11 @@ Now that the configuration is in place, it remains to compile the project:
 
 .. tip::
 
-   Use ``make -j`` to speed-up compilation by utilizing as many CPU cores
-   as possible or ``make -jN`` to allow at most *N* concurrent jobs.
+   Use ``make -jN`` to speed-up compilation by utilizing as many CPU cores
+   as possible, where *N* is as many CPU cores you want to spare (and have
+   memory for). Be careful using ``make -j`` with no argument, as this puts
+   no limit on the number of jobs, and compilation can sometimes use up a
+   lot of memory (like when building with LTO).
 
 * ``make regen-configure`` updates the :cpy-file:`configure` script.
 

getting-started/setup-building.rst

@@ -203,14 +203,13 @@ do to get a pydebug build of CPython.
 
 Once ``configure`` is done, you can then compile CPython with::
 
-   $ make -s -j2
+   $ make -s -j $(nproc)
 
 This will build CPython with only warnings and errors being printed to
-stderr and utilize up to 2 CPU cores. If you are using a multi-core machine
-with more than 2 cores (or a single-core machine), you can adjust the number
-passed into the ``-j`` flag to match the number of cores you have (or if your
-version of Make supports it, you can use ``-j`` without a number and Make
-will not limit the number of steps that can run simultaneously.).
+stderr. The ``-j`` argument means that :program:`make` will concurrently run
+tasks, limiting the number of parallel jobs to the number of CPU cores in your
+computer. You can adjust the number passed to the ``-j`` flag to change
+the limit on parallel jobs, which can trade RAM usage versus compilation time.
 
 At the end of the build you should see a success message, followed
 by a list of extension modules that haven't been built because their
@@ -875,7 +874,7 @@ some of CPython's modules (for example, ``zlib``).
 
    And finally, run ``make``::
 
-      $ make -s -j2
+      $ make -s -j $(nproc)
 
    There will sometimes be optional modules added for a new release which
    won't yet be identified in the OS-level build dependencies. In those cases,

index.rst

@@ -43,13 +43,13 @@ instructions please see the :ref:`setup guide <setup>`.
 
       .. code-block:: shell
 
-         ./configure --with-pydebug && make -j
+         ./configure --with-pydebug && make -j $(nproc)
 
    .. tab:: macOS
 
       .. code-block:: shell
 
-         ./configure --with-pydebug && make -j
+         ./configure --with-pydebug && make -j $(nproc)
 
    .. tab:: Windows