FindOpenGL: Add policy CMP0072 to prefer GLVND for legacy GL

Fixes: #17449

17 files changed, 135 insertions, 6 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index c81ba59..96d5c7d 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.11
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072>
+
 Policies Introduced by CMake 3.10
 =================================
 
diff --git a/Help/policy/CMP0072.rst b/Help/policy/CMP0072.rst
new file mode 100644
index 0000000..3abbad7
--- /dev/null
+++ b/Help/policy/CMP0072.rst
@@ -0,0 +1,26 @@
+CMP0072
+-------
+
+:module:`FindOpenGL` prefers GLVND by default when available.
+
+The :module:`FindOpenGL` module provides an ``OpenGL::GL`` target and an
+``OPENGL_LIBRARIES`` variable for projects to use for legacy GL interfaces.
+When both a legacy GL library (e.g. ``libGL.so``) and GLVND libraries
+for OpenGL and GLX (e.g. ``libOpenGL.so`` and ``libGLX.so``) are available,
+the module must choose between them.  It documents an ``OpenGL_GL_PREFERENCE``
+variable that can be used to specify an explicit preference.  When no such
+preference is set, the module must choose a default preference.
+
+CMake 3.11 and above prefer to choose GLVND libraries.  This policy provides
+compatibility with projects that expect the legacy GL library to be used.
+
+The ``OLD`` behavior for this policy is to set ``OpenGL_GL_PREFERENCE`` to
+``LEGACY``.  The ``NEW`` behavior for this policy is to set
+``OpenGL_GL_PREFERENCE`` to ``GLVND``.
+
+This policy was introduced in CMake version 3.11.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/FindOpenGL-glvnd-policy.rst b/Help/release/dev/FindOpenGL-glvnd-policy.rst
new file mode 100644
index 0000000..3348acf
--- /dev/null
+++ b/Help/release/dev/FindOpenGL-glvnd-policy.rst
@@ -0,0 +1,5 @@
+FindOpenGL-glvnd-policy
+-----------------------
+
+* The :module:`FindOpenGL` module now prefers GLVND libraries if available.
+  See policy :policy:`CMP0072`.
diff --git a/Modules/FindOpenGL.cmake b/Modules/FindOpenGL.cmake
index 9063492..91db5af 100644
--- a/Modules/FindOpenGL.cmake
+++ b/Modules/FindOpenGL.cmake
@@ -99,11 +99,13 @@
 #  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).
+#  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.
+#  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*
@@ -220,6 +222,7 @@ else()
           /usr/shlib /usr/X11R6/lib
   )
 
+  set(_OpenGL_GL_POLICY_WARN 0)
   if(NOT DEFINED OpenGL_GL_PREFERENCE)
     set(OpenGL_GL_PREFERENCE "")
   endif()
@@ -237,8 +240,17 @@ else()
     set(OpenGL_GL_PREFERENCE "GLVND")
   else()
     # No preference was explicitly specified and no GLVND components were
-    # requested.  Prefer libGL for legacy GL.
-    set(OpenGL_GL_PREFERENCE "LEGACY")
+    # requested.  Use a policy to choose the default.
+    cmake_policy(GET CMP0072 _OpenGL_GL_POLICY)
+    if("x${_OpenGL_GL_POLICY}x" STREQUAL "xNEWx")
+      set(OpenGL_GL_PREFERENCE "GLVND")
+    else()
+      set(OpenGL_GL_PREFERENCE "LEGACY")
+      if("x${_OpenGL_GL_POLICY}x" STREQUAL "xx")
+        set(_OpenGL_GL_POLICY_WARN 1)
+      endif()
+    endif()
+    unset(_OpenGL_GL_POLICY)
   endif()
 
   if("x${OpenGL_GL_PREFERENCE}x" STREQUAL "xGLVNDx" AND OPENGL_opengl_LIBRARY AND OPENGL_glx_LIBRARY)
@@ -257,6 +269,23 @@ else()
       )
   endif()
 
