From eb9c63541af676210052d493dc3dd72b3af28f19 Mon Sep 17 00:00:00 2001
From: Billae <65948826+Billae@users.noreply.github.com>
Date: Tue, 5 Dec 2023 12:59:41 +0100
Subject: documentation: add instructions on how to use external opengl 
 (#40987)

---
 lib/spack/docs/gpu_configuration.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

(limited to 'lib/spack/docs/gpu_configuration.rst')

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``.
-- 
cgit v1.2.3-60-g2f50