README.md
1# Extra CMake Modules
2
3## Introduction
4
5The Extra CMake Modules package, or ECM, adds to the modules provided by CMake,
6including ones used by ``find_package()`` to find common software, ones that
7can be used directly in ``CMakeLists.txt`` files to perform common tasks and
8toolchain files that must be specified on the commandline by the user.
9
10In addition, it provides common build settings used in software produced by the
11KDE community.
12
13While the driving force of this module is to reduce duplication in CMake scripts
14across KDE software, it is intended to be useful for any software that uses the
15CMake build system.
16
17For more information visit the documentation at https://api.kde.org/ecm/
18
README.rst
1Extra CMake Modules
2*******************
3
4Introduction
5============
6
7The Extra CMake Modules package, or ECM, adds to the modules provided by CMake,
8including ones used by ``find_package()`` to find common software, ones that
9can be used directly in ``CMakeLists.txt`` files to perform common tasks and
10toolchain files that must be specified on the commandline by the user.
11
12In addition, it provides common build settings used in software produced by the
13KDE community.
14
15While the driving force of this module is to reduce duplication in CMake scripts
16across KDE software, it is intended to be useful for any software that uses the
17CMake build system.
18
19
20Usage
21=====
22
23To use ECM, add the following to your ``CMakeLists.txt``:
24
25.. code-block:: cmake
26
27 find_package(ECM REQUIRED NO_MODULE)
28 set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
29
30(note that you may want to append ``${ECM_MODULE_PATH}`` to
31``CMAKE_MODULE_PATH`` rather than discarding the existing value). You can then
32just include the modules you require, or use ``find_package()`` as needed. For
33example:
34
35.. code-block:: cmake
36
37 include(ECMInstallIcons)
38
39Developers of KDE software will often want to use the KDE standard settings
40provided by ECM; they can do the following:
41
42.. code-block:: cmake
43
44 find_package(ECM REQUIRED NO_MODULE)
45 set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
46 include(KDEInstallDirs)
47 include(KDECompilerSettings)
48 include(KDECMakeSettings)
49
50Note that any combination of the above includes can be used if you only want
51some of the settings. Some of the functionality of
52:kde-module:`KDECMakeSettings` can also be selectively disabled.
53
54
55Organization
56------------
57
58ECM provides four different types of modules.
59
60* Core modules provide helpful macros for use in project CMake scripts.
61 See :manual:`ecm-modules(7)` for more information.
62* Find modules extend the functionality of CMake's ``find_package()`` command.
63 See :manual:`ecm-find-modules(7)` for more information.
64* KDE modules provide common settings for software produced by KDE; much of this
65 may also be useful to other projects. See :manual:`ecm-kde-modules(7)` for
66 more information.
67* Toolchain files change the build tools and targets used by CMake. See
68 :manual:`ecm-toolchains(7)` for more information.
69
70The ``${ECM_MODULE_DIR}``, ``${ECM_FIND_MODULE_DIR}`` and
71``${ECM_KDE_MODULE_DIR}`` variables may be used instead of
72``${ECM_MODULE_PATH}`` if you only need some of this functionality.
73
74
75Development
76===========
77
78The :manual:`ecm-developer(7)` manual contains more information about
79developing for Extra CMake Modules.
80
81
82License
83=======
84
85All code is licensed under the `BSD 3-Clause license`_.
86
87.. _BSD 3-Clause license: https://opensource.org/licenses/BSD-3-Clause
88
89
90Links
91=====
92
93* Home page: https://commits.kde.org/extra-cmake-modules
94* Documentation: https://api.kde.org/ecm/
95* Mailing list: https://mail.kde.org/mailman/listinfo/kde-buildsystem
96* IRC channel: #kde-devel on Libera Chat
97* Git repository: https://commits.kde.org/extra-cmake-modules
98