09: EGL is source-built now, so four of the five packages are

compat.egl bound xim:libglvnd, and its own comment recorded why that was wrong:
libglvnd IS a separable project, so by the criterion it should have been a
source build; it stayed a binding for effort alone. It is now freedesktop.egl,
out of mcpplibs/libglvnd, and GBM is the only binding left in this example --
which is the honest picture, since GBM is the one that genuinely fails the test.

That package also carries libGLdispatch.so.0, as a sibling workspace member
reached by a path dependency rather than a second index entry, because being the
one dispatch point in a process is what GLVND is for.

The program now prints __EGL_VENDOR_LIBRARY_DIRS beside GBM_BACKENDS_PATH. Both
loaders in this stack dlopen something the environment has to point them at, and
the EGL package compiles in an EMPTY default rather than upstream's: a wrong
compiled-in path is worse than none, because it would make a missing declaration
load the HOST's driver into a sandboxed process, silently and successfully.

Measured end to end, with every library attributed through the binary's own
loader -- libEGL.so.1, libGLdispatch.so.0, libdrm.so.2 and both libwayland
libraries come from this project's build output, libgbm.so.1 from compat-x-libgbm
(the binding), and nothing from a host path. eglInitialize reaches
"EGL 1.5, vendor Mesa Project" through the source-built dispatch.

Author: speak-agent

examples/09-graphics-stack/README.md

