<!--
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="building-and-troubleshooting">
<title>Using the &kdesrc-build; script</title>
<para>With the configuration data established, now you are ready to run the
script.  Even if you still have some tweaking or other reading you wish to do,
it is a good idea to at least load the &kde; project metadata.</para>

<sect2 id="loading-kdesrc-build-metadata">
<title>Loading project metadata</title>

<para>
From a terminal window, log in to the user you are using to compile &kde; software and
execute the script:
</para>
<screen>
    <prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command> <option>--metadata-only</option></userinput>
</screen>

<para>This command will setup the source directory and connect to the KDE &git;
repositories to download the database of &kde; git repositories, and the
database of dependency metadata, without making any further changes.  It is
useful to run this separately as this metadata is useful for other
&kdesrc-build; commands. </para>

</sect2>

<sect2 id="pretend-mode">
<title>Previewing what will happen when kdesrc-build runs</title>

<para>With the project metadata installed, it is possible to preview what
&kdesrc-build; will do when launched.  This can be done with the <option><link
linkend="cmdline-pretend">--pretend</link></option> command line option.</para>

<screen>
    <prompt>&percnt; </prompt><command>./kdesrc-build</command> <option>--pretend</option>
</screen>

<para>You should see a message saying that some packages were successfully built (although
    nothing was actually built).  If there were no significant problems shown, you can proceed
    to actually running the script.</para>

<screen>
    <prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command></userinput>
</screen>

<para>This command will download the appropriate source code, build and install each module in order. Afterwards, you should see output similar to that in <xref
linkend="example-build-sequence"/>:</para>

<example id="example-build-sequence">
<title>Example output of a kdesrc-build run</title>
<screen>
<prompt>&percnt;</prompt> <userinput><command>kdesrc-build</command></userinput>
Updating kde-build-metadata (to branch master)
Updating sysadmin-repo-metadata (to branch master)

Building libdbusmenu-qt (1/200)
        No changes to libdbusmenu-qt source, proceeding to build.
        Compiling... succeeded (after 0 seconds)
        Installing.. succeeded (after 0 seconds)

Building taglib (2/200)
        Updating taglib (to branch master)
        Source update complete for taglib: 68 files affected.
        Compiling... succeeded (after 0 seconds)
        Installing.. succeeded (after 0 seconds)

Building extra-cmake-modules from &lt;module-set at line 32&gt; (3/200)
        Updating extra-cmake-modules (to branch master)
        Source update complete for extra-cmake-modules: 2 files affected.
        Compiling... succeeded (after 0 seconds)
        Installing.. succeeded (after 0 seconds)

        ...

Building kdevelop from kdev (200/200)
        Updating kdevelop (to branch master)
        Source update complete for kdevelop: 29 files affected.
        Compiling... succeeded (after 1 minute, and 34 seconds)
        Installing.. succeeded (after 2 seconds)

&lt;&lt;&lt;  PACKAGES SUCCESSFULLY BUILT  &gt;&gt;&gt;
Built 200 modules

Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07
</screen>
</example>
</sect2>

<sect2 id="fixing-build-failures">
<title>Resolving build failures</title>

<para>
Depending on how many modules you are downloading, it is possible that
&kdesrc-build; will not succeed the first time you compile &kde; software.
Do not despair!
</para>

<para>&kdesrc-build; logs the output of every command it runs. By default,
the log files are kept in <filename class="directory">~/kdesrc/log</filename>. To see what
the caused an error for a module in the last &kdesrc-build; command, usually
it is sufficient to look at <filename class="directory">~/kdesrc/log/latest/<replaceable>module-name</replaceable>/error.log</filename>.</para>

<tip><para>Perhaps the easiest way to find out what error caused a module to
fail to build is to search backward with a case-insensitive search, starting
from the end of the file looking for the word <literal>error</literal>.  Once
that is found, scroll up to make sure there are no other error messages nearby.
The first error message in a group is usually the underlying
problem.</para></tip>

<para>In that file, you will see the error that caused the build to fail for
that module. If the file says (at the bottom) that you are missing some
packages, try installing the package (including any appropriate -dev packages)
before trying to build that module again. Make sure that when you run
&kdesrc-build; again to pass the <link
linkend="cmdline-reconfigure">--reconfigure</link> option so that
&kdesrc-build; forces the module to check for the missing packages
again.</para>

<para>Or, if the error appears to be a build error (such as a syntax error,
<quote>incorrect prototype</quote>, <quote>unknown type</quote>, or similar)
then it is probably an error with the &kde; source, which will hopefully be
resolved within a few days. If it is not resolved within that time, feel free
to mail the <email>kde-devel@kde.org</email> mailing list (subscription may be
required first) in order to report the build failure.</para>

<para>You can find more common examples of things that can go wrong and their
solutions, as well as general tips and strategies to build &kde; software in the
<ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source">
Build from Source</ulink>.
</para>

<para>On the other hand, assuming everything went well, you should have a new
&kde; install on your computer, and now it is simply a matter of running
it, described next in <xref linkend="environment"/>.</para>

<note><para>For more information about &kdesrc-build;'s logging features,
please see <xref linkend="kdesrc-build-logging"/>.</para></note>
</sect2>

</sect1>
