|
| 1 | +# Design doc: bump `compat.eui-neo` to 0.5.6 |
| 2 | + |
| 3 | +Date: 2026-08-10 |
| 4 | + |
| 5 | +Follow-up to `.agents/docs/2026-08-05-add-eui-neo-0.5.5-plan.md` (0.5.3 → 0.5.5). |
| 6 | +Upstream released 0.5.6; this bumps the index from 0.5.5 to 0.5.6. |
| 7 | + |
| 8 | +## Source and version |
| 9 | + |
| 10 | +| | | |
| 11 | +|---|---| |
| 12 | +| Upstream | `https://github.com/sudoevolve/EUI-NEO` | |
| 13 | +| Version | `0.5.6` (latest release) | |
| 14 | +| Tarball | `archive/refs/tags/v0.5.6.tar.gz` | |
| 15 | +| sha256 | `0df8d79897a480566b0989060f206431d12c4a83eb7aef50b8e5d21f1676abf8` (computed twice, stable; 14,794,160 bytes) | |
| 16 | +| Wrap dir | `EUI-NEO-0.5.6/` — absorbed by the standard `*/` glob prefix, no `install()` hook | |
| 17 | +| CN mirror | **pending** — no `mcpp-res` write access on this machine (same as 0.5.5); plain-string url fallback | |
| 18 | +| License | Apache-2.0 (unchanged) | |
| 19 | + |
| 20 | +0.5.5 tarball re-downloaded during this work and its sha256 re-derived — matches the |
| 21 | +descriptor's `cf0da91d…`, which validates the download/verify pipeline. |
| 22 | + |
| 23 | +## What changed upstream (0.5.5 → 0.5.6) |
| 24 | + |
| 25 | +The release is substantial (32 commits, 86 files changed, 5 contributors), but almost all |
| 26 | +of it is either build-system plumbing, app/example wiring, or the new `modules/` tree |
| 27 | +(keyboard/serial modules) — none of which the compat descriptor touches. The only thing |
| 28 | +that matters for this index is the **core library source list**: |
| 29 | + |
| 30 | +- `CORE_SOURCES` gains exactly one file: `core/window/window_input_backend.cpp`. Upstream |
| 31 | + moved the input/IME event pumping (mouse buttons, scroll, text composition, key queueing) |
| 32 | + out of `window_backend.cpp` into its own TU. |
| 33 | +- Everything else the descriptor names is unchanged in upstream's `CORE_SOURCES` / |
| 34 | + OpenGL block / glfw `ime_bridge.c` / vulkan feature list — verified by diffing the |
| 35 | + 0.5.5 and 0.5.6 `CMakeLists.txt` source blocks. |
| 36 | +- `3rd/dependencies.cmake` and the `3rd/` directory are **byte-identical** across the two |
| 37 | + tags — all eight vendored dependencies stay at the versions the descriptor pins |
| 38 | + (freetype 2.13.3, libpng 1.6.43, zlib 1.3.1, glfw 3.4, glad 651a425, yyjson 0.12.0, tray |
| 39 | + 8dd1358, opengl). |
| 40 | + |
| 41 | +### The new TU compiles on both backends with no new deps |
| 42 | + |
| 43 | +`window_input_backend.cpp` has two `#if`-branches that match the descriptor's generated |
| 44 | +backend header exactly: |
| 45 | + |
| 46 | +- **GLFW branch** (default): reaches `core/platform/ime_bridge.h` (`eui_ime_*` — supplied by |
| 47 | + `ime_bridge.c`, already in the base source list) and `<GLFW/glfw3.h>` (`compat.glfw`, already |
| 48 | + a dep). The `core::detail::inputQueue` / `core::queueKeyInput` / `core::queueScrollInput` |
| 49 | + helpers it calls live in the header-only `core/input/input_state.h` — no new TU needed. |
| 50 | +- **SDL2 branch** (`sdl2` feature): needs only `<SDL.h>` (`compat.sdl2`, already the feature's dep). |
| 51 | + |
| 52 | +`core/input/` is headers-only in both tags (`input_state.h`, `input_types.h`), so no new |
| 53 | +compiled input sources are introduced by the refactor. |
| 54 | + |
| 55 | +## Descriptor changes (`pkgs/e/compat.eui-neo.lua`) |
| 56 | + |
| 57 | +1. `xpm.{linux,macosx,windows}` each gain a `["0.5.6"]` entry (0.5.3/0.5.5 retained). |
| 58 | +2. Base `sources` goes 24 → 25: `*/core/window/window_input_backend.cpp` added to the |
| 59 | + Window layer group. |
| 60 | +3. Header comment updated to v0.5.6 + the `window_input_backend.cpp` note; wrap-layer |
| 61 | + mention `EUI-NEO-0.5.5/` → `EUI-NEO-0.5.6/`. |
| 62 | +4. No feature/deps/cflags changes: the `-fno-char8_t` package-wide flag is still required — |
| 63 | + re-verified that 0.5.6 still returns `path::u8string()` as `std::string` in |
| 64 | + `core/platform/platform.cpp:616`, `core/render/shadertoy_json.cpp:40/260`, |
| 65 | + `core/render/image_source.cpp:216/220/574`. Backend-exclusivity encoding unchanged |
| 66 | + (`mcpp_eui_backends.h` reads `MCPP_FEATURE_VULKAN`/`MCPP_FEATURE_SDL2`, which 0.5.6's |
| 67 | + `window_input_backend.cpp` also keys off). |
| 68 | + |
| 69 | +## CN mirror: pending (fallback form used) |
| 70 | + |
| 71 | +`gtc` still not installed and no `~/.config/gitcode-tool/config.json` on this machine, so the |
| 72 | +0.5.6 mirror cannot be published from here. Per `docs/cn-mirror.md`'s no-write-access |
| 73 | +fallback, the 0.5.6 entries use a **plain-string url** (GLOBAL upstream release); |
| 74 | +`check_mirror_urls.lua` exempts plain strings, so lint stays green and CN users fall back to |
| 75 | +upstream. The 0.5.3 entries keep their `{ GLOBAL, CN }` tables. |
| 76 | + |
| 77 | +Once `mcpp-res/eui-neo` has a `0.5.6` release (same tarball as GLOBAL for byte-identical |
| 78 | +sha), flip the 0.5.6 `url` to `{ GLOBAL = …, CN = |
| 79 | +"https://gitcode.com/mcpp-res/eui-neo/releases/download/0.5.6/eui-neo-0.5.6.tar.gz" }`. |
| 80 | +sha256 does not change. |
| 81 | + |
| 82 | +## Test members |
| 83 | + |
| 84 | +All six `tests/examples/eui-neo*` members bumped their `compat.eui-neo` dep from `0.5.5` to |
| 85 | +`0.5.6` so the whole feature surface (markdown / vulkan / sdl2+network / app-main / window) |
| 86 | +exercises the new version. CI's selective-member logic already maps the descriptor edit to |
| 87 | +these members (`pkgs/e/compat.eui-neo.lua` → `$lib = eui-neo` → all six match). |
| 88 | + |
| 89 | +Note: `tests/examples/eui-neo-window` includes `core/input/input_state.h` directly, so the |
| 90 | +0.5.6 input refactor is exercised from a consumer TU too, not just through the lib's own |
| 91 | +sources. |
| 92 | + |
| 93 | +## API break caught by local verification: `app::*` impl moved out of the umbrella |
| 94 | + |
| 95 | +`eui-neo-window`(the own-main member) failed the first local run at LINK time: |
| 96 | + |
| 97 | +``` |
| 98 | +undefined symbol: app::initialize(void*) / app::update(...) / app::render(...) / app::shutdown() |
| 99 | +``` |
| 100 | + |
| 101 | +Root cause is a 0.5.6 umbrella change: `include/eui_neo.h` **dropped |
| 102 | +`#include "eui/detail/dsl_app_impl.h"`** (and the Windows `<windows.h>` block it carried). |
| 103 | +That header is what emits `app::initialize/update/render/shutdown` + `openWindow()` into a |
| 104 | +consumer TU. In 0.5.6 upstream scoped it to the app-main entry points — only |
| 105 | +`core/app/glfw_app_main.cpp` and `core/app/sdl2_app_main.cpp` include it directly — so |
| 106 | +`eui-neo-app-main` (whose main() IS glfw_app_main.cpp) still links, while the hand-written |
| 107 | +`eui-neo-window` main() lost the impl. The other members never call the `app::*` driver |
| 108 | +functions, so they pass regardless. |
| 109 | + |
| 110 | +Fix: `tests/examples/eui-neo-window/tests/window.cpp` now includes |
| 111 | +`"eui/detail/dsl_app_impl.h"` explicitly — exactly what upstream's own app-main TU does. It |
| 112 | +compiles cleanly in a plain consumer TU: no `u8string()`/char8_t in the header or its core |
| 113 | +includes, no `EUI_RENDER_BACKEND_*` macro dependency (verified by grep), and `3rd/stb_image.h` |
| 114 | +resolves through the descriptor's existing `"*"` include dir. The `eui-neo` member's |
| 115 | +`header.cpp` comment was also updated to stop claiming the umbrella emits `app::update/render`. |
| 116 | + |
| 117 | +(No descriptor change was needed for this — the library build is unaffected; it is a |
| 118 | +consumer-surface change upstream made.) |
| 119 | + |
| 120 | +## Verification |
| 121 | + |
| 122 | +- `mcpp xpkg parse` (mcpp 2026.8.10.1) → `parse OK`: versions 0.5.3/0.5.5/0.5.6 on all three |
| 123 | + platforms, sources 25, features 6. |
| 124 | +- Repo lint loop (lua 5.4): syntax / required fields / no-leading-v / `check_mirror_urls.lua` / |
| 125 | + `check_package_name.lua` all pass. |
| 126 | +- Local `mcpp test -p <member>` (mcpp 2026.8.10.1, linux, `MCPP_INDEX_MIRROR=GLOBAL`, cold |
| 127 | + member dirs) — all six members pass: |
| 128 | + |
| 129 | +| member | result | |
| 130 | +|---|---| |
| 131 | +| eui-neo (default OpenGL+GLFW) | `test result ok. 1 passed; 0 failed` | |
| 132 | +| eui-neo-markdown | exit=0 | |
| 133 | +| eui-neo-app-main | exit=0 | |
| 134 | +| eui-neo-window | `test result ok` (after the dsl_app_impl.h fix) | |
| 135 | +| eui-neo-sdl2 (SDL2+network) | `test result ok` — `SDL driver=dummy, curl 8.21.0-DEV ssl=OpenSSL/3.5.1` | |
| 136 | +| eui-neo-vulkan | `test result ok` — `backend=vulkan, loader api 1.4.357` | |
| 137 | + |
| 138 | +Local network was intermittently hung on the mcpp registry downloads during this run; the |
| 139 | +EUI-NEO / curl / sdl2 / Vulkan-Loader tarballs were verified by sha256 and pre-seeded into |
| 140 | +the member package caches (then extracted, matching what mcpp's install does) to keep the |
| 141 | +cold builds moving. This is an environment workaround, not a descriptor concern. |
| 142 | + |
| 143 | +> NOTE: local mcpp is 2026.8.10.1 while CI pins 2026.8.8.2 in `validate.yml`. The change is a |
| 144 | +> plain version bump with no new descriptor grammar, so the difference is benign; a CI green |
| 145 | +> on the pinned version remains the authoritative signal. The user opted to verify locally |
| 146 | +> with the newest mcpp (its rapid-release policy makes newer preferable). |
| 147 | +> |
| 148 | +> macosx/windows cannot be exercised on this linux box; the windows `app-main` TU |
| 149 | +> (`_WIN32_WINNT`, winmm/user32/pdh) and the mac Cocoa tray link are re-exercised by CI's |
| 150 | +> other two runners. |
0 commit comments