<!--
SPDX-FileCopyrightText: 2005 - 2008, 2010 - 2022 Michael Pyne <mpyne@kde.org>
SPDX-FileCopyrightText: 2005 - 2024 The kdesrc-build authors

SPDX-License-Identifier: GFDL-1.2-no-invariants-or-later
-->

<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>
