diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake index bf5e92185..a88eaecd2 100644 --- a/Modules/FindPackageHandleStandardArgs.cmake +++ b/Modules/FindPackageHandleStandardArgs.cmake @@ -1,113 +1,126 @@ -#.rst: -# FindPackageHandleStandardArgs -# ----------------------------- -# -# -# -# FIND_PACKAGE_HANDLE_STANDARD_ARGS( ... ) -# -# This function is intended to be used in FindXXX.cmake modules files. -# It handles the REQUIRED, QUIET and version-related arguments to -# find_package(PackageName). It also sets the _FOUND -# variable. The package is considered found if all variables ... -# 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( -# (DEFAULT_MSG|"Custom failure message") ... ) -# -# If the variables to are all valid, then -# _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( -# [FOUND_VAR ] -# [REQUIRED_VARS ...] -# [VERSION_VAR ] -# [HANDLE_COMPONENTS] -# [CONFIG_MODE] -# [FAIL_MESSAGE "Custom failure message"] ) -# -# The FOUND_VAR option is obsolete. ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` -# always populates ``_FOUND``. For backward compatibility, -# it also always populates ``_FOUND``. -# -# As in the simple mode, if through are all valid, -# _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 _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 _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 . On -# repeated Cmake runs, the same message won't be printed again. -# -# Example for mode 2: -# -# :: -# -# find_package_handle_standard_args(LibXslt -# 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. 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. 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()` calls. It handles the +``REQUIRED``, ``QUIET`` and version-related arguments of ``find_package``. +It also sets the ``_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( + (DEFAULT_MSG|) + ... + ) + + find_package_handle_standard_args( + [FOUND_VAR ] + [REQUIRED_VARS ...] + [VERSION_VAR ] + [HANDLE_COMPONENTS] + [CONFIG_MODE] + [FAIL_MESSAGE ] + ) + + The ``_FOUND`` variable will be set to ``TRUE`` if all + the variables ``...`` 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|)`` + 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 `` + Obselete. Specifies either ``_FOUND`` or + ``_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 ...`` + Specify the variables which are required for this package. + + ``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 ``_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( NO_MODULE)``. This implies + a ``VERSION_VAR`` value of ``_VERSION``. The command + will automatically check whether the package configuration file + was found. + + ``FAIL_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 ````. 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.