[sdk/kdesrc-build/docbook_historied_per_file] doc: rc-file: Add "num-cpus" option by default and use it in default setup.

[Michael Pyne]

Git commit 60be7b8ccf9955046a8ee04a0e9981b41591f473 by Michael Pyne.
Committed on 07/07/2020 at 02:07.
Pushed by ashark into branch 'docbook_historied_per_file'.

rc-file: Add "num-cpus" option by default and use it in default setup.

This change introduces a "num-cpus" option that is inherently present in
the build context.

This permits config file reading code to refer to this option (due to an
existing kdesrc-build feature). So I also update the various available
methods of generating a default configuration to use this option instead
of hardcoding a -j value for make-options (or leaving it blank).

This should provide maximum performance for most users (who aren't using
or can't use the existing Ninja support, anyways), as long as they are
able to start from a generated configuration.

Users with existing configuration files would need to regenerate it or
edit it to add "make-options -j ${num-cpus}" (including separately to
their Qt5 options if applicable, as global options are ignored for
non-KDE modules).

See issue #39.

Original commit: 57e6c0c3
https://invent.kde.org/sdk/kdesrc-build/-/commit/57e6c0c3b9299b136fc20c02846563bea49e3cf4

M  +7    -2    doc/getting-started/configure-data.docbook
M  +14   -0    doc/kdesrc-buildrc/conf-options-table.docbook
M  +19   -0    doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/60be7b8ccf9955046a8ee04a0e9981b41591f473

diff --git a/doc/getting-started/configure-data.docbook b/doc/getting-started/configure-data.docbook
index 50eefc42..10f27e82 100644
--- a/doc/getting-started/configure-data.docbook
+++ b/doc/getting-started/configure-data.docbook
@@ -65,11 +65,16 @@ compile jobs you wish to allow.  A higher number (up to the number of logical CP
 your system has available) leads to quicker builds, but requires more system resources.
 </para>
 
+<tip><para>&kdesrc-build; sets the option <option><link linkend="conf-num-cpus">num-cpus</link></option> to
+the detected number of available processing cores. You can use this value
+in your own configuration file to avoid having to set it manually.
+</para></tip>
+
 <example id="make-options-example">
-<title>Configuring Make for 4 compiles at once, with exceptions</title>
+<title>Configuring Make to use all available CPUs, with exceptions</title>
 <screen>
 global
-    make-options -j4
+    make-options -j <literal>${num-cpus}</literal>
     …
 end global
 
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index 2f4648e0..0abbb9bd 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -876,6 +876,20 @@ module if it normally would have tried anyways.</entry>
 due to fixes in the underlying build system.</entry>
 </row>
 
+<row id="conf-num-cpus">
+<entry>num-cpus</entry>
+<entry>Cannot be overridden</entry>
+<entry>
+<para>This option is automatically set by &kdesrc-build; to 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>
+
+<para>See <xref linkend="make-options-example"/> for an example of this
+option's usage. 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>
diff --git a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
index 122a3760..9196ea85 100644
--- a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
+++ b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
@@ -85,6 +85,25 @@ linkend="conf-use-modules">use-modules</link> for more information.
 
 </sect3>
 
+<sect3 id="kdesrc-buildrc-option-values">
+<title>Processing of option values</title>
+
+<para>In general, the entire line contents after the
+<replaceable>option-name</replaceable> is used as the
+<replaceable>option-value</replaceable>.</para>
+
+<para>One modification that &kdesrc-build; performs is that a sequence
+<userinput>${<replaceable>name-of-option</replaceable>}</userinput> is replaced
+with the value of that option from the global configuration. This allows you
+to reference the value of existing options, including options already set by
+&kdesrc-build;.</para>
+
+<para>
+To see an example of this in use, see
+<xref linkend="make-options-example"/>.</para>
+
+</sect3>
+
 <sect3 id="kdesrc-buildrc-options-groups">
 <title><quote>options</quote> modules</title>