<!--
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="advanced-features">
<title>Advanced features</title>

<sect2 id="partial-builds">
<title>Partially building a module</title>
<para>It is possible to build only pieces from a single &kde; module. For
example, you may want to compile only one program from a module. &kdesrc-build;
has features to make this easy. There are several complementing ways to
do this.
</para>

<sect3 id="not-compiling">
<title>Removing directories from a build</title>
<para>It is possible to download an entire repository
but have the build system leave out a few directories when it does
the build. This requires that the module uses &cmake; and that the
module's build system allows the directory to remove to be
optional.
</para>

<para>This is controlled with the &do-not-compile; option.</para>

<important><para>
This option requires at least that the
build system for the module is reconfigured after changing
it. This is done using the <userinput><command>kdesrc-build</command>
<option>&cmd-reconfigure;</option>
<option><replaceable>module</replaceable></option></userinput> command.
</para></important>

<informalexample>
<para>To remove the <filename class="directory">python</filename> directory
from the kdebindings build process:</para>

<screen>
module <replaceable>kdebindings</replaceable>
  &do-not-compile; <replaceable>python</replaceable>
end module
</screen>

</informalexample>

<note><para>This function depends on some standard conventions used in most
&kde; modules. Therefore it may not work for all programs.</para></note>

</sect3>

</sect2>

<sect2 id="using-branches">
<title>Branching and tagging support for &kdesrc-build;</title>

<sect3 id="branches-and-tags">
<title>What are branches and tags?</title>

<para>&git; supports managing the history of the &kde; source code. &kde;
uses this support to create branches for development, and to tag the repository
every so often with a new version release.
</para>

<para>For example, the &kmail; developers may be working on a new feature in
a different branch in order to avoid breaking the version being used by most
developers. This branch has development ongoing inside it, even while the
main branch (called master) may have development going on inside of it.
</para>

<para>A tag, on the other hand, is a specified point in the source code repository
at a position in time. This is used by the &kde; administration team to mark
off a version of code suitable for release and still allow the developers to
work on the code.
</para>

</sect3>

<sect3 id="branch-support">
<title>How to use branches and tags</title>

<para>Support for branches and tags is handled by a set of options, which
range from a generic request for a version, to a specific &url; to download
for advanced users.
</para>

<para>The easiest method is to use the &branch; and &tag; options. You simply
use the option along with the name of the desired branch or tag for a module,
and &kdesrc-build; will try to determine the appropriate location within the
&kde; repository to download from. For most &kde; modules this works very
well.</para>

<informalexample>
<para>To download kdelibs from &kde; 4.6 (which is simply known as the 4.6 branch):
</para>

<screen>
module kdelibs
  branch <replaceable>4.6</replaceable>
  # other options...
end module
</screen>

<para>Or, to download kdemultimedia as it was released with &kde; 4.6.1:</para>

<screen>
module kdemultimedia
  tag <replaceable>4.6.1</replaceable>
  # other options...
end module
</screen>

</informalexample>

<tip><para>You can specify a global branch value. But if you do so, do not forget
to specify a different branch for modules that should not use the global branch!
</para></tip>
</sect3>

</sect2>

<sect2 id="stopping-the-build-early">
<title>Stopping the build early</title>

<sect3 id="the-build-continues">
<title>The build normally continues even if failures occur</title>

<para>&kdesrc-build; normally will update, build and install all modules
in the specified list of modules to build, even if a module fails to build.
This is usually a convenience to allow you to update software packages even
if a simple mistake is made in one of the source repositories during
development that causes the build to break.
</para>

<para>
However you may wish for &kdesrc-build; to stop what it is doing once a
module fails to build and install. This can help save you time that will be
wasted trying to make progress when modules remaining in the build list will
not be able to successfully build either, especially if you have not ever
successfully built the modules in the list.
</para>

</sect3>

<sect3 id="stop-on-failure-stops-early">
<title>Not stopping early with --no-stop-on-failure</title>

<para>
The primary method to do this is to use the
<link linkend="cmdline-stop-on-failure">--no-stop-on-failure</link>
command line option when you run &kdesrc-build;.
</para>

<para>This option can also be set in the
<link linkend="conf-stop-on-failure">configuration file</link> to make
it the normal mode of operation.
</para>

