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

<chapter id="features">
<title>Script Features</title>

<sect1 id="features-overview">
<title>Feature Overview</title>

<para>
&kdesrc-build; features include:
</para>

<itemizedlist>

<listitem><para>
You can <quote>pretend</quote> to do the operations. If you pass
<option>--pretend</option> or <option>-p</option> on the
command line, the script will give a verbose description of the commands
it is about to execute, without actually executing it. However if you've never
run &kdesrc-build;, you would want to run the <command>kdesrc-build
<option><link
linkend="cmdline-metadata-only">--metadata-only</link></option></command>
command first in order for <option>--pretend</option> to work.

<tip><para>For an even more verbose description of what &kdesrc-build; is
doing, try using the <option>--debug</option> option.
</para></tip>

</para></listitem>

<listitem><para>
&kdesrc-build; allows you to checkout modules quickly. If the module you are checking out
has already been checked out previously, then &kdesrc-build; will download only commits
that are not yet on your computer.
</para>

<tip><para>There is generally no need for any special preparation to perform
the initial checkout of a Git module, as the entire Git repository must be
downloaded anyways, so it is easy for the server to determine what to
send.</para></tip>

<para>This is faster for you, and helps to ease the load on the kde.org
anonymous &git; servers.</para>
</listitem>

<listitem><para>
Another speedup is provided by starting the build process for a module as soon
as the source code for that module has been downloaded.  (Available since
version 1.6)
</para></listitem>

<listitem><para>
Excellent support for building the &Qt; library (in case the &kde; software you
are trying to build depends on a recent &Qt; not available in your
distribution).
</para></listitem>

<listitem><para>
&kdesrc-build; does not require a <acronym>GUI</acronym> present to operate. So,
you can build &kde; software without needing a graphical environment.
</para></listitem>

<listitem><para>
Supports setting default options for all modules (such as the compilation
settings or the configuration options). Such options can normally be changed
for specific modules as well.</para>

<para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add
standard flags</link> as appropriate to save you the trouble and possible
errors from typing them yourself. Nota Bene: this does not apply when a (custom)
toolchain is configured through e.g.:
<link linkend="conf-cmake-toolchain">cmake-toolchain</link>
</para></listitem>

<listitem><para>
&kdesrc-build; can checkout a specific <link linkend="using-branches">branch
or tag</link> of a module. You can also ensure that a specific <link
linkend="conf-revision">revision</link> is checked out of a module.
</para></listitem>

<listitem><para>
&kdesrc-build; can automatically switch a source directory to checkout from
a different repository, branch, or tag. This happens automatically when you
change an option that changes what the repository &url; should be, but you must
use the <link linkend="cmdline-src-only">--src-only</link> option to let
&kdesrc-build; know that it is acceptable to perform the switch.
</para></listitem>

<listitem><para>
&kdesrc-build; can <link linkend="partial-builds">checkout only portions of a
module</link>, for those situations where you only need one program from a
large module.
</para></listitem>

<listitem><para>
For developers: &kdesrc-build; will <link linkend="ssh-agent-reminder">remind
you</link> if you use git+ssh:// but <application>ssh-agent</application> is
not running, as this will lead to repeated password requests from
&ssh;.
</para></listitem>

<listitem><para>
Can <link linkend="deleting-build-dir">delete the build directory</link> of a
module after its installation to save space at the expense of future compilation
time.
</para></listitem>

<listitem><para>
The locations for the directories used by &kdesrc-build; are configurable (even
per module).
</para></listitem>

<listitem><para>
Can use &sudo;, or a different user-specified command
to <link linkend="root-installation">install modules</link> so that
&kdesrc-build; does not need to be run as the super user.
</para></listitem>

<listitem><para>
&kdesrc-build; runs <link linkend="build-priority">with reduced priority</link>
by default to allow you to still use your computer while &kdesrc-build; is
working.
</para></listitem>

<listitem><para>
Has support for using &kde;'s <link linkend="using-branches">tags and
branches</link>.
</para></listitem>

<listitem><para>
There is support for <link linkend="resuming">resuming a build</link> from a
given module. You can even <link linkend="ignoring-modules">ignore some
modules</link> temporarily for a given build.
</para></listitem>

<listitem><para>
&kdesrc-build; will show the <link linkend="build-progress">progress of your
build</link> when using &cmake;, and will always time the build
process so you know after the fact how long it took.
</para></listitem>

<listitem><para>
Comes built-in with a sane set of default options appropriate for building
a base &kde; single-user installation from the anonymous source repositories.
</para></listitem>

<listitem><para>
Tilde-expansion for your configuration options. For example, you can
specify:
<programlisting>install-dir ~/kde/usr</programlisting>
</para></listitem>

<listitem><para>
Automatically sets up a build system, with the source directory not the
same as the build directory, in order to keep the source directory
pristine.
</para></listitem>

<listitem><para>
You can specify global options to apply to every module to check out, and
you can specify options to apply to individual modules as well.
</para></listitem>

<listitem><para>
Forced full rebuilds, by running
&kdesrc-build; with the <option>--refresh-build</option> option.
</para></listitem>

<listitem><para>
You can specify various environment values to be used during the build,
including <envar>DO_NOT_COMPILE</envar>
and <envar>CXXFLAGS</envar>.
</para></listitem>

<listitem><para>
Command logging. Logs are dated and numbered so that you always have a
log of a script run. Also, a special symlink called latest is created to
always point to the most recent log entry in the log directory.
</para></listitem>

</itemizedlist>

</sect1>

&kdesrc-build-logging;

</chapter>