@@ -9,7 +9,8 @@ mcpp run
 
 ```
 == the graphics stack, resolved from the index ==
-  GBM_BACKENDS_PATH = …/subos/default/usr/lib/gbm
+  GBM_BACKENDS_PATH         = …/subos/default/usr/lib/gbm
+  __EGL_VENDOR_LIBRARY_DIRS = …/subos/default/share/glvnd/egl_vendor.d
   wl_display_create        0x3f798be0
 -- DRM node -> GBM device -> EGL display --
   /dev/dri/renderD128
@@ -123,10 +124,13 @@ the ecosystem already owns, where building it would mean forking that project.
 |---|---|---|
 | `compat.libdrm` | source | `drmModeGetResources`, `drmModeAddFB2`, `drmModeSetCrtc` — the KMS side |
 | `compat.libgbm` | binds `xim:mesa` | `gbm_create_device`, `gbm_bo_create` — buffers out of a DRM device |
-| `compat.egl` | binds `xim:libglvnd` | `eglGetPlatformDisplay(EGL_PLATFORM_GBM_KHR, …)` — rendering onto them |
+| `freedesktop.egl` | source | `eglGetPlatformDisplay(EGL_PLATFORM_GBM_KHR, …)` — rendering onto them, and `import egl;` |
 | `freedesktop.wayland` | source | `libwayland-client.so.0`, and `import wayland.client;` |
 | `freedesktop.wayland-server` | source | `libwayland-server.so.0`, and `import wayland.server;` |
 
+**Four of the five are source builds.** GBM is the only binding, and the
+paragraphs below are about why the line falls where it does.
+
 libdrm passes the test — an independent freedesktop project with its own
 releases — so it is compiled here, five translation units with no dependencies
 at all. GBM fails it: `src/gbm/meson.build` is `link_with: [libloader]`, and
@@ -152,9 +156,20 @@ through it. That only holds because the package builds a *shared* library with
 the canonical soname; merged into the consumer as objects there would be two
 copies of libdrm's internal state over one set of file descriptors.
 
-`compat.egl` is a binding for a duller reason: libglvnd IS separable, but
-`libEGL.so` also needs its Python-generated dispatch stubs, `winsys_dispatch`
-and the whole of `libGLdispatch.so`, so it has not been done yet.
+EGL used to be the exception that proved the criterion was being applied
+loosely. It was a binding for a duller reason than GBM's — libglvnd IS
+separable, but `libEGL.so` also needs its generated dispatch stubs,
+`winsys_dispatch` and the whole of `libGLdispatch.so`, so it simply had not
+been done. "Not done yet" is not a shape, so it is now a source build out of
+[mcpplibs/libglvnd](https://github.com/mcpplibs/libglvnd), and the dispatch
+tables upstream generates with ~1000 lines of Python are checked into that fork
+and diffed by its CI rather than regenerated during your build.
+
+That package also carries `libGLdispatch.so.0`, as a **sibling workspace member
+reached by a path dependency** rather than as a second index entry. GLVND
+exists to be the one dispatch point in a process; two index entries would let a
+project name both and resolve two instances, and — by the same soname-reuse
+rule as above — one would be mapped and the other silently discarded.
 
 One honest gap, since "Mesa/Vulkan" usually get named together: Vulkan is not
 part of this example and is not in the same state. `compat.vulkan-runtime`
@@ -164,15 +179,25 @@ to bind to yet. The GBM/KMS/EGL/Wayland stack above has no such edge.
 
 ## Two things worth knowing
 
-**`GBM_BACKENDS_PATH` is not set by any of these packages.** libgbm is a
-loader: `gbm_create_device()` dlopens `<path>/<driver>_gbm.so`, and the path
-Mesa compiles in is `/usr/lib/gbm` — correct on a distribution, wrong the
-moment the payload lives anywhere else. Setting that variable is Mesa's own
-mechanism and the *environment's* job, which is where every relocated stack
-puts it (Valve's pressure-vessel, Nix, Conda all do exactly this). Here
-`xim:mesa` declares it into the SubOS and mcpp carries SubOS declarations into
-the processes it launches, so it is simply already set — which is why the
-program prints it rather than computing it.
+**Neither `GBM_BACKENDS_PATH` nor `__EGL_VENDOR_LIBRARY_DIRS` is set by any of
+these packages**, and both are needed, because two of the five are *loaders*.
+`gbm_create_device()` dlopens `<path>/<driver>_gbm.so`; `eglInitialize()`
+dlopens whatever a JSON file in the vendor directory names. The paths upstream
+compiles in — `/usr/lib/gbm`, `<prefix>/share/glvnd/egl_vendor.d` — are correct
+on a distribution and wrong the moment the payload lives anywhere else.
+
+Those two variables are Mesa's and GLVND's own mechanisms, and setting them is
+the *environment's* job, which is where every relocated stack puts it (Valve's
+pressure-vessel, Nix, Conda all do exactly this). Here `xim:mesa` declares both
+into the SubOS and mcpp carries SubOS declarations into the processes it
+launches, so they are simply already set — which is why the program prints them
+rather than computing them.
+
+`freedesktop.egl` goes one step further and compiles in an **empty** default
+rather than upstream's. A wrong compiled-in path is worse than no path: it
+would make a missing declaration load the *host's* driver into a sandboxed
+process, silently and successfully. Empty makes the same situation say "no
+vendor found".
 
 **The wayland client and server are separate packages**, and this example asks
 for both because it creates a `wl_display` on the server side. That is not a

examples/09-graphics-stack/mcpp.toml

@@ -8,19 +8,36 @@ standard = "c++23"
 # The versions are the upstream projects' own release numbers, and the shapes
 # differ on one criterion: a library is BUILT FROM SOURCE when upstream ships it
 # as a separable unit, and BOUND to the ecosystem's payload when it is an
-# internal target of a project the ecosystem already owns. libdrm and wayland
-# pass that test; GBM does not — it is a build target inside Mesa, and a loader
-# whose backends are Mesa's own.
+# internal target of a project the ecosystem already owns.
+#
+# Exactly ONE of the four is a binding, and it is GBM: it is a build target
+# inside Mesa (`src/gbm/meson.build` is `link_with: [libloader]`, which wants
+# ~120 TUs of Mesa's internal util library for one function), and it is a
+# LOADER whose backends are Mesa's own `dri_gbm.so` — built apart from Mesa it
+# would have nothing to load. libdrm, EGL and wayland all pass the test and are
+# built from source.
 [target.'cfg(linux)'.dependencies.compat]
 libdrm = "2.4.134"       # source-built; the KMS side: modes, CRTCs, framebuffers
 libgbm = "25.0.7"        # Mesa's GBM: buffer allocation out of a DRM device
-egl    = "1.7.0"         # libglvnd's EGL dispatch: rendering onto those buffers
 
-# wayland is source-built too, out of mcpplibs/wayland — the client and the
-# server are distinct SONAMEs that Mesa's libEGL_mesa needs BOTH of, so they are
-# two packages rather than one with an ldflags escape hatch. Each also ships a
-# C++23 module wrapper; this example uses the headers, and 09's sibling text
-# explains what `import wayland.client;` would change (nothing but the include).
+# These three are source builds out of forks that add mcpp support and patch no
+# upstream file.
+#
+# wayland is two packages rather than one with an ldflags escape hatch: the
+# client and the server are distinct SONAMEs that Mesa's libEGL_mesa needs BOTH
+# of, and mcpp links every library target against all of a package's sources.
+#
+# egl is libglvnd's vendor-neutral dispatch — the piece that makes GBM useful
+# for RENDERING rather than only for allocation. It also carries
+# `libGLdispatch.so.0`, as a sibling workspace member reached by a path
+# dependency rather than as a second index entry, because being the ONE dispatch
+# point in a process is what GLVND is for.
+#
+# All three ship a C++23 module wrapper too. This example uses the headers, and
+# for a reason worth knowing: `EGL_PLATFORM_GBM_KHR` and friends are MACROS, and
+# no module can export a macro — so `import egl;` replaces the declarations but
+# never the `#include <EGL/eglext.h>` that the constants come from.
 [target.'cfg(linux)'.dependencies.freedesktop]
 wayland        = "1.26.0"
 wayland-server = "1.26.0"
