Merge topic 'cmake_policy-get_warning'

0d988f98e5 cmake_policy: Add undocumented GET_WARNING command
f9f96598df Help: Convert FindOpenGL documentation to block comment

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2472

8 files changed, 177 insertions, 144 deletions

diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake
index 31db25a..a7e80e7 100644
--- a/Modules/BundleUtilities.cmake
+++ b/Modules/BundleUtilities.cmake
@@ -230,11 +230,8 @@ if(DEFINED CMAKE_GENERATOR)
   if(_BundleUtilities_CMP0080 STREQUAL "NEW")
     message(FATAL_ERROR "BundleUtilities cannot be included at configure time!")
   elseif(NOT _BundleUtilities_CMP0080 STREQUAL "OLD")
-    message(AUTHOR_WARNING
-      "Policy CMP0080 is not set: BundleUtilities prefers not to be included at configure time. "
-      "Run \"cmake --help-policy CMP0080\" for policy details. "
-      "Use the cmake_policy command to set the policy and suppress this warning."
-      )
+    cmake_policy(GET_WARNING CMP0080 _cmp0080_warning)
+    message(AUTHOR_WARNING "${_cmp0080_warning}\n")
   endif()
 endif()
 
diff --git a/Modules/FindOpenGL.cmake b/Modules/FindOpenGL.cmake
index 4d0786c..832dca2 100644
--- a/Modules/FindOpenGL.cmake
+++ b/Modules/FindOpenGL.cmake
@@ -1,125 +1,126 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-#.rst:
-# FindOpenGL
-# ----------
-#
-# FindModule for OpenGL and GLU.
-#
-# Optional COMPONENTS
-# ^^^^^^^^^^^^^^^^^^^
-#
-# This module respects several optional COMPONENTS: ``EGL``, ``GLX``, and
-# ``OpenGL``.  There are corresponding import targets for each of these flags.
-#
-# IMPORTED Targets
-# ^^^^^^^^^^^^^^^^
-#
-# This module defines the :prop_tgt:`IMPORTED` targets:
-#
-# ``OpenGL::GL``
-#  Defined to the platform-specific OpenGL libraries if the system has OpenGL.
-# ``OpenGL::OpenGL``
-#  Defined to libOpenGL if the system is GLVND-based.
-# ``OpenGL::GLU``
-#  Defined if the system has GLU.
-# ``OpenGL::GLX``
-#  Defined if the system has GLX.
-# ``OpenGL::EGL``
-#  Defined if the system has EGL.
-#
-# Result Variables
-# ^^^^^^^^^^^^^^^^
-#
-# This module sets the following variables:
-#
-# ``OPENGL_FOUND``
-#  True, if the system has OpenGL and all components are found.
-# ``OPENGL_XMESA_FOUND``
-#  True, if the system has XMESA.
-# ``OPENGL_GLU_FOUND``
-#  True, if the system has GLU.
-# ``OpenGL_OpenGL_FOUND``
-#  True, if the system has an OpenGL library.
-# ``OpenGL_GLX_FOUND``
-#  True, if the system has GLX.
-# ``OpenGL_EGL_FOUND``
-#  True, if the system has EGL.
-# ``OPENGL_INCLUDE_DIR``
-#  Path to the OpenGL include directory.
-# ``OPENGL_EGL_INCLUDE_DIRS``
-#  Path to the EGL include directory.
-# ``OPENGL_LIBRARIES``
-#  Paths to the OpenGL library, windowing system libraries, and GLU libraries.
-#  On Linux, this assumes GLX and is never correct for EGL-based targets.
-#  Clients are encouraged to use the ``OpenGL::*`` import targets instead.
-#
-# Cache variables
-# ^^^^^^^^^^^^^^^
-#
-# The following cache variables may also be set:
-#
-# ``OPENGL_egl_LIBRARY``
-#  Path to the EGL library.
-# ``OPENGL_glu_LIBRARY``
-#  Path to the GLU library.
-# ``OPENGL_glx_LIBRARY``
-#  Path to the GLVND 'GLX' library.
-# ``OPENGL_opengl_LIBRARY``
-#  Path to the GLVND 'OpenGL' library
-# ``OPENGL_gl_LIBRARY``
-#  Path to the OpenGL library.  New code should prefer the ``OpenGL::*`` import
-#  targets.
-#
-# Linux-specific
-# ^^^^^^^^^^^^^^
-#
-# Some Linux systems utilize GLVND as a new ABI for OpenGL.  GLVND separates
-# context libraries from OpenGL itself; OpenGL lives in "libOpenGL", and
-# contexts are defined in "libGLX" or "libEGL".  GLVND is currently the only way
-# to get OpenGL 3+ functionality via EGL in a manner portable across vendors.
-# Projects may use GLVND explicitly with target ``OpenGL::OpenGL`` and either
-# ``OpenGL::GLX`` or ``OpenGL::EGL``.
-#
-# Projects may use the ``OpenGL::GL`` target (or ``OPENGL_LIBRARIES`` variable)
-# to use legacy GL interfaces.  These will use the legacy GL library located
-# by ``OPENGL_gl_LIBRARY``, if available.  If ``OPENGL_gl_LIBRARY`` is empty or
-# not found and GLVND is available, the ``OpenGL::GL`` target will use GLVND
-# ``OpenGL::OpenGL`` and ``OpenGL::GLX`` (and the ``OPENGL_LIBRARIES``
-# variable will use the corresponding libraries).  Thus, for non-EGL-based
-# Linux targets, the ``OpenGL::GL`` target is most portable.
-#
-# A ``OpenGL_GL_PREFERENCE`` variable may be set to specify the preferred way
-# to provide legacy GL interfaces in case multiple choices are available.
-# The value may be one of:
-#
-# ``GLVND``
-#  If the GLVND OpenGL and GLX libraries are available, prefer them.
-#  This forces ``OPENGL_gl_LIBRARY`` to be empty.
-#  This is the default if components were requested (since components
-#  correspond to GLVND libraries) or if policy :policy:`CMP0072` is
-#  set to ``NEW``.
-#
-# ``LEGACY``
-#  Prefer to use the legacy libGL library, if available.
-#  This is the default if no components were requested and
-#  policy :policy:`CMP0072` is not set to ``NEW``.
-#
-# For EGL targets the client must rely on GLVND support on the user's system.
-# Linking should use the ``OpenGL::OpenGL OpenGL::EGL`` targets.  Using GLES*
-# libraries is theoretically possible in place of ``OpenGL::OpenGL``, but this
-# module does not currently support that; contributions welcome.
-#
-# ``OPENGL_egl_LIBRARY`` and ``OPENGL_EGL_INCLUDE_DIRS`` are defined in the case of
-# GLVND.  For non-GLVND Linux and other systems these are left undefined.
-#
-# macOS-Specific
-# ^^^^^^^^^^^^^^
-#
-# On OSX FindOpenGL defaults to using the framework version of OpenGL. People
-# will have to change the cache values of OPENGL_glu_LIBRARY and
-# OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
+#[=======================================================================[.rst:
+FindOpenGL
+----------
+
+FindModule for OpenGL and GLU.
+
+Optional COMPONENTS
+^^^^^^^^^^^^^^^^^^^
+
+This module respects several optional COMPONENTS: ``EGL``, ``GLX``, and
+``OpenGL``.  There are corresponding import targets for each of these flags.
+
+IMPORTED Targets
+^^^^^^^^^^^^^^^^
+
+This module defines the :prop_tgt:`IMPORTED` targets:
+
+``OpenGL::GL``
+ Defined to the platform-specific OpenGL libraries if the system has OpenGL.
+``OpenGL::OpenGL``
+ Defined to libOpenGL if the system is GLVND-based.
+``OpenGL::GLU``
+ Defined if the system has GLU.
+``OpenGL::GLX``
+ Defined if the system has GLX.
+``OpenGL::EGL``
+ Defined if the system has EGL.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module sets the following variables:
+
+``OPENGL_FOUND``
+ True, if the system has OpenGL and all components are found.
+``OPENGL_XMESA_FOUND``
+ True, if the system has XMESA.
+``OPENGL_GLU_FOUND``
+ True, if the system has GLU.
+``OpenGL_OpenGL_FOUND``
+ True, if the system has an OpenGL library.
+``OpenGL_GLX_FOUND``
+ True, if the system has GLX.
+``OpenGL_EGL_FOUND``
+ True, if the system has EGL.
+``OPENGL_INCLUDE_DIR``
+ Path to the OpenGL include directory.
+``OPENGL_EGL_INCLUDE_DIRS``
+ Path to the EGL include directory.
+``OPENGL_LIBRARIES``
+ Paths to the OpenGL library, windowing system libraries, and GLU libraries.
+ On Linux, this assumes GLX and is never correct for EGL-based targets.
+ Clients are encouraged to use the ``OpenGL::*`` import targets instead.
+
+Cache variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OPENGL_egl_LIBRARY``
+ Path to the EGL library.
+``OPENGL_glu_LIBRARY``
+ Path to the GLU library.
+``OPENGL_glx_LIBRARY``
+ Path to the GLVND 'GLX' library.
+``OPENGL_opengl_LIBRARY``
+ Path to the GLVND 'OpenGL' library
+``OPENGL_gl_LIBRARY``
+ Path to the OpenGL library.  New code should prefer the ``OpenGL::*`` import
+ targets.
+
+Linux-specific
+^^^^^^^^^^^^^^
+
+Some Linux systems utilize GLVND as a new ABI for OpenGL.  GLVND separates
+context libraries from OpenGL itself; OpenGL lives in "libOpenGL", and
+contexts are defined in "libGLX" or "libEGL".  GLVND is currently the only way
+to get OpenGL 3+ functionality via EGL in a manner portable across vendors.
+Projects may use GLVND explicitly with target ``OpenGL::OpenGL`` and either
+``OpenGL::GLX`` or ``OpenGL::EGL``.
+
+Projects may use the ``OpenGL::GL`` target (or ``OPENGL_LIBRARIES`` variable)
+to use legacy GL interfaces.  These will use the legacy GL library located
+by ``OPENGL_gl_LIBRARY``, if available.  If ``OPENGL_gl_LIBRARY`` is empty or
+not found and GLVND is available, the ``OpenGL::GL`` target will use GLVND
+``OpenGL::OpenGL`` and ``OpenGL::GLX`` (and the ``OPENGL_LIBRARIES``
+variable will use the corresponding libraries).  Thus, for non-EGL-based
+Linux targets, the ``OpenGL::GL`` target is most portable.
+
+A ``OpenGL_GL_PREFERENCE`` variable may be set to specify the preferred way
+to provide legacy GL interfaces in case multiple choices are available.
+The value may be one of:
+
+``GLVND``
+ If the GLVND OpenGL and GLX libraries are available, prefer them.
+ This forces ``OPENGL_gl_LIBRARY`` to be empty.
+ This is the default if components were requested (since components
+ correspond to GLVND libraries) or if policy :policy:`CMP0072` is
+ set to ``NEW``.
+
+``LEGACY``
+ Prefer to use the legacy libGL library, if available.
+ This is the default if no components were requested and
+ policy :policy:`CMP0072` is not set to ``NEW``.
+
+For EGL targets the client must rely on GLVND support on the user's system.
+Linking should use the ``OpenGL::OpenGL OpenGL::EGL`` targets.  Using GLES*
+libraries is theoretically possible in place of ``OpenGL::OpenGL``, but this
+module does not currently support that; contributions welcome.
+
+``OPENGL_egl_LIBRARY`` and ``OPENGL_EGL_INCLUDE_DIRS`` are defined in the case of
+GLVND.  For non-GLVND Linux and other systems these are left undefined.
+
+macOS-Specific
+^^^^^^^^^^^^^^
+
+On OSX FindOpenGL defaults to using the framework version of OpenGL. People
+will have to change the cache values of OPENGL_glu_LIBRARY and
+OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
+#]=======================================================================]
 
 set(_OpenGL_REQUIRED_VARS OPENGL_gl_LIBRARY)
 
