[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: rc-file: Add "num-cores-low-mem" and move num-cores* defs to initial-setup.

[Michael Pyne]

Git commit 03d5ed404767a82a00ee92184d09104f4fa179e1 by Michael Pyne.
Committed on 12/07/2020 at 00:08.
Pushed by ashark into branch 'docbook_historied_per_file'.

rc-file: Add "num-cores-low-mem" and move num-cores* defs to initial-setup.

It is annoying to be maintaining kdesrc-build-setup and --initial-setup
but combining those two can be a subsequent refactoring.

This adds a separate num-cores-low-mem to address the qtwebengine case
and makes both num-cores and num-cores-low-mem into an option generated
during initial setup, and only used by the default config (rather than
any part of the kdesrc-build internals directly).

There is a fallback reference in the code in case there is a usage of
the default configuration file sections (e.g. qt5-build-include) but
this is set conservatively (4 cores, 2 cores during low-mem).

At this point it's almost "just" a configuration convention with a bit
of code in the setup wizard so perhaps it's best not to touch the rest
of the code/docs at all, but I'm happy with where this is at.

I've tested --initial-setup in a Docker container (Fedora 29 with perl
manually installed first) and tested kdesrc-build-setup separately.

Original commit: 654e1392
https://invent.kde.org/sdk/kdesrc-build/-/commit/654e1392a90777c3bb53e156cf26098dc128e3a1

M  +27   -1    doc/kdesrc-buildrc/conf-options-table.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/03d5ed404767a82a00ee92184d09104f4fa179e1

diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index 386f3cf5..699ef4e4 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -880,7 +880,8 @@ due to fixes in the underlying build system.</entry>
 <entry>num-cores</entry>
 <entry>Cannot be overridden</entry>
 <entry>
-<para>This option is automatically set by &kdesrc-build; to the number of
+<para>This option is defined by &kdesrc-build; (when using the kdesrc-build-setup tool
+or <command>kdesrc-build --initial-setup</command>), set to be the number of
 available CPUs (as indicated by the external application
 <application>nproc</application>). If &kdesrc-build; cannot detect the
 number of CPUs, this value is set to 4.</para>
@@ -890,6 +891,31 @@ option's usage. This option was added in version 20.07.</para>
 </entry>
 </row>
 
+<row id="conf-num-cores-low-mem">
+<entry>num-cores-low-mem</entry>
+<entry>Cannot be overridden</entry>
+<entry>
+<para>This option is defined by &kdesrc-build; (when using the kdesrc-build-setup tool
+or <command>kdesrc-build --initial-setup</command>), set to be the number of
+CPUs that is deemed safe for heavyweight or other highly-intensive modules,
+such as <literal>qtwebengine</literal>, to avoid running out of memory
+during the build.</para>
+
+<para>The typical calculation is one CPU core for every 2
+gigabytes (GiB) of total memory. At least 1 core will be specified,
+and no more than <option><link linkend="conf-num-cores">num-cores</link></option>
+cores will be specified.</para>
+
+<para>Although this option is intended to support &Qt; modules, you can use it for your
+any module in the same way that <option>num-cores</option> is used.</para>
+
+<para>If &kdesrc-build; cannot detect available memory then this value will be
+set to 2.</para>
+
+<para>This option was added in version 20.07.</para>
+</entry>
+</row>
+
 <row id="conf-override-build-system">
 <entry>override-build-system</entry>
 <entry>Module setting overrides global</entry>