<para>It is also possible to tell &kdesrc-build; at runtime to stop building
<emphasis>after</emphasis> completing the current module it is working on.
This is as opposed to interrupting &kdesrc-build; using a command like
<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>, which interrupts
&kdesrc-build; immediately, losing the progress of the current module.
</para>

<important><para>Interrupting &kdesrc-build; during a module install when
the <link linkend="conf-use-clean-install">use-clean-install</link> option
is enabled will mean that the interrupted module will be unavailable until
&kdesrc-build; is able to successfully build the module!</para>

<para>If you need to interrupt &kdesrc-build; without permitting a graceful shutdown
in this situation, at least try to avoid doing this while &kdesrc-build; is
installing a module.</para>
</important>

</sect3>

<sect3 id="stopping-early-without-stop-on-failure">
<title>Stopping &kdesrc-build; gracefully when stop-on-failure is false</title>

<para>As mentioned above, it is possible to cause &kdesrc-build; to gracefully
shutdown early once it has completed the module it is currently working on.
To do this, you need to send the POSIX <literal>HUP</literal> signal to &kdesrc-build;
</para>

<para>You can do this with a command such as <command>pkill</command> (on &Linux; systems) as follows:</para>

<programlisting>
<prompt>$ </prompt><userinput><command>pkill <option>-HUP</option> kdesrc-build</command></userinput>
</programlisting>

<para>If done successfully, you will see a message in the &kdesrc-build; output similar
to:</para>

<programlisting>
[ build ] recv SIGHUP, will end after this module
</programlisting>

<note>
<para>&kdesrc-build; may show this message multiple times depending on the
number of individual &kdesrc-build; processes that are active. This is
normal and not an indication of an error.</para>
</note>

<para>
Once &kdesrc-build; has acknowledged the signal, it will stop processing
after the current module is built and installed. If &kdesrc-build; is still
updating source code when the request is received, &kdesrc-build; will stop
after the module source code update is complete. Once both the update and build
processes have stopped early, &kdesrc-build; will print its partial results
and exit.
</para>

</sect3>

</sect2>

<sect2 id="building-successfully">
<title>How &kdesrc-build; tries to ensure a successful build</title>

<sect3 id="automatic-rebuilds">
<title>Automatic rebuilds</title>

<para>&kdesrc-build; used to include features to automatically attempt to
rebuild the module after a failure (as sometimes this re-attempt would work,
due to bugs in the build system at that time). Thanks to switching to &cmake;
the build system no longer suffers from these bugs, and so &kdesrc-build; will
not try to build a module more than once. There are situations where
&kdesrc-build; will automatically take action though:</para>

<itemizedlist>

<listitem><para>If you change <link linkend="conf-configure-flags">configure-flags</link>
or <link linkend="conf-cmake-options">cmake-options</link> for a module, then
&kdesrc-build; will detect that and automatically re-run configure or cmake
for that module.</para></listitem>

<listitem><para>If the buildsystem does not exist (even if &kdesrc-build; did
not delete it) then &kdesrc-build; will automatically re-create it. This is
useful to allow for performing a full <link
linkend="cmdline-refresh-build">--refresh-build</link> for a specific module
without having that performed on other modules.</para></listitem>

</itemizedlist>

</sect3>

<sect3 id="manual-rebuilds">
<title>Manually rebuilding a module</title>
<para>If you make a change to a module's option settings, or the module's
source code changes in a way &kdesrc-build; does not recognize, you may need to
manually rebuild the module.</para>

<para>You can do this by simply running <userinput><command>kdesrc-build</command>
 <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>.
</para>

<para>If you would like to have &kdesrc-build; automatically rebuild the module
during the next normal build update instead, you can create a special file.
Every module has a build directory. If you create a file called <filename>.refresh-me</filename>
in the build directory for a module, &kdesrc-build; will rebuild the module
next time the build process occurs, even if it would normally perform the
faster incremental build.</para>

<tip>
<para>By default, the build directory is <filename class="directory">~/kde/build/<replaceable>module</replaceable>/</filename>.
If you change the setting of the &build-dir; option, then use that instead of
<filename class="directory">~/kde/build</filename>.</para>
</tip>

<informalexample>
<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>kdelibs</replaceable>:</para>
<screen>
<prompt>&percnt;</prompt> <userinput><command>touch</command> <filename>~/kdesrc/build/<replaceable>kdelibs</replaceable>/.refresh-me</filename></userinput>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command></userinput>
</screen>
</informalexample>
</sect3>