@@ -267,11 +268,9 @@ else()
   endif()
 
   if(_OpenGL_GL_POLICY_WARN AND OPENGL_gl_LIBRARY AND OPENGL_opengl_LIBRARY AND OPENGL_glx_LIBRARY)
+    cmake_policy(GET_WARNING CMP0072 _cmp0072_warning)
     message(AUTHOR_WARNING
-      "Policy CMP0072 is not set: FindOpenGL prefers GLVND by default when available.  "
-      "Run \"cmake --help-policy CMP0072\" for policy details.  "
-      "Use the cmake_policy command to set the policy and suppress this warning."
-      "\n"
+      "${_cmp0072_warning}\n"
       "FindOpenGL found both a legacy GL library:\n"
       "  OPENGL_gl_LIBRARY: ${OPENGL_gl_LIBRARY}\n"
       "and GLVND libraries for OpenGL and GLX:\n"
diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake
index f20a53b..edb8294 100644
--- a/Modules/UseSWIG.cmake
+++ b/Modules/UseSWIG.cmake
@@ -554,11 +554,8 @@ function(SWIG_ADD_LIBRARY name)
     set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
   else()
     if (NOT target_name_policy)
-      message(AUTHOR_WARNING
-        "Policy CMP0078 is not set.  "
-        "Run \"cmake --help-policy CMP0078\" for policy details.  "
-        "Use the cmake_policy command to set the policy and suppress this warning."
-        )
+      cmake_policy(GET_WARNING CMP0078 _cmp0078_warning)
+      message(AUTHOR_WARNING "${_cmp0078_warning}\n")
     endif()
     if (NOT DEFINED UseSWIG_TARGET_NAME_PREFERENCE)
       set (UseSWIG_TARGET_NAME_PREFERENCE LEGACY)
diff --git a/Source/cmCMakePolicyCommand.cxx b/Source/cmCMakePolicyCommand.cxx
index adf9ef8..3209ea5 100644
--- a/Source/cmCMakePolicyCommand.cxx
+++ b/Source/cmCMakePolicyCommand.cxx
@@ -46,6 +46,9 @@ bool cmCMakePolicyCommand::InitialPass(std::vector<std::string> const& args,
   if (args[0] == "VERSION") {
     return this->HandleVersionMode(args);
   }
+  if (args[0] == "GET_WARNING") {
+    return this->HandleGetWarningMode(args);
+  }
 
   std::ostringstream e;
   e << "given unknown first argument \"" << args[0] << "\"";
@@ -181,3 +184,33 @@ bool cmCMakePolicyCommand::HandleVersionMode(
   this->Makefile->SetPolicyVersion(version_min, version_max);
   return true;
 }
+
+bool cmCMakePolicyCommand::HandleGetWarningMode(
+  std::vector<std::string> const& args)
+{
+  if (args.size() != 3) {
+    this->SetError(
+      "GET_WARNING must be given exactly 2 additional arguments.");
+    return false;
+  }
+
+  // Get arguments.
+  std::string const& id = args[1];
+  std::string const& var = args[2];
+
+  // Lookup the policy number.
+  cmPolicies::PolicyID pid;
+  if (!cmPolicies::GetPolicyID(id.c_str(), pid)) {
+    std::ostringstream e;
+    e << "GET_WARNING given policy \"" << id
+      << "\" which is not known to this version of CMake.";
+    this->SetError(e.str());
+    return false;
+  }
+
+  // Lookup the policy warning.
+  this->Makefile->AddDefinition(var,
+                                cmPolicies::GetPolicyWarning(pid).c_str());
+
+  return true;
+}
diff --git a/Source/cmCMakePolicyCommand.h b/Source/cmCMakePolicyCommand.h
index b18576c..cca1406 100644
--- a/Source/cmCMakePolicyCommand.h
+++ b/Source/cmCMakePolicyCommand.h
@@ -37,6 +37,7 @@ private:
   bool HandleSetMode(std::vector<std::string> const& args);
   bool HandleGetMode(std::vector<std::string> const& args);
   bool HandleVersionMode(std::vector<std::string> const& args);
+  bool HandleGetWarningMode(std::vector<std::string> const& args);
 };
 
 #endif
diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h
index a469f1e..5c27124 100644
--- a/Source/cmPolicies.h
+++ b/Source/cmPolicies.h
@@ -236,7 +236,7 @@ class cmMakefile;
     "target_link_libraries allows use with targets in other directories.", 3, \
     13, 0, cmPolicies::WARN)                                                  \
   SELECT(POLICY, CMP0080,                                                     \
-         "BundleUtilities cannot be included at configure time", 3, 13, 0,    \
+         "BundleUtilities cannot be included at configure time.", 3, 13, 0,   \
          cmPolicies::WARN)                                                    \
   SELECT(POLICY, CMP0081,                                                     \
          "Relative paths not allowed in LINK_DIRECTORIES target property.",   \
diff --git a/Tests/RunCMake/BundleUtilities/CMP0080-WARN-stderr.txt b/Tests/RunCMake/BundleUtilities/CMP0080-WARN-stderr.txt
index a1a0e8f..460bbae 100644
--- a/Tests/RunCMake/BundleUtilities/CMP0080-WARN-stderr.txt
+++ b/Tests/RunCMake/BundleUtilities/CMP0080-WARN-stderr.txt
@@ -1,4 +1,9 @@
 CMake Warning \(dev\) at .*/Modules/BundleUtilities\.cmake:[0-9]+ \(message\):
-  Policy CMP0080 is not set: BundleUtilities prefers not to be included at
-  configure time\.  Run "cmake --help-policy CMP0080" for policy details\.  Use
-  the cmake_policy command to set the policy and suppress this warning\.
+  Policy CMP0080 is not set: BundleUtilities cannot be included at configure
+  time\.  Run "cmake --help-policy CMP0080" for policy details\.  Use the
+  cmake_policy command to set the policy and suppress this warning\.
+
+Call Stack \(most recent call first\):
+  CMP0080-WARN\.cmake:[0-9]+ \(include\)
+  CMakeLists\.txt:[0-9]+ \(include\)
+This warning is for project developers\.  Use -Wno-dev to suppress it\.
diff --git a/Tests/RunCMake/UseSWIG/CMP0078-WARN-stderr.txt b/Tests/RunCMake/UseSWIG/CMP0078-WARN-stderr.txt
index bc8da4c..f0ed577 100644
--- a/Tests/RunCMake/UseSWIG/CMP0078-WARN-stderr.txt
+++ b/Tests/RunCMake/UseSWIG/CMP0078-WARN-stderr.txt
@@ -1,9 +1,10 @@
-CMake Warning \(dev\) at .*/Modules/UseSWIG.cmake:[0-9]+ \(message\):
-  Policy CMP0078 is not set.  Run "cmake --help-policy CMP0078" for policy
-  details.  Use the cmake_policy command to set the policy and suppress this
-  warning.
+CMake Warning \(dev\) at .*/Modules/UseSWIG\.cmake:[0-9]+ \(message\):
+  Policy CMP0078 is not set: UseSWIG generates standard target names\.  Run
+  "cmake --help-policy CMP0078" for policy details\.  Use the cmake_policy
+  command to set the policy and suppress this warning\.
+
 Call Stack \(most recent call first\):
-  CMP0078-common.cmake:6 \(swig_add_library\)
-  CMP0078-WARN.cmake:1 \(include\)
-  CMakeLists.txt:3 \(include\)
+  CMP0078-common\.cmake:6 \(swig_add_library\)
+  CMP0078-WARN\.cmake:1 \(include\)
+  CMakeLists\.txt:3 \(include\)
 This warning is for project developers.  Use -Wno-dev to suppress it.$