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