<!--
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="conf-options-table">
<title>Table of available configuration options</title>

<para>Here are tables of various options, containing the following
information:</para>

<itemizedlist>

<listitem><para>The option name</para></listitem>

<listitem><para>The scope of the option: <emphasis>global</emphasis>, <emphasis>module</emphasis> or <emphasis>module-set</emphasis>.
Options in <emphasis>module</emphasis> or/and <emphasis>module-set</emphasis> scope can also be defined in <emphasis>options</emphasis> sections.
</para></listitem>

<listitem><para>Special comments on the purpose and usage of the
option.</para></listitem>

</itemizedlist>

<table id="options-global-table">
<title>Global scope only options</title>
<tgroup cols="2">

<thead>
<row>
<entry>Option name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>

<row id="conf-async">
<entry><link linkend="conf-async">async</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
<member>Available since</member><member>1.6</member>
</simplelist>
<para>This option enables the asynchronous mode of operation, where the source
code update and the build process will be performed in parallel, instead of waiting for
all of the source code updates before starting the build process.</para>
<para>Related command-line option: <xref linkend="cmdline-async"/></para>
</entry>
</row>

<row id="conf-colorful-output">
<entry><link linkend="conf-colorful-output">colorful-output</link></entry>
<entry><simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
</simplelist><para>Set this option to <userinput>false</userinput> to disable the colorful output of &kdesrc-build;.
Note that &kdesrc-build; will not output the
color codes to anything but a terminal (such as xterm, &konsole;, or the normal
&Linux; console).</para>
<para>Related command-line option: <xref linkend="cmdline-color"/></para>
</entry>
</row>

<row id="conf-disable-agent-check">
<entry><link linkend="conf-disable-agent-check">disable-agent-check</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
</simplelist>
<para>If you are using &ssh; to download the &git; sources
(such as if you are using the git+ssh protocol), this option controls if &kdesrc-build; will try and
make sure that if you are using ssh-agent, it is actually managing some &ssh;
identities. This is to try and prevent &ssh; from asking for your pass phrase
for every module.</para>
<para>Related command-line option: --disable-agent-check, --no-disable-agent-check</para>
</entry>
</row>

<row id="conf-git-desired-protocol">
<entry><link linkend="conf-git-desired-protocol">git-desired-protocol</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member>git</member>
<member>History information</member><member>This option was added in &kdesrc-build; 1.16. Prior to 20.06 this option
was used to configure the fetch URL instead of the push URL. As of 20.06
<literal>https</literal> is always used when updating KDE projects.</member>
</simplelist>
<para>This option only applies to modules from a <link
linkend="kde-projects-module-sets">&kde; project</link> repository.</para>

<para>What this option actually does is configure which network protocol to
prefer when pushing source code for these modules. Normally the very-efficient
<literal>git</literal> protocol is used, but this may be blocked in some
networks (e.g. corporate intranets, public Wi-Fi). An alternative protocol
which is much better supported is the <literal>https</literal> protocol used for
Internet web sites.</para>

<para>If you are using one of these constrained networks you can set this
option to <userinput>http</userinput> to prefer <literal>https</literal>
communications instead.</para>

<tip><para>You may also need the <link
linkend="conf-http-proxy">http-proxy</link> option if an HTTP proxy is also
needed for network traffic.</para></tip>

<para>In any other situation you should not set this option as the default
protocol is most efficient.</para>

</entry>
</row>

<row id="conf-git-repository-base">
<entry><link linkend="conf-git-repository-base">git-repository-base</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.12.1</member>
</simplelist>
<para>This option is used to create a short
name to reference a specific Git repository base URL in later <link
linkend="module-sets">module set</link> declarations, which is useful for
quickly declaring many Git modules to build.</para>

<para>You must specify two things (separated by a space): The name to assign
to the base URL, and the actual base URL itself. For example:</para>

<para>
<programlisting>
global
    # other options
    # This is the common path to all anonymous Git server modules.
    git-repository-base <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable>
end global

# Module declarations

module-set
    # Now you can use the alias you defined earlier, but <emphasis>only</emphasis> in a module-set.
    repository <replaceable>kde-git</replaceable>
    <link linkend="conf-use-modules">use-modules</link> <replaceable>module1.git</replaceable> <replaceable>module2.git</replaceable>
end module-set
</programlisting>
</para>

<para>The module-set's <literal>use-modules</literal> option created two modules
internally, with &kdesrc-build; behaving as if it had read:</para>

<programlisting>
module module1
    repository kde:<replaceable>module1.git</replaceable>
end module

module module2
    repository kde:<replaceable>module2.git</replaceable>
end module
</programlisting>

<para>The <literal>kde:</literal> &git; repository prefix used above is a
shortcut which will be setup by &kdesrc-build; automatically. See the TechBase
<ulink
url="https://techbase.kde.org/Development/Git/Configuration#URL_Renaming">URL
Renaming</ulink> article for more information. Note that unlike most other
options, this option can be specified multiple times in order to create as
many aliases as necessary.</para>

<tip><para>It is not required to use this option to take advantage of module-set,
this option exists to make it easy to use the same repository across many
different module sets.</para></tip>
</entry>
</row>

<row id="conf-install-environment-driver">
<entry><link linkend="conf-install-environment-driver">install-environment-driver</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
<member>Available since</member><member>17.08</member>
</simplelist>
<para>Install a shell script that can be
sourced in a user's profile setup scripts to easily establish needed environment
variables to run the Plasma desktop built by &kdesrc-build;.</para>

<para>This driver will alter the following files:</para>

<itemizedlist>
<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem>
</itemizedlist>

