feat: add compat.eui-neo 0.5.3 with selectable render and window backends (#133)

EUI-NEO as a Form B compat package: the core TUs compiled into one lib, public
headers exposed via include_dirs, so consumers write `#include <eui_neo.h>`.
The C++23 module surface is out of scope — upstream ships no module interface
units.

Builds on #134 (compat.vulkan / sdl2 / curl), and carries two fixes to that
half that only a machine with a GPU could have found — see below.

Backend selection. Upstream compiles exactly one render backend and one window
backend, dispatching on `#if OPENGL ... #elif VULKAN` and `#if SDL2` /
else-GLFW, so defining both halves of either pair silently picks the first.
mcpp features are additive with no `default-features = false` (mcpp#242), and
all three obvious encodings fail silently: a `default` feature carrying
defines/sources/deps is inert, `default = { implies = ... }` always applies,
and a package-level define cannot be unset. Verified with probes on 0.0.109 and
2026.7.29.1. What works is resolving the choice in the preprocessor from the
-DMCPP_FEATURE_<NAME> flags mcpp already passes, via a force-included header.

That exposed a second problem: mcpp routes `cflags` to C translation units and
`cxxflags` to C++ ones. The first revision carried only
`cflags = { "-DEUI_RENDER_BACKEND_OPENGL=1" }`, so render_backend.cpp never saw
it — the package built, linked, passed its tests, and had no render backend.

REAL GUI VERIFICATION, on a workstation with an X display and an RTX 4080: all
four backend combinations open a window, create the backend and present three
frames, with no environment variables set. Getting the Vulkan half there needed
two changes, both invisible to a headless test:

  * compat.vulkan-runtime (new) — the loader found every host ICD manifest and
    then failed to dlopen any driver, because an mcpp binary runs under mcpp's
    own glibc and a bare-soname dlopen never searches the host path. This is
    the counterpart of compat.glx-runtime, which is why OpenGL already worked:
    a symlink farm plus runtime.library_dirs, no vendored driver. Instance
    extensions 4 -> 22. Versioned sonames only — library_dirs lands on the link
    line too, so a bare libxcb.so there shadows compat.xcb.

  * compat.vulkan is now kind="shared" with soname libvulkan.so.1. SDL2's
    SDL_CreateWindow(SDL_WINDOW_VULKAN) dlopens libvulkan.so.1 and resolves
    surface creation through whatever it finds; against a static loader the
    application ends up with two, and createSurface gets an instance the second
    one never saw. Shared, the application, GLFW (via glfwInitVulkanLoader) and
    SDL all converge on one object — which is what the loader is designed to be.

Also: glfwInitVulkanLoader must be called before glfwInit. Upstream's
glfw_app_main.cpp gets this right; a consumer writing its own entry point must
too.

Verified cold on all three platforms with mcpp 0.0.109, plus the local GUI
harness on Linux.

Design: .agents/docs/2026-07-29-add-eui-neo-plan.md

Co-authored-by: SPeak Agent <248744407+speak-agent@users.noreply.github.com>

Author: FarnaHerry

.agents/docs/2026-07-29-add-eui-neo-plan.md

@@ -38,6 +38,9 @@ mcpp self config --mirror CN   # 切换至国内镜像,默认使用 GLOBAL 上
 | 运行时 loader compat(纯源码,绕开上游 codegen/asm) | [`compat.vulkan`](pkgs/c/compat.vulkan.lua)(Khronos loader:`loader/generated/` 已签入,汇编路径经 `UNKNOWN_FUNCTIONS_SUPPORTED` 降级为纯 C,故无需 CMake/Python/汇编器;windows 延后)· [`compat.vulkan-headers`](pkgs/c/compat.vulkan-headers.lua) |
 | 全源码直编 + 生成 config(仅缺口平台) | [`compat.curl`](pkgs/c/compat.curl.lua)(win32 用上游签入 config,unix 生成) · [`compat.sdl2`](pkgs/c/compat.sdl2.lua)(win/mac 用上游签入 config,linux 生成 + 手工开 X11) |
 | 补索引空缺的头文件包 | [`compat.glx-headers`](pkgs/c/compat.glx-headers.lua)(libglvnd 的 `GL/glx.h`,Khronos registry 不含,SDL 的 X11 后端必需) |
+| C++ 应用框架 compat(依赖复用索引内既有包) | [`compat.eui-neo`](pkgs/e/compat.eui-neo.lua)(上游 `3rd/` 自带 8 个 vendored 依赖,此处一个不编,全部改指索引内同版本 `compat.*`) |
+| 互斥后端(同包多后端二选一) | [`compat.eui-neo`](pkgs/e/compat.eui-neo.lua) 的 `opengl`/`vulkan` 与 `glfw`/`sdl2`。**`default` feature 在 mcpp 上不可用**(带 `defines/sources/deps` 完全不生效;带 `implies` 反而恒生效),可行解是用 `-DMCPP_FEATURE_<NAME>` 在强制包含头里做前置判定。另注意 `cflags` 只作用于 C TU,C++ 需 `cxxflags` |
+| 宿主运行时适配(不 vendor 驱动) | [`compat.glx-runtime`](pkgs/c/compat.glx-runtime.lua) · [`compat.vulkan-runtime`](pkgs/c/compat.vulkan-runtime.lua)(mcpp 产物跑在自带 glibc 下,裸 soname 的 `dlopen` 够不到宿主驱动;用符号链接农场 + `runtime.library_dirs` 打通。注意 farm 只放带版本号的 soname —— `library_dirs` 同时进链接行) |
 | 恒开的 interface define | [`compat.curl`](pkgs/c/compat.curl.lua) 的 `CURL_STATICLIB`:`cflags` 恒开但包私有,feature `defines` 可达消费端但需点名 —— `default = { implies = … }` 无条件生效,恰好两者兼得 |
 | 单包多 major(形态随版本切换) | [`compat.catch2`](pkgs/c/compat.catch2.lua)(3.x 编 `src/catch2/` 出静态库;2.x 走 `single_include/` header-only) |
 | 外部构建系统(`install()` 从源码构建) | [`compat.openblas`](pkgs/c/compat.openblas.lua)(Make) · [`compat.openssl`](pkgs/c/compat.openssl.lua)(Perl Configure + Make,静态 libssl/libcrypto) |

README.md

@@ -19,6 +19,10 @@ members = [
     "tests/examples/core",
     "tests/examples/curl",
     "tests/examples/eigen",
+    "tests/examples/eui-neo",
+    "tests/examples/eui-neo-markdown",
+    "tests/examples/eui-neo-sdl2",
+    "tests/examples/eui-neo-vulkan",
     "tests/examples/ffmpeg",
     "tests/examples/ffmpeg-module",
     "tests/examples/fmtlib.fmt",

mcpp.toml

@@ -0,0 +1,199 @@
+-- compat.vulkan-runtime — host Vulkan ICD adapter for mcpp Linux applications.
+--
+-- The exact counterpart of `compat.glx-runtime`, for the same reason and in the
+-- same shape. A GPU driver cannot be a package: the ICD has to match the kernel
+-- driver on the machine it runs on, so the GL runtime plan
+-- (.agents/docs/2026-06-03-gl-runtime-packages-plan.md) settled on modelling it
+-- as a HOST CAPABILITY rather than "silently pretending vendor drivers are
+-- normal redistributable packages". Nothing is vendored here either — this is a
+-- symlink farm plus the metadata that makes it reachable.
+--
+-- WHAT IT FIXES. `compat.vulkan` builds the Khronos loader, and the loader finds
+-- every ICD manifest on the host correctly. It then fails to dlopen a single
+-- driver:
+--
+--   DRIVER: Found the following files: /usr/share/vulkan/icd.d/lvp_icd.json …
+--   ERROR: libvulkan_lvp.so: cannot open shared object file
+--
+-- The libraries are right there in /usr/lib/x86_64-linux-gnu. What cannot reach
+-- them is the process: an mcpp-built binary runs under mcpp's OWN glibc
+--
+--   interp: …/xpkgs/xim-x-glibc/2.39/lib64/ld-linux-x86-64.so.2
+--   rpath : …/xim-x-glibc/2.39/lib64:…/xim-x-gcc/…/lib64:$ORIGIN
+--
+-- so a bare-soname dlopen from inside the sandbox does not search the host's
+-- library path at all. `runtime.library_dirs` below puts a package-owned
+-- directory of symlinks on that path, which is precisely how `compat.glx-runtime`
+-- makes host OpenGL work — and why the OpenGL backends already run while Vulkan
+-- did not.
+--
+-- THE PATTERN LIST covers the ICDs plus their transitive dependencies, because
+-- the whole chain has to resolve through the same directory. Mesa's software
+-- rasterizer pulls LLVM; NVIDIA pulls its own family. `libstdc++` is in the list
+-- and that is not an oversight: mcpp links libstdc++ STATICALLY (it is absent
+-- from a built binary's NEEDED), so a dlopen'd C++ ICD like lavapipe has nothing
+-- to resolve against unless the host copy is provided here.
+--
+-- NOTHING IS REQUIRED. Unlike `compat.glx-runtime`, which errors when libGL is
+-- missing, a machine with no Vulkan driver at all is a legitimate configuration
+-- — every CI runner in this repo is one. The farm is then simply empty and the
+-- loader reports its own four extensions, which is what
+-- `tests/examples/vulkan` asserts.
+package = {
+    spec        = "1",
+    namespace   = "compat",
+    name        = "vulkan-runtime",
+    description = "Host Vulkan ICD runtime adapter for mcpp Linux applications",
+    licenses    = {"Apache-2.0"},
+    repo        = "https://github.com/KhronosGroup/Vulkan-Loader",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["2026.07.29"] = {
+                -- Nothing is downloaded that matters: the package's content is
+                -- the symlink farm install() builds from the host. This is just
+                -- a stable, tiny anchor so the xpm entry is well-formed, the
+                -- same trick compat.glx-runtime uses with an OpenGL-Registry
+                -- README.
+                url    = "https://raw.githubusercontent.com/KhronosGroup/Vulkan-Loader/vulkan-sdk-1.4.357.0/README.md",
+                sha256 = "21ec0987a05bd680ecd11f8be747e27744d7558f7318736f6cb8a5c5ec1b8ba8",
+            },
+        },
+    },
+
+    mcpp = {
+        language     = "c++23",
+        import_std   = false,
+        c_standard   = "c11",
+        sources      = { "mcpp_generated/vulkan_runtime_empty.c" },
+        targets      = { ["vulkan_runtime"] = { kind = "lib" } },
+        deps         = {},
+        runtime = {
+            library_dirs = { "mcpp_generated/vulkan_runtime/lib" },
+            capabilities = { "vulkan.icd.driver" },
+            provides     = { "vulkan.icd.driver" },
+        },
+    },
+}
+
+import("xim.libxpkg.pkginfo")
+import("xim.libxpkg.log")
+
+local function sh_quote(value)
+    return "'" .. tostring(value):gsub("'", "'\\''") .. "'"
+end
+
+local function split_paths(value)
+    local out = {}
+    if not value or value == "" then
+        return out
+    end
+    for item in tostring(value):gmatch("[^:]+") do
+        if item ~= "" then
+            table.insert(out, item)
+        end
+    end
+    return out
+end
+
+local function candidate_dirs()
+    local out = {}
+    local seen = {}
+    local function add(dir)
+        if dir and dir ~= "" and not seen[dir] and os.isdir(dir) then
+            seen[dir] = true
+            table.insert(out, dir)
+        end
+    end
+
+    for _, dir in ipairs(split_paths(os.getenv("MCPP_HOST_VULKAN_LIBRARY_PATH"))) do
+        add(dir)
+    end
+    add("/lib/x86_64-linux-gnu")
+    add("/usr/lib/x86_64-linux-gnu")
+    add("/lib64")
+    add("/usr/lib64")
+    add("/usr/lib")
+    return out
+end
+
+-- ICDs first, then the transitive set they pull in — the whole chain has to
+-- resolve through this one directory. Verified against Mesa's lavapipe (LLVM,
+-- drm, expat, xcb, wayland, zstd) and NVIDIA's ICD, which is libGLX_nvidia.so.0
+-- and drags the libnvidia* family.
+--
+-- EVERY DEPENDENCY PATTERN IS VERSIONED (`lib*.so.*`), deliberately. mcpp puts
+-- `runtime.library_dirs` on the LINK line as well as the runtime path, so a bare
+-- `libxcb.so` harvested here would shadow this index's own `compat.xcb` and the
+-- link fails with `undefined reference to XauDisposeAuth`. Versioned sonames are
+-- invisible to the linker (it resolves `-lxcb` through `libxcb.so`/`libxcb.a`)
+-- and are exactly what dlopen asks for, so the split is not a workaround so much
+-- as the correct spelling. `compat.glx-runtime` never hit this only because the
+-- GL family it harvests is not otherwise linked from the index.
+--
+-- The Mesa ICDs themselves are genuinely named `libvulkan_lvp.so` with no
+-- version, which is safe: nothing links `-lvulkan_lvp`.
+--
+-- The host's own `libvulkan.so*` is deliberately NOT harvested: `compat.vulkan`
+-- builds the loader itself, as a shared object with the canonical
+-- `libvulkan.so.1` soname, and a second one on the path would be resolved by
+-- SDL2's `dlopen` instead. One loader per process is the whole point.
+local host_vulkan_patterns = {
+    -- Mesa ICDs: lavapipe, intel, radeon, nouveau, virtio, asahi, gfxstream
+    "libvulkan_*.so",
+    -- NVIDIA's ICD and its family
+    "libGLX_nvidia.so.*",
+    "libnvidia*.so.*",
+    -- transitive dependencies, versioned only
+    "libLLVM*.so.*",
+    "libdrm*.so.*",
+    "libexpat.so.*",
+    -- The X client stack, including its own auth dependencies. Incomplete is
+    -- worse than absent here: a farm carrying libxcb.so.1 but not libXau.so.6
+    -- shadows the host copy that would otherwise have resolved, and the
+    -- executable fails to start.
+    "libxcb*.so.*",
+    "libX11-xcb.so.*",
+    "libXau.so.*",
+    "libXdmcp.so.*",
+    "libbsd.so.*",
+    "libmd.so.*",
+    "libxshmfence.so.*",
+    "libwayland-client.so.*",
+    "libz.so.*",
+    "libzstd.so.*",
+    "libelf.so.*",
+    "libffi.so.*",
+    "libedit.so.*",
+    "libtinfo.so.*",
+    "libxml2.so.*",
+    "libstdc++.so.*",
+}
+
+local function link_runtime_libs(outdir)
+    os.mkdir(outdir)
+    for _, dir in ipairs(candidate_dirs()) do
+        for _, pattern in ipairs(host_vulkan_patterns) do
+            os.exec(
+                "for lib in " .. sh_quote(dir) .. "/" .. pattern ..
+                "; do [ -e \"$lib\" ] || continue; " ..
+                "ln -sf \"$lib\" " .. sh_quote(outdir) .. "/\"$(basename \"$lib\")\"; " ..
+                "done"
+            )
+        end
+    end
+    return true
+end
+
+function install()
+    os.tryrm(pkginfo.install_dir())
+    os.mkdir(pkginfo.install_dir())
+
+    local generated = path.join(pkginfo.install_dir(), "mcpp_generated")
+    os.mkdir(generated)
+    io.writefile(path.join(generated, "vulkan_runtime_empty.c"),
+        "int mcpp_compat_vulkan_runtime_anchor(void) { return 0; }\n")
+
+    return link_runtime_libs(path.join(generated, "vulkan_runtime", "lib"))
+end

pkgs/c/compat.vulkan-runtime.lua

@@ -20,15 +20,32 @@
 --     entry points (ones this loader version has never heard of) get no
 --     trampoline, which no consumer in this index uses.
 --
--- WINDOWS IS DEFERRED. A statically linked loader is not something upstream
--- supports there: the only static option in its CMake is `APPLE_STATIC_LOADER`,
--- gated to macOS and carrying the warning that it "will only work on MacOS and
--- is not supported" elsewhere. Built anyway, the Windows loader links but faults
--- at the first entry point (0xC0000005 out of vkEnumerateInstanceVersion). Linux
--- is not covered by that option either, but a static loader is the ordinary
--- case there and works — Chromium ships one. Rather than carry a package that
--- crashes, this follows `compat.openssl` and declares no windows xpm entry;
--- consumers gate with `[target.'cfg(...)']`.
+-- WINDOWS TAKES A DIFFERENT SHAPE: an import library, not a built loader.
+--
+-- A statically linked loader cannot work there, and the reason is in upstream's
+-- own source rather than just its docs. `vk_loader_platform.h` says the Windows
+-- build "does initialization in the first API call made, using
+-- InitOnceExecuteOnce, EXCEPT for initialization primitives which must be done
+-- in DllMain" — and `loader_windows.c`'s DllMain is what creates `loader_lock`
+-- and `loader_preload_icd_lock`. A static library never gets a DllMain, so the
+-- first API call takes an uninitialized CRITICAL_SECTION and faults
+-- (0xC0000005 out of vkEnumerateInstanceVersion, observed in CI). macOS escapes
+-- this through `APPLE_STATIC_LOADER` + pthread_once; Linux through
+-- `__attribute__((constructor))`. Windows has neither.
+--
+-- The supported Windows arrangement is the ordinary one every Vulkan
+-- application uses: link `vulkan-1.lib` and let the system `vulkan-1.dll`,
+-- installed by any GPU driver, do the ICD loading. The windows xpm entry is
+-- therefore a small artifact carrying that import library — symbol stubs, no
+-- code — generated from Khronos' own `loader/vulkan-1.def` (shipped in this
+-- very loader tarball) with a single reproducible command:
+--
+--     llvm-dlltool -d vulkan-1.def -l lib/vulkan-1.lib -m i386:x86-64
+--
+-- Deliberately NOT an install() hook running that command at build time: the
+-- hook would have to locate llvm-dlltool inside the resolved toolchain, and the
+-- output is a fixed function of an upstream text file. Prebuilt Windows
+-- artifacts on xlings-res are the pattern `compat.openssl` already anticipates.
 --
 -- SYSCONFDIR / FALLBACK_*_DIRS are the ICD and layer manifest search paths.
 -- Upstream's CMake derives them from the install prefix; the values below are
