From 55f273ca968cda36c54000e296231a9826c7aed3 Mon Sep 17 00:00:00 2001 From: sunrisepeak Date: Wed, 3 Jun 2026 02:58:34 +0800 Subject: [PATCH 1/3] docs: plan GL runtime packages --- .../2026-06-03-gl-runtime-packages-plan.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 .agents/docs/2026-06-03-gl-runtime-packages-plan.md diff --git a/.agents/docs/2026-06-03-gl-runtime-packages-plan.md b/.agents/docs/2026-06-03-gl-runtime-packages-plan.md new file mode 100644 index 0000000..d3083e2 --- /dev/null +++ b/.agents/docs/2026-06-03-gl-runtime-packages-plan.md @@ -0,0 +1,83 @@ +# mcpp-index: GL Runtime Packages Plan + +> 状态: active +> 分支: `codex/gl-runtime-closure-index` +> PR: pending +> Last updated: 2026-06-03 +> 目标: 让 GLFW/OpenGL 相关包描述表达标准运行时需求,而不是依赖 smoke 脚本里的临时 `LD_LIBRARY_PATH` shim。 + +## Scope + +This repository owns package metadata and package-level smoke tests. It should +model OpenGL headers, GL dispatch/runtime libraries, and system GPU/display +requirements as separate concepts. + +## Package Boundary + +- `compat.opengl` + - Keep as Khronos OpenGL registry/header provider. + - Do not turn it into a host driver wrapper. +- `compat.glfw` + - Owns GLFW source build and X11/GLX backend selection. + - Should declare runtime requirements for the GLX libraries it loads through + GLFW's upstream `dlopen` behavior. +- `compat.glvnd` or `compat.libglvnd` + - New standard runtime package candidate for GL dispatch libraries: + `libOpenGL.so`, `libGL.so`, `libGLX.so`, `libGLdispatch.so`. +- `compat.mesa-llvmpipe` + - Optional follow-up for self-contained software rendering and CI/headless + validation. This is larger and should not block the first metadata path. +- Host GPU/OpenGL driver + - Model as a system capability such as `opengl.glx.driver`. + - Do not silently pretend vendor drivers are normal redistributable packages. + +## Implementation Plan + +- [x] Create this repository-level plan checkpoint. +- [ ] Keep `compat.opengl` header-only and update docs if needed. + - Candidate file: `pkgs/c/compat.opengl.lua`. +- [ ] Add a GL runtime provider package. + - Candidate file: `pkgs/c/compat.glvnd.lua`. + - The first version may expose libglvnd runtime/headers if the source build + 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. + - 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 + X11/GLX window execution. + - Keep X11 link/runtime packages as normal dependencies. +- [ ] Replace script-only GL runtime behavior in the window smoke. + - Candidate file: `tests/smoke_compat_imgui_window.sh`. + - 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. + - Candidate file: `README.md`. + - Document the difference between OpenGL headers, GL runtime dispatch, and + host display/GPU capabilities. + +## Verification + +- [ ] `MCPP= tests/smoke_compat_imgui.sh` +- [ ] `MCPP= tests/smoke_compat_imgui_window.sh` +- [ ] `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. +- [ ] 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. +- [ ] Squash merge after required checks pass. + +## Cross-Repository Dependencies + +- Depends on `mcpp` runtime metadata support for the final no-shim run smoke. +- Feeds `imgui-m` validation by making its window example runnable through + standard package metadata. +- Does not require `xim-pkgindex` until a released mcpp or package-index update + needs to be mirrored or distributed through xlings. From 7bf067bd50d684e0512c4bf6ad080c0841b3c1d2 Mon Sep 17 00:00:00 2001 From: sunrisepeak Date: Wed, 3 Jun 2026 03:18:02 +0800 Subject: [PATCH 2/3] feat: declare GLFW GLX runtime metadata --- .agents/docs/2026-06-03-gl-runtime-packages-plan.md | 12 +++++++++--- README.md | 5 +++-- pkgs/c/compat.glfw.lua | 4 ++++ tests/smoke_compat_imgui_window.sh | 10 ++++++++++ 4 files changed, 26 insertions(+), 5 deletions(-) diff --git a/.agents/docs/2026-06-03-gl-runtime-packages-plan.md b/.agents/docs/2026-06-03-gl-runtime-packages-plan.md index d3083e2..97d24e8 100644 --- a/.agents/docs/2026-06-03-gl-runtime-packages-plan.md +++ b/.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= tests/smoke_compat_imgui.sh` - [ ] `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_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. diff --git a/README.md b/README.md index 192110e..dfb8893 100644 --- a/README.md +++ b/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 验证 diff --git a/pkgs/c/compat.glfw.lua b/pkgs/c/compat.glfw.lua index df076d4..9693814 100644 --- a/pkgs/c/compat.glfw.lua +++ b/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", diff --git a/tests/smoke_compat_imgui_window.sh b/tests/smoke_compat_imgui_window.sh index 02f4cab..e1df169 100755 --- a/tests/smoke_compat_imgui_window.sh +++ b/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" From 52ddede9f8b53d55c06c88833a38ac7b905fed22 Mon Sep 17 00:00:00 2001 From: sunrisepeak Date: Wed, 3 Jun 2026 03:20:15 +0800 Subject: [PATCH 3/3] docs: record GL runtime package validation --- .agents/docs/2026-06-03-gl-runtime-packages-plan.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.agents/docs/2026-06-03-gl-runtime-packages-plan.md b/.agents/docs/2026-06-03-gl-runtime-packages-plan.md index 97d24e8..bfeb46e 100644 --- a/.agents/docs/2026-06-03-gl-runtime-packages-plan.md +++ b/.agents/docs/2026-06-03-gl-runtime-packages-plan.md @@ -60,6 +60,9 @@ requirements as separate concepts. ## Verification +- [x] `lua5.4 -e "assert(loadfile('pkgs/c/compat.glfw.lua', 't'))"` +- [x] `lua5.4 -e "assert(loadfile('pkgs/c/compat.opengl.lua', 't'))"` +- [x] Lua syntax check for all `pkgs/**/*.lua` - [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`.