<para>The <filename>kde-env-user.sh</filename> is optional.  It is
intended for user customizations (see the <ulink url="https://userbase.kde.org/KDE_System_Administration/Environment_Variables#Troubleshooting_and_Debugging">Troubleshooting and Debugging</ulink>
section of the &kde; UserBase for examples of customizable settings), but these settings
can be set elsewhere by the user in their existing profile setup scripts.</para>

<para>You can disable this feature by setting this option to
<replaceable>false</replaceable>, and ensuring that the <link
linkend="conf-install-session-driver">install-session-driver</link> option is
also disabled.</para>

<tip><para>&kdesrc-build; will not overwrite your existing files (if present)
unless you also pass the <option><link
linkend="cmdline-delete-my-settings">--delete-my-settings</link></option>
command-line option.</para></tip>
<para>Related command-line option: --install-environment-driver, --no-install-environment-driver</para>
</entry>
</row>

<row id="conf-install-session-driver">
<entry><link linkend="conf-install-session-driver">install-session-driver</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
<member>Available since</member><member>1.16</member>
</simplelist>
<para>If enabled, &kdesrc-build; will try to install a driver for the graphical
login manager that allows you to login to your &kdesrc-build;-built &kde; desktop.</para>

<para>This driver will alter the following files:</para>

<itemizedlist>
<listitem><para><filename>~/.xsession</filename></para></listitem>
<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem>
</itemizedlist>

<para>If you maintain your own login driver then you can disable this feature by setting this
option to <replaceable>false</replaceable>.  If enabled, this feature also enables the
<link linkend="conf-install-environment-driver">install-environment-driver</link> feature.</para>

<tip><para>&kdesrc-build; will not overwrite your existing files (if present)
unless you also pass the <option><link
linkend="cmdline-delete-my-settings">--delete-my-settings</link></option>
command-line option.</para></tip>
<para>Related command-line option: --install-session-driver, --no-install-session-driver</para>
</entry>
</row>

<row id="conf-niceness">
<entry><link linkend="conf-niceness">niceness</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Integer</member>
<member>Default value</member><member>10</member>
</simplelist>
<para>Set this option to a number between 20 and 0. The higher the number, the
lower a priority &kdesrc-build; will set for itself, i.e. the higher the
number, the "nicer" the program is.</para>
<para>Related command-line option: <xref linkend="cmdline-nice"/></para>
</entry>
</row>

<row id="conf-num-cores">
<entry><link linkend="conf-num-cores">num-cores</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Integer</member>
<member>Default value</member><member>Depends on system</member>
<member>Available since</member><member>20.07</member>
</simplelist>
<para>This option is defined by &kdesrc-build; (when using <command>kdesrc-build --generate-config</command>), set to be the number of
available CPUs (as indicated by the external application
<application>nproc</application>). If &kdesrc-build; cannot detect the
number of CPUs, this value is set to 4.</para>

<para>See <xref linkend="make-options-example"/> for an example of this
option's usage.</para>
<para>Related command-line option: --num-cores <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-num-cores-low-mem">
<entry><link linkend="conf-num-cores-low-mem">num-cores-low-mem</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Integer</member>
<member>Default value</member><member>Depends on system</member>
<member>Available since</member><member>20.07</member>
</simplelist>
<para>This option is defined by &kdesrc-build; (when using <command>kdesrc-build --generate-config</command>), set to be the number of
CPUs that is deemed safe for heavyweight or other highly-intensive modules,
such as <literal>qtwebengine</literal>, to avoid running out of memory
during the build.</para>

<para>The typical calculation is one CPU core for every 2
gigabytes (GiB) of total memory. At least 1 core will be specified,
and no more than <option><link linkend="conf-num-cores">num-cores</link></option>
cores will be specified.</para>

<para>Although this option is intended to support &Qt; modules, you can use it for your
any module in the same way that <option>num-cores</option> is used.</para>

<para>If &kdesrc-build; cannot detect available memory then this value will be
set to 2.</para>

<para>Related command-line option: --num-cores-low-mem <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-persistent-data-file">
<entry><link linkend="conf-persistent-data-file">persistent-data-file</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.15</member>
</simplelist>
<para>Use this option to change where &kdesrc-build; stores its
persistent data. The default is to store this data in a file called
<filename>.kdesrc-build-data</filename>, placed in the same directory as the
configuration file in use. If the global configuration file is in use, it will
be saved to <filename>~/.local/state/kdesrc-build-data</filename>
(<filename>$XDG_STATE_HOME/kdesrc-build-data</filename>, if
<envar>$XDG_STATE_HOME</envar> is set). If you have multiple available
configurations in the same directory, you may want to manually set this option,
so that different configurations do not end up with conflicting persistent data.
</para>
<para>Related command-line option: --persistent-data-file <replaceable>file</replaceable></para>
</entry>
</row>

<row id="conf-ssh-identity-file">
<entry><link linkend="conf-ssh-identity-file">ssh-identity-file</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.14.2</member>
</simplelist>
<para>Set this option to control which private SSH key file is passed to the
<command>ssh-add</command> command when &kdesrc-build; is downloading source
code from repositories that require authentication. See also: <xref
linkend="ssh-agent-reminder"/>.</para>
</entry>
</row>

<row id="conf-use-idle-io-priority">
<entry><link linkend="conf-use-idle-io-priority">use-idle-io-priority</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
<member>Available since</member><member>1.12</member>
</simplelist>
<para>Use lower priority for disk and other I/O, which can significantly improve the
responsiveness of the rest of the system at the expense of slightly longer
running times for &kdesrc-build;.</para>
<para>Related command-line option: --use-idle-io-priority, --no-use-idle-io-priority</para>
</entry>
</row>

<row id="conf-use-inactive-modules">
<entry><link linkend="conf-use-inactive-modules">use-inactive-modules</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
</simplelist>
<para>Allow kdesrc-build to also clone and pull from repositories marked as inactive.</para>
<para>Related command-line option: --use-inactive-modules, --no-use-inactive-modules</para>
</entry>
</row>

