<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
>qtdir ~/kdesrc/build/qt</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
>QTDIR</envar
>, <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>
