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