feat: declare GLFW GLX runtime metadata

Author: Sunrisepeak

.agents/docs/2026-06-03-gl-runtime-packages-plan.md

@@ -42,7 +42,7 @@ requirements as separate concepts.
     is practical in current mcpp package descriptors.
   - If libglvnd source packaging is not yet practical, keep this task open and
     document the exact blocker rather than replacing it with a host shim.
-- [ ] Update `compat.glfw` runtime metadata.
+- [x] Update `compat.glfw` runtime metadata.
   - Candidate file: `pkgs/c/compat.glfw.lua`.
   - Declare `dlopen_libs = {"libGLX.so.0", "libGL.so.1", "libGL.so"}`.
   - Declare `capabilities = {"x11.display", "opengl.glx.driver"}` for Linux
@@ -53,22 +53,28 @@ requirements as separate concepts.
   - The target behavior is `mcpp run` with package-declared runtime metadata.
   - The existing host shim may remain only as diagnostic evidence until the
     mcpp runtime metadata support lands.
-- [ ] Add README package semantics.
+- [x] Add README package semantics.
   - Candidate file: `README.md`.
   - Document the difference between OpenGL headers, GL runtime dispatch, and
     host display/GPU capabilities.
 
 ## Verification
 
+- [x] `bash -n tests/smoke_compat_imgui_window.sh`
+- [x] Static metadata check: `compat.glfw` contains `dlopen_libs`,
+      `libGLX.so.0`, and `opengl.glx.driver`.
 - [ ] `MCPP=<mcpp> tests/smoke_compat_imgui.sh`
 - [ ] `MCPP=<mcpp> tests/smoke_compat_imgui_window.sh`
+  - Attempted locally on 2026-06-03; the run was stopped after the temporary
+    sandbox stalled in dependency installation. This remains unchecked until a
+    full smoke completes.
 - [ ] `MCPP=<mcpp> MCPP_INDEX_RUN_WINDOW_SMOKE=1 tests/smoke_compat_imgui_window.sh`
 - [ ] A focused GLFW/OpenGL smoke that uses `mcpp run` without script-local
       `LD_LIBRARY_PATH` once mcpp runtime metadata support is available.
 
 ## PR / CI / Merge Notes
 
-- [ ] Commit this plan as the first checkpoint.
+- [x] Commit this plan as the first checkpoint.
 - [ ] Open a PR with sanitized paths and no local machine details.
 - [ ] Include a test plan and note which runtime checks require a display.
 - [ ] Wait for repository validation CI.

README.md

@@ -112,8 +112,9 @@ mcpp 0.0.3+ 的 transitive walker 自动沿链路传播头文件和依赖,消费
 
 > 当前 X11/XCB/Xau/Xdmcp 以及 GLFW 需要的 Xcursor/Xext/Xfixes/Xi/Xinerama/
 > Xrandr/Xrender 都已按上游源码提供 runtime `.so`。`compat.glfw` 仍沿用
-> GLFW 上游的 GLX/OpenGL 动态加载行为,窗口运行时需要宿主环境提供可用的
-> X server/GLX/OpenGL 驱动。
+> GLFW 上游的 GLX/OpenGL 动态加载行为,包描述会声明需要 `dlopen` 的
+> `libGLX.so.0`/`libGL.so.1`/`libGL.so` 以及 `opengl.glx.driver` 能力。
+> 窗口运行时仍需要宿主环境提供可用的 X server/GLX/OpenGL 驱动。
 
 ### 本地 smoke 验证
 

pkgs/c/compat.glfw.lua

@@ -54,6 +54,10 @@ package = {
         },
         linux = {
             cflags = { "-D_DEFAULT_SOURCE", "-D_GLFW_X11" },
+            runtime = {
+                dlopen_libs = { "libGLX.so.0", "libGL.so.1", "libGL.so" },
+                capabilities = { "x11.display", "opengl.glx.driver" },
+            },
             sources = {
                 "src/x11_init.c",
                 "src/x11_monitor.c",

tests/smoke_compat_imgui_window.sh

@@ -14,6 +14,16 @@ if [[ -z "$MCPP_BIN" || ! -x "$MCPP_BIN" ]]; then
     exit 1
 fi
 
+glfw_pkg="$ROOT/pkgs/c/compat.glfw.lua"
+grep -q 'dlopen_libs' "$glfw_pkg" || {
+    echo "FATAL: compat.glfw missing GLX/OpenGL dlopen runtime metadata" >&2
+    exit 1
+}
+grep -q 'opengl.glx.driver' "$glfw_pkg" || {
+    echo "FATAL: compat.glfw missing OpenGL GLX system capability metadata" >&2
+    exit 1
+}
+
 TMP="$(mktemp -d)"
 if [[ "${MCPP_INDEX_KEEP_SMOKE_TMP:-0}" == "1" ]]; then
     echo "KEEP: $TMP"