</sect2>

<sect2 id="changing-environment">
<title>Changing environment variable settings</title>
<para>Normally &kdesrc-build; uses the environment that is present when
starting up when running programs to perform updates and builds. This is useful
for when you are running &kdesrc-build; from the command line.</para>

<para>However, you may want to change the setting for environment variables
that &kdesrc-build; does not provide an option for directly. (For instance,
to setup any required environment variables when running &kdesrc-build; on
a timer such as &cron;) This is possible with the &set-env; option.</para>

<para>Unlike most options, it can be set more than once, and it accepts two
entries, separated by a space. The first one is the name of the environment
variable to set, and the remainder of the line is the value.</para>

<informalexample>
<para>Set <userinput><envar>DISTRO</envar>=<replaceable>BSD</replaceable></userinput>
for all modules:</para>
<screen>
global
  set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable>
end global
</screen>
</informalexample>

</sect2>

<sect2 id="resuming">
<title>Resuming builds</title>

<sect3 id="resuming-failed">
<title>Resuming a failed or canceled build</title>

<para>You can tell &kdesrc-build; to start building from a different module
than it normally would. This can be useful when a set of modules failed, or
if you canceled a build run in the middle. You can control this using the
&cmd-resume-from; option and the &cmd-resume-after; option.</para>

<note><para>Older versions of &kdesrc-build; would skip the source update when
resuming a build. This is no longer done by default, but you can always use
the <option>--no-src</option> command line option
to skip the source update.</para></note>

<informalexample>
<para>Resuming the build starting from kdebase:</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput>
</screen>
</informalexample>

<informalexample>
<para>Resuming the build starting after kdebase (in case you manually fixed
the issue and installed the module yourself):</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--resume-after=<replaceable>kdebase</replaceable></option></userinput>
</screen>
</informalexample>

<para>If the last &kdesrc-build; build ended with a build failure, you can also
use the <link linkend="cmdline-resume">--resume</link> command line option,
which resumes the last build starting at the module that failed. The source and
metadata updates are skipped as well (but if you need these, it's generally
better to use <link linkend="cmdline-resume-from">--resume-from</link>
instead).</para>


</sect3>

<sect3 id="ignoring-modules">
<title>Ignoring modules in a build</title>

<para>Similar to the way you can <link linkend="resuming-failed">resume the
build from a module</link>, you can instead choose to update and build everything
normally, but ignore a set of modules.</para>

<para>You can do this using the &cmd-ignore-modules; option. This option tells
&kdesrc-build; to ignore all the modules on the command line when
performing the update and build.</para>

<informalexample>
<para>Ignoring extragear/multimedia and kdereview during a full run:</para>
<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdereview</replaceable></userinput>
</screen>
</informalexample>

</sect3>
</sect2>

<sect2 id="changing-env-from-cmd-line">
<title>Changing options from the command line</title>

<sect3 id="changing-global-opts">
<title>Changing global options</title>
<para>You can change the setting of options read from the <link linkend="configure-data">configuration file</link> directly
from the command line. This change will override the configuration file
setting, but is only temporary. It only takes effect as long as it is still
present on the command line.</para>

<para>&kdesrc-build; allows you to change options named like <replaceable>option-name</replaceable>
by passing an argument on the command line in the form <userinput><option>--<replaceable>option-name</replaceable>=value</option></userinput>.
&kdesrc-build; will recognize whether it does not know what the option is, and search
for the name in its list of option names. If it does not recognize the name, it
will warn you, otherwise it will remember the value you set it to and override
any setting from the configuration file.</para>

<informalexample>
<para>Setting the &source-dir; option to <filename>/dev/null</filename> for
testing:</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput>
</screen>

</informalexample>

</sect3>

<sect3 id="changing-module-opts">
<title>Changing module options</title>
<para>It is also possible to change options only for a specific module. The
syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>.
</para>

<para>This change overrides any duplicate setting for the module found in the
<link linkend="configure-data">configuration file</link>, and applies only while the option is passed on the command line.</para>

<informalexample>
<para>Using a different build directory for the kdeedu module:</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput>
</screen>

</informalexample>

</sect3>

</sect2>

</sect1>
