[sdk/kdesrc-build] doc: doc: configure-data - separate docbook

[Andrew Shark]

Git commit bdd65e23ec996e9b2d286d556de32890e70833e6 by Andrew Shark.
Committed on 05/01/2024 at 19:58.
Pushed by ashark into branch 'master'.

doc: configure-data - separate docbook

A  +110  -0    doc/configure-data.docbook
M  +2    -110  doc/index.docbook

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

diff --git a/doc/configure-data.docbook b/doc/configure-data.docbook
new file mode 100644
index 00000000..a4019619
--- /dev/null
+++ b/doc/configure-data.docbook
@@ -0,0 +1,110 @@
+<sect1 id="configure-data">
+<title>Setting the Configuration Data</title>
+
+<para>
+To use &kdesrc-build;, you should have a file in your <filename>~/.config</filename>
+(or in <envar>$XDG_CONFIG_HOME</envar>, if set) directory called
+<filename>kdesrc-buildrc</filename>, which sets the general options and
+specifies the modules you would like to download and build.
+</para>
+
+<note><para>
+It is possible to use different configuration files for &kdesrc-build;, which is
+described in <xref linkend="kdesrc-buildrc" />. If you need to use multiple
+configurations, please see that section. Here, we will assume that the
+configuration is stored in <filename>~/.config/kdesrc-buildrc</filename>.
+</para></note>
+
+<para>
+The easiest way to proceed is to use the
+<filename>kdesrc-buildrc-kf5-sample</filename> file as a template, changing global
+options to match your wants, and also change the list of modules you want to
+build.
+</para>
+
+<para>
+The default settings should be appropriate to perform a
+&kde; build. Some settings that you may wish to alter include:
+</para>
+
+<itemizedlist>
+<listitem><para><link linkend="conf-install-dir">install-dir</link>, which changes the
+destination directory that your &kde; software is installed to. This defaults to
+<filename class="directory">~/kde/usr</filename>, which is a single-user
+installation.</para></listitem>
+
+<listitem><para><link linkend="conf-branch-group">branch-group</link>, which can
+be
+used to choose the appropriate branch of development for the &kde; modules as a
+whole. There are many supported build configurations but you will likely want to
+choose <option>kf5-qt5</option> so that &kdesrc-build; downloads the latest code
+based on &Qt; 5 and &kde; Frameworks 5.</para>
+
+<tip><para>&kdesrc-build; will use a default branch group if you do not choose
+one, but this default will change over time, so it's better to choose one so
+that the branch group does not change unexpectedly.</para></tip>
+</listitem>
+
+<listitem><para><link linkend="conf-source-dir">source-dir</link>, to control the directory
+&kdesrc-build; uses for downloading the source code, running the build process, and saving
+logs.
+This defaults to <filename class="directory">~/kde/src</filename>.</para></listitem>
+
+<listitem><para><link linkend="conf-cmake-options">cmake-options</link>, which
+sets the options to pass to the &cmake; command when building each module.
+Typically this is used to set between <quote>debug</quote> or
+<quote>release</quote> builds, to enable (or disable) optional features, or to
+pass information to the build process about the location of required libraries.
+</para></listitem>
+
+<listitem><para><link linkend="conf-make-options">make-options</link>, which
+sets the options used when actually running the <application>make</application>
+command to build each module (once &cmake; has established the build system).
+</para>
+
+<para>The most typical option is <option>-j<replaceable>N</replaceable></option>,
+where <replaceable>N</replaceable> should be replaced with the maximum number of
+compile jobs you wish to allow.  A higher number (up to the number of logical CPUs
+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-cores">num-cores</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 to use all available CPUs, with exceptions</title>
+<screen>
+global
+    # This environment variable is automatically used by make, including
+    # make commands not run by kdesrc-build directly, such as Qt's configure
+    set-env MAKEFLAGS -j<literal>${num-cores}</literal>
+    …
+end global
+
+…
+
+module-set <replaceable>big-module-set</replaceable>
+    repository kde-projects
+    use-modules <replaceable>calligra</replaceable>
+    make-options -j2 # Reduced number of build jobs for just these modules
+end module-set
+</screen>
+</example>
+
+<note><para>Some very large Git repositories may swamp your system if you try to
+compile with a too many build jobs at one time, especially repositories like the
+&Qt; WebKit and &Qt; WebEngine repositories.  To maintain system interactivity
+you may have to reduce the number of build jobs for specific modules.</para>
+<para><xref linkend="make-options-example"/> gives an example of how to do
+this.</para>
+</note>
+
+</listitem>
+</itemizedlist>
+
+<para>You may want to select different modules to build,
+which is described in <xref linkend="selecting-modules"/>.</para>
+
+</sect1>
diff --git a/doc/index.docbook b/doc/index.docbook
index 2df7f7b9..12020c0d 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -75,6 +75,7 @@
   <!ENTITY building-specific-modules SYSTEM "building-specific-modules.docbook">
   <!ENTITY cmdline SYSTEM "cmdline.docbook">
   <!ENTITY conf-options-table SYSTEM "conf-options-table.docbook">
+  <!ENTITY configure-data SYSTEM "configure-data.docbook">
 ]>
 
 <book id="kdesrc-build" lang="&language;">
