reactos/CMake
1
0
Fork 0
mirror of https://github.com/reactos/CMake.git synced 2025-02-24 22:12:46 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge topic 'FPHSA-updates'

Browse Source 
84f06d0c FPHSA: Document REQUIRED_VARS recommendation (#15352)
a3ad275c FPHSA: Revise and format documentation
d1a6d15b FPHSA: Always populate the ExactCase_FOUND variable (#15412).
This commit is contained in:
Brad King 2015-04-17 10:50:10 -04:00 committed by CMake Topic Stage
commit f4e5a0e6aa
5 changed files with 160 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Help/release/dev/FPHSA-ExactCase-name.rst Normal file
View File

@ -0,0 +1,10 @@
FPHSA-ExactCase-name
--------------------
* The :module:`FindPackageHandleStandardArgs` module
``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now
always populates the both ``<PackageName>_FOUND``
and ``<UPPERCASE_NAME>_FOUND`` variables (the latter
for backwards compatibility). The ``FOUND_VAR``
option is now ignored except to enforce its allowed
values.

266
Modules/FindPackageHandleStandardArgs.cmake
View File

@ -1,120 +1,130 @@
#.rst: #[=======================================================================[.rst:
# FindPackageHandleStandardArgs FindPackageHandleStandardArgs
# ----------------------------- -----------------------------
#
# This module provides a function intended to be used in :ref:`Find Modules`
# implementing :command:`find_package(<PackageName>)` calls. It handles the
# FIND_PACKAGE_HANDLE_STANDARD_ARGS(<name> ... ) ``REQUIRED``, ``QUIET`` and version-related arguments of ``find_package``.
# It also sets the ``<PackageName>_FOUND`` variable. The package is
# This function is intended to be used in FindXXX.cmake modules files. considered found if all variables listed contain valid results, e.g.
# It handles the REQUIRED, QUIET and version-related arguments to valid filepaths.
# find_package(). It also sets the <packagename>_FOUND variable. The
# package is considered found if all variables <var1>... listed contain .. command:: find_package_handle_standard_args
# valid results, e.g. valid filepaths.
# There are two signatures::
# There are two modes of this function. The first argument in both
# modes is the name of the Find-module where it is called (in original find_package_handle_standard_args(<PackageName>
# casing). (DEFAULT_MSG|<custom-failure-message>)
# <required-var>...
# The first simple mode looks like this: )
#
# :: find_package_handle_standard_args(<PackageName>
# [FOUND_VAR <result-var>]
# FIND_PACKAGE_HANDLE_STANDARD_ARGS(<name> [REQUIRED_VARS <required-var>...]
# (DEFAULT_MSG|"Custom failure message") <var1>...<varN> ) [VERSION_VAR <version-var>]
# [HANDLE_COMPONENTS]
# If the variables <var1> to <varN> are all valid, then [CONFIG_MODE]
# <UPPERCASED_NAME>_FOUND will be set to TRUE. If DEFAULT_MSG is given [FAIL_MESSAGE <custom-failure-message>]
# as second argument, then the function will generate itself useful )
# success and error messages. You can also supply a custom error
# message for the failure case. This is not recommended. The ``<PackageName>_FOUND`` variable will be set to ``TRUE`` if all
# the variables ``<required-var>...`` are valid and any optional
# The second mode is more powerful and also supports version checking: constraints are satisfied, and ``FALSE`` otherwise. A success or
# failure message may be displayed based on the results and on
# :: whether the ``REQUIRED`` and/or ``QUIET`` option was given to
# the :command:`find_package` call.
# FIND_PACKAGE_HANDLE_STANDARD_ARGS(<NAME>
# [FOUND_VAR <resultVar>] The options are:
# [REQUIRED_VARS <var1>...<varN>]
# [VERSION_VAR <versionvar>] ``(DEFAULT_MSG|<custom-failure-message>)``
# [HANDLE_COMPONENTS] In the simple signature this specifies the failure message.
# [CONFIG_MODE] Use ``DEFAULT_MSG`` to ask for a default message to be computed
# [FAIL_MESSAGE "Custom failure message"] ) (recommended). Not valid in the full signature.
#
# In this mode, the name of the result-variable can be set either to ``FOUND_VAR <result-var>``
# either <UPPERCASED_NAME>_FOUND or <OriginalCase_Name>_FOUND using the Obselete. Specifies either ``<PackageName>_FOUND`` or
# FOUND_VAR option. Other names for the result-variable are not ``<PACKAGENAME>_FOUND`` as the result variable. This exists only
# allowed. So for a Find-module named FindFooBar.cmake, the two for compatibility with older versions of CMake and is now ignored.
# possible names are FooBar_FOUND and FOOBAR_FOUND. It is recommended Result variables of both names are always set for compatibility.
# to use the original case version. If the FOUND_VAR option is not
# used, the default is <UPPERCASED_NAME>_FOUND. ``REQUIRED_VARS <required-var>...``
# Specify the variables which are required for this package.
# As in the simple mode, if <var1> through <varN> are all valid, These may be named in the generated failure message asking the
# <packagename>_FOUND will be set to TRUE. After REQUIRED_VARS the user to set the missing variable values. Therefore these should
# variables which are required for this package are listed. Following typically be cache entries such as ``FOO_LIBRARY`` and not output
# VERSION_VAR the name of the variable can be specified which holds the variables like ``FOO_LIBRARIES``.
# version of the package which has been found. If this is done, this
# version will be checked against the (potentially) specified required ``VERSION_VAR <version-var>``
# version used in the find_package() call. The EXACT keyword is also Specify the name of a variable that holds the version of the package
# handled. The default messages include information about the required that has been found. This version will be checked against the
# version and the version which has been actually found, both if the (potentially) specified required version given to the
# version is ok or not. If the package supports components, use the :command:`find_package` call, including its ``EXACT`` option.
# HANDLE_COMPONENTS option to enable handling them. In this case, The default messages include information about the required
# find_package_handle_standard_args() will report which components have version and the version which has been actually found, both
# been found and which are missing, and the <packagename>_FOUND variable if the version is ok or not.
# will be set to FALSE if any of the required components (i.e. not the
# ones listed after OPTIONAL_COMPONENTS) are missing. Use the option ``HANDLE_COMPONENTS``
# CONFIG_MODE if your FindXXX.cmake module is a wrapper for a Enable handling of package components. In this case, the command
# find_package(... NO_MODULE) call. In this case VERSION_VAR will be will report which components have been found and which are missing,
# set to <NAME>_VERSION and the macro will automatically check whether and the ``<PackageName>_FOUND`` variable will be set to ``FALSE``
# the Config module was found. Via FAIL_MESSAGE a custom failure if any of the required components (i.e. not the ones listed after
# message can be specified, if this is not used, the default message the ``OPTIONAL_COMPONENTS`` option of :command:`find_package`) are
# will be displayed. missing.
#
# Example for mode 1: ``CONFIG_MODE``
# Specify that the calling find module is a wrapper around a
# :: call to ``find_package(<PackageName> NO_MODULE)``. This implies
# a ``VERSION_VAR`` value of ``<PackageName>_VERSION``. The command
# find_package_handle_standard_args(LibXml2 DEFAULT_MSG will automatically check whether the package configuration file
# LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR) was found.
#
# ``FAIL_MESSAGE <custom-failure-message>``
# Specify a custom failure message instead of using the default
# LibXml2 is considered to be found, if both LIBXML2_LIBRARY and generated message. Not recommended.
# LIBXML2_INCLUDE_DIR are valid. Then also LIBXML2_FOUND is set to
# TRUE. If it is not found and REQUIRED was used, it fails with Example for the simple signature:
# FATAL_ERROR, independent whether QUIET was used or not. If it is
# found, success will be reported, including the content of <var1>. On .. code-block:: cmake
# repeated Cmake runs, the same message won't be printed again.
# find_package_handle_standard_args(LibXml2 DEFAULT_MSG
# Example for mode 2: LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
#
# :: The ``LibXml2`` package is considered to be found if both
# ``LIBXML2_LIBRARY`` and ``LIBXML2_INCLUDE_DIR`` are valid.
# find_package_handle_standard_args(LibXslt Then also ``LibXml2_FOUND`` is set to ``TRUE``. If it is not found
# FOUND_VAR LibXslt_FOUND and ``REQUIRED`` was used, it fails with a
# REQUIRED_VARS LibXslt_LIBRARIES LibXslt_INCLUDE_DIRS :command:`message(FATAL_ERROR)`, independent whether ``QUIET`` was
# VERSION_VAR LibXslt_VERSION_STRING) used or not. If it is found, success will be reported, including
# the content of the first ``<required-var>``. On repeated CMake runs,
# In this case, LibXslt is considered to be found if the variable(s) the same message will not be printed again.
# listed after REQUIRED_VAR are all valid, i.e. LibXslt_LIBRARIES and
# LibXslt_INCLUDE_DIRS in this case. The result will then be stored in Example for the full signature:
# LibXslt_FOUND . Also the version of LibXslt will be checked by using
# the version contained in LibXslt_VERSION_STRING. Since no .. code-block:: cmake
# FAIL_MESSAGE is given, the default messages will be printed.
# find_package_handle_standard_args(LibArchive
# Another example for mode 2: REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
# VERSION_VAR LibArchive_VERSION)
# ::
# In this case, the ``LibArchive`` package is considered to be found if
# find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4) both ``LibArchive_LIBRARY`` and ``LibArchive_INCLUDE_DIR`` are valid.
# find_package_handle_standard_args(Automoc4 CONFIG_MODE) Also the version of ``LibArchive`` will be checked by using the version
# contained in ``LibArchive_VERSION``. Since no ``FAIL_MESSAGE`` is given,
# In this case, FindAutmoc4.cmake wraps a call to find_package(Automoc4 the default messages will be printed.
# NO_MODULE) and adds an additional search directory for automoc4. Here
# the result will be stored in AUTOMOC4_FOUND. The following Another example for the full signature:
# FIND_PACKAGE_HANDLE_STANDARD_ARGS() call produces a proper
# success/error message. .. code-block:: cmake
find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
find_package_handle_standard_args(Automoc4 CONFIG_MODE)
In this case, a ``FindAutmoc4.cmake`` module wraps a call to
``find_package(Automoc4 NO_MODULE)`` and adds an additional search
directory for ``automoc4``. Then the call to
``find_package_handle_standard_args`` produces a proper success/failure
message.
#]=======================================================================]
#============================================================================= #=============================================================================
# Copyright 2007-2009 Kitware, Inc. # Copyright 2007-2009 Kitware, Inc.
@ -239,17 +249,21 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
set(MISSING_VARS "") set(MISSING_VARS "")
set(DETAILS "") set(DETAILS "")
# check if all passed variables are valid # check if all passed variables are valid
unset(${_FOUND_VAR}) set(FPHSA_FOUND_${_NAME} TRUE)
foreach(_CURRENT_VAR ${FPHSA_REQUIRED_VARS}) foreach(_CURRENT_VAR ${FPHSA_REQUIRED_VARS})
if(NOT ${_CURRENT_VAR}) if(NOT ${_CURRENT_VAR})
set(${_FOUND_VAR} FALSE) set(FPHSA_FOUND_${_NAME} FALSE)
set(MISSING_VARS "${MISSING_VARS} ${_CURRENT_VAR}") set(MISSING_VARS "${MISSING_VARS} ${_CURRENT_VAR}")
else() else()
set(DETAILS "${DETAILS}[${${_CURRENT_VAR}}]") set(DETAILS "${DETAILS}[${${_CURRENT_VAR}}]")
endif() endif()
endforeach() endforeach()
if(NOT "${${_FOUND_VAR}}" STREQUAL "FALSE") if(FPHSA_FOUND_${_NAME})
set(${_FOUND_VAR} TRUE) set(${_NAME}_FOUND TRUE)
set(${_NAME_UPPER}_FOUND TRUE)
else()
set(${_NAME}_FOUND FALSE)
set(${_NAME_UPPER}_FOUND FALSE)
endif() endif()
# component handling # component handling
@ -273,7 +287,7 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
set(MISSING_COMPONENTS_MSG "${MISSING_COMPONENTS_MSG} ${comp}") set(MISSING_COMPONENTS_MSG "${MISSING_COMPONENTS_MSG} ${comp}")
if(${_NAME}_FIND_REQUIRED_${comp}) if(${_NAME}_FIND_REQUIRED_${comp})
set(${_FOUND_VAR} FALSE) set(${_NAME}_FOUND FALSE)
set(MISSING_VARS "${MISSING_VARS} ${comp}") set(MISSING_VARS "${MISSING_VARS} ${comp}")
endif() endif()
@ -356,12 +370,12 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
if(VERSION_OK) if(VERSION_OK)
set(DETAILS "${DETAILS}[v${VERSION}(${${_NAME}_FIND_VERSION})]") set(DETAILS "${DETAILS}[v${VERSION}(${${_NAME}_FIND_VERSION})]")
else() else()
set(${_FOUND_VAR} FALSE) set(${_NAME}_FOUND FALSE)
endif() endif()
# print the result: # print the result:
if (${_FOUND_VAR}) if (${_NAME}_FOUND)
FIND_PACKAGE_MESSAGE(${_NAME} "Found ${_NAME}: ${${_FIRST_REQUIRED_VAR}} ${VERSION_MSG} ${COMPONENT_MSG}" "${DETAILS}") FIND_PACKAGE_MESSAGE(${_NAME} "Found ${_NAME}: ${${_FIRST_REQUIRED_VAR}} ${VERSION_MSG} ${COMPONENT_MSG}" "${DETAILS}")
else () else ()
@ -377,6 +391,6 @@ function(FIND_PACKAGE_HANDLE_STANDARD_ARGS _NAME _FIRST_ARG)
endif () endif ()
set(${_FOUND_VAR} ${${_FOUND_VAR}} PARENT_SCOPE) set(${_NAME}_FOUND ${${_NAME}_FOUND} PARENT_SCOPE)
set(${_NAME_UPPER}_FOUND ${${_NAME}_FOUND} PARENT_SCOPE)
endfunction() endfunction()

10
Tests/FindPackageTest/CMakeLists.txt
View File

@ -45,12 +45,18 @@ endif()
find_package(SomePackage) find_package(SomePackage)
if(NOT SomePackage_FOUND) if(NOT SomePackage_FOUND)
message(SEND_ERROR "SomePackage with FOUND_VAR SomePackage_FOUND not found !") message(SEND_ERROR "SomePackage not found !")
endif()
if(NOT SOMEPACKAGE_FOUND)
message(SEND_ERROR "SomePackage compatibility name SOMEPACKAGE_FOUND not set!")
endif() endif()
find_package(UpperCasePackage) find_package(UpperCasePackage)
if(NOT UpperCasePackage_FOUND)
message(SEND_ERROR "UpperCasePackage not found!")
endif()
if(NOT UPPERCASEPACKAGE_FOUND) if(NOT UPPERCASEPACKAGE_FOUND)
message(SEND_ERROR "UpperCasePackage with FOUND_VAR UPPERCASEPACKAGE_FOUND not found !") message(SEND_ERROR "SomePackage compatibility name SOMEPACKAGE_FOUND not set!")
endif() endif()
#----------------------------------------------------------------------------- #-----------------------------------------------------------------------------

3
Tests/FindPackageTest/FindSomePackage.cmake
View File

@ -2,5 +2,4 @@ set(SOP_FOO TRUE)
include(${CMAKE_ROOT}/Modules/FindPackageHandleStandardArgs.cmake) include(${CMAKE_ROOT}/Modules/FindPackageHandleStandardArgs.cmake)
find_package_handle_standard_args(SomePackage REQUIRED_VARS SOP_FOO find_package_handle_standard_args(SomePackage REQUIRED_VARS SOP_FOO)
FOUND_VAR SomePackage_FOUND )

3
Tests/FindPackageTest/FindUpperCasePackage.cmake
View File

@ -2,5 +2,4 @@ set(UCP_FOO TRUE)
include(${CMAKE_ROOT}/Modules/FindPackageHandleStandardArgs.cmake) include(${CMAKE_ROOT}/Modules/FindPackageHandleStandardArgs.cmake)
find_package_handle_standard_args(UpperCasePackage REQUIRED_VARS UCP_FOO find_package_handle_standard_args(UpperCasePackage REQUIRED_VARS UCP_FOO)
FOUND_VAR UPPERCASEPACKAGE_FOUND )