FindOpenGL: Add policy CMP0072 to prefer GLVND for legacy GL

Fixes: #17449

3 files changed, 39 insertions, 0 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`.