</tbody>
</tgroup>
</table>

<!-- Between tables -->

<table id="option-table">
<title>All scopes (module, module-set and global) options</title>
<tgroup cols="2">

<thead>
<row>
<entry>Option name</entry>
<entry>Description</entry>
</row>
</thead>

<tbody>

<row id="conf-binpath">
<entry><link linkend="conf-binpath">binpath</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Set this option to set the environment variable PATH while building.
You cannot override this setting in a module option. The default value is
the $<envar>PATH</envar> that is set when the script starts. This environment
variable should include the colon-separated paths of your development
toolchain. The paths <filename class="directory">${install-dir}/bin</filename> and
<filename class="directory">${qt-install-dir}/bin</filename> are automatically added. You
may use the tilde (~) for any paths you add using this option.</para>
<para>Related command-line option: --binpath <replaceable>path</replaceable></para>
</entry>
</row>

<row id="conf-branch">
<entry><link linkend="conf-branch">branch</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member>master</member>
</simplelist>
<para>Checkout the specified branch instead of the default branch.</para>
<note><para>For most &kde; modules you probably wish to use the <link
linkend="conf-branch-group">branch-group</link> option instead and use this
option for case-by-case exceptions.</para></note>
<para>Related command-line option: --branch <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-branch-group">
<entry><link linkend="conf-branch-group">branch-group</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.16-pre2</member>
</simplelist>
<para>Set this option to a general group from which you want modules to be
chosen.</para>

<para>For supported &git; module types, &kdesrc-build; will determine the
actual branch to use automatically based on rules encoded by the &kde;
developers (these rules may be viewed in the
<literal>kde-build-metadata</literal> source repository in your source
directory). After a branch is determined that branch is used as if you had
specified it yourself using the <link linkend="conf-branch">branch</link>
option.
</para>

<para>This is useful if you're just trying to maintain up-to-date on some
normal development track without having to pay attention to all the branch name
changes.</para>

<para>Note that if you <emphasis>do</emphasis> choose a
<literal>branch</literal> yourself, that it will override this setting. The
same is true of other specific branch selection options such as <link
linkend="conf-tag">tag</link>.</para>

<note><para>This option only applies to <literal>kde-projects</literal> &git;
modules (the common case).  See also <xref
linkend="kde-projects-module-sets"/>.
</para></note>

<para>Related command-line option: --branch-group <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-build-dir">
<entry><link linkend="conf-build-dir">build-dir</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member><filename class="directory">~/kde/build</filename></member>
</simplelist>
<para>
Use this option to change the directory to contain the built sources. There
are three different ways to use it:</para>

<orderedlist>

<listitem><para>Relative to the &kde; &git; source directory (see <link
linkend="conf-source-dir">the source-dir option</link>). This is the default,
and is selected if you type a directory name that does not start with a tilde
(~) or a slash (/).</para></listitem>

<listitem><para>Absolute path. If you specify a path that begins with a /, then
that path is used directly. For example, <filename
class="directory">/tmp/kde-obj-dir/</filename>.</para></listitem>

<listitem><para>Relative to your home directory. If you specify a path that
begins with a ~, then the path is used relative to your home directory,
analogous to the shell's tilde-expansion. For example, <filename
class="directory">~/builddir</filename> would set the build directory to
<filename
class="directory">/home/user-name/builddir</filename>.</para></listitem>

</orderedlist>

<para>Perhaps surprisingly, this option can be changed per module.</para>
<para>Related command-line option: --build-dir <replaceable>path</replaceable></para>
</entry>
</row>

<row id="conf-build-when-unchanged">
<entry><link linkend="conf-build-when-unchanged">build-when-unchanged</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
</simplelist>
<para>Control whether &kdesrc-build; always
tries to build a module that has not had any source code updates.</para>

<para>If set to <userinput>true</userinput>, &kdesrc-build; always attempts the build phase
for a module, even if the module did not have any source code updates.
With this value it will more likely lead to a correct build.</para>

<para>If set to <userinput>false</userinput>, &kdesrc-build; will only attempt to run the
build phase for a module if the module has a source code update, or in other
situations where it is likely that a rebuild is actually required. This can save
time, especially if you run &kdesrc-build; daily, or more frequently.</para>

<important><para>This feature is provided as an optimization only. Like many
other optimizations, there are trade-offs for the correctness of your
installation. For instance, changes to the qt or kdelibs modules may cause
a rebuild of other modules to be necessary, even if the source code doesn't
change at all.</para></important>
<para>Related command-line option: <xref linkend="cmdline-build-when-unchanged"/></para>
</entry>
</row>

<row id="conf-cmake-generator">
<entry><link linkend="conf-cmake-generator">cmake-generator</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member>Unix Makefiles</member>
</simplelist>
<para>Specify which generator to use with &cmake;.
Currently both <literal>Ninja</literal> and <literal>Unix Makefiles</literal>
as well as extra generators based on them like <literal>Eclipse CDT4 - Ninja
</literal> are supported. Invalid (unsupported) values are ignored and treated
as if unset.
</para>

