Merge topic 'FPHSA-updates'

84f06d0c FPHSA: Document REQUIRED_VARS recommendation (#15352)
a3ad275c FPHSA: Revise and format documentation
d1a6d15b FPHSA: Always populate the ExactCase_FOUND variable (#15412).

1 files changed, 140 insertions, 126 deletions

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