@@ -65,14 +82,24 @@ package = {
                 sha256 = "54f2537df22313768da0317dda2abdaaab7711b4081c48c869a79db343d0ae70",
             },
         },
-        -- windows deferred, see the note at the top of this file.
+        windows = {
+            ["1.4.357.0"] = {
+                url = {
+                    GLOBAL = "https://github.com/xlings-res/vulkan-import/releases/download/1.4.357.1/vulkan-import-1.4.357.1.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/vulkan-import/releases/download/1.4.357.1/vulkan-import-1.4.357.1.tar.gz",
+                },
+                sha256 = "37a206f866f75f54a56bdb428e4767c9926acd3f8abc8e1b9539853bb45acbf9",
+            },
+        },
     },
 
     mcpp = {
         language     = "c++23",
         import_std   = false,
         c_standard   = "c11",
 
+        -- `*/loader*` simply match nothing in the windows artifact, which
+        -- carries only lib/ and the .def.
         include_dirs = { "*/loader", "*/loader/generated", "mcpp_generated" },
 
         -- SYSCONFDIR / FALLBACK_*_DIRS have to reach the compiler as STRING
@@ -83,6 +110,8 @@ package = {
         -- the command line entirely — the same move `compat.opencv5` made for
         -- its space-bearing defines.
         generated_files = {
+            ["mcpp_generated/vulkan_import_anchor.c"] =
+                "int mcpp_compat_vulkan_import_anchor(void) { return 0; }\n",
             ["mcpp_generated/mcpp_vulkan_paths.h"] = [==[
 /* Manifest search paths for the Vulkan loader — see the descriptor note. */
 #pragma once
@@ -111,6 +140,22 @@ package = {
             "*/loader/wsi.c",
         },
 
+        -- SHARED, with the canonical soname — not a static lib, and the choice
+        -- is load-bearing rather than stylistic.
+        --
+        -- The Vulkan loader is designed to be the one shared object in a
+        -- process. SDL2 insists on that: `SDL_CreateWindow(SDL_WINDOW_VULKAN)`
+        -- calls `SDL_Vulkan_LoadLibrary(NULL)`, which dlopens `libvulkan.so.1`
+        -- and resolves surface creation through whatever it finds. Built
+        -- static, an application ends up with TWO loaders — its own for
+        -- `vkCreateInstance`, SDL's for `vkCreateXlibSurfaceKHR` — and
+        -- `createSurface` fails on an instance the second loader never saw.
+        -- Measured, not assumed. Shared, everyone (the application, GLFW via
+        -- glfwInitVulkanLoader, SDL via dlopen) converges on this one object.
+        --
+        -- The soname is what makes SDL's bare `dlopen("libvulkan.so.1")` land
+        -- here, so it is not optional either. Same shape the X11 family in this
+        -- index already uses.
         targets = { ["vulkan"] = { kind = "lib" } },
         deps    = { ["compat.vulkan-headers"] = "1.4.357.0" },
 
@@ -125,6 +170,12 @@ package = {
             -- loader_linux.c: it sorts physical devices by PCI bus info so
             -- device 0 is the discrete GPU rather than whichever ICD replied
             -- first.
+            -- SHARED here, and the choice is load-bearing: SDL2's
+            -- SDL_CreateWindow(SDL_WINDOW_VULKAN) dlopens libvulkan.so.1 and
+            -- resolves surface creation through whatever it finds. Static, an
+            -- application ends up with two loaders and createSurface fails on
+            -- an instance the second never saw.
+            targets = { ["vulkan"] = { kind = "shared", soname = "libvulkan.so.1" } },
             sources = { "*/loader/loader_linux.c" },
             cflags  = {
                 "-D_GNU_SOURCE",
@@ -144,6 +195,11 @@ package = {
                 ["compat.x11"]       = "1.8.13",
                 ["compat.xcb"]       = "1.17.0",
                 ["compat.xorgproto"] = "2025.1",
+                -- Without this the loader finds every ICD manifest and then
+                -- fails to dlopen a single driver: an mcpp binary runs under
+                -- mcpp's own glibc, whose search path does not include the
+                -- host's. See the note at the top of compat.vulkan-runtime.
+                ["compat.vulkan-runtime"] = "2026.07.29",
             },
             -- dlopen for the ICDs and layers; pthread for the loader's locks.
             ldflags = { "-ldl", "-lpthread", "-lm" },
@@ -184,6 +240,23 @@ package = {
             },
         },
 
-        -- No `windows` block: see the deferral note at the top.
+        windows = {
+            -- Nothing to compile: the artifact is the import library plus the
+            -- .def it came from. The anchor keeps a buildable target, the same
+            -- shape `compat.opengl` uses for a headers-only package.
+            --
+            -- The artifact is packed FLAT — lib/ at the archive root, no wrap
+            -- directory — because `-L` is not glob-expanded the way
+            -- include_dirs and sources are. With a wrap layer the relative
+            -- `-Llib` below misses and the link fails with
+            -- "LNK1181: cannot open input file 'vulkan-1.lib'".
+            sources = { "mcpp_generated/vulkan_import_anchor.c" },
+            ldflags = { "-Llib", "-lvulkan-1" },
+            runtime = {
+                -- vulkan-1.dll ships with the GPU driver, not with us.
+                dlopen_libs  = { "vulkan-1.dll" },
+                capabilities = { "vulkan.icd.driver" },
+            },
+        },
     },
 }