<para>Note that if a valid generator is also specified through
<link linkend="conf-cmake-options">cmake-options</link> it will override the
value for <literal>cmake-generator</literal>.</para>
<para>Related command-line option: --cmake-generator <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-cmake-toolchain">
<entry><link linkend="conf-cmake-toolchain">cmake-toolchain</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Specify a toolchain file to use with &cmake;.
</para>
<para>When a valid toolchain file is configured, &kdesrc-build; will
<emphasis>no longer set environment variables automatically</emphasis>.
You can use &set-env;, &binpath; and &libpath; to fix up the environment
manually if your toolchain file does not work out of the box with
&kdesrc-build;. Refer to <link linkend="kdesrc-build-std-flags">the overview
of standard flags added by &kdesrc-build;</link> for more information.
</para>
<para>Note that if a valid toolchain is also specified through
<link linkend="conf-cmake-options">cmake-options</link> it will override the
value for <literal>cmake-toolchain</literal>.</para>
<para>Related command-line option: --cmake-toolchain <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-cmake-options">
<entry><link linkend="conf-cmake-options">cmake-options</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Appends to global options for the default buildsystem, overrides global
for other buildsystems.</para>
<para>Use this option to specify what flags to pass to &cmake; when
creating the build system for the module. When this is used as a global option,
it is applied to all modules that this script builds. When used as a module
option, it is added to the end of the global options. This allows you to
specify common &cmake; options in the global section.</para>

<para>This option does not apply to qt (which does not use &cmake;). Use
<link linkend="conf-configure-flags">configure-flags</link> instead.</para>

<para>If a valid generator is specified among the listed options it will
override the value of
<link linkend="conf-cmake-generator">cmake-generator</link>. Invalid
(unsupported) generators are ignored and will not be passed to &cmake;.
</para>

<para>If a valid toolchain file is specified among the listed options it will
override the value of
<link linkend="conf-cmake-toolchain">cmake-toolchain</link>. Invalid
toolchains are ignored and will not be passed to &cmake;.
</para>

<para>Since these options are passed directly to the &cmake; command line, they
should be given as they would be typed into &cmake;. For example:</para>

<programlisting>
cmake-options -DCMAKE_BUILD_TYPE=RelWithDebInfo
</programlisting>

<para>Since this is a hassle, &kdesrc-build; takes pains to ensure that as long
as the rest of the options are set correctly, you should be able to leave this
option blank. (In other words, <emphasis>required</emphasis> &cmake; parameters
are set for you automatically)</para>
<para>Related command-line option: --cmake-options <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-compile-commands-export">
<entry><link linkend="conf-compile-commands-export">compile-commands-export</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
</simplelist>
<para>Enables the generation of a <literal>compile_commands.json</literal> via CMake inside the build directory.
</para>
<para>Related command-line option: --compile-commands-export, --no-compile-commands-export</para>
</entry>
</row>

<row id="conf-compile-commands-linking">
<entry><link linkend="conf-compile-commands-linking">compile-commands-linking</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
</simplelist>
<para>Enables the creation of symbolic links from <literal>compile_commands.json</literal> generated via CMake
inside the build directory to the matching source directory.
</para>
<para>Related command-line option: --compile-commands-linking, --no-compile-commands-linking</para>
</entry>
</row>

<row id="conf-configure-flags">
<entry><link linkend="conf-configure-flags">configure-flags</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Appends to global options for the default buildsystem, overrides global
for other buildsystems.</para>
<para>Use this option to specify what flags to pass to ./configure when
creating the build system for the module. When this is used as a global-option,
it is applied to all modules that this script builds. <emphasis>This option
only works for qt.</emphasis></para>

<para>To change configuration settings for KDE modules, see
<link linkend="conf-cmake-options">cmake-options</link>.
</para>
<para>Related command-line option: --configure-flags <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-custom-build-command">
<entry><link linkend="conf-custom-build-command">custom-build-command</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
    <para>This option can be set to run a different command (other than
    <command>make</command>, for example) in order to perform the build
    process.  &kdesrc-build; should in general do the right thing, so you
    should not need to set this option. However it can be useful to use
    alternate build systems.
    </para>

    <para>The value of this option is used as the command line to run, modified
    by the <link linkend="conf-make-options">make-options</link> option as
    normal.
    </para>
<para>Related command-line option: --custom-build-command <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-cxxflags">
<entry><link linkend="conf-cxxflags">cxxflags</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Appends to global options for the default buildsystem, overrides global
for other buildsystems.</para>
<para>Use this option to specify what flags to use for building the
module. This option is
specified here instead of with <link
linkend="conf-configure-flags">configure-flags</link> or <link
linkend="conf-cmake-options">cmake-options</link> because this option will also
set the environment variable <envar>CXXFLAGS</envar> during the build process.</para>

<para>Note that for &kde; 4 and any other modules that use &cmake;, it is
necessary to set the CMAKE_BUILD_TYPE option to <userinput>none</userinput>
when configuring the module.  This can be done using the <link
linkend="conf-cmake-options">cmake-options</link> option.
</para>
<para>Related command-line option: --cxxflags <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-dest-dir">
<entry><link linkend="conf-dest-dir">dest-dir</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Use this option to change the name a module is given on disk. For
example, if your module was extragear/network, you could rename it to
extragear-network using this option.  Note that although this changes the
name of the module on disk, it is not a good idea to include directories
or directory separators in the name as this will interfere with any
<link linkend="conf-build-dir">build-dir</link> or
<link linkend="conf-source-dir">source-dir</link> options.</para>
<para>Related command-line option: --dest-dir <replaceable>path</replaceable></para>
</entry>
</row>

<row id="conf-do-not-compile">
<entry><link linkend="conf-do-not-compile">do-not-compile</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Use this option to select a specific set of directories not to be built in a
module (instead of all of them). The directories not to build should be space-separated.</para>

<para>Note that the sources to the programs will still be downloaded.</para>

<para>For example, to disable building the <literal>codeeditor</literal> and <literal>minimaltest</literal>
directories of the <literal>syntaxhighlighting</literal> framework, you
would add <userinput>do-not-compile codeeditor minimaltest</userinput>
compiling, you would add "do-not-compile juk kscd" to your syntaxhighlighting
options.</para>

