This module provides a function intended to be used in Find Modules implementing 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.
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 find_package() call.
The options are:
Example for the simple signature:
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 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:
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:
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.