+egl            = "1.7.0"

examples/09-graphics-stack/src/main.cpp

@@ -10,7 +10,7 @@
 #include <xf86drm.h>          // compat.libdrm
 #include <xf86drmMode.h>
 #include <drm_fourcc.h>
-#include <EGL/egl.h>          // compat.egl
+#include <EGL/egl.h>          // freedesktop.egl
 #include <EGL/eglext.h>
 #include <wayland-client.h>   // compat.wayland
 #include <wayland-server-core.h>
@@ -43,13 +43,18 @@ int main()
 {
     std::puts("== the graphics stack, resolved from the index ==");
 
-    // Where the GBM backends are found. Nothing in this program and nothing in
-    // compat.libgbm sets this: `xim:mesa` declares it into the SubOS through
-    // the graphics discovery layer, and mcpp carries SubOS declarations into
-    // the processes it launches.
-    const char *backends = std::getenv("GBM_BACKENDS_PATH");
-    std::printf("  GBM_BACKENDS_PATH = %s\n",
-                backends ? backends : "<unset — the ecosystem did not supply it>");
+    // Where the two LOADERS in this stack find what they dlopen. Nothing in
+    // this program and none of the packages sets either: `xim:mesa` declares
+    // both into the SubOS through the graphics discovery layer, and mcpp
+    // carries SubOS declarations into the processes it launches.
+    //
+    // GBM_BACKENDS_PATH        -> gbm_create_device() dlopens <path>/<drv>_gbm.so
+    // __EGL_VENDOR_LIBRARY_DIRS -> eglInitialize() dlopens what a JSON there names
+    for (const char *name : {"GBM_BACKENDS_PATH", "__EGL_VENDOR_LIBRARY_DIRS"}) {
+        const char *value = std::getenv(name);
+        std::printf("  %-25s = %s\n", name,
+                    value ? value : "<unset — the ecosystem did not supply it>");
+    }
 
     // Wayland: build a server-side display. No socket is bound, so this needs
     // no session and no privileges — the cheapest proof the library is live.