<sect1 id="kde-modules-and-selection">
<title
>Module Organization and selection</title>

<sect2 id="kde-layers">
<title
>KDE Software Organization</title>

<para
>&kde; software is split into different components, many of which can be built by &kdesrc-build;. Understanding this organization will help you properly select the software modules that you want built. </para>

<orderedlist>
<listitem
><para
>At the lowest level comes the &Qt; library, which is a very powerful, cross-platform <quote
>toolkit</quote
> library. &kde; is based on &Qt;, and some of the non-&kde; libraries required by &kde; are also based on &Qt;. &kdesrc-build; can build &Qt;, or use the one already installed on your system if it is a recent enough version.</para
></listitem>

<listitem
><para
>On top of &Qt; are required libraries that are necessary for &kde; software to work. Some of these libraries are not considered part of &kde; itself due to their generic nature, but are still essential to the &kde; Platform. These libraries are collected under a <literal
>kdesupport</literal
> module grouping but are not considered part of the <quote
>Frameworks</quote
> libraries.</para>
</listitem>

<listitem
><para
>On top of these essential libraries come the <ulink url="https://community.kde.org/Frameworks"
>&kde; Frameworks</ulink
>, sometimes abbreviated as KF5, which are essential libraries for the &kde; Plasma desktop, &kde; Applications, and other third-party software. </para
> </listitem>

<listitem
><para
>On top of the Frameworks, come several different things:</para>
    <itemizedlist>
        <listitem
><para
><quote
>Third-party</quote
> applications. These are applications that use the &kde; Frameworks or are designed to run under &kde; Plasma but are not authored by or in association with the &kde; project.</para
></listitem>

        <listitem
><para
>Plasma, which is a full <quote
>workspace</quote
> desktop environment. This is what users normally see when they <quote
>log-in to &kde;</quote
>.</para
></listitem>

        <listitem
><para
>The &kde; Application suite. This is a collection of useful software included with the Platform and &plasma; Desktop, grouped into individual modules, including utilities like &dolphin;, games like <application
>KSudoku</application
>, and productivity software released by &kde; such as &kontact;.</para
></listitem>

        <listitem
><para
>Finally, there is a collection of software (also collected in modules) whose development is supported by &kde; resources (such as translation, source control, bug tracking, &etc;) but is not released by &kde; as part of Plasma or the Application suite. These modules are known as <quote
>Extragear</quote
>. </para
></listitem>
    </itemizedlist>
</listitem>
</orderedlist>
</sect2>

<sect2 id="selecting-modules">
<title
>Selecting modules to build</title>

<para
>Selecting which of the possible modules to build is controlled by <link linkend="kdesrc-buildrc"
>the configuration file</link
>. After the <literal
>global</literal
> section is a list of modules to build, bracketed by module ... end module lines. An example entry for a module is shown in <xref linkend="conf-module-example"/>.</para>

<example id="conf-module-example">
<title
>Example module entry in the configuration file</title>
<programlisting
>module <replaceable
>kdesrc-build-git</replaceable>
    # Options for this module go here, example:
    <link linkend="conf-repository"
>repository</link
> kde:kdesrc-build
    <link linkend="conf-make-options"
>make-options</link
> -j4 # Run 4 compiles at a time
end module
</programlisting>
</example>

<note
><para
>In practice, this module construct is not usually used directly. Instead most modules are specified via module-sets as described below.</para
></note>

<para
>When using only <literal
>module</literal
> entries, &kdesrc-build; builds them in the order you list, and does not attempt to download any other repositories other than what you specify directly. </para>

</sect2>

<sect2 id="module-sets">
<title
>Module Sets</title>

<para
>The &kde; source code is decomposed into a great number of relatively small Git-based repositories. To make it easier to manage the large number of repositories involved in any useful &kde;-based install, &kdesrc-build; supports grouping multiple modules and treating the group as a <quote
>module set</quote
>. </para>

<sect3 id="module-set-concept">
<title
>The basic module set concept</title>

<para
>By using a module set, you can quickly declare many Git modules to be downloaded and built, as if you'd typed out a separate module declaration for each one. The <link linkend="conf-repository"
>repository</link
> option is handled specially to setup where each module is downloaded from, and every other option contained in the module set is copied to every module generated in this fashion.</para>

<example id="example-using-module-sets">
<title
>Using module sets</title>
<programlisting
>global
    <option
><link linkend="conf-git-repository-base"
>git-repository-base</link
></option
> <replaceable
>kde-git</replaceable
> <replaceable
>kde:</replaceable>
end global

module <replaceable
>qt</replaceable>
    # Options removed for brevity
end module

module-set <replaceable
>kde-support-libs</replaceable>
    <option
><link linkend="conf-repository"
>repository</link
></option
> <replaceable
>kde-git</replaceable>
    <option
