1ECM-DEVELOPER(7) Extra CMake Modules ECM-DEVELOPER(7)
2
6 ecm-developer - ECM Developer Reference
7
9 The CMake 3 documentation (and cmake-developer(7) in particular) has a
10 lot of useful information about writing CMake modules, including a
11 large section devoted to find modules. This guide will only highlight
12 things that are particular to the Extra CMake Modules project.
13 Most of these are stylistic points. For example, the license header for
15 a module in ECM should look like:
16 # SPDX-FileCopyrightText: 20XX Your Name <your.email@example.com>
18 #
19 # SPDX-License-Identifier: BSD-3-Clause
20 Documentation is written in reStructuredText format and put inside a
22 bracket comment with a .rst: id after the opening bracket:
23 #[=======================================================================[.rst:
25 The docs
26 #]=======================================================================]
27 (docs/sphinx/ext/ecm.py has code to extract the rst text from a comment
29 with such wrapping)
30 Functions should be used instead of macros unless there is a good rea‐
32 son not to (and that reason should be noted in a comment), and lower‐
33 case should be used for macros, functions and commands.
34 4 spaces is the generally-recommended indent, although there are sev‐
36 eral files that use 2 spaces; consistency within a file is more impor‐
37 tant than consistency across files.
38 If in doubt, look at how other modules in Extra CMake Modules are writ‐
40 ten, and follow the same pattern.
41 Find Modules
43 A good template for find module documentation is:
44 #[=======================================================================[.rst:
46 FindFoo
47 -------
48 Finds the Foo library.
50 This will define the following variables:
52 ``Foo_FOUND``
54 True if (the requested version of) Foo is available
55 ``Foo_VERSION``
56 The version of Foo, if it is found
57 ``Foo_LIBRARIES``
58 This can be passed to target_link_libraries() instead of the ``Foo::Foo``
59 target
60 ``Foo_INCLUDE_DIRS``
61 This should be passed to target_include_directories() if the target is not
62 used for linking
63 ``Foo_DEFINITIONS``
64 This should be passed to target_compile_options() if the target is not
65 used for linking
66 If ``Foo_FOUND`` is TRUE, it will also define the following imported target:
68 ``Foo::Foo``
70 The Foo library
71 In general we recommend using the imported target, as it is easier to use.
73 Bear in mind, however, that if the target is in the link interface of an
74 exported library, it must be made available by the package config file.
75 #]=======================================================================]
76 Note the use of definition lists for the variables.
78 Because of the ECMUseFindModules module, projects may easily make local
80 copies of find modules, and may install those copies with their own
81 CMake project config files. For this reason, find modules should in‐
82 clude the full BSD 3-clause license:
83 #=============================================================================
85 # Copyright 20XX Your Name <your.email@example.com>
86 #
87 # Redistribution and use in source and binary forms, with or without
88 # modification, are permitted provided that the following conditions
89 # are met:
90 #
91 # 1. Redistributions of source code must retain the copyright
92 # notice, this list of conditions and the following disclaimer.
93 # 2. Redistributions in binary form must reproduce the copyright
94 # notice, this list of conditions and the following disclaimer in the
95 # documentation and/or other materials provided with the distribution.
96 # 3. The name of the author may not be used to endorse or promote products
97 # derived from this software without specific prior written permission.
98 #
99 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
100 # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
101 # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
102 # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
103 # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
104 # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
105 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
106 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
107 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
108 # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
109 #=============================================================================
110 Find modules should always provide imported targets in addition to the
112 traditional variables (like Foo_LIBRARIES, etc).
113 Unlike find modules shipped with CMake, if the module requires a spe‐
115 cific CMake version it is not enough to warn when the minimum required
116 version is not high enough: you should also produce an error when the
117 actual CMake version being used is not high enough. This can be done
118 with:
119 if(CMAKE_VERSION VERSION_LESS 3.16.0)
121 message(FATAL_ERROR "CMake 3.16.0 is required by FindFoo.cmake")
122 endif()
123 if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 3.16.0)
124 message(AUTHOR_WARNING "Your project should require at least CMake 3.16.0 to use FindFoo.cmake")
125 endif()
126 The ECMFindModuleHelpers module has several useful functions and
128 macros. For example, it allows you to replace the above version check
129 with:
130 ecm_find_package_version_check(Foo)
132 Components
134 Using ECMFindModuleHelpers, creating a find module for a library with
135 several inter-dependent components is reasonably straightforward. After
136 the documentation, you need to include the module and do the usual ver‐
137 sion check:
138 include(ECMFindModuleHelpers)
140 ecm_find_package_version_check(Foo)
141 The important macros are ecm_find_package_parse_components and
143 ecm_find_package_handle_library_components. These take a list of com‐
144 ponents, and query other variables you provide to find out the informa‐
145 tion they require. The documentation for ECMFindModuleHelpers provides
146 more information, but a simple setup might look like:
147 set(Foo_known_components Bar Baz)
149 set(Foo_Bar_pkg_config "foo-bar")
150 set(Foo_Bar_lib "bar")
151 set(Foo_Bar_header "foo/bar.h")
152 set(Foo_Bar_pkg_config "foo-baz")
153 set(Foo_Baz_lib "baz")
154 set(Foo_Baz_header "foo/baz.h")
155 If Baz depends on Bar, for example, you can specify this with
157 set(Foo_Baz_component_deps "Bar")
159 Then call the macros:
161 ecm_find_package_parse_components(Foo
163 RESULT_VAR Foo_components
164 KNOWN_COMPONENTS ${Foo_known_components}
165 )
166 ecm_find_package_handle_library_components(Foo
167 COMPONENTS ${Foo_components}
168 )
169 Of course, if your components need unusual handling, you may want to
171 replace ecm_find_package_handle_library_components with, for example, a
172 foreach loop over the components (the body of which should implement
173 most of what a normal find module does, including setting Foo_<compo‐
174 nent>_FOUND).
175 At this point, you should set Foo_VERSION using whatever information
177 you have available (such as from parsing header files). Note that
178 ecm_find_package_handle_library_components will set it to the version
179 reported by pkg-config of the first component found, but this depends
180 on the presence of pkg-config files, and the version of a component may
181 not be the same as the version of the whole package. After that, fin‐
182 ish off with
183 include(FindPackageHandleStandardArgs)
185 find_package_handle_standard_args(Foo
186 FOUND_VAR
187 Foo_FOUND
188 REQUIRED_VARS
189 Foo_LIBRARIES
190 VERSION_VAR
191 Foo_VERSION
192 HANDLE_COMPONENTS
193 )
194 include(FeatureSummary)
196 set_package_properties(Foo PROPERTIES
197 URL "https://www.foo.example.com/"
198 DESCRIPTION "A library for doing useful things")
199
201 Proposed new modules should be submitted using the KDE Review Board in‐
202 stance, and be assigned to the buildsystem and extracmakemodules
203 groups. You should be able to point to two separate projects that will
204 make use of the module.
205 The mailing list can be found at
207 https://mail.kde.org/mailman/listinfo/kde-buildsystem.
208
210 KDE Developers
2115.102 Jan 14, 2023 ECM-DEVELOPER(7)