Jump to content

Guidelines and HOWTOs/CMake: Difference between revisions

From KDE Community Wiki
← Older edit
*>Pippin
Nmariusp (talk | contribs)
994 edits
https://develop.kde.org/docs/getting-started/building/cmake-build/
 
(23 intermediate revisions by 6 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.


This is the central directory of all [http://www.cmake.org CMake]-related pages on TechBase.
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.


== KDE4 Specific CMake Documentation==
==Beginners==


;[[Development/Tutorials/CMake|CMake tutorial]]
* [[/FirstProject|A first CMake project]]: if you've never even looked at CMake code before, start here.
:''An introduction to using CMake for KDE4''
* [[/Frameworks|Using a framework]]: introduces you to using a KDE Framework - finding the package and linking your program against it.


;[[Guidelines HOWTOs/CMake_FAQ|KDE's CMake FAQ]]
==Intermediate==
:''Some Frequently Asked Questions''


;[http://api.kde.org/cmake/modules.html KDE CMake modules API]
* [[/Library|Creating a library]]: demonstrates best practices when creating a library with a CMake-based buildsystem (such as a KDE Framework).
:''Documentation for all CMake modules in kdelibs (generated from kdelibs svn)''


;[[Guidelines HOWTOs/CMake/DashboardBuilds|Nightly dashboard builds for KDE]]
== Building with CMake in short ==
: ''Describes the quality dashboard for KDE and how to set up Nightly builds for it''


;[[Guidelines HOWTOs/CMake/Addons for KDE|KDE4 CMake Buildtypes, macros and variables]]
If you just want to build a CMake-based project on a UNIX system, the following recipe will do that:
:''Documentation for the buildtypes (debugfull, release, ...), macros and variables for building KDE4 software, provided by FindKDE4Internal.cmake (manually written)''


;[[Development/Tools/Automoc4|Automoc4]]
<syntaxhighlight lang="bash">
:''Automoc4 documentation.''
cd /path/to/project/source
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/where/to/install/to ..
make
make install
</syntaxhighlight>


;[[Guidelines HOWTOs/CMake/Python|CMake for Python projects]]
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 integrate a Python project into the KDE4 cmake system.''


==How to debug CMake==


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


;[[Policies/CMake_Commit_Policy|Commit Policy for kdelibs/cmake/modules/]]
Run:
:''The files in kdelibs/cmake/modules/ are part of the public interface of KDE, some special policies apply to committing there.''
<pre>
cmake --help
</pre>


;[[Policies/CMake_and_Source_Compatibility|Source compatiblity with CMake]]
<pre>
:''This page discusses what has to be taken care of in order to stay source compatible on the CMake level.''
# 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.


;[[Policies/CMake_Coding_Style|Coding style for CMake files]]
# Run a CMake command line with more verbose output. Using the command line parameter:
:''Some guidelines how to write CMake scripts in KDE.''
# --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>


==Changelog for KDE's CMake buildsystem==
==Useful resources==


;[[Guidelines HOWTOs/CMake_KDE_4_5 |Changes in the buildsystem with KDE 4.5]]
[https://cmake.org/resources/ CMake Resources]
:''What has changed in KDE 4.5 compared to KDE 4.4''


;[[Guidelines HOWTOs/CMake_KDE_4_4 |Changes in the buildsystem with KDE 4.4]]
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.
:''What has changed in KDE 4.4 compared to KDE 4.3''


;[[Guidelines HOWTOs/CMake_KDE_4_3 |Changes in the buildsystem with KDE 4.3]]
===Reference documentation===
:''What has changed in KDE 4.3 compared to KDE 4.2''
* [http://www.cmake.org/HTML/Documentation.html CMake's own documentation]
* [http://api.kde.org/ecm Extra CMake Modules documentation]


;[[Guidelines HOWTOs/CMake_KDE_4_2 |Changes in the buildsystem with KDE 4.2]]
===Upgrading from KDELibs4===
:''What has changed in KDE 4.2 compared to KDE 4.0/4.1''
See https://techbase.kde.org/ECM5/IncompatibleChangesKDELibs4ToECM.


==Extra-CMake-Modules==
===FAQs===
* [[Development/ECM_SourceIncompatChanges|Source Incompatible changes]]
* [http://api.kde.org/ecm API documentation]


==More Places to learn about CMake==
* [[/FAQs|KDE's CMake FAQs]]
* [https://gitlab.kitware.com/cmake/community/-/wikis/FAQ CMake FAQ on the CMake wiki]


Here are some good places to learn about CMake in general:
===Mailing lists===
* [http://www.cmake.org/HTML/Documentation.html CMake Manual]
* [http://www.cmake.org/Wiki/CMake CMake Wiki]
* [http://www.cmake.org/Wiki/CMake_HowToDoPlatformChecks CMake System Checks ]
* [http://www.cmake.org/Wiki/CMake_HowToFindInstalledSoftware Finding Optional Packages ]
* [http://www.cmake.org/Wiki/HowToBuildKDE4Software KDE 4 Tutorial at the CMake Wiki ]
* [http://www.cmake.org/Wiki/CMake_FAQ CMake FAQ]
* [http://www.elpauer.org/stuff/learning_cmake.pdf Slides for the "Learning CMake" seminar]
* [http://mail.kde.org/pipermail/kde-buildsystem/ The kde-buildsystem Mailing List Archive]


Also, consider joining the [http://www.cmake.org/mailman/listinfo/cmake CMake 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.

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"