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