View source for Guidelines and HOWTOs/CMake/Frameworks

This tutorial will show you how to use a [http://api.kde.org/frameworks-api/frameworks5-apidocs/ 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.

{{Note|This will assume a basic familiarity with CMake; if you are completely unfamiliar with CMake, you should check out the [[Guidelines and HOWTOs/CMake/FirstProject|first CMake project]] tutorial.}}

==Tutorial==

We start off the <tt>CMakeLists.txt</tt> file with the lines any CMake project needs:

{{Input|1=
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:cmake_minimum_required cmake_minimum_required](VERSION 2.8.12)
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:project project](UsingFrameworksTutorial)
}}

Next, we search for the framework we want to use. We'll pick [http://api.kde.org/frameworks-api/frameworks5-apidocs/karchive/html/index.html KArchive], a framework for dealing with compressed file formats.

{{Input|1=
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package 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:

{{Input|1=
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:set set](tutorial_SRCS
    main.cpp
)
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:add_executable add_executable](tutorial ${tutorial_SRCS})
}}

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

{{Input|1=
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:target_link_libraries 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 <tt>main.cpp</tt> file with the following:

{{Input|1=
#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 <tt>CMakeLists.txt</tt> file is:

{{Input|1=
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:cmake_minimum_required cmake_minimum_required](VERSION 2.8.12)
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:project project](UsingFrameworksTutorial)

[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package find_package](KF5Archive REQUIRED)

[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:set set](tutorial_SRCS
    main.cpp
)
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:add_executable add_executable](tutorial ${tutorial_SRCS})

[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:target_link_libraries target_link_libraries](
    tutorial
    PRIVATE
        KF5::Archive
)
}}

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

==Next steps==

Try changing the [http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package 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 a previous version), it should succeed.