@@ -434,116 +435,7 @@ linkend="configure-data" /> and in <xref linkend="kdesrc-buildrc" />.
 </sect2>
 </sect1>
 
-<sect1 id="configure-data">
-<title>Setting the Configuration Data</title>
-
-<para>
-To use &kdesrc-build;, you should have a file in your <filename>~/.config</filename>
-(or in <envar>$XDG_CONFIG_HOME</envar>, if set) directory called
-<filename>kdesrc-buildrc</filename>, which sets the general options and
-specifies the modules you would like to download and build.
-</para>
-
-<note><para>
-It is possible to use different configuration files for &kdesrc-build;, which is
-described in <xref linkend="kdesrc-buildrc" />. If you need to use multiple
-configurations, please see that section. Here, we will assume that the
-configuration is stored in <filename>~/.config/kdesrc-buildrc</filename>.
-</para></note>
-
-<para>
-The easiest way to proceed is to use the
-<filename>kdesrc-buildrc-kf5-sample</filename> file as a template, changing global
-options to match your wants, and also change the list of modules you want to
-build.
-</para>
-
-<para>
-The default settings should be appropriate to perform a
-&kde; build. Some settings that you may wish to alter include:
-</para>
-
-<itemizedlist>
-<listitem><para><link linkend="conf-install-dir">install-dir</link>, which changes the
-destination directory that your &kde; software is installed to. This defaults to
-<filename class="directory">~/kde/usr</filename>, which is a single-user
-installation.</para></listitem>
-
-<listitem><para><link linkend="conf-branch-group">branch-group</link>, which can
-be
-used to choose the appropriate branch of development for the &kde; modules as a
-whole. There are many supported build configurations but you will likely want to
-choose <option>kf5-qt5</option> so that &kdesrc-build; downloads the latest code
-based on &Qt; 5 and &kde; Frameworks 5.</para>
-
-<tip><para>&kdesrc-build; will use a default branch group if you do not choose
-one, but this default will change over time, so it's better to choose one so
-that the branch group does not change unexpectedly.</para></tip>
-</listitem>
-
-<listitem><para><link linkend="conf-source-dir">source-dir</link>, to control the directory
-&kdesrc-build; uses for downloading the source code, running the build process, and saving
-logs.
-This defaults to <filename class="directory">~/kde/src</filename>.</para></listitem>
-
-<listitem><para><link linkend="conf-cmake-options">cmake-options</link>, which
-sets the options to pass to the &cmake; command when building each module.
-Typically this is used to set between <quote>debug</quote> or
-<quote>release</quote> builds, to enable (or disable) optional features, or to
-pass information to the build process about the location of required libraries.
-</para></listitem>
-
-<listitem><para><link linkend="conf-make-options">make-options</link>, which
-sets the options used when actually running the <application>make</application>
-command to build each module (once &cmake; has established the build system).
-</para>
-
-<para>The most typical option is <option>-j<replaceable>N</replaceable></option>,
-where <replaceable>N</replaceable> should be replaced with the maximum number of
-compile jobs you wish to allow.  A higher number (up to the number of logical CPUs
-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-cores">num-cores</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 to use all available CPUs, with exceptions</title>
-<screen>
-global
-    # This environment variable is automatically used by make, including
-    # make commands not run by kdesrc-build directly, such as Qt's configure
-    set-env MAKEFLAGS -j<literal>${num-cores}</literal>
-    …
-end global
-
-…
-
-module-set <replaceable>big-module-set</replaceable>
-    repository kde-projects
-    use-modules <replaceable>calligra</replaceable>
-    make-options -j2 # Reduced number of build jobs for just these modules
-end module-set
-</screen>
-</example>
-
-<note><para>Some very large Git repositories may swamp your system if you try to
-compile with a too many build jobs at one time, especially repositories like the
-&Qt; WebKit and &Qt; WebEngine repositories.  To maintain system interactivity
-you may have to reduce the number of build jobs for specific modules.</para>
-<para><xref linkend="make-options-example"/> gives an example of how to do
-this.</para>
-</note>
-
-</listitem>
-</itemizedlist>
-
-<para>You may want to select different modules to build,
-which is described in <xref linkend="selecting-modules"/>.</para>
-
-</sect1>
+&configure-data;
 
 &building-and-troubleshooting;