From e48acfc501cec71337a6dbe04e9d61e9224fba6b Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 8 Sep 2017 10:41:46 -0400 Subject: CMakeFindDependencyMacro: Document return() behavior and caveats The `find_dependency` macro is designed to be called from Package Configuration Files, not from Find Modules. The return() behavior is particularly problematic for find modules. Document this more clearly. Issue: #17257 --- Modules/CMakeFindDependencyMacro.cmake | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/Modules/CMakeFindDependencyMacro.cmake b/Modules/CMakeFindDependencyMacro.cmake index 0ad4531..6a89fff 100644 --- a/Modules/CMakeFindDependencyMacro.cmake +++ b/Modules/CMakeFindDependencyMacro.cmake @@ -5,18 +5,29 @@ CMakeFindDependencyMacro ------------------------- -:: +.. command:: find_dependency + + The ``find_dependency()`` macro wraps a :command:`find_package` call for + a package dependency:: find_dependency( [...]) + It is designed to be used in a + :ref:`Package Configuration File ` + (``Config.cmake``). ``find_dependency`` forwards the correct + parameters for ``QUIET`` and ``REQUIRED`` which were passed to + the original :command:`find_package` call. Any additional arguments + specified are forwarded to :command:`find_package`. + + If the dependency could not be found it sets an informative diagnostic + message and calls :command:`return` to end processing of the calling + package configuration file and return to the :command:`find_package` + command that loaded it. -``find_dependency()`` wraps a :command:`find_package` call for a package -dependency. It is designed to be used in a Config.cmake file, and it -forwards the correct parameters for QUIET and REQUIRED which were passed to -the original :command:`find_package` call. It also sets an informative -diagnostic message if the dependency could not be found. + .. note:: -Any additional arguments specified are forwarded to :command:`find_package`. + The call to :command:`return` makes this macro unsuitable to call + from :ref:`Find Modules`. #]=======================================================================] macro(find_dependency dep) -- cgit v0.12