Guidelines and HOWTOs/CMake/Frameworks: Difference between revisions

From KDE Community Wiki
*>Pippin
No edit summary
No edit summary
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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.
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.


This will assume a basic familiarity with CMake; if you are completely unfamiliar with CMake, you should check out the [[Guidelines HOWTOs/CMake/FirstProject|first CMake project]] tutorial.
{{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:
We start off the <tt>CMakeLists.txt</tt> file with the lines any CMake project needs:


[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:cmake_minimum_required cmake_minimum_required](VERSION 2.8.12)
{{Input|1=
[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: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.
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.


[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:find_package find_package](KF5Archive REQUIRED)
{{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 this case.
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:
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:


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


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


[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:target_link_libraries target_link_libraries](
{{Input|1=
    tutorial
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:target_link_libraries target_link_libraries](
    PRIVATE
    tutorial
        KF5::Archive
    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.


This will not only link 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:
To actually build this project, we'll need some C++ code to compile, so create a <tt>main.cpp</tt> file with the following:


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


For reference, the entire <tt>CMakeLists.txt</tt> file is:
For reference, the entire <tt>CMakeLists.txt</tt> file is:


[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:cmake_minimum_required cmake_minimum_required](VERSION 2.8.12)
{{Input|1=
[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: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:find_package find_package](KF5Archive REQUIRED)


[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:set set](tutorial_SRCS
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:set set](tutorial_SRCS
    main.cpp
    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: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](
[http://www.cmake.org/cmake/help/v2.8.12/cmake.html#command:target_link_libraries target_link_libraries](
    tutorial
    tutorial
    PRIVATE
    PRIVATE
        KF5::Archive
        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.
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.

Latest revision as of 16:32, 10 March 2016

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.

Note

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 2.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 a previous version), it should succeed.