frameworks/extra-cmake-modules/README.rst

0001 Extra CMake Modules
0002 *******************
0003
0004 Introduction
0005 ============
0006
0007 The Extra CMake Modules package, or ECM, adds to the modules provided by CMake,
0008 including ones used by ``find_package()`` to find common software, ones that
0009 can be used directly in ``CMakeLists.txt`` files to perform common tasks and
0010 toolchain files that must be specified on the commandline by the user.
0011
0012 In addition, it provides common build settings used in software produced by the
0013 KDE community.
0014
0015 While the driving force of this module is to reduce duplication in CMake scripts
0016 across KDE software, it is intended to be useful for any software that uses the
0017 CMake build system.
0018
0019
0020 Usage
0021 =====
0022
0023 To use ECM, add the following to your ``CMakeLists.txt``:
0024
0025 .. code-block:: cmake
0026
0027   find_package(ECM REQUIRED NO_MODULE)
0028   set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
0029
0030 (note that you may want to append ``${ECM_MODULE_PATH}`` to
0031 ``CMAKE_MODULE_PATH`` rather than discarding the existing value).  You can then
0032 just include the modules you require, or use ``find_package()`` as needed.  For
0033 example:
0034
0035 .. code-block:: cmake
0036
0037   include(ECMInstallIcons)
0038
0039 Developers of KDE software will often want to use the KDE standard settings
0040 provided by ECM; they can do the following:
0041
0042 .. code-block:: cmake
0043
0044   find_package(ECM REQUIRED NO_MODULE)
0045   set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
0046   include(KDEInstallDirs)
0047   include(KDECompilerSettings)
0048   include(KDECMakeSettings)
0049
0050 Note that any combination of the above includes can be used if you only want
0051 some of the settings.  Some of the functionality of
0052 :kde-module:`KDECMakeSettings` can also be selectively disabled.
0053
0054
0055 Organization
0056 ------------
0057
0058 ECM provides four different types of modules.
0059
0060 * Core modules provide helpful macros for use in project CMake scripts.
0061   See :manual:`ecm-modules(7)` for more information.
0062 * Find modules extend the functionality of CMake's ``find_package()`` command.
0063   See :manual:`ecm-find-modules(7)` for more information.
0064 * KDE modules provide common settings for software produced by KDE; much of this
0065   may also be useful to other projects.  See :manual:`ecm-kde-modules(7)` for
0066   more information.
0067 * Toolchain files change the build tools and targets used by CMake. See
0068   :manual:`ecm-toolchains(7)` for more information.
0069
0070 The ``${ECM_MODULE_DIR}``, ``${ECM_FIND_MODULE_DIR}`` and
0071 ``${ECM_KDE_MODULE_DIR}`` variables may be used instead of
0072 ``${ECM_MODULE_PATH}`` if you only need some of this functionality.
0073
0074
0075 Development
0076 ===========
0077
0078 The :manual:`ecm-developer(7)` manual contains more information about
0079 developing for Extra CMake Modules.
0080
0081
0082 License
0083 =======
0084
0085 All code is licensed under the `BSD 3-Clause license`_.
0086
0087 .. _BSD 3-Clause license: https://opensource.org/licenses/BSD-3-Clause
0088
0089
0090 Links
0091 =====
0092
0093 * Home page: https://commits.kde.org/extra-cmake-modules
0094 * Documentation: https://api.kde.org/ecm/
0095 * Mailing list: https://mail.kde.org/mailman/listinfo/kde-buildsystem
0096 * IRC channel: #kde-devel on Libera Chat
0097 * Git repository: https://commits.kde.org/extra-cmake-modules