summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2015-04-15 15:30:28 (GMT)
committerBrad King <brad.king@kitware.com>2015-04-17 14:46:24 (GMT)
commita3ad275ce08784493267604d57207fce14602c48 (patch)
tree592d06d7b8b6f16e29a7637dae0f9d68f34568a5
parentd1a6d15bcd4df3d3e347411bd457be32275fb594 (diff)
downloadCMake-a3ad275ce08784493267604d57207fce14602c48.zip
CMake-a3ad275ce08784493267604d57207fce14602c48.tar.gz
CMake-a3ad275ce08784493267604d57207fce14602c48.tar.bz2
FPHSA: Revise and format documentation
Use better reStructuredText markup and add cross-references.
-rw-r--r--Modules/FindPackageHandleStandardArgs.cmake233
1 files changed, 123 insertions, 110 deletions
diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake
index bf5e921..a88eaec 100644
--- a/Modules/FindPackageHandleStandardArgs.cmake
+++ b/Modules/FindPackageHandleStandardArgs.cmake
@@ -1,113 +1,126 @@
-#.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(PackageName). 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
-# <PackageName>_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"] )
-#
-# The FOUND_VAR option is obsolete. ``FIND_PACKAGE_HANDLE_STANDARD_ARGS``
-# always populates ``<PackageName>_FOUND``. For backward compatibility,
-# it also always populates ``<UPPERCASE_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
-# 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(<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.
+
+ ``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.