+  if(_OpenGL_GL_POLICY_WARN AND OPENGL_gl_LIBRARY AND OPENGL_opengl_LIBRARY AND OPENGL_glx_LIBRARY)
+    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"
+      "FindOpenGL found both a legacy GL library:\n"
+      "  OPENGL_gl_LIBRARY: ${OPENGL_gl_LIBRARY}\n"
+      "and GLVND libraries for OpenGL and GLX:\n"
+      "  OPENGL_opengl_LIBRARY: ${OPENGL_opengl_LIBRARY}\n"
+      "  OPENGL_glx_LIBRARY: ${OPENGL_glx_LIBRARY}\n"
+      "OpenGL_GL_PREFERENCE has not been set to \"GLVND\" or \"LEGACY\", so for "
+      "compatibility with CMake 3.10 and below the legacy GL library will be used."
+      )
+  endif()
+  unset(_OpenGL_GL_POLICY_WARN)
+
   # FPHSA cannot handle "this OR that is required", so we conditionally set what
   # it must look for.  First clear any previous config we might have done:
   set(_OpenGL_REQUIRED_VARS)
diff --git a/Source/cmPolicies.h b/Source/cmPolicies.h
index f614dca..c39f927 100644
--- a/Source/cmPolicies.h
+++ b/Source/cmPolicies.h
@@ -211,7 +211,10 @@ class cmMakefile;
          "Define file(GENERATE) behavior for relative paths.", 3, 10, 0,      \
          cmPolicies::WARN)                                                    \
   SELECT(POLICY, CMP0071, "Let AUTOMOC and AUTOUIC process GENERATED files.", \
-         3, 10, 0, cmPolicies::WARN)
+         3, 10, 0, cmPolicies::WARN)                                          \
+  SELECT(POLICY, CMP0072,                                                     \
+         "FindOpenGL prefers GLVND by default when available.", 3, 11, 0,     \
+         cmPolicies::WARN)
 
 #define CM_SELECT_ID(F, A1, A2, A3, A4, A5, A6) F(A1)
 #define CM_FOR_EACH_POLICY_ID(POLICY)                                         \
diff --git a/Tests/FindOpenGL/Test/CMakeLists.txt b/Tests/FindOpenGL/Test/CMakeLists.txt
index 3b5ffee..9004a98 100644
--- a/Tests/FindOpenGL/Test/CMakeLists.txt
+++ b/Tests/FindOpenGL/Test/CMakeLists.txt
@@ -1,4 +1,5 @@
-cmake_minimum_required(VERSION 3.9)
+cmake_minimum_required(VERSION 3.10)
+cmake_policy(SET CMP0072 NEW)
 project(TestFindOpenGL C)
 include(CTest)
 
diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index 5d584af..07d9f08 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -144,6 +144,7 @@ add_RunCMake_test(ExternalData)
 add_RunCMake_test(FeatureSummary)
 add_RunCMake_test(FPHSA)
 add_RunCMake_test(FindBoost)
+add_RunCMake_test(FindOpenGL)
 if(NOT CMAKE_C_COMPILER_ID MATCHES "Watcom")
   add_RunCMake_test(GenerateExportHeader)
 endif()