<para>See <xref linkend="not-compiling"/> for an example.</para>
<para>Related command-line option: --do-not-compile <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-git-user">
<entry><link linkend="conf-git-user">git-user</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>15.09</member>
</simplelist>
<para>This option is intended for &kde; developers. If set, it will be used to
automatically setup identity information for the &git; source control software
for <emphasis>newly downloaded</emphasis> &git; modules (including the vast
majority of &kde; modules).</para>

<para>Specifically, the user's name and email fields for each new &git; repository are filled
in to the values set by this option.</para>

<para>The value must be specified in the form <option><replaceable>User
Name</replaceable> &lt;<replaceable>email@example.com</replaceable>&gt;</option>.</para>

<para>For instance, a developer named <quote>Foo Barbaz</quote> with the
email address <quote>foo@abc.xyz</quote> would use:</para>
<para>
<programlisting>
    <symbol>git-user</symbol> <replaceable>Foo Barbaz</replaceable> &lt;<replaceable>foo@abc.xyz</replaceable>&gt;
</programlisting>
</para>

</entry>
</row>

<row id="conf-http-proxy">
<entry><link linkend="conf-http-proxy">http-proxy</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.16</member>
</simplelist>
<para>This option, if set, uses the specified URL as a proxy server to use for
any HTTP network communications (for example, when downloading the <link linkend="kde-projects-module-sets">KDE project
database</link>).</para>

<para>In addition, &kdesrc-build; will try to ensure that the tools it depends
on also use that proxy server, if possible, by setting the
<envar>http_proxy</envar> environment variable to the indicated server,
<emphasis>if that environment variable is not already set</emphasis>.</para>
<para>Related command-line option: --http-proxy <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-directory-layout">
<entry><link linkend="conf-directory-layout">directory-layout</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Valid values</member><member><userinput>flat</userinput>,
<userinput>invent</userinput>, <userinput>metadata</userinput></member>
<member>Default value</member><member>flat</member>
</simplelist>
<para>This option is used to configure the layout which &kdesrc-build; should use when
creating source and build directories.</para>
<para>The <userinput>flat</userinput> layout will group all modules
directly underneath the top level source and build directories. For example,
<literal>source/extragear/network/telepathy/ktp-text-ui</literal> in the <userinput>metadata</userinput>
layout would be <literal>source/ktp-text-ui</literal> using the <userinput>flat</userinput> layout
instead.
</para>
<para>The <userinput>invent</userinput> layout creates a directory hierarchy mirroring the relative
paths of repositories on <ulink url="https://invent.kde.org/">invent.kde.org</ulink>. For example
<literal>source/kde/applications/kate</literal> in the <userinput>metadata</userinput> layout would
be <literal>source/utilities/kate</literal> using the <userinput>invent</userinput> layout instead.
This layout only affects KDE projects. It is a good choice for people starting out with
&kdesrc-build;.
</para>
<para>Finally, the <userinput>metadata</userinput> layout is the same as the old default
behaviour. This layout organises KDE projects according to the project paths specified in the
project metadata for these modules. This is a good choice if you want a directory layout which
tracks with certain KDE processes, but note that this path is therefore not always stable. As a
result, &kdesrc-build; may abandon an old copy of the repository and clone a new one for a project
due to changes in the project metadata.</para>
<para>Related command-line option: --directory-layout <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-generate-vscode-project-config">
<entry><link linkend="conf-generate-vscode-project-config">generate-vscode-project-config</link></entry>

<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
</simplelist>

<para>Module setting overrides global</para>

<para>Set this option to <userinput>true</userinput> to make
&kdesrc-build; create VS Code project files (.vscode directory) in the module
source directory.</para>

<para>The .vscode folder will be created in the project source directory, only
if it does not already exist. The configurations will enable the use of LSP,
building, debugging, and running the project from within VS Code.</para>

<para>The configuration also recommends extensions to install that are useful
for working on most KDE projects.</para>

<para>Related command-line option: <xref linkend="cmdline-generate-vscode-project-config"/></para>
</entry>
</row>

<row id="conf-include-dependencies">
<entry><link linkend="conf-include-dependencies">include-dependencies</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
</simplelist>
<para>Controls if &kdesrc-build; will include known dependencies of this module in its build,
without requiring you to mention those dependencies (even indirectly).</para>

<note><para>This option only works for <link
linkend="kde-projects-module-sets"><literal>kde-project</literal>-based
modules</link>, and requires that the metadata maintained by the &kde;
developers is accurate for your selected <link
linkend="conf-branch-group">branch-group</link>.</para></note>

<para>This is to support building applications
that need versions of &Qt; or &plasma; more recent than supported on
common operating systems.</para>
<para>Related command-line option: <xref linkend="cmdline-include-dependencies"/></para>
</entry>
</row>

<row id="conf-install-after-build">
<entry><link linkend="conf-install-after-build">install-after-build</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member>True</member>
</simplelist>
<para>This option is used to install the package after it successfully builds.
You can also use the <link
linkend="cmdline-no-install"><option>--no-install</option></link> command line
flag.</para>
<para>Related command-line option: --install-after-build, --no-install-after-build</para>
</entry>
</row>

<row id="conf-install-dir">
<entry><link linkend="conf-install-dir">install-dir</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member><filename class="directory">~/kde/usr</filename></member>
</simplelist>
<para>This option controls where to install the module after it
is built. If you
change this to a directory needing root access, you may want to read about the
<link linkend="conf-make-install-prefix">make-install-prefix</link> option as
well.</para>
<para>
Changing this option for specific module allows you to install it to a different directory than
where the &kde; Platform libraries are installed, such as if you were using
&kdesrc-build; only to build applications.</para>
<para>You can use <varname>${MODULE}</varname> or <varname>$MODULE</varname>
in the path to have them expanded to the module's name.</para>
<para>Related command-line option: <xref linkend="cmdline-install-dir"/></para>
</entry>
</row>

