<!--
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="kdesrc-build-logging">
<title>&kdesrc-build;'s build logging</title>

<sect2 id="logging-overview">
<title>Logging overview</title>

<para>Logging is a &kdesrc-build; feature whereby the output from every command
that &kdesrc-build; runs is saved to a file for examination later, if
necessary. This is done because it is often necessary to have the output of
these programs when there is a build failure, because there are so many
reasons why a build can fail in the first place.</para>

<sect3 id="log-directory-layout">
<title>Logging directory layout</title>

<para>The logs are always stored under the log directory. The destination of
the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link>
option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
option. The in rest of this section, this value will be referred to as
<symbol>${log-dir}</symbol>).</para>

<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every
time that &kdesrc-build; was run. Each directory is named with the date, and
the run number. For instance, the second time that &kdesrc-build; is run on
May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>,
where the 2004-05-26 is for the date, and the -02 is the run number.</para>

<para>For your convenience, &kdesrc-build; will also create a link to the
logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
</para>

<para>Now, each directory for a &kdesrc-build; run will itself contain a set of
directories, one for every &kde; module that &kdesrc-build; tries to build. Also,
a file called <filename>build-status</filename> will be contained in the directory,
which will allow you to determine which modules built and which failed.</para>

<note><para>
If a module itself has a submodule (such as extragear/multimedia,
playground/utils, or KDE/kdelibs), then there would actually be a matching
layout in the log directory. For example, the logs for KDE/kdelibs after the
last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
</para></note>

<para>In each module log directory, you will find a set of files for each
operation that &kdesrc-build; performs. If &kdesrc-build; updates a module,
you may see filenames such as <filename>git-checkout-update.log</filename> (for a
module checkout or when updating a module
that has already been checked out). If the <command>configure</command>
command was run, then you would expect to see a <filename>configure.log</filename>
in that directory.</para>

<para>If an error occurred, you should be able to see an explanation of why in
one of the files. To help you determine which file contains the error,
&kdesrc-build; will create a link from the file containing the error (such as
<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para>

<para>The upshot to all of this is that to see why a module failed to build
after your last &kdesrc-build;, the file you should look at first is
<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>.
</para>

<tip><para>If the file <filename>error.log</filename> is empty (especially after
an installation), then perhaps there was no error. Some of the tools used by
the &kde; build system will sometimes mistakenly report an error when there was
none.</para>

<para>Also, some commands will evade &kdesrc-build;'s output redirection and
bypass the log file in certain circumstances (normally when performing the
first &git; checkout), and the error output in that case is not in the log file
but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para>
</tip>

</sect3>
</sect2>
</sect1>