><link linkend="conf-use-modules"
>use-modules</link
></option
> <replaceable
>automoc</replaceable
> <replaceable
>attica</replaceable
> <replaceable
>akonadi</replaceable>
end module-set

# Other modules as necessary...
module <replaceable
>kdesupport</replaceable>
end module
</programlisting>
</example>

<para
>In <xref linkend="example-using-module-sets"/> a brief module set is shown. When &kdesrc-build; encounters this module set, it acts as if, for every module given in <option
>use-modules</option
>, that an individual module has been declared, with its <option
>repository</option
> equal to the module-set's <option
>repository</option
> followed immediately by the given module name.</para>

<para
>In addition, other options can be passed in a module set, which are copied to every new module that is created this way. By using module-set it is possible to quickly declare many Git modules that are all based on the same repository URL. In addition, it is possible to give module-sets a name (as shown in the example), which allows you to quickly refer to the entire group of modules from the command line.</para>

</sect3>
<sect3 id="module-sets-kde">
<title
>Special Support for KDE module sets</title>

<para
>The module set support described so far is general to any Git-based modules. For the &kde; Git repositories, &kdesrc-build; includes additional features to make things easier for users and developers. This support is enabled by specifying <literal
>kde-projects</literal
> as the <option
>repository</option
> for the module set. </para>

<para
>&kdesrc-build; normally only builds the modules you have listed in your configuration file, in the order you list them. But with a <literal
>kde-projects</literal
> module set, &kdesrc-build; can do dependency resolution of &kde;-specific modules, and in addition automatically include modules into the build even if only indirectly specified.</para>

<example id="example-using-kde-module-sets">
<title
>Using kde-projects module sets</title>
<programlisting
># Only adds a module for juk (the kde/kdemultimedia/juk repo)
module-set <replaceable
>juk-set</replaceable>
    <option
>repository</option
> kde-projects
    <option
>use-modules</option
> <replaceable
>juk</replaceable>
end module-set

# Adds all modules that are in kde/multimedia/*, including juk,
# but no other dependencies
module-set <replaceable
>multimedia-set</replaceable>
    <option
>repository</option
> kde-projects
    <option
>use-modules</option
> <replaceable
>kde/multimedia</replaceable>
end module-set

# Adds all modules that are in kde/multimedia/*, and all kde-projects
# dependencies from outside of kde/kdemultimedia
module-set <replaceable
>multimedia-deps-set</replaceable>
    <option
>repository</option
> kde-projects
    <option
>use-modules</option
> <replaceable
>kde/multimedia</replaceable>
    <option
>include-dependencies</option
> <replaceable
>true</replaceable>
end module-set

# All modules created out of these three module sets are automatically put in
# proper dependency order, regardless of the setting for include-dependencies
</programlisting>
</example>

<tip
><para
>This <literal
>kde-projects</literal
> module set construct is the main method of declaring which modules you want to build.</para
></tip>

<para
>All module sets use the <link linkend="conf-repository"
>repository</link
> and <link linkend="conf-use-modules"
>use-modules</link
> options. <link linkend="kde-projects-module-sets"
><literal
>kde-projects</literal
></link
> module sets have a predefined <option
>repository</option
> value, but other types of module sets also will use the <link linkend="conf-git-repository-base"
>git-repository-base</link
> option. </para>
</sect3>

</sect2>

<sect2 id="kde-projects-module-sets">
<title
>The official &kde; module database</title>

<para
>&kde;'s Git repositories allow for grouping related Git modules into collections of related modules (e.g. kdegraphics). Git doesn't recognize these groupings, but &kdesrc-build; can understand these groups, using <link linkend="module-sets"
>module sets</link
> with a <option
>repository</option
> option set to <quote
><literal
>kde-projects</literal
></quote
>.</para>

<para
>&kdesrc-build; will recognize that the <literal
>kde-projects</literal
> repository requires special handling, and adjust the build process appropriately. Among other things, &kdesrc-build; will:</para>

<itemizedlist>

<listitem
><para
>Download the latest module database from the <ulink url=" https://commits.kde.org/"
>&kde; git archive</ulink
>.</para
></listitem>

<listitem
><para
>Try to find a module with the name given in the module set's <option
>use-modules</option
> setting in that database.</para
></listitem>

<listitem
><para
>For every module that is found, &kdesrc-build; will lookup the appropriate repository in the database, based upon the <link linkend="conf-branch-group"
>branch-group</link
> setting in effect. If a repository exists and is active for the branch group, &kdesrc-build; will automatically use that to download or update the source code. </para
></listitem>

</itemizedlist>

<note
><para
>In the current database, some module groups not only have a collection of modules, but they <emphasis
>also</emphasis
> declare their own &git; repository. In these situations &kdesrc-build; will currently prefer the group's &git; repository instead of including the childrens' repositories. </para
></note>