diff --git a/Tests/RunCMake/FindOpenGL/CMP0072-NEW-stdout.txt b/Tests/RunCMake/FindOpenGL/CMP0072-NEW-stdout.txt
new file mode 100644
index 0000000..f5ee220
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-NEW-stdout.txt
@@ -0,0 +1,3 @@
+-- OpenGL_GL_PREFERENCE='GLVND'
+-- OPENGL_gl_LIBRARY=''
+-- OPENGL_LIBRARIES='OpenGL;GLX;GLU'
diff --git a/Tests/RunCMake/FindOpenGL/CMP0072-NEW.cmake b/Tests/RunCMake/FindOpenGL/CMP0072-NEW.cmake
new file mode 100644
index 0000000..6cbbeec
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-NEW.cmake
@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0072 NEW)
+include(CMP0072-common.cmake)
diff --git a/Tests/RunCMake/FindOpenGL/CMP0072-OLD-stdout.txt b/Tests/RunCMake/FindOpenGL/CMP0072-OLD-stdout.txt
new file mode 100644
index 0000000..22df1b1
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-OLD-stdout.txt
@@ -0,0 +1,3 @@
+-- OpenGL_GL_PREFERENCE='LEGACY'
+-- OPENGL_gl_LIBRARY='GL'
+-- OPENGL_LIBRARIES='GL;GLU'
diff --git a/Tests/RunCMake/FindOpenGL/CMP0072-OLD.cmake b/Tests/RunCMake/FindOpenGL/CMP0072-OLD.cmake
new file mode 100644
index 0000000..6d57004
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-OLD.cmake
@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0072 OLD)
+include(CMP0072-common.cmake)
diff --git a/Tests/RunCMake/FindOpenGL/CMP0072-WARN-stderr.txt b/Tests/RunCMake/FindOpenGL/CMP0072-WARN-stderr.txt
new file mode 100644
index 0000000..f26f217
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-WARN-stderr.txt
@@ -0,0 +1,21 @@
+^CMake Warning \(dev\) at .*/Modules/FindOpenGL.cmake:[0-9]+ \(message\):
+  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.
+
+  FindOpenGL found both a legacy GL library:
+
+    OPENGL_gl_LIBRARY: GL
+
+  and GLVND libraries for OpenGL and GLX:
+
+    OPENGL_opengl_LIBRARY: OpenGL
+    OPENGL_glx_LIBRARY: GLX
+
+  OpenGL_GL_PREFERENCE has not been set to "GLVND" or "LEGACY", so for
+  compatibility with CMake 3.10 and below the legacy GL library will be used.
+Call Stack \(most recent call first\):
+  CMP0072-common.cmake:[0-9]+ \(find_package\)
+  CMP0072-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/FindOpenGL/CMP0072-WARN-stdout.txt b/Tests/RunCMake/FindOpenGL/CMP0072-WARN-stdout.txt
new file mode 100644
index 0000000..22df1b1
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-WARN-stdout.txt
@@ -0,0 +1,3 @@
+-- OpenGL_GL_PREFERENCE='LEGACY'
+-- OPENGL_gl_LIBRARY='GL'
+-- OPENGL_LIBRARIES='GL;GLU'
diff --git a/Tests/RunCMake/FindOpenGL/CMP0072-WARN.cmake b/Tests/RunCMake/FindOpenGL/CMP0072-WARN.cmake
new file mode 100644
index 0000000..459c458
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-WARN.cmake
@@ -0,0 +1 @@
+include(CMP0072-common.cmake)
diff --git a/Tests/RunCMake/FindOpenGL/CMP0072-common.cmake b/Tests/RunCMake/FindOpenGL/CMP0072-common.cmake
new file mode 100644
index 0000000..3fe8030
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMP0072-common.cmake
@@ -0,0 +1,13 @@
+set(CYGWIN 0)
+set(WIN32 0)
+set(APPLE 0)
+set(OPENGL_INCLUDE_DIR GL/include)
+set(OPENGL_GLX_INCLUDE_DIR GLX/include)
+set(OPENGL_gl_LIBRARY GL)
+set(OPENGL_opengl_LIBRARY OpenGL)
+set(OPENGL_glx_LIBRARY GLX)
+set(OPENGL_glu_LIBRARY GLU)
+find_package(OpenGL)
+message(STATUS "OpenGL_GL_PREFERENCE='${OpenGL_GL_PREFERENCE}'")
+message(STATUS "OPENGL_gl_LIBRARY='${OPENGL_gl_LIBRARY}'")
+message(STATUS "OPENGL_LIBRARIES='${OPENGL_LIBRARIES}'")
diff --git a/Tests/RunCMake/FindOpenGL/CMakeLists.txt b/Tests/RunCMake/FindOpenGL/CMakeLists.txt
new file mode 100644
index 0000000..bf2ef15
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/CMakeLists.txt
@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.10)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)
diff --git a/Tests/RunCMake/FindOpenGL/RunCMakeTest.cmake b/Tests/RunCMake/FindOpenGL/RunCMakeTest.cmake
new file mode 100644
index 0000000..fcc130f
--- /dev/null
+++ b/Tests/RunCMake/FindOpenGL/RunCMakeTest.cmake
@@ -0,0 +1,5 @@
+include(RunCMake)
+
+run_cmake(CMP0072-WARN)
+run_cmake(CMP0072-OLD)
+run_cmake(CMP0072-NEW)