Guidelines and HOWTOs/CMake: Difference between revisions

From KDE Community Wiki
(https://develop.kde.org/docs/getting-started/building/cmake-build/)
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
See https://develop.kde.org/docs/getting-started/building/cmake-build
Most KDE software uses [http://www.cmake.org CMake] as a buildsystem. This page is the starting point for CMake-related documentation for KDE software.
Most KDE software uses [http://www.cmake.org CMake] as a buildsystem. This page is the starting point for CMake-related documentation for KDE software.
You should be aware that there are two main development platforms that KDE software is based on: the older kdelibs4, and its replacement, the [http://api.kde.org/frameworks-api/frameworks5-apidocs/ KDE Frameworks]. Quite a bit of KDE software is in the process of transitioning from kdelibs4 to KDE Frameworks, and the way CMake is used is slightly different between the two.


This page contains some tutorials to help you get started on building a CMake-based buildsystem. This is the recommended way of building your software if you use KDE technologies, such as KDE Frameworks.
This page contains some tutorials to help you get started on building a CMake-based buildsystem. This is the recommended way of building your software if you use KDE technologies, such as KDE Frameworks.
Reference documentation for using CMake with KDE software can be found at [[Development/CMake]].


==Beginners==
==Beginners==
Line 15: Line 12:
==Intermediate==
==Intermediate==


* [[Development/Tutorials/CMake/Library|Creating a library]]: demonstrates best practices when creating a library with a CMake-based buildsystem (such as a KDE Framework).
* [[/Library|Creating a library]]: demonstrates best practices when creating a library with a CMake-based buildsystem (such as a KDE Framework).


== Building with CMake in short ==
== Building with CMake in short ==
Line 21: Line 18:
If you just want to build a CMake-based project on a UNIX system, the following recipe will do that:
If you just want to build a CMake-based project on a UNIX system, the following recipe will do that:


    cd /path/to/project/source
<syntaxhighlight lang="bash">
    mkdir build
cd /path/to/project/source
    cd build
mkdir build
    cmake -DCMAKE_INSTALL_PREFIX=/where/to/install/to ..
cd build
    make
cmake -DCMAKE_INSTALL_PREFIX=/where/to/install/to ..
    make install
make
make install
</syntaxhighlight>
 
Don't forget to replace both paths. If you want an explanation of what this command does and how to make CMake behave differently, or you want to build on Windows or OS/X, see [[/Building | the building with CMake]] chapter.
 
==How to debug CMake==


Don't forget to replace both paths. If you want an explanation of what this command does and how to make CMake behave differently, or you want to build on Windows or OS/X, see [[Guidelines HOWTOs/CMake/Building]].
See https://cliutils.gitlab.io/modern-cmake/chapters/features/debug.html
 
Run:
<pre>
cmake --help
</pre>
 
<pre>
# Go to the directory that is used in order to run CMake.
cd ~/kde/build/kconfig
# Run the usual CMake configure command line.
cmake -B . -S /home/username/kde/src/kate -G Unix\ Makefiles -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DQT_MAJOR_VERSION=6 -DBUILD_WITH_QT6=ON -DBUILD_TESTING=TRUE -DBUILD_WITH_QT6=ON -DCMAKE_CXX_FLAGS:STRING=-pipe -DCMAKE_INSTALL_PREFIX=/home/username/kde/usr
# Says: "Qt5Core". Which is wrong because it should only use Qt6.
 
# Run a CMake command line with more verbose output. Using the command line parameter:
# --trace-expand
cmake -B . -S /home/username/kde/src/kate -G Unix\ Makefiles -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DQT_MAJOR_VERSION=6 -DBUILD_WITH_QT6=ON -DBUILD_TESTING=TRUE -DBUILD_WITH_QT6=ON -DCMAKE_CXX_FLAGS:STRING=-pipe -DCMAKE_INSTALL_PREFIX=/home/username/kde/usr --trace-expand |& tee ~/a.txt
kate  ~/a.txt &
# Go to the end of the file by pressing "Ctrl + End".
# Important information can be at the end of the file.
# Search for "Qt5". E.g. Search backwards from the end of the file towards the start of the file, i.e. press the button with the tooltip "Jump to the previous match" "Shift+F3".
# Says
# "/usr/lib/x86_64-linux-gnu/cmake/KUserFeedback/KUserFeedbackConfig.cmake(37):  find_package(Qt5 5.15 NO_MODULE REQUIRED COMPONENTS Core Network )"
# which is wrong because we build using kdesrc-build and
# all of the KDE Frameworks that are used in order to build
# should be in ~/kde/usr
# not in /usr.  
</pre>


==Useful resources==
==Useful resources==


You may want to check out the [http://www.cmake.org/Wiki/CMake CMake wiki], although beware that it contains quite a bit of out-of-date information.
[https://cmake.org/resources/ CMake Resources]
 
You may want to check out the [https://gitlab.kitware.com/cmake/community/-/wikis/home CMake wiki], although beware that it contains quite a bit of out-of-date information.


===Reference documentation===
===Reference documentation===
Line 43: Line 75:
===FAQs===
===FAQs===


* [[Guidelines HOWTOs/CMake/FAQs|KDE's CMake FAQs]]
* [[/FAQs|KDE's CMake FAQs]]
* [http://www.cmake.org/Wiki/CMake_FAQ CMake FAQ on the CMake wiki]
* [https://gitlab.kitware.com/cmake/community/-/wikis/FAQ CMake FAQ on the CMake wiki]


===Mailing lists===
===Mailing lists===
Line 50: Line 82:
;[http://mail.kde.org/pipermail/kde-buildsystem/ The kde-buildsystem mailing list]
;[http://mail.kde.org/pipermail/kde-buildsystem/ The kde-buildsystem mailing list]
:Discussion of CMake in the KDE community, as well as development of Extra CMake Modules.
:Discussion of CMake in the KDE community, as well as development of Extra CMake Modules.
;[http://www.cmake.org/mailman/listinfo/cmake CMake mailing list]
:For users of CMake.
;[http://www.cmake.org/mailman/listinfo/cmake-developers CMake mailing list]
:For anyone wanting to contribute to CMake.

Latest revision as of 23:18, 7 October 2024

See https://develop.kde.org/docs/getting-started/building/cmake-build

Most KDE software uses CMake as a buildsystem. This page is the starting point for CMake-related documentation for KDE software.

This page contains some tutorials to help you get started on building a CMake-based buildsystem. This is the recommended way of building your software if you use KDE technologies, such as KDE Frameworks.

Beginners

  • A first CMake project: if you've never even looked at CMake code before, start here.
  • Using a framework: introduces you to using a KDE Framework - finding the package and linking your program against it.

Intermediate

  • Creating a library: demonstrates best practices when creating a library with a CMake-based buildsystem (such as a KDE Framework).

Building with CMake in short

If you just want to build a CMake-based project on a UNIX system, the following recipe will do that: 

cd /path/to/project/source
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/where/to/install/to ..
make
make install

Don't forget to replace both paths. If you want an explanation of what this command does and how to make CMake behave differently, or you want to build on Windows or OS/X, see the building with CMake chapter.

How to debug CMake

See https://cliutils.gitlab.io/modern-cmake/chapters/features/debug.html

Run: 

cmake --help

# Go to the directory that is used in order to run CMake.
cd ~/kde/build/kconfig
# Run the usual CMake configure command line.
cmake -B . -S /home/username/kde/src/kate -G Unix\ Makefiles -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DQT_MAJOR_VERSION=6 -DBUILD_WITH_QT6=ON -DBUILD_TESTING=TRUE -DBUILD_WITH_QT6=ON -DCMAKE_CXX_FLAGS:STRING=-pipe -DCMAKE_INSTALL_PREFIX=/home/username/kde/usr
# Says: "Qt5Core". Which is wrong because it should only use Qt6.

# Run a CMake command line with more verbose output. Using the command line parameter:
# --trace-expand
cmake -B . -S /home/username/kde/src/kate -G Unix\ Makefiles -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=ON -DCMAKE_BUILD_TYPE=Debug -DQT_MAJOR_VERSION=6 -DBUILD_WITH_QT6=ON -DBUILD_TESTING=TRUE -DBUILD_WITH_QT6=ON -DCMAKE_CXX_FLAGS:STRING=-pipe -DCMAKE_INSTALL_PREFIX=/home/username/kde/usr --trace-expand |& tee ~/a.txt
kate  ~/a.txt &
# Go to the end of the file by pressing "Ctrl + End".
# Important information can be at the end of the file.
# Search for "Qt5". E.g. Search backwards from the end of the file towards the start of the file, i.e. press the button with the tooltip "Jump to the previous match" "Shift+F3".
# Says
# "/usr/lib/x86_64-linux-gnu/cmake/KUserFeedback/KUserFeedbackConfig.cmake(37):  find_package(Qt5 5.15 NO_MODULE REQUIRED COMPONENTS Core Network )"
# which is wrong because we build using kdesrc-build and
# all of the KDE Frameworks that are used in order to build
# should be in ~/kde/usr
# not in /usr.

Useful resources

CMake Resources

You may want to check out the CMake wiki, although beware that it contains quite a bit of out-of-date information.

Reference documentation

Upgrading from KDELibs4

See https://techbase.kde.org/ECM5/IncompatibleChangesKDELibs4ToECM.

FAQs

Mailing lists

The kde-buildsystem mailing list
Discussion of CMake in the KDE community, as well as development of Extra CMake Modules.
Retrieved from "https://community.kde.org/index.php?title=Guidelines_and_HOWTOs/CMake&oldid=101866"