<row id="conf-libname">
<entry><link linkend="conf-libname">libname</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member>Auto detected</member>
</simplelist>
<para>Set this option to change the default name of the installed library directory
inside ${install-dir} and ${qt-install-dir}. On many systems this is either
"lib" or "lib64". Auto-detection is attempted to set the correct name by default,
but if the guess is wrong then it can be changed with this setting.</para>
<para>Related command-line option: --libname <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-libpath">
<entry><link linkend="conf-libpath">libpath</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Set this option to set the environment variable
<envar>LD_LIBRARY_PATH</envar> while building. You cannot override this setting
in a module option. The default value is blank, but the paths <filename
class="directory">${install-dir}/$<envar>LIBNAME</envar></filename> and <filename
class="directory">${qt-install-dir}/$<envar>LIBNAME</envar></filename> are automatically added.
You may use the tilde (~) for any paths you add using this option.</para>
<para>Related command-line option: --libpath <replaceable>path</replaceable></para>
</entry>
</row>

<row id="conf-log-dir">
<entry><link linkend="conf-log-dir">log-dir</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Use this option to change the directory used to hold the log files
generated by the script.</para>
<para>Related command-line option: --log-dir <replaceable>path</replaceable></para>
</entry>
</row>

<row id="conf-make-install-prefix">
<entry><link linkend="conf-make-install-prefix">make-install-prefix</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Set this variable to a space-separated list, which is interpreted as a
command and its options to precede the <userinput><command>make</command> <option>install</option></userinput> command used to install
modules. This is useful for installing packages with &sudo; for example, but
please be careful while dealing with root privileges.</para>
<para>Related command-line option: --make-install-prefix <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-make-options">
<entry><link linkend="conf-make-options">make-options</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Set this variable in order to pass command line options to the
<command>make</command> command. This is useful for programs such as <ulink
url="https://github.com/distcc/distcc"><application>distcc</application></ulink> or
systems with more than one processor core.</para>
<para>Note that not all supported build systems use <command>make</command>. For
build systems that use <command>ninja</command> for build (such as the
<link linkend="conf-override-build-system"><application>Meson</application>
build system</link>), see the <link linkend="conf-ninja-options">ninja-options</link>
setting.</para>
<para>Related command-line option: --make-options <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-manual-build">
<entry><link linkend="conf-manual-build">manual-build</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
</simplelist>
<para>Set the option value to <userinput>true</userinput> to keep the
build process from attempting to build this module. It will still be kept
up-to-date when updating from &git;. This option is exactly equivalent
to the
<link linkend="cmdline-no-build">
<option>--no-build</option>
</link>
command line option.
</para>
</entry>
</row>

<row id="conf-manual-update">
<entry><link linkend="conf-manual-update">manual-update</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
</simplelist>
<para>Set the option value to <userinput>true</userinput> to keep the
build process from attempting to update (and by extension, build or install)
this module. If you set this option for a module, then you have essentially
commented it out.</para>
</entry>
</row>

<row id="conf-ninja-options">
<entry><link linkend="conf-ninja-options">ninja-options</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>Set this variable in order to pass command line options to the

<command>ninja</command> build command. This can be useful to enable <quote>verbose</quote> output
or to manually reduce the number of parallel build jobs that <command>ninja</command> would
use.</para>

<note><para>Note that this setting only controls ninja when used by &kdesrc-build;.
The &Qt; <quote>webengine</quote> module uses <command>ninja</command> indirectly, but
only officially supports being built by <command>make</command>.
In this situation, you can set <literal>NINJAFLAGS</literal> as a way to have
<command>make</command> pass the appropriate flags when it later calls
<command>ninja</command>, by using
<link linkend="conf-make-options">make-options</link>.</para>

<programlisting>
options <replaceable>qtwebengine</replaceable>
    # Restrict make and ninja to using no more than 6 separate compile jobs even
    # when more CPU is available, to avoid running out of memory
    <option><link linkend="conf-make-options">make-options</link></option> -j<replaceable>6</replaceable> NINJAFLAGS=-j<replaceable>6</replaceable>
end options
</programlisting>
</note>
<para>Related command-line option: --ninja-options <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-override-build-system">
<entry><link linkend="conf-override-build-system">override-build-system</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member>Auto detected</member>
<member>Valid values</member><member>KDE, Qt, qmake, generic, autotools, meson</member>
<member>Available since</member><member>1.16</member>
</simplelist>
<para>Normally &kdesrc-build; will detect the appropriate build system to use
for a module after it is downloaded. This is done by checking for the existence
of specific files in the module's source directory.</para>

<para>Some modules may include more than one required set of files, which could confuse
the auto-detection. In this case you can manually specify the correct build type.</para>

<para>Currently supported build types that can be set are:</para>

<variablelist>
    <varlistentry>
        <term>KDE</term>
        <listitem><para>Used to build &kde; modules. In reality it can be used to build
            almost any module that uses &cmake; but it is best not to rely on this.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>Qt</term>
        <listitem><para>Used to build the &Qt; library itself.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>qmake</term>
        <listitem><para>Used to build &Qt; modules that use
            <application>qmake</application>-style <literal>.pro</literal>
            files.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>generic</term>
        <listitem><para>Used to build modules that use plain Makefiles and that do not
            require any special configuration.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>autotools</term>
        <listitem><para>This is the standard configuration tool used for most Free and
            open-source software not in any of the other categories.</para></listitem>
    </varlistentry>
    <varlistentry>
        <term>meson</term>
        <listitem><para>This is a <ulink url="https://mesonbuild.com">relatively new
            tool</ulink> gaining popularity as a replacement for the autotools and may
            be required for some non-&kde; modules.</para></listitem>
    </varlistentry>
</variablelist>

