Git commit 93412946d1e2df4374d280350631da819e5f0caf by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'.
doc: kdesrc-build-logging - separate docbook M +1 -78 doc/features.docbook M +1 -0 doc/index.docbook A +78 -0 doc/kdesrc-build-logging.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/93412946d1e2df4374d280350631da819e5f0caf diff --git a/doc/features.docbook b/doc/features.docbook index 2a911dc3..723cb706 100644 --- a/doc/features.docbook +++ b/doc/features.docbook @@ -180,83 +180,6 @@ always point to the most recent log entry in the log directory. </sect1> -<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> +&kdesrc-build-logging; </chapter> diff --git a/doc/index.docbook b/doc/index.docbook index b7801670..78e55044 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -85,6 +85,7 @@ <!ENTITY introduction SYSTEM "introduction.docbook"> <!ENTITY kde-cmake SYSTEM "kde-cmake.docbook"> <!ENTITY kde-modules-and-selection SYSTEM "kde-modules-and-selection.docbook"> + <!ENTITY kdesrc-build-logging SYSTEM "kdesrc-build-logging.docbook"> ]> <book id="kdesrc-build" lang="&language;"> diff --git a/doc/kdesrc-build-logging.docbook b/doc/kdesrc-build-logging.docbook new file mode 100644 index 00000000..91f751ac --- /dev/null +++ b/doc/kdesrc-build-logging.docbook @@ -0,0 +1,78 @@ +<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>
