[sdk/kdesrc-build] doc: doc: appendix-modules - separate docbook
Andrew Shark
null at kde.org
Fri Jan 5 19:07:02 GMT 2024
Git commit b9d905dff7bf8aaa0d943d96bac2bf69494161fe by Andrew Shark.
Committed on 05/01/2024 at 19:56.
Pushed by ashark into branch 'master'.
doc: appendix-modules - separate docbook
A +131 -0 doc/appendix-modules.docbook
M +2 -131 doc/index.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/b9d905dff7bf8aaa0d943d96bac2bf69494161fe
diff --git a/doc/appendix-modules.docbook b/doc/appendix-modules.docbook
new file mode 100644
index 00000000..109f2daf
--- /dev/null
+++ b/doc/appendix-modules.docbook
@@ -0,0 +1,131 @@
+<appendix id="appendix-modules">
+<title>&kde; modules and source code organization</title>
+<sect1 id="module-concept">
+<title>The <quote>Module</quote></title>
+
+<para>&kde; groups its software into <quote>modules</quote> of various size.
+This was initially a loose grouping of a few large modules, but with the
+introduction of the <ulink url="https://git-scm.com/">Git</ulink>-based <ulink
+url="https://commits.kde.org/">source code repositories</ulink>, these large
+modules were further split into many smaller modules.
+</para>
+
+<para>&kdesrc-build; uses this module concept as well. In essence, a
+<quote>module</quote> is a grouping of code that can be downloaded, built,
+tested, and installed.
+</para>
+
+<sect2 id="single-modules">
+<title>Individual modules</title>
+
+<para>It is easy to set &kdesrc-build; to build a single module. The following
+listing is an example of what a declaration for a Git-based module would
+look like in <link linkend="kdesrc-buildrc">the configuration
+file</link>.</para>
+
+<programlisting>
+module <replaceable>kdefoo</replaceable>
+ <option><replaceable>cmake-options -DCMAKE_BUILD_TYPE=Debug</replaceable></option>
+end module
+</programlisting>
+
+<tip><para>This is a Git-based module since it doesn't use a <link
+linkend="conf-repository">repository</link> option. Also, the
+<option>cmake-options</option> option is listed as an example only, it is not
+required.</para></tip>
+
+</sect2>
+<sect2 id="module-groups">
+<title>Groups of related modules</title>
+
+<para>Now most &kde; source modules are Git-based &kde;, and are normally
+combined into groups of modules.</para>
+
+<para>&kdesrc-build; therefore supports groups of modules as well, using
+<link linkend="module-sets">module sets</link>. An example:</para>
+
+<programlisting>
+module-set <replaceable>base-modules</replaceable>
+ <option>repository</option> kde-projects
+ <option>use-modules</option> <replaceable>kde-runtime kde-workspace kde-baseapps</replaceable>
+end module-set
+</programlisting>
+
+<tip><para>You can leave the module set name (<replaceable>base-modules</replaceable>
+in this case) empty if you like. This <option>repository</option> setting tells
+&kdesrc-build; where to download the source from, but you can also use a
+<symbol>git://</symbol> URL.</para></tip>
+
+<para>One special feature of the <quote><option>repository</option>
+<literal>kde-projects</literal></quote> is that &kdesrc-build; will
+automatically include any Git modules that are grouped under the modules you
+list (in the KDE Project database).</para>
+</sect2>
+
+<sect2 id="module-branch-groups">
+<title>Module <quote>branch groups</quote></title>
+
+<para>Taking the concept of a <link linkend="module-groups">group of
+modules</link> further, the &kde; developers eventually found that
+synchronizing the names of the Git branches across a large number of
+repositories was getting difficult, especially during the development push for
+the new &kde; Frameworks for &Qt; 5.
+</para>
+
+<para>So the concept of <quote>branch groups</quote> was developed, to allow
+users and developers to select one of only a few groups, and allow the script
+to automatically select the appropriate Git branch.
+</para>
+
+<para>&kdesrc-build; supports this feature as of version 1.16-pre2, via the
+<link linkend="conf-branch-group">branch-group</link> option.
+</para>
+
+<example id="ex-branch-group">
+<title>Example of using branch-group</title>
+
+<para>branch-group can be used in the configuration file as follows:
+</para>
+
+<programlisting>
+global
+ # Select KDE Frameworks 5 and other Qt5-based apps
+ <option>branch-group</option> <replaceable>kf5-qt5</replaceable>
+
+ # Other global options here ...
+end global
+
+module-set
+ # branch-group only works for kde-projects
+ <option>repository</option> kde-projects
+
+ # branch-group is inherited from the one set globally, but could
+ # specified here.
+
+ <option>use-modules</option> <replaceable>kdelibs kde-workspace</replaceable>
+end module-set
+
+# kdelibs's branch will be "frameworks"
+# kde-workspace's branch will be "master" (as of August 2013)
+</programlisting>
+
+<para>In this case the same <literal>branch-group</literal> gives different
+branch names for each Git module.
+</para>
+</example>
+
+<para>This feature requires some data maintained by the &kde; developers in a Git
+repository named <literal>kde-build-metadata</literal>, however this module
+will be included automatically by &kdesrc-build; (though you may see it appear
+in the script output).
+</para>
+
+<tip><para>&kde; modules that do not have a set branch name for the branch
+group you choose will default to an appropriate branch name, as if you had not
+specified <literal>branch-group</literal> at all.
+</para></tip>
+
+</sect2>
+
+</sect1>
+</appendix>
diff --git a/doc/index.docbook b/doc/index.docbook
index 228b67bb..db3eddcf 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -68,6 +68,7 @@
Just add them as necessary.
-->
<!ENTITY advanced-features SYSTEM "advanced-features.docbook">
+ <!ENTITY appendix-modules SYSTEM "appendix-modules.docbook">
]>
<book id="kdesrc-build" lang="&language;">
@@ -4388,137 +4389,7 @@ as of &kdesrc-build; version 1.6.3.
</chapter>
-<appendix id="appendix-modules">
-<title>&kde; modules and source code organization</title>
-<sect1 id="module-concept">
-<title>The <quote>Module</quote></title>
-
-<para>&kde; groups its software into <quote>modules</quote> of various size.
-This was initially a loose grouping of a few large modules, but with the
-introduction of the <ulink url="https://git-scm.com/">Git</ulink>-based <ulink
-url="https://commits.kde.org/">source code repositories</ulink>, these large
-modules were further split into many smaller modules.
-</para>
-
-<para>&kdesrc-build; uses this module concept as well. In essence, a
-<quote>module</quote> is a grouping of code that can be downloaded, built,
-tested, and installed.
-</para>
-
-<sect2 id="single-modules">
-<title>Individual modules</title>
-
-<para>It is easy to set &kdesrc-build; to build a single module. The following
-listing is an example of what a declaration for a Git-based module would
-look like in <link linkend="kdesrc-buildrc">the configuration
-file</link>.</para>
-
-<programlisting>
-module <replaceable>kdefoo</replaceable>
- <option><replaceable>cmake-options -DCMAKE_BUILD_TYPE=Debug</replaceable></option>
-end module
-</programlisting>
-
-<tip><para>This is a Git-based module since it doesn't use a <link
-linkend="conf-repository">repository</link> option. Also, the
-<option>cmake-options</option> option is listed as an example only, it is not
-required.</para></tip>
-
-</sect2>
-<sect2 id="module-groups">
-<title>Groups of related modules</title>
-
-<para>Now most &kde; source modules are Git-based &kde;, and are normally
-combined into groups of modules.</para>
-
-<para>&kdesrc-build; therefore supports groups of modules as well, using
-<link linkend="module-sets">module sets</link>. An example:</para>
-
-<programlisting>
-module-set <replaceable>base-modules</replaceable>
- <option>repository</option> kde-projects
- <option>use-modules</option> <replaceable>kde-runtime kde-workspace kde-baseapps</replaceable>
-end module-set
-</programlisting>
-
-<tip><para>You can leave the module set name (<replaceable>base-modules</replaceable>
-in this case) empty if you like. This <option>repository</option> setting tells
-&kdesrc-build; where to download the source from, but you can also use a
-<symbol>git://</symbol> URL.</para></tip>
-
-<para>One special feature of the <quote><option>repository</option>
-<literal>kde-projects</literal></quote> is that &kdesrc-build; will
-automatically include any Git modules that are grouped under the modules you
-list (in the KDE Project database).</para>
-</sect2>
-
-<sect2 id="module-branch-groups">
-<title>Module <quote>branch groups</quote></title>
-
-<para>Taking the concept of a <link linkend="module-groups">group of
-modules</link> further, the &kde; developers eventually found that
-synchronizing the names of the Git branches across a large number of
-repositories was getting difficult, especially during the development push for
-the new &kde; Frameworks for &Qt; 5.
-</para>
-
-<para>So the concept of <quote>branch groups</quote> was developed, to allow
-users and developers to select one of only a few groups, and allow the script
-to automatically select the appropriate Git branch.
-</para>
-
-<para>&kdesrc-build; supports this feature as of version 1.16-pre2, via the
-<link linkend="conf-branch-group">branch-group</link> option.
-</para>
-
-<example id="ex-branch-group">
-<title>Example of using branch-group</title>
-
-<para>branch-group can be used in the configuration file as follows:
-</para>
-
-<programlisting>
-global
- # Select KDE Frameworks 5 and other Qt5-based apps
- <option>branch-group</option> <replaceable>kf5-qt5</replaceable>
-
- # Other global options here ...
-end global
-
-module-set
- # branch-group only works for kde-projects
- <option>repository</option> kde-projects
-
- # branch-group is inherited from the one set globally, but could
- # specified here.
-
- <option>use-modules</option> <replaceable>kdelibs kde-workspace</replaceable>
-end module-set
-
-# kdelibs's branch will be "frameworks"
-# kde-workspace's branch will be "master" (as of August 2013)
-</programlisting>
-
-<para>In this case the same <literal>branch-group</literal> gives different
-branch names for each Git module.
-</para>
-</example>
-
-<para>This feature requires some data maintained by the &kde; developers in a Git
-repository named <literal>kde-build-metadata</literal>, however this module
-will be included automatically by &kdesrc-build; (though you may see it appear
-in the script output).
-</para>
-
-<tip><para>&kde; modules that do not have a set branch name for the branch
-group you choose will default to an appropriate branch name, as if you had not
-specified <literal>branch-group</literal> at all.
-</para></tip>
-
-</sect2>
-
-</sect1>
-</appendix>
+&appendix-modules;
<appendix id="appendix-profile">
<title>Superseded profile setup procedures</title>
More information about the kde-doc-english
mailing list