Guidelines and HOWTOs/CMake/Frameworks

This tutorial will show you how to use a KDE Framework in a CMake-based project. It will introduce you to searching for external packages in CMake, and linking to libraries provided by those packages.

This will assume a basic familiarity with CMake; if you are completely unfamiliar with CMake, you should check out the first CMake project tutorial.

Tutorial

We start off the CMakeLists.txt file with the lines any CMake project needs:

cmake_minimum_required(VERSION 2.8.12)
project(UsingFrameworksTutorial)

Next, we search for the framework we want to use. We'll pick KArchive, a framework for dealing with compressed file formats.

find_package(KF5Archive REQUIRED)

Here, KF5Archive is the name of the package. The exact result of this call will depend on the package, but at a minimum, we would expect the variable KF5Archive_FOUND to be set to TRUE if the package was found, and FALSE otherwise. Because we passed REQUIRED as an argument, CMake will exit with an error message if the package was not found.

In the case of KF5Archive, we will get an imported target named KF5::Archive. Imported targets refer to libraries and executables external to the project, and include all the information you need to use them. So if you have an exectuable:

set(tutorial_SRCS
    main.cpp
)
add_executable(tutorial ${tutorial_SRCS})

you can start using KArchive just by linking against KF5::Archive:

target_link_libraries(
    tutorial
    PRIVATE
        KF5::Archive
)

This will not only link the tutorial target against the KArchive library, it will set up the include paths properly as well. Don't worry about the PRIVATE keyword for now - it's only important when you are compiling a library.

Building

To actually build this project, we'll need some C++ code to compile, so create a main.cpp file with the following:

#include <QCoreApplication>
#include <KCompressionDevice>
int main(int argc, char**argv) {
     QCoreApplication qapp(argc, argv);
    KCompressionDevice dev("test.gz", KCompressionDevice::GZip);
    dev.open(QIODevice::WriteOnly);
    dev.write("Hello world!\n");
    dev.close();
    return 0;
}

For reference, the entire CMakeLists.txt file is:

cmake_minimum_required(VERSION .8.12)
project(UsingFrameworksTutorial)

find_package(KF5Archive REQUIRED)

set(tutorial_SRCS
    main.cpp
)
add_executable(tutorial ${tutorial_SRCS})

target_link_libraries(
    tutorial
    PRIVATE
        KF5::Archive
)

Now you can build and run the test application, which should create a file named test.gz in your current directory.

Next steps

Try changing the find_package call to only look for KF5Archive versions greater than or equal to 5.10 (or some other version). You need to add the version number as an argument after the package name. If you set it to a number larger than the version you have installed, it should fail. If you set it to the version you have installed or less, it should succeed.