Update OpenGL bits of build documentation slightly

This removes most references to GLU, replaces the legacy CMake cache
variables for OpenGL with the modern namespaced target and switches to
$() for command substitution.

Fixes #1580.

(cherry picked from commit d973acc123)

README.md

@@ -238,6 +238,7 @@ skills.
  - Eyal Lotem
  - Aaron Loucks
  - Luflosi
+ - lukect
  - Tristam MacDonald
  - Hans Mackowiak
  - Дмитри Малышев

docs/build.dox

@@ -78,6 +78,11 @@ compiler that the GLFW functions are defined in a DLL.
 The following macros control which OpenGL or OpenGL ES API header is included.
 Only one of these may be defined at a time.
 
+@note GLFW does not provide any of the API headers mentioned below.  They are
+provided by your development environment or your OpenGL, OpenGL ES or Vulkan
+SDK, and most of them can be downloaded from the
+[Khronos Registry](https://www.khronos.org/registry/).
+
 @anchor GLFW_INCLUDE_GLCOREARB
 __GLFW_INCLUDE_GLCOREARB__ makes the GLFW header include the modern
 `GL/glcorearb.h` header (`OpenGL/gl3.h` on macOS) instead of the regular OpenGL
@@ -129,10 +134,6 @@ header selected above.  This should only be used with the standard OpenGL header
 and only for compatibility with legacy code.  GLU has been deprecated and should
 not be used in new code.
 
-@note GLFW does not provide any of the API headers mentioned above.  They must
-be provided by your development environment or your OpenGL, OpenGL ES or Vulkan
-SDK.
-
 @note None of these macros may be defined during the compilation of GLFW itself.
 If your build includes GLFW and you define any these in your build files, make
 sure they are not applied to the GLFW sources.
@@ -166,16 +167,11 @@ must also explicitly link with `gdi32`. Other toolchains including MinGW-w64
 include it in the set of default libraries along with other dependencies like
 `user32` and `kernel32`.
 
-If you are using GLU, you must also link with `glu32`.
-
 The link library for the GLFW DLL is named `glfw3dll`.  When compiling an
 application that uses the DLL version of GLFW, you need to define the @ref
 GLFW_DLL macro _before_ any inclusion of the GLFW header.  This can be done
 either with a compiler switch or by defining it in your source code.
 
-An application using the GLFW DLL does not need to link against any of its
-dependencies, but you still have to link against `glu32` if it uses GLU.
-
 
 @subsection build_link_cmake_source With CMake and GLFW source
 
@@ -196,52 +192,39 @@ set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
 set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
 @endcode
 
-Then add the root directory of the GLFW source tree to your project.  This
+Add the root directory of the GLFW source tree to your project.  This will add
-will add the `glfw` target and the necessary cache variables to your project.
+the `glfw` target to your project.
 
 @code{.cmake}
 add_subdirectory(path/to/glfw)
 @endcode
 
-Once GLFW has been added to the project, link against it with the `glfw` target.
+Once GLFW has been added, link your application against the `glfw` target.
-This adds all link-time dependencies of GLFW as it is currently configured,
+This adds the GLFW library and its link-time dependencies as it is currently
-the include directory for the GLFW header and, when applicable, the @ref
+configured, the include directory for the GLFW header and, when applicable, the
-GLFW_DLL macro.
+@ref GLFW_DLL macro.
 
 @code{.cmake}
 target_link_libraries(myapp glfw)
 @endcode
 
-Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
+Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL,
-OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
+OpenGL ES or Vulkan libraries it needs at runtime.  If your application calls
-If your application calls OpenGL directly, instead of using a modern
+OpenGL directly, instead of using a modern
-[extension loader library](@ref context_glext_auto) you can find it by requiring
+[extension loader library](@ref context_glext_auto), use the OpenGL CMake
-the OpenGL package.
+package.
 
 @code{.cmake}
 find_package(OpenGL REQUIRED)
 @endcode
 
-If OpenGL is found, the `OPENGL_FOUND` variable is true and the
+If OpenGL is found, the `OpenGL::GL` target is added to your project, containing
-`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
+library and include directory paths.  Link against this like above.
 
 @code{.cmake}
-target_include_directories(myapp PUBLIC ${OPENGL_INCLUDE_DIR})
+target_link_libraries(myapp OpenGL::GL)
-target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
 @endcode
 
-The OpenGL CMake package also looks for GLU.  If GLU is found, the
-`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
-`OPENGL_glu_LIBRARY` cache variables can be used.
-
-@code{.cmake}
-target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
-@endcode
-
-@note GLU has been deprecated and should not be used in new code, but some
-legacy code requires it.  See the [section on GLU](@ref moving_glu) in the
-transition guide for suggested replacements.
-
 
 @subsection build_link_cmake_package With CMake and installed GLFW binaries
 
@@ -257,44 +240,30 @@ find_package(glfw3 3.3 REQUIRED)
 @endcode
 
 Once GLFW has been added to the project, link against it with the `glfw` target.
-This adds all link-time dependencies of GLFW as it is currently configured,
+This adds the GLFW library and its link-time dependencies, the include directory
-the include directory for the GLFW header and, when applicable, the @ref
+for the GLFW header and, when applicable, the @ref GLFW_DLL macro.
-GLFW_DLL macro.
 
 @code{.cmake}
 target_link_libraries(myapp glfw)
 @endcode
 
-Note that the dependencies do not include OpenGL or GLU, as GLFW loads any
+Note that the `glfw` target does not depend on OpenGL, as GLFW loads any OpenGL,
-OpenGL, OpenGL ES or Vulkan libraries it needs at runtime and does not use GLU.
+OpenGL ES or Vulkan libraries it needs at runtime.  If your application calls
-If your application calls OpenGL directly, instead of using a modern
+OpenGL directly, instead of using a modern
-[extension loader library](@ref context_glext_auto) you can find it by requiring
+[extension loader library](@ref context_glext_auto), use the OpenGL CMake
-the OpenGL package.
+package.
 
 @code{.cmake}
 find_package(OpenGL REQUIRED)
 @endcode
 
-If OpenGL is found, the `OPENGL_FOUND` variable is true and the
+If OpenGL is found, the `OpenGL::GL` target is added to your project, containing
-`OPENGL_INCLUDE_DIR` and `OPENGL_gl_LIBRARY` cache variables can be used.
+library and include directory paths.  Link against this like above.
 
 @code{.cmake}
-target_include_directories(myapp PUBLIC ${OPENGL_INCLUDE_DIR})
+target_link_libraries(myapp OpenGL::GL)
-target_link_libraries(myapp ${OPENGL_gl_LIBRARY})
 @endcode
 
-The OpenGL CMake package also looks for GLU.  If GLU is found, the
-`OPENGL_GLU_FOUND` variable is true and the `OPENGL_INCLUDE_DIR` and
-`OPENGL_glu_LIBRARY` cache variables can be used.
-
-@code{.cmake}
-target_link_libraries(myapp ${OPENGL_glu_LIBRARY})
-@endcode
-
-@note GLU has been deprecated and should not be used in new code, but some
-legacy code requires it.  See the [section on GLU](@ref moving_glu) in the
-transition guide for suggested replacements.
-
 
 @subsection build_link_pkgconfig With makefiles and pkg-config on Unix
 
@@ -309,42 +278,31 @@ A typical compile and link command-line when using the static version of the
 GLFW library may look like this:
 
 @code{.sh}
-cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --static --libs glfw3`
+cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --static --libs glfw3)
 @endcode
 
 If you are using the shared version of the GLFW library, omit the `--static`
 flag.
 
 @code{.sh}
-cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
+cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3)
 @endcode
 
 You can also use the `glfw3.pc` file without installing it first, by using the
 `PKG_CONFIG_PATH` environment variable.
 
 @code{.sh}
-env PKG_CONFIG_PATH=path/to/glfw/src cc `pkg-config --cflags glfw3` -o myprog myprog.c `pkg-config --libs glfw3`
+env PKG_CONFIG_PATH=path/to/glfw/src cc $(pkg-config --cflags glfw3) -o myprog myprog.c $(pkg-config --libs glfw3)
 @endcode
 
-The dependencies do not include OpenGL or GLU, as GLFW loads any OpenGL, OpenGL
+The dependencies do not include OpenGL, as GLFW loads any OpenGL, OpenGL ES or
-ES or Vulkan libraries it needs at runtime and does not use GLU.  On macOS, GLU
+Vulkan libraries it needs at runtime.  If your application calls OpenGL
-is built into the OpenGL framework, so if you need GLU you don't need to do
+directly, instead of using a modern
-anything extra.  If you need GLU and are using Linux or BSD, you should add the
+[extension loader library](@ref context_glext_auto), you should add the `gl`
-`glu` pkg-config package.
+pkg-config package.
 
 @code{.sh}
-cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --libs glfw3 glu`
+cc $(pkg-config --cflags glfw3 gl) -o myprog myprog.c $(pkg-config --libs glfw3 gl)
-@endcode
-
-@note GLU has been deprecated and should not be used in new code, but some
-legacy code requires it.  See the [section on GLU](@ref moving_glu) in the
-transition guide for suggested replacements.
-
-If you are using the static version of the GLFW library, make sure you don't
-link statically against GLU.
-
-@code{.sh}
-cc `pkg-config --cflags glfw3 glu` -o myprog myprog.c `pkg-config --static --libs glfw3` `pkg-config --libs glu`
 @endcode
 
 
@@ -378,9 +336,7 @@ for `-lglfw`.
 Note that you do not add the `.framework` extension to a framework when linking
 against it from the command-line.
 
-The OpenGL framework contains both the OpenGL and GLU APIs, so there is nothing
+@note Your machine may have `libGL.*.dylib` style OpenGL library, but that is
-special to do when using GLU.  Also note that even though your machine may have
+for the X Window System and will not work with the macOS native version of GLFW.
-`libGL`-style OpenGL libraries, they are for use with the X Window System and
-will _not_ work with the macOS native version of GLFW.
 
 */