documentation: add instructions on how to use external opengl (#40987)

1 files changed, 25 insertions, 0 deletions

diff --git a/lib/spack/docs/gpu_configuration.rst b/lib/spack/docs/gpu_configuration.rst
index 1f807bb3b8..610431342f 100644
--- a/lib/spack/docs/gpu_configuration.rst
+++ b/lib/spack/docs/gpu_configuration.rst
@@ -111,3 +111,28 @@ CUDA is split into fewer components and is simpler to specify:
          prefix: /opt/cuda/cuda-11.0.2/
 
 where ``/opt/cuda/cuda-11.0.2/lib/`` contains ``libcudart.so``.
+
+
+
+-----------------------------------
+Using an External OpenGL API
+-----------------------------------
+Depending on whether we have a graphics card or not, we may choose to use OSMesa or GLX to implement the OpenGL API.
+
+If a graphics card is unavailable, OSMesa is recommended and can typically be built with Spack.
+However, if we prefer to utilize the system GLX tailored to our graphics card, we need to declare it as an external. Here's how to do it:
+
+
+.. code-block:: yaml
+
+  packages:
+    libglx:
+      require: [opengl]
+    opengl:
+      buildable: false
+      externals:
+      - prefix: /usr/
+        spec: opengl@4.6
+
+Note that prefix has to be the root of both the libraries and the headers, using is /usr not the path the the lib.
+To know which spec for opengl is available use ``cd /usr/include/GL && grep -Ri gl_version``.