<para
>The following example shows how to use the &kde; module database to install the Phonon multimedia library.</para>

<informalexample>
<programlisting
>module-set <replaceable
>media-support</replaceable>
    # This option must be kde-projects to use the module database.
    <option
><link linkend="conf-repository"
>repository</link
></option
> <literal
>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option
><link linkend="conf-use-modules"
>use-modules</link
></option
> <replaceable
>phonon/phonon</replaceable
> <replaceable
>phonon-gstreamer</replaceable
> <replaceable
>phonon-vlc</replaceable>
end module-set
</programlisting>
</informalexample>

<tip
><para
><literal
>phonon/phonon</literal
> is used since (with the current project database) &kdesrc-build; would otherwise have to decide between the group of projects called <quote
>phonon</quote
> or the individual project named <quote
>phonon</quote
>. Currently &kdesrc-build; would pick the former, which would build many more backends than needed.</para
></tip>

<para
>The following example is perhaps more realistic, and shows a feature only available with the &kde; module database: Building all of the &kde; graphics applications with only a single declaration.</para>

<informalexample>
<programlisting
>module-set <replaceable
>kdegraphics</replaceable>
    # This option must be kde-projects to use the module database.
    <option
><link linkend="conf-repository"
>repository</link
></option
> <literal
>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option
><link linkend="conf-use-modules"
>use-modules</link
></option
> <literal
>kdegraphics/libs</literal
> <literal
>kdegraphics/*</literal>
end module-set
</programlisting>
</informalexample>

<para
>There are two important abilities demonstrated here:</para>

<orderedlist>

<listitem
><para
>&kdesrc-build; allows you to specify modules that are descendents of a given module, without building the parent module, by using the syntax <userinput
><replaceable
>module-name</replaceable
>/*</userinput
>. It is actually required in this case since the base module, kdegraphics, is marked as inactive so that it is not accidentally built along with its children modules. Specifying the descendent modules allows &kdesrc-build; to skip around the disabled module. </para
></listitem>

<listitem
><para
>&kdesrc-build; will also not add a given module to the build list more than once. This allows us to manually set <literal
>kdegraphics/libs</literal
> to build first, before the rest of <literal
>kdegraphics</literal
>, without trying to build <literal
>kdegraphics/libs</literal
> twice. This used to be required for proper dependency handling, and today remains a fallback option in case the &kde; project database is missing dependency metadata. </para
></listitem>
</orderedlist>
</sect2>

<sect2 id="ignoring-project-modules">
<title
>Filtering out &kde; project modules</title>

<para
>You might decide that you'd like to build all programs within a &kde; module grouping <emphasis
>except</emphasis
> for a given program.</para>

<para
>For instance, the <literal
>kdeutils</literal
> group includes a program named <application
>kremotecontrol</application
>. If your computer does not have the proper hardware to receive the signals sent by remote controls then you may decide that you'd rather not download, build, and install <application
>kremotecontrol</application
> every time you update <literal
>kdeutils</literal
>.</para>

<para
>You can achieve this by using the <link linkend="conf-ignore-modules"
>ignore-modules</link
> configuration option. On the command line the <link linkend="ignoring-modules"
>&cmd-ignore-modules; option</link
> does the same thing, but is more convenient for filtering out a module just once. </para>

<example id="example-ignoring-a-module">
<title
>Example for ignoring a kde-project module in a group</title>
<programlisting
>module-set <replaceable
>utils</replaceable>
    <option
><link linkend="conf-repository"
>repository</link
></option
> <literal
>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option
><link linkend="conf-use-modules"
>use-modules</link
></option
> <replaceable
>kdeutils</replaceable>

    # This option "subtracts out" modules from the modules chosen by use-modules, above.
    <option
><link linkend="conf-ignore-modules"
>ignore-modules</link
></option
> <replaceable
>kremotecontrol</replaceable>
end module-set

module-set <replaceable
>graphics</replaceable>
    <option
><link linkend="conf-repository"
>repository</link
></option
> <literal
>kde-projects</literal>

    # This option chooses what modules to look for in the database.
    <option
><link linkend="conf-use-modules"
>use-modules</link
></option
> <replaceable
>extragear/graphics</replaceable>

    # This option "subtracts out" modules from the modules chosen by use-modules, above.
    # In this case, *both* extragear/graphics/kipi-plugins and
    # extragear/graphics/kipi-plugins/kipi-plugins-docs are ignored
    <option
><link linkend="conf-ignore-modules"
>ignore-modules</link
></option
> <replaceable
>extragear/graphics/kipi-plugins</replaceable>
end module-set
</programlisting>
</example>

</sect2>

</sect1>
