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

<chapter id="getting-started">
<title>Getting Started</title>

<para>
In this chapter, we show how to use the &kdesrc-build; to checkout modules from
the &kde; repository and build them. We also provide a basic explanation of the
&kde; source code structure and the steps you have to perform before running
the script.
</para>

<para>
All topics present in this chapter are covered with even more detail in the
<ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source">
Build from Source</ulink> article, at the
<ulink url="https://community.kde.org/">&kde; Community Wiki</ulink>.
If you are compiling &kde; for the first time, it is a good idea to read
it, or consult it as a reference source. You will find detailed information
about packaging tools and requirements, common compilation pitfalls and
strategies and information about running your new &kde; installation.
</para>

<sect1 id="before-building">
<title>Preparing the System to Build &kde;</title>

<sect2 id="before-building-users">
<title>Setup a new user account</title>

<para>
It is recommended that you use a different user account to build, install,
and run your &kde; software from, since less permissions are required, and
to avoid interfering with your distribution's packages.
If you already have &kde; packages installed, the best choice
would be to create a different (dedicated) user to build and run the new &kde;.
</para>

<tip><para>Leaving your system &kde; untouched also allows you to have an
emergency fallback in case a coding mistake causes your latest software build
to be unusable.
</para></tip>

<para>
You can do also setup to install to a system-wide directory (&eg; <filename
class="directory">/usr/src/local</filename>) if you wish. This document
does not cover this installation type, since we assume you know what you are doing.
</para>

</sect2>
<sect2 id="before-building-preparation">
<title>Ensure your system is ready to build &kde; software</title>

<para>Before using the &kdesrc-build; script (or any other building
strategy) you must install the development tools and libraries needed for &kde;.
The nearly complete list of required tools can be found from
the <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source#Install_required_devel_packages">&kde;
Community Wiki Build Requirements</ulink> page.
</para>

<para>Here is a list of some of the things you will need:</para>
<itemizedlist>

<listitem><para>You will need &cmake;, this software is what &kde; uses to handle
build-time configuration of the source code and generation of the specific build
commands for your system.  The required version will vary
depending on what versions of &kde; software you are building (see TechBase for
specifics), but with modern distributions the &cmake; included with your distribution
should be quite sufficient.
</para></listitem>

<listitem><para>You must also install the source control clients needed to checkout
the &kde; source code. This means you need at least the following:</para>

<itemizedlist>
<listitem><para>The <ulink url="https://git-scm.com/">Git
source control manager</ulink>, which is used for all &kde; <ulink
url=" https://commits.kde.org/">source code</ulink></para></listitem>

<listitem><para>Although it is not required, the <ulink
url="http://bazaar.canonical.com/">Bazaar</ulink> source control manager is
used for a single module (libdbusmenu-qt) that is required for the &kde;
libraries. Most users can install this library through their distribution
packages but &kdesrc-build; supports building it as well if you desire. But to
build libdbusmenu-qt, you must have Bazaar installed.</para></listitem>
</itemizedlist></listitem>

<listitem><para>The Perl scripting language is required for &kdesrc-build;, some &kde;
repositories, and &Qt; (if you build that from source).</para>

<para>The Perl that comes with your distribution should be suitable (it needs to be at
least Perl 5.14), but you will also need some additional modules (&kdesrc-build;
will warn if they are not present):</para>

<itemizedlist>
    <listitem><para>IO::Socket::SSL</para></listitem>
    <listitem><para>JSON::PP or JSON::XS</para></listitem>
    <listitem><para>YAML::PP, YAML::XS, or YAML::Syck</para></listitem>
</itemizedlist>
</listitem>

<listitem><para>You will need a full C++ development environment (compiler, standard library, runtime,
and any required development packages).  The minimum required versions vary based on the &kde; module:
the &kde; Frameworks 5 collection supports the oldest compilers, while &kde; Plasma 5 and &kde; Applications
tend to require more recent compilers.</para>
<para>The GCC 4.8 or Clang 4 compilers are the minimum recommended.  Many distributions support easily
installing these tools using a <quote>build-essentials</quote> package, an option to install
"build dependencies" with &Qt;, or similar features.  The KDE Community Wiki has a page <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/Install_the_dependencies">tracking
recommended packages for major distributions</ulink>.
</para>
</listitem>