<para>Related command-line option: --override-build-system <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-purge-old-logs">
<entry><link linkend="conf-purge-old-logs">purge-old-logs</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
</simplelist>
<para>This option controls whether old log directories are automatically
deleted or not.</para>
<para>Related command-line option: --purge-old-logs, --no-purge-old-logs</para>
</entry>
</row>

<row id="conf-qmake-options">
<entry><link linkend="conf-qmake-options">qmake-options</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.16</member>
</simplelist>
<para>Any options specified here are passed to the
<command>qmake</command> command, for modules that use the
<symbol>qmake</symbol> build system. For instance, you can use the
<userinput>PREFIX=/path/to/qt</userinput> option to qmake to override where it
installs the module.
</para>
<para>Related command-line option: --qmake-options <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-qt-install-dir">
<entry><link linkend="conf-qt-install-dir">qt-install-dir</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>This option controls where to install qt modules after build.
If you do not specify this option, &kdesrc-build; will assume that &Qt; is
provided by the operating system.
</para>
<para>Related command-line option: --qt-install-dir <replaceable>path</replaceable></para>
</entry>
</row>

<row id="conf-remove-after-install">
<entry><link linkend="conf-remove-after-install">remove-after-install</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Valid values</member><member>none, builddir, all</member>
<member>Default value</member><member>none</member>
</simplelist>
<para>If you are low on hard disk space, you may want to use this option
in order to automatically delete the build directory (or both the source and
build directories for one-time installs) after the module is successfully
installed.
</para>
<para>Possible values for this option are:
<itemizedlist>
<listitem><para>none - Do not delete anything.</para></listitem>
<listitem><para>builddir - Delete the build directory, but not the source.</para></listitem>
<listitem><para>all - Delete both the source code and build directory.</para></listitem>
</itemizedlist>
</para>

<para>Note that using this option can have a significant detrimental impact on
both your bandwidth usage (if you use <replaceable>all</replaceable>) and the time taken to compile &kde; software,
since &kdesrc-build; will be unable to perform incremental builds.</para>
<para>Related command-line option: --remove-after-install <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-repository">
<entry><link linkend="conf-repository">repository</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.10</member>
</simplelist>
<para>This option is used to
specify the &git; repository to download the source code for the module.
&Qt; (and therefore qt) would need this option, as well as various
&kde; modules that are in the process of conversion to use &git;.</para></entry>
</row>

<row id="conf-revision">
<entry><link linkend="conf-revision">revision</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.16</member>
</simplelist>
<para>If this option is set to a value other than 0 (zero), &kdesrc-build;
will force the source update to bring the module to the exact revision
given, even if options like <link linkend="conf-branch">branch</link> are in
effect. If the module is already at the given revision then it will not be
updated further unless this option is changed or removed from the
configuration.</para>
<para>Related command-line option: <xref linkend="cmdline-revision"/></para>
</entry>
</row>

<row id="conf-run-tests">
<entry><link linkend="conf-run-tests">run-tests</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
</simplelist>
<para>If set to <userinput>true</userinput>, then the module will be
built with support for running its test suite, and the test suite will be
executed as part of the build process. &kdesrc-build; will show a simple
report of the test results. This is useful for developers or those who want
to ensure their system is setup correctly.</para>
<para>Related command-line option: --run-tests, --no-run-tests</para>
</entry>
</row>

<row id="conf-set-env">
<entry><link linkend="conf-set-env">set-env</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
</simplelist>
<para>This option accepts a space-separated set of values, where the first value
is the environment variable to set, and the rest of the values is what you
want the variable set to. For example, to set the variable <envar>RONALD</envar> to
McDonald, you would put in the appropriate section this command:</para>
<programlisting>
<command>set-env</command> <envar>RONALD</envar> <userinput>McDonald</userinput>
</programlisting>
<para>This option is special in that it can be repeated without overriding
earlier set-env settings in the same section of the <link linkend="configure-data">configuration file</link>. This
way you can set more than one environment variable per module (or
globally).</para>
</entry>
</row>

<row id="conf-source-dir">
<entry><link linkend="conf-source-dir">source-dir</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Default value</member><member><filename class="directory">~/kde/src</filename></member>
</simplelist>
<para>This option is used to set the directory on your computer to store the &kde;
&git; sources at. You may use the tilde (~)
to represent the home directory if using this option.</para>
<para>Related command-line option: --source-dir <replaceable>path</replaceable></para>
</entry>
</row>

<row id="conf-stop-on-failure">
<entry><link linkend="conf-stop-on-failure">stop-on-failure</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>True</member>
</simplelist>
<para>Setting this option to <userinput>false</userinput> allows the script to continue execution
after an error occurs during the build or install process.</para>
<para>Related command-line option: <xref linkend="cmdline-stop-on-failure"/></para>
</entry>
</row>

<row id="conf-tag">
<entry><link linkend="conf-tag">tag</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.16</member>
</simplelist>
<para>Use this option to download a specific release of a module.</para>
<para><emphasis>Note:</emphasis> The odds are very good that you <emphasis>do not
want</emphasis> to use this option. &kde; releases are available in tarball form
from the <ulink
url="https://download.kde.org/">&kde; download site</ulink>.</para>
<para>Related command-line option: --tag <replaceable>value</replaceable></para>
</entry>
</row>

<row id="conf-use-clean-install">
<entry><link linkend="conf-use-clean-install">use-clean-install</link></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>Boolean</member>
<member>Default value</member><member>False</member>
<member>Available since</member><member>1.12</member>
</simplelist>
<para>Set this option to <userinput>true</userinput> in order to
have &kdesrc-build; run <command>make uninstall</command> directly before
running <command>make install</command>.</para>

