diff --git a/README.md b/README.md index f54d7ad34b6..243e3c03868 100644 --- a/README.md +++ b/README.md @@ -334,12 +334,18 @@ in the Installation Guide. 11. Optional, but highly recommended: Set some environment variables to customize the build. - For example, the `MAKE` environment variable controls whether to - run several jobs in parallel. On a machine with 4 processors, say, - typing `export MAKE="make -j4"` will configure the build script to - perform a parallel compilation of Sage using 4 jobs. On some - powerful machines, you might even consider `-j16`, as building with - more jobs than CPU cores can speed things up further. + The `MAKEFLAGS` variable controls whether to run several jobs in parallel. + To saturate all the execution threads of your CPU, we recommend to run + `export MAKEFLAGS="-j$(nproc) -l$(nproc).5"` if you are on Linux, and + `export MAKEFLAGS="-j$(sysctl -n hw.ncpu) -l$(sysctl -n hw.ncpu).5"` if you + are on macOS. + + Note that the compilation may nonetheless use a different number of + processes, e.g., for parts that are built with `ninja` which automatically + decides on the amount of parallelity to use. In practice, you might + therefore see twice as many processes during the build process than your + CPU has execution threads. Unless your system is low on RAM, this should + not affect the time the compilation takes substantially. To reduce the terminal output during the build, type `export V=0`. (`V` stands for "verbosity".) diff --git a/src/doc/en/faq/faq-usage.rst b/src/doc/en/faq/faq-usage.rst index 393a9c369e5..ca7cab3458b 100644 --- a/src/doc/en/faq/faq-usage.rst +++ b/src/doc/en/faq/faq-usage.rst @@ -70,7 +70,7 @@ Sage. The command .. CODE-BLOCK:: shell-session - $ export MAKE='make -j8' + $ export MAKEFLAGS='-j8' will enable 8 threads for parts of the build that support parallelism. Change the number 8 as appropriate to suit the number of diff --git a/src/doc/en/installation/source.rst b/src/doc/en/installation/source.rst index 12b1483dfa2..12ab938f0f3 100644 --- a/src/doc/en/installation/source.rst +++ b/src/doc/en/installation/source.rst @@ -669,8 +669,8 @@ Environment variables Sage uses several environment variables to control its build process. Most users won't need to set any of these: the build process just works on many platforms. -(Note though that setting :envvar:`MAKE`, as described below, can significantly -speed up the process.) +(Note though that setting :envvar:`MAKEFLAGS`, as described below, can +significantly speed up the process.) Building Sage involves building many packages, each of which has its own compilation instructions. @@ -680,19 +680,26 @@ Standard environment controlling the build process Here are some of the more commonly used variables affecting the build process: -.. envvar:: MAKE +.. envvar:: MAKEFLAGS - One useful setting for this variable when building Sage is - ``MAKE='make -jNUM'`` to tell the ``make`` program to run ``NUM`` jobs in - parallel when building. - Note that some Sage packages may not support this variable. + This variable can be set to tell the ``make`` program to build things in + parallel. Set it to ``-jNUM`` to run ``NUM`` jobs in parallel when building. + Add ``-lNUM`` to tell make not to spawn more processes when the load exceeds + ``NUM``. + + A good value for this variable is ``MAKEFLAGS="-j$(nproc) -l$(nproc).5"`` on + Linux and ``MAKEFLAGS="-j$(sysctl -n hw.ncpu) -l$(sysctl -n hw.ncpu).5"`` on + macOS. This instructs make to use all the execution threads of your CPU while + bounding the load if there are other processes generating load. If your + system does not have a lot of RAM, you might want to choose lower limits, if + you have lots of RAM, it can sometimes be beneficial to set these limits + slightly higher. + + Note that some parts of the SageMath build system do not respect this + variable, e.g., when ninja gets invoked, it figures out the number of + processes to use on its own so the number of processes and the system load + you see might exceed the number configured here. - Some people advise using more jobs than there are CPU cores, at least if the - system is not heavily loaded and has plenty of RAM; for example, a good - setting for ``NUM`` might be between 1 and 1.5 times the number of cores. - In addition, the ``-l`` option sets a load limit: ``MAKE='make -j4 -l5.5``, - for example, tells ``make`` to try to use four jobs, but to not start more - than one job if the system load average is above 5.5. See the manual page for GNU ``make``: `Command-line options `_ and `Parallel building diff --git a/src/doc/it/faq/faq-usage.rst b/src/doc/it/faq/faq-usage.rst index 677d1a24bc2..2d2b32352a0 100644 --- a/src/doc/it/faq/faq-usage.rst +++ b/src/doc/it/faq/faq-usage.rst @@ -70,7 +70,7 @@ questi prerequisiti come segue:: Se hai un sistema multiprocessore puoi scegliere una compilazione parallela di Sage. Il comando :: - export MAKE='make -j8' + export MAKEFLAGS='-j8' abiliterà 8 threads per quelle parti della compilazione che supportano il parallelismo. Al posto del numero 8 metti il numero di