<listitem><para>You will need a build tool that actually performs the
compilation steps (as generated by &cmake;). GNU Make is recommended and should
be available through your package manager. &cmake; does support others options, such
as the &ninja; build tool, which can be used by &kdesrc-build; using the
<link linkend="conf-custom-build-command">custom-build-command</link> configuration file
option.
</para></listitem>

<listitem><para>Finally, you will need the appropriate &Qt; libraries (including development packages)
for the version of &kde; software you are building.  &kdesrc-build; does not officially support building &Qt; 5 (the current major version), so it is recommended to use your distribution's development packages or to
see the KDE Community wiki page on <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/OwnQt5">self-building Qt 5</ulink>.
</para></listitem>
</itemizedlist>

<note><para>Most operating system distributions include a method of easily
installing required development tools. Consult the Community Wiki page <ulink
url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source#Install_required_devel_packages"
>Required devel packages</ulink> to see
if these instructions are already available.</para></note>

<important><para>
Some of these packages are divided into libraries (or programs or utilities),
and development packages. You will need at least the program or library
<emphasis>and</emphasis> its development package.
</para></important>

</sect2>

<sect2 id="before-building-prepare-script">
<title>Setup &kdesrc-build;</title>

<sect3 id="get-kdesrc-build">
<title>Install &kdesrc-build;</title>
<para>
The &kde; developers make frequent changes to &kdesrc-build; to keep it in
sync with advances in &kde; development, including improvements to the
recommended &kdesrc-build; configuration, added modules, improving &cmake;
flags, &etc;</para>

<para>Because of this, we recommend obtaining &kdesrc-build; directly from its
source repository and then periodically updating it.</para>

<para>You can obtain &kdesrc-build; from its source repository by running:</para>
<programlisting>
<prompt>$ </prompt><userinput><command>git <option>clone</option> <option>https://invent.kde.org/sdk/kdesrc-build.git</option> <option><filename class="directory"><replaceable>~/kdesrc-build</replaceable></filename></option></command></userinput>
</programlisting>

<para>Replace <option><replaceable>~/kdesrc-build</replaceable></option> with
the directory you would like to install to.
</para>

<para>You can update &kdesrc-build; later by running:</para>
<programlisting>
<prompt>$ </prompt><userinput><command>cd <option><filename class="directory"><replaceable>~/kdesrc-build</replaceable></filename></option></command></userinput>
<prompt>$ </prompt><userinput><command>git <option>pull</option></command></userinput>
</programlisting>

<tip><para>We recommend adding the &kdesrc-build; installation directory to
your <envar>PATH</envar> environment variable, so that you can run &kdesrc-build;
without having to fully specify its path every time.</para></tip>
</sect3>

<sect3 id="setup-rcfile">
<title>Prepare the configuration file</title>

<para>&kdesrc-build; uses a <link linkend="configure-data">configuration file</link>
to control which modules are built, where they are installed to, etc.
This file is located at <filename>~/.config/kdesrc-buildrc</filename>
(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if
<envar>$XDG_CONFIG_HOME</envar> is set).</para>

<para>You can use <application>kdesrc-build --generate-config</application> in order to prepare a simple
kdesrc-build configuration. You can then edit the
<filename>~/.config/kdesrc-buildrc</filename> configuration file to make
any changes you see fit.</para>

<sect4 id="setup-rcfile-manually">
<title>Manual setup of configuration file</title>

<para>You can also setup your configuration file manually, by copying the
included sample configuration file <filename>kdesrc-buildrc-kf5-sample</filename>
to <filename>~/.config/kdesrc-buildrc</filename> and then editing the file.
<xref linkend="kdesrc-buildrc"/> will be a useful reference for this, especially
its <link linkend="conf-options-table">table of configuration options</link>.
</para>

<para>&kdesrc-build; contains many recommended configuration files to support
&kde; Frameworks 5, &plasma; 5, and other &kde; applications. See
<xref linkend="kdesrc-buildrc-including"/> for information on how to use other
configuration files from your own <filename>kdesrc-buildrc</filename>.
</para>

<para>You can find more information about the syntax of the <link
linkend="configure-data">configuration file</link> in <xref
linkend="configure-data" /> and in <xref linkend="kdesrc-buildrc" />.
</para>
</sect4>
</sect3>
</sect2>
</sect1>

&configure-data;

&building-and-troubleshooting;

&building-specific-modules;

&environment;

&kde-modules-and-selection;

&quick-start-conclusion;

</chapter>