<para>This can be useful in ensuring that there are not stray old library
files, &cmake; metadata, etc. that can cause issues in long-lived &kde;
installations. However this only works on build systems that support
<command>make uninstall</command>.</para>
<para>Related command-line option: --use-clean-install, --no-use-clean-install</para>
</entry>
</row>

</tbody>

</tgroup>
</table>

<para>These options do not require any value (except "filter-out-phases"). They are applied if they are presented in a section.</para>
<table id="options-phase-selection-table">
<title>Phase selection options</title>
<tgroup cols="2">

<thead>
<row>
<entry>Option name</entry>
<entry>Scope</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>

<row id="conf-no-src">
<entry><link linkend="conf-no-src">no-src</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>Remove <emphasis>update</emphasis> phase. The other phases that were presented will still be processed.</para>
<para>Related command-line option: <xref linkend="cmdline-no-src"/></para>
</entry>
</row>

<row id="conf-no-install">
<entry><link linkend="conf-no-install">no-install</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>Remove <emphasis>install</emphasis> phase. The other phases that were presented will still be processed.</para>
<para>Related command-line option: <xref linkend="cmdline-no-install"/></para>
</entry>
</row>

<row id="conf-no-tests">
<entry><link linkend="conf-no-tests">no-tests</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>Remove <emphasis>test</emphasis> phase. The other phases that were presented will still be processed.</para>
<para>Related command-line option: --no-tests</para>
</entry>
</row>

<row id="conf-no-build">
<entry><link linkend="conf-no-build">no-build</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>Remove <emphasis>build</emphasis> phase. The other phases that were presented will still be processed.</para>
<para>Related command-line option: <xref linkend="cmdline-no-build"/></para>
</entry>
</row>

<row id="conf-build-only">
<entry><link linkend="conf-build-only">build-only</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>If had <emphasis>build</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
<para>Related command-line option: <xref linkend="cmdline-build-only"/></para>
</entry>
</row>

<row id="conf-install-only">
<entry><link linkend="conf-install-only">install-only</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>If had <emphasis>install</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
<para>Related command-line option: <xref linkend="cmdline-install-only"/></para>
</entry>
</row>

<row id="conf-uninstall">
<entry><link linkend="conf-uninstall">uninstall</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>If had <emphasis>uninstall</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
<para>Related command-line option: --uninstall</para>
</entry>
</row>

<row id="conf-filter-out-phases">
<entry><link linkend="conf-filter-out-phases">filter-out-phases</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
<entry>
<para>Remove those phases that are listed (space separated) in this option. The other phases that were presented will still be processed.</para>
</entry>
</row>

</tbody>
</tgroup>
</table>

<table id="options-module-set-table">
<title>Modules selection options</title>
<tgroup cols="2">

<thead>
<row>
<entry>Option name</entry>
<entry>Scope</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>


<row id="conf-ignore-modules">
<entry><link linkend="conf-ignore-modules">ignore-modules</link></entry>
<entry><simplelist type='vert'><member>global</member><member>module-set</member></simplelist></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.16</member>
</simplelist>
<para>Note that when specified in global section, &cmd-ignore-modules; cmdline option does not override this, but instead appends.</para>
<para>Modules named by this option, which would be chosen by &kdesrc-build;
due to a <link linkend="conf-use-modules">use-modules</link> option, are
instead skipped entirely. Use this option when you want to build an entire
<link linkend="kde-projects-module-sets">kde-projects</link> project grouping
<emphasis>except for</emphasis> some specific modules.</para>

<para>The option value does not necessarily have to name the module directly.
Any module that has full consecutive parts of its <link
linkend="kde-projects-module-sets">&kde; projects module path</link> match one
of the option values will be ignored, so you can ignore multiple modules this
way.</para>

<para>For example, an option value of <replaceable>libs</replaceable> would
result in both <symbol>kde/kdegraphics/libs</symbol> and
<symbol>playground/libs</symbol> being excluded (though not
<symbol>kde/kdelibs</symbol> since the full part <quote>kdelibs</quote> is what
is compared).</para>

<tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip>
<para>Related command-line option: <xref linkend="cmdline-ignore-modules"/></para>
</entry>
</row>

<row id="conf-use-modules">
<entry><link linkend="conf-use-modules">use-modules</link></entry>
<entry><simplelist type='vert'><member>module-set</member></simplelist></entry>
<entry>
<simplelist type='horiz' columns='2'>
<member>Type</member><member>String</member>
<member>Available since</member><member>1.12.1</member>
</simplelist>
<para>This option allows you to easily
specify many different modules to build at the same point in <link
linkend="kdesrc-buildrc">the configuration file</link>.</para>

<para>Every identifier passed to this option is
internally converted to a &kdesrc-build; module, with a <link
linkend="conf-repository"><option>repository</option></link> option set to the
module-set's repository combined with the identifier name in order to setup the
final repository to download from. All other options that are assigned in the
module-set are also copied to the generated modules unaltered.</para>

<para>The order that modules are defined in this option is important, because
that is also the order that &kdesrc-build; will process the generated modules
when updating, building, and installing. All modules defined in the given
module-set will be handled before &kdesrc-build; moves to the next module after
the module-set.</para>

<para>If you need to change the options for a generated module, simply declare
the module again after it is defined in the module-set, and set your options
as needed. Although you will change the options set for the module this way,
the module will still be updated and built in the order set by the module-set
(i.e. you can't reorder the build sequence doing this).</para>

<important><para>The name to use for the module if you do this is simply the
name that you passed to <option>use-modules</option>, with the exception that
any <literal>.git</literal> is removed.</para></important>

<para>See <xref linkend="module-sets"/> and <link
linkend="conf-git-repository-base">git-repository-base</link> for a description
of its use and an example.</para>
</entry>
</row>

</tbody>
</tgroup>
</table>

</sect1>
