Debian Codegraph @

cmake_modules/FindPackageHandleStandardArgs.cmake

raw
1 #[=======================================================================[.rst:
2 FindPackageHandleStandardArgs
3 -----------------------------
4
5 This module provides a function intended to be used in :ref:`Find Modules`
6 implementing :command:`find_package(<PackageName>)` calls. It handles the
7 ``REQUIRED``, ``QUIET`` and version-related arguments of ``find_package``.
8 It also sets the ``<PackageName>_FOUND`` variable. The package is
9 considered found if all variables listed contain valid results, e.g.
10 valid filepaths.
11
12 .. command:: find_package_handle_standard_args
13
14 There are two signatures::
15
16 find_package_handle_standard_args(<PackageName>
17 (DEFAULT_MSG|<custom-failure-message>)
18 <required-var>...
19 )
20
21 find_package_handle_standard_args(<PackageName>
22 [FOUND_VAR <result-var>]
23 [REQUIRED_VARS <required-var>...]
24 [VERSION_VAR <version-var>]
25 [HANDLE_COMPONENTS]
26 [CONFIG_MODE]
27 [FAIL_MESSAGE <custom-failure-message>]
28 )
29
30 The ``<PackageName>_FOUND`` variable will be set to ``TRUE`` if all
31 the variables ``<required-var>...`` are valid and any optional
32 constraints are satisfied, and ``FALSE`` otherwise. A success or
33 failure message may be displayed based on the results and on
34 whether the ``REQUIRED`` and/or ``QUIET`` option was given to
35 the :command:`find_package` call.
36
37 The options are:
38
39 ``(DEFAULT_MSG|<custom-failure-message>)``
40 In the simple signature this specifies the failure message.
41 Use ``DEFAULT_MSG`` to ask for a default message to be computed
42 (recommended). Not valid in the full signature.
43
44 ``FOUND_VAR <result-var>``
45 Obsolete. Specifies either ``<PackageName>_FOUND`` or
46 ``<PACKAGENAME>_FOUND`` as the result variable. This exists only
47 for compatibility with older versions of CMake and is now ignored.
48 Result variables of both names are always set for compatibility.
49
50 ``REQUIRED_VARS <required-var>...``
51 Specify the variables which are required for this package.
52 These may be named in the generated failure message asking the
53 user to set the missing variable values. Therefore these should
54 typically be cache entries such as ``FOO_LIBRARY`` and not output
55 variables like ``FOO_LIBRARIES``.
56
57 ``VERSION_VAR <version-var>``
58 Specify the name of a variable that holds the version of the package
59 that has been found. This version will be checked against the
60 (potentially) specified required version given to the
61 :command:`find_package` call, including its ``EXACT`` option.
62 The default messages include information about the required
63 version and the version which has been actually found, both
64 if the version is ok or not.
65
66 ``HANDLE_COMPONENTS``
67 Enable handling of package components. In this case, the command
68 will report which components have been found and which are missing,
69 and the ``<PackageName>_FOUND`` variable will be set to ``FALSE``
70 if any of the required components (i.e. not the ones listed after
71 the ``OPTIONAL_COMPONENTS`` option of :command:`find_package`) are
72 missing.
73
74 ``CONFIG_MODE``
75 Specify that the calling find module is a wrapper around a
76 call to ``find_package(<PackageName> NO_MODULE)``. This implies
77 a ``VERSION_VAR`` value of ``<PackageName>_VERSION``. The command
78 will automatically check whether the package configuration file
79 was found.
80
81 ``FAIL_MESSAGE <custom-failure-message>``
82 Specify a custom failure message instead of using the default
83 generated message. Not recommended.
84
85 Example for the simple signature:
86
87 .. code-block:: cmake
88
89 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
90 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
91
92 The ``LibXml2`` package is considered to be found if both
93 ``LIBXML2_LIBRARY`` and ``LIBXML2_INCLUDE_DIR`` are valid.
94 Then also ``LibXml2_FOUND`` is set to ``TRUE``. If it is not found
95 and ``REQUIRED`` was used, it fails with a
96 :command:`message(FATAL_ERROR)`, independent whether ``QUIET`` was
97 used or not. If it is found, success will be reported, including
98 the content of the first ``<required-var>``. On repeated CMake runs,
99 the same message will not be printed again.
100
101 Example for the full signature:
102
103 .. code-block:: cmake
104
105 find_package_handle_standard_args(LibArchive
106 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
107 VERSION_VAR LibArchive_VERSION)
108
109 In this case, the ``LibArchive`` package is considered to be found if
110 both ``LibArchive_LIBRARY`` and ``LibArchive_INCLUDE_DIR`` are valid.
111 Also the version of ``LibArchive`` will be checked by using the version
112 contained in ``LibArchive_VERSION``. Since no ``FAIL_MESSAGE`` is given,
113 the default messages will be printed.
114
115 Another example for the full signature:
116
117 .. code-block:: cmake
118
119 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
120 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
121
122 In this case, a ``FindAutmoc4.cmake`` module wraps a call to
123 ``find_package(Automoc4 NO_MODULE)`` and adds an additional search
124 directory for ``automoc4``. Then the call to
125 ``find_package_handle_standard_args`` produces a proper success/failure
126 message.
127 #]=======================================================================]
128
129 #=============================================================================
130 # Copyright 2007-2009 Kitware, Inc.
131 #
132 # Distributed under the OSI-approved BSD License (the "License");
133 # see accompanying file Copyright.txt for details.
134 #
135 # This software is distributed WITHOUT ANY WARRANTY; without even the
136 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
137 # See the License for more information.
138 #=============================================================================
139 # (To distribute this file outside of CMake, substitute the full
140 # License text for the above reference.)
141
142 include(${CMAKE_CURRENT_LIST_DIR}/FindPackageMessage.cmake)
143 include(${CMAKE_CURRENT_LIST_DIR}/CMakeParseArguments.cmake)
144
145 # internal helper macro
146 macro(_FPHSA_FAILURE_MESSAGE _msg)
147 if (${_NAME}_FIND_REQUIRED)
148 message(FATAL_ERROR "${_msg}")
149 else ()
150 if (NOT ${_NAME}_FIND_QUIETLY)
151 message(STATUS "${_msg}")
152 endif ()
153 endif ()
154 endmacro()
155
156
157 # internal helper macro to generate the failure message when used in CONFIG_MODE:
158 macro(_FPHSA_HANDLE_FAILURE_CONFIG_MODE)
159 # <name>_CONFIG is set, but FOUND is false, this means that some other of the REQUIRED_VARS was not found:
160 if(${_NAME}_CONFIG)
161 _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE}: missing: ${MISSING_VARS} (found ${${_NAME}_CONFIG} ${VERSION_MSG})")
162 else()
163 # If _CONSIDERED_CONFIGS is set, the config-file has been found, but no suitable version.
164 # List them all in the error message:
165 if(${_NAME}_CONSIDERED_CONFIGS)
166 set(configsText "")
167 list(LENGTH ${_NAME}_CONSIDERED_CONFIGS configsCount)
168 math(EXPR configsCount "${configsCount} - 1")
169 foreach(currentConfigIndex RANGE ${configsCount})
170 list(GET ${_NAME}_CONSIDERED_CONFIGS ${currentConfigIndex} filename)
171 list(GET ${_NAME}_CONSIDERED_VERSIONS ${currentConfigIndex} version)
172 set(configsText "${configsText} ${filename} (version ${version})\n")
173 endforeach()
174 if (${_NAME}_NOT_FOUND_MESSAGE)
175 set(configsText "${configsText} Reason given by package: ${${_NAME}_NOT_FOUND_MESSAGE}\n")
176 endif()
177 _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE} ${VERSION_MSG}, checked the following files:\n${configsText}")
178
179 else()
180 # Simple case: No Config-file was found at all:
181 _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE}: found neither ${_NAME}Config.cmake nor ${_NAME_LOWER}-config.cmake ${VERSION_MSG}")
182 endif()
183 endif()
184 endmacro()
185
186
187 function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
188
189 # set up the arguments for CMAKE_PARSE_ARGUMENTS and check whether we are in
190 # new extended or in the "old" mode:
191 set(options CONFIG_MODE HANDLE_COMPONENTS)
192 set(oneValueArgs FAIL_MESSAGE VERSION_VAR FOUND_VAR)
193 set(multiValueArgs REQUIRED_VARS)
194 set(_KEYWORDS_FOR_EXTENDED_MODE ${options} ${oneValueArgs} ${multiValueArgs} )
195 list(FIND _KEYWORDS_FOR_EXTENDED_MODE "${_FIRST_ARG}" INDEX)
196
197 if(${INDEX} EQUAL -1)
198 set(FPHSA_FAIL_MESSAGE ${_FIRST_ARG})
199 set(FPHSA_REQUIRED_VARS ${ARGN})
200 set(FPHSA_VERSION_VAR)
201 else()
202
203 CMAKE_PARSE_ARGUMENTS(FPHSA "${options}" "${oneValueArgs}" "${multiValueArgs}" ${_FIRST_ARG} ${ARGN})
204
205 if(FPHSA_UNPARSED_ARGUMENTS)
206 message(FATAL_ERROR "Unknown keywords given to FIND_PACKAGE_HANDLE_STANDARD_ARGS(): \"${FPHSA_UNPARSED_ARGUMENTS}\"")
207 endif()
208
209 if(NOT FPHSA_FAIL_MESSAGE)
210 set(FPHSA_FAIL_MESSAGE "DEFAULT_MSG")
211 endif()
212 endif()
213
214 # now that we collected all arguments, process them
215
216 if("x${FPHSA_FAIL_MESSAGE}" STREQUAL "xDEFAULT_MSG")
217 set(FPHSA_FAIL_MESSAGE "Could NOT find ${_NAME}")
218 endif()
219
220 # In config-mode, we rely on the variable <package>_CONFIG, which is set by find_package()
221 # when it successfully found the config-file, including version checking:
222 if(FPHSA_CONFIG_MODE)
223 list(INSERT FPHSA_REQUIRED_VARS 0 ${_NAME}_CONFIG)
224 list(REMOVE_DUPLICATES FPHSA_REQUIRED_VARS)
225 set(FPHSA_VERSION_VAR ${_NAME}_VERSION)
226 endif()
227
228 if(NOT FPHSA_REQUIRED_VARS)
229 message(FATAL_ERROR "No REQUIRED_VARS specified for FIND_PACKAGE_HANDLE_STANDARD_ARGS()")
230 endif()
231
232 list(GET FPHSA_REQUIRED_VARS 0 _FIRST_REQUIRED_VAR)
233
234 string(TOUPPER ${_NAME} _NAME_UPPER)
235 string(TOLOWER ${_NAME} _NAME_LOWER)
236
237 if(FPHSA_FOUND_VAR)
238 if(FPHSA_FOUND_VAR MATCHES "^${_NAME}_FOUND$" OR FPHSA_FOUND_VAR MATCHES "^${_NAME_UPPER}_FOUND$")
239 set(_FOUND_VAR ${FPHSA_FOUND_VAR})
240 else()
241 message(FATAL_ERROR "The argument for FOUND_VAR is \"${FPHSA_FOUND_VAR}\", but only \"${_NAME}_FOUND\" and \"${_NAME_UPPER}_FOUND\" are valid names.")
242 endif()
243 else()
244 set(_FOUND_VAR ${_NAME_UPPER}_FOUND)
245 endif()
246
247 # collect all variables which were not found, so they can be printed, so the
248 # user knows better what went wrong (#6375)
249 set(MISSING_VARS "")
250 set(DETAILS "")
251 # check if all passed variables are valid
252 set(FPHSA_FOUND_${_NAME} TRUE)
253 foreach(_CURRENT_VAR ${FPHSA_REQUIRED_VARS})
254 if(NOT ${_CURRENT_VAR})
255 set(FPHSA_FOUND_${_NAME} FALSE)
256 set(MISSING_VARS "${MISSING_VARS} ${_CURRENT_VAR}")
257 else()
258 set(DETAILS "${DETAILS}[${${_CURRENT_VAR}}]")
259 endif()
260 endforeach()
261 if(FPHSA_FOUND_${_NAME})
262 set(${_NAME}_FOUND TRUE)
263 set(${_NAME_UPPER}_FOUND TRUE)
264 else()
265 set(${_NAME}_FOUND FALSE)
266 set(${_NAME_UPPER}_FOUND FALSE)
267 endif()
268
269 # component handling
270 unset(FOUND_COMPONENTS_MSG)
271 unset(MISSING_COMPONENTS_MSG)
272
273 if(FPHSA_HANDLE_COMPONENTS)
274 foreach(comp ${${_NAME}_FIND_COMPONENTS})
275 if(${_NAME}_${comp}_FOUND)
276
277 if(NOT DEFINED FOUND_COMPONENTS_MSG)
278 set(FOUND_COMPONENTS_MSG "found components: ")
279 endif()
280 set(FOUND_COMPONENTS_MSG "${FOUND_COMPONENTS_MSG} ${comp}")
281
282 else()
283
284 if(NOT DEFINED MISSING_COMPONENTS_MSG)
285 set(MISSING_COMPONENTS_MSG "missing components: ")
286 endif()
287 set(MISSING_COMPONENTS_MSG "${MISSING_COMPONENTS_MSG} ${comp}")
288
289 if(${_NAME}_FIND_REQUIRED_${comp})
290 set(${_NAME}_FOUND FALSE)
291 set(MISSING_VARS "${MISSING_VARS} ${comp}")
292 endif()
293
294 endif()
295 endforeach()
296 set(COMPONENT_MSG "${FOUND_COMPONENTS_MSG} ${MISSING_COMPONENTS_MSG}")
297 set(DETAILS "${DETAILS}[c${COMPONENT_MSG}]")
298 endif()
299
300 # version handling:
301 set(VERSION_MSG "")
302 set(VERSION_OK TRUE)
303 set(VERSION ${${FPHSA_VERSION_VAR}})
304
305 # check with DEFINED here as the requested or found version may be "0"
306 if (DEFINED ${_NAME}_FIND_VERSION)
307 if(DEFINED ${FPHSA_VERSION_VAR})
308
309 if(${_NAME}_FIND_VERSION_EXACT) # exact version required
310 # count the dots in the version string
311 string(REGEX REPLACE "[^.]" "" _VERSION_DOTS "${VERSION}")
312 # add one dot because there is one dot more than there are components
313 string(LENGTH "${_VERSION_DOTS}." _VERSION_DOTS)
314 if (_VERSION_DOTS GREATER ${_NAME}_FIND_VERSION_COUNT)
315 # Because of the C++ implementation of find_package() ${_NAME}_FIND_VERSION_COUNT
316 # is at most 4 here. Therefore a simple lookup table is used.
317 if (${_NAME}_FIND_VERSION_COUNT EQUAL 1)
318 set(_VERSION_REGEX "[^.]*")
319 elseif (${_NAME}_FIND_VERSION_COUNT EQUAL 2)
320 set(_VERSION_REGEX "[^.]*\\.[^.]*")
321 elseif (${_NAME}_FIND_VERSION_COUNT EQUAL 3)
322 set(_VERSION_REGEX "[^.]*\\.[^.]*\\.[^.]*")
323 else ()
324 set(_VERSION_REGEX "[^.]*\\.[^.]*\\.[^.]*\\.[^.]*")
325 endif ()
326 string(REGEX REPLACE "^(${_VERSION_REGEX})\\..*" "\\1" _VERSION_HEAD "${VERSION}")
327 unset(_VERSION_REGEX)
328 if (NOT ${_NAME}_FIND_VERSION VERSION_EQUAL _VERSION_HEAD)
329 set(VERSION_MSG "Found unsuitable version \"${VERSION}\", but required is exact version \"${${_NAME}_FIND_VERSION}\"")
330 set(VERSION_OK FALSE)
331 else ()
332 set(VERSION_MSG "(found suitable exact version \"${VERSION}\")")
333 endif ()
334 unset(_VERSION_HEAD)
335 else ()
336 if (NOT ${_NAME}_FIND_VERSION VERSION_EQUAL VERSION)
337 set(VERSION_MSG "Found unsuitable version \"${VERSION}\", but required is exact version \"${${_NAME}_FIND_VERSION}\"")
338 set(VERSION_OK FALSE)
339 else ()
340 set(VERSION_MSG "(found suitable exact version \"${VERSION}\")")
341 endif ()
342 endif ()
343 unset(_VERSION_DOTS)
344
345 else() # minimum version specified:
346 if (${_NAME}_FIND_VERSION VERSION_GREATER VERSION)
347 set(VERSION_MSG "Found unsuitable version \"${VERSION}\", but required is at least \"${${_NAME}_FIND_VERSION}\"")
348 set(VERSION_OK FALSE)
349 else ()
350 set(VERSION_MSG "(found suitable version \"${VERSION}\", minimum required is \"${${_NAME}_FIND_VERSION}\")")
351 endif ()
352 endif()
353
354 else()
355
356 # if the package was not found, but a version was given, add that to the output:
357 if(${_NAME}_FIND_VERSION_EXACT)
358 set(VERSION_MSG "(Required is exact version \"${${_NAME}_FIND_VERSION}\")")
359 else()
360 set(VERSION_MSG "(Required is at least version \"${${_NAME}_FIND_VERSION}\")")
361 endif()
362
363 endif()
364 else ()
365 if(VERSION)
366 set(VERSION_MSG "(found version \"${VERSION}\")")
367 endif()
368 endif ()
369
370 if(VERSION_OK)
371 set(DETAILS "${DETAILS}[v${VERSION}(${${_NAME}_FIND_VERSION})]")
372 else()
373 set(${_NAME}_FOUND FALSE)
374 endif()
375
376
377 # print the result:
378 if (${_NAME}_FOUND)
379 FIND_PACKAGE_MESSAGE(${_NAME} "Found ${_NAME}: ${${_FIRST_REQUIRED_VAR}} ${VERSION_MSG} ${COMPONENT_MSG}" "${DETAILS}")
380 else ()
381
382 if(FPHSA_CONFIG_MODE)
383 _FPHSA_HANDLE_FAILURE_CONFIG_MODE()
384 else()
385 if(NOT VERSION_OK)
386 _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE}: ${VERSION_MSG} (found ${${_FIRST_REQUIRED_VAR}})")
387 else()
388 _FPHSA_FAILURE_MESSAGE("${FPHSA_FAIL_MESSAGE} (missing: ${MISSING_VARS}) ${VERSION_MSG}")
389 endif()
390 endif()
391
392 endif ()
393
394 set(${_NAME}_FOUND ${${_NAME}_FOUND} PARENT_SCOPE)
395 set(${_NAME_UPPER}_FOUND ${${_NAME}_FOUND} PARENT_SCOPE)
396 endfunction()