From 07a05079d366fad306117a99267b71141d3731b2 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 8 Sep 2017 10:30:24 -0400 Subject: CMakeFindDependencyMacro: Convert documentation to bracket comment --- Modules/CMakeFindDependencyMacro.cmake | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Modules/CMakeFindDependencyMacro.cmake b/Modules/CMakeFindDependencyMacro.cmake index 81606ce..0ad4531 100644 --- a/Modules/CMakeFindDependencyMacro.cmake +++ b/Modules/CMakeFindDependencyMacro.cmake @@ -1,23 +1,23 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -#.rst: -# CMakeFindDependencyMacro -# ------------------------- -# -# :: -# -# find_dependency( [...]) -# -# -# ``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. -# -# Any additional arguments specified are forwarded to :command:`find_package`. -# +#[=======================================================================[.rst: +CMakeFindDependencyMacro +------------------------- + +:: + + find_dependency( [...]) + + +``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. + +Any additional arguments specified are forwarded to :command:`find_package`. +#]=======================================================================] macro(find_dependency dep) if (NOT ${dep}_FOUND) -- cgit v0.12 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