KDE Frameworks/Getting Started/Build/For Beginners

Most of the software produced by KDE uses CMake to control how it is built and installed. If you're not used to building software that uses CMake, don't worry! This guide will teach you how.

This guide will assume you are reasonably familiar with the command line (changing directory, creating and deleting directories and files, etc).

Overview

The build process follows four basic steps:

Configuring

Determines what is available on the system, where to find it and how to use it. For example, do you have a C++ compiler? What arguments will need to be passed to it? Do you have the required libraries? Where can they be found?

Generating

Using the information gathered in the previous step, creates files that describe how to build the project.

Building

Calls the compiler, linker and other tools to create the libraries, executables and other files that are part of the "finished product". The descriptions generated in the previous step control how this is done.

Installing

Copies the files that were built (and possibly some other resources) to the right locations on the system.

There is also an optional extra step, running automated tests, which can happen either before or after installing.

CMake is used to perform the configuring and generating steps. The build description it generates is then used by another tool - typically Make on UNIX systems - to do the building and installing steps. Running the automated tests is done by CTest, which ships as part of CMake.

Prerequisites

Before you can start, you will need to install a few pieces of software.

Build environment

There is usually a fairly easy way to get the basic software you will need to build C++ programs. For example, most Linux distributions offer a "virtual package" that includes a C++ compiler, Make and other useful tools (eg: Debian calls this "build-essential"). On Windows, you might use Visual Studio, while OS X has XCode. You will need to find out how to get this for your particular system.

Git

KDE produces releases of most software, and provides archives that snapshot the product at a particular point in time. You can download these (eg: Frameworks releases are available here), extract them and build them. However, if you want to contribute back to the project, you will need to get the latest development version, and for that you will need Git. If you are not familiar with version control systems like Git, check out About Version Control from the Pro Git book. On Windows, you might want to try TortoiseGit, although we'll be concentrating on how to do it on the command line.

CMake

On Linux systems, you can usually get this through your package manager. Otherwise, you will need to download and install it. You will need at least version 2.8.12.

Qt

Almost all software produced by KDE is built on top of Qt, so it would be sensible to get hold of it now. Again, you can get it via your package manager on Linux, or download it yourself. Watch out, though! While a lot of KDE software is using Qt 5 (you'll probably want at least 5.4 if possible), some is still using Qt 4 (specifically 4.8). These are not compatible. The general rule is: software using KDE Frameworks needs Qt 5, software using kdelibs needs Qt 4.

Note

On most Linux distributions, packages come in several parts; specifically, the core package can be installed without the "development files" or the debugging information. When you are building software, you need to make sure the development packages of any libraries are installed (and you may want the debugging ones as well). For example, in addition to the "qtbase5" package, you will also want a package called something like "qtbase5-dev" or "qtbase5-devel"

Getting the source

First, find the project you want to build on KDE QuickGit. We're going to start with Extra CMake Modules, mostly because it has no dependencies (other than CMake), and so you can get going right away.

Near the top of the page for your project, you'll find a line that starts "clone url". This is what you need to pass to Git to get a copy of the source. For Extra CMake Modules, this is git://anongit.kde.org/extra-cmake-modules.git.

You now need to tell Git to clone this repository, so that you have a copy of it on your computer. From a terminal, go to a directory where you want to do your development, and run

git clone git://anongit.kde.org/extra-cmake-modules.git

This will produce a directory called extra-cmake-modules, which contains the latest (unreleased) source code for the Extra CMake Modules project. You can use Git to get different versions of the source code, such as previous releases, as well as to make changes you can submit back to the project. If you want to get into this, you can read the Pro Git book.

Running CMake

TODO: examples, etc.

Building

make (and other systems?)

Installing

make install (and other systems?)

A Simpler Way

TODO: link to kdesrc-build instructions