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

<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>
    &hellip;
end global

&hellip;

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>
