feat(compat): the eight general-purpose libraries a modern Vulkan app needs

CHANGELOG.md

@@ -9,6 +9,41 @@
 
 ### Added
 
+- 收录 **vulkan-rt 依赖的八个通用库**,一次补齐:`compat.glm` 1.0.2、
+  `compat.doctest` 2.4.12、`compat.argparse` 3.2、`compat.mio` 2023.3.3、
+  `compat.gzip-hpp` 0.1.0、`compat.cpptrace` 1.0.4、`compat.libassert` 2.2.1、
+  `compat.libcoro` 0.16.0。八个都带**已验证的 CN 镜像**
+  (`gitcode.com/mcpp-res/<slug>`,逐个比对 sha256 与 GLOBAL **逐字节相同**,
+  8/8),八个都带 workspace 成员做行为断言。
+  四个不是「拉个头文件就完事」,记在配方里:
+  ⚠️ **`compat.gzip-hpp`** 冻结在一个已经编不过的点上:`utils.hpp` 六处、
+  `decompress.hpp` 一处用 `uint8_t` 却不 include `<cstdint>`(实测 gcc 16.1.0)。
+  而且它是**消费者侧**失败 —— 本包一个 C++ TU 都没有,`cxxflags = {"-include",
+  "cstdint"}`(`compat.redis-plus-plus` 的修法)到不了出错的 TU。唯一可用的杠杆是
+  同名遮蔽头 + `#include_next`,与 `compat.catch2` 修 `<new>` 是同一招;
+  `include_dirs` 因此必须 `mcpp_generated` 在前,调换两行会静默失效。
+  ⭐ **`compat.cpptrace`** 是形态 E 去掉 config 头:六个符号后端、六个 unwinder、
+  三个 demangler **每个文件自己 `#ifdef`**,所以源列表是一条 glob,配置全在 defines。
+  选的后端一律**零外部依赖**:unix 走 libgcc 的 `_Unwind_Backtrace` + `dladdr` +
+  `__cxa_demangle`,windows 走 DbgHelp。⚠️ 代价写在配方里:`dladdr` 不读 DWARF,
+  所以栈帧有函数名、**没有 file:line**;要行号得再加一个 libdwarf 包,留作 feature。
+  **`compat.libassert`** 依赖上面那个(上游是 FetchContent 一份进自己的树,这里是
+  正经依赖,消费者链两次也只有一份 cpptrace);magic_enum **不需要** —— 读 CMakeLists
+  会发现它只在 `LIBASSERT_BUILD_TESTING` 下打开,库源码一次都没提过它。
+  ⚠️ **`compat.libcoro`** 只出**核心**:上游 networking 默认开,但它的 c-ares 在
+  `vendor/c-ares` 这个 **git submodule** 里,而 GitHub 归档从不含 submodule
+  (实测 `find vendor -type f` → 0 个文件)—— 这个产物根本编不出网络那半。所以源列表
+  是上游 `LIBCORO_SOURCE_FILES` 在 `if(LIBCORO_FEATURE_NETWORKING)` 之前的部分,
+  逐条转录而非 glob(`scheduler.cpp`/`poll.cpp`/epoll/kqueue/`net/` 全都不自 guard)。
+  另外 `coro/export.hpp` 是 `generate_export_header` 生成的,tarball 里没有,
+  缺了它第一个 TU 就 fatal error;快照进 `generated_files`,`CORO_STATIC_DEFINE` 走
+  `defines`(要到消费者)而非 `cxxflags`。
+  测试都断言真行为而非「能编译」:glm 断言叉积/列主序/`GLM_FORCE_DEPTH_ZERO_TO_ONE`
+  下近平面映射到 0;gzip 断言 gzip magic + 真的变小 + 往返;cpptrace 断言四层调用链
+  的帧数与**互不相同**的返回地址;libassert 走**失败路径**,断言报告里有表达式原文、
+  消息和两个操作数的值,并且拿到了非空 stacktrace(这条同时证明 cpptrace 是传递到达的);
+  libcoro 用 200 个协程在 `coro::mutex` 下累加。
+
 - 收录 `khronos.vulkan-hpp` 1.4.357.0 —— Vulkan 的 C++ 绑定,按 Khronos 现在自己
   发布的形态消费:`import vulkan;` / `import vulkan_video;`。⭐ 这是本索引第一个走
   **形态 C 第一条分支**的包(上游自带 `.cppm`,直接点名),此前所有模块包都是合成

mcpp.toml

@@ -9,6 +9,7 @@
 members = [
     "tests/examples/abseil",
     "tests/examples/archive",
+    "tests/examples/argparse",
     "tests/examples/asio-module",
     "tests/examples/asio-ssl",
     "tests/examples/boost-asio",
@@ -33,12 +34,14 @@ members = [
     "tests/examples/cmdline",
     "tests/examples/cmp-module",
     "tests/examples/cli11",
+    "tests/examples/cpptrace",
     "tests/examples/concurrentqueue",
     "tests/examples/concurrentqueue-c-api",
     "tests/examples/core",
     "tests/examples/cuda-curand",
     "tests/examples/cuda-driver",
     "tests/examples/curl",
+    "tests/examples/doctest",
     "tests/examples/eigen",
     "tests/examples/eui-neo",
     "tests/examples/eui-neo-app-main",
@@ -52,6 +55,7 @@ members = [
     "tests/examples/fmtlib.fmt",
     "tests/examples/ftxui-module",
     "tests/examples/gmp",
+    "tests/examples/gzip-hpp",
     "tests/examples/gmp-gmpxx",
     "tests/examples/godot-cpp",
     "tests/examples/godot-cpp-module",
@@ -65,6 +69,7 @@ members = [
     "tests/examples/imgui-window",
     "tests/examples/jwt-cpp",
     "tests/examples/marzer.tomlplusplus",
+    "tests/examples/mio",
     "tests/examples/libmysqlclient",
     "tests/examples/mysql-connector-cpp",
     "tests/examples/nlohmann.json",
@@ -89,7 +94,10 @@ members = [
     "tests/examples/fontconfig",
     "tests/examples/freetype",
     "tests/examples/glad",
+    "tests/examples/glm",
     "tests/examples/libaio",
+    "tests/examples/libassert",
+    "tests/examples/libcoro",
     "tests/examples/libdrm",
     "tests/examples/libffi",
     "tests/examples/expat",

pkgs/c/compat.argparse.lua

@@ -0,0 +1,72 @@
+-- compat.argparse — p-ranav/argparse, a single-header command line parser.
+--
+-- Shape B: one header at `include/argparse/argparse.hpp`, so `include_dirs` is
+-- `*/include` and consumers write `#include <argparse/argparse.hpp>`.
+--
+-- The index's third answer to argument parsing, and they are not
+-- interchangeable: `compat.CLI11` is the large one (subcommands, config files,
+-- validators), `mcpplibs.cmdline` is the mcpp-native module, and this one is
+-- the small header that models an argument as a typed `add_argument(...)`
+-- chain and throws on a bad command line. A project already using it does not
+-- want to be told to rewrite its `main`.
+--
+-- Needs C++17; `language = "c++23"` here is the index's usual setting for a
+-- compat entry and does not force anything on a consumer's own dialect.
+--
+-- CN mirror: `gitcode.com/mcpp-res/argparse`, the upstream tarball re-hosted
+-- BYTE-IDENTICALLY (verified: the mirror's sha256 equals the one declared
+-- here, which is what lets one `sha256` serve both arms). GLOBAL stays the
+-- default; CN is the fallback `mcpp self config --mirror CN` selects.
+package = {
+    spec        = "1",
+    namespace   = "compat",
+    name        = "argparse",
+    description = "argparse — header-only argument parser for modern C++",
+    licenses    = {"MIT"},
+    repo        = "https://github.com/p-ranav/argparse",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["3.2"] = {
+                url    = {
+                    GLOBAL = "https://github.com/p-ranav/argparse/archive/refs/tags/v3.2.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/argparse/releases/download/3.2/argparse-3.2.tar.gz",
+                },
+                sha256 = "9dcb3d8ce0a41b2a48ac8baa54b51a9f1b6a2c52dd374e28cc713bab0568ec98",
+            },
+        },
+        macosx = {
+            ["3.2"] = {
+                url    = {
+                    GLOBAL = "https://github.com/p-ranav/argparse/archive/refs/tags/v3.2.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/argparse/releases/download/3.2/argparse-3.2.tar.gz",
+                },
+                sha256 = "9dcb3d8ce0a41b2a48ac8baa54b51a9f1b6a2c52dd374e28cc713bab0568ec98",
+            },
+        },
+        windows = {
+            ["3.2"] = {
+                url    = {
+                    GLOBAL = "https://github.com/p-ranav/argparse/archive/refs/tags/v3.2.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/argparse/releases/download/3.2/argparse-3.2.tar.gz",
+                },
+                sha256 = "9dcb3d8ce0a41b2a48ac8baa54b51a9f1b6a2c52dd374e28cc713bab0568ec98",
+            },
+        },
+    },
+
+    mcpp = {
+        language     = "c++23",
+        import_std   = false,
+        c_standard   = "c11",
+        include_dirs = { "*/include" },
+        generated_files = {
+            ["mcpp_generated/argparse_anchor.c"] =
+                "int mcpp_compat_argparse_anchor(void) { return 0; }\n",
+        },
+        sources      = { "mcpp_generated/argparse_anchor.c" },
+        targets      = { ["argparse"] = { kind = "lib" } },
+        deps         = { },
+    },
+}

pkgs/c/compat.cpptrace.lua

@@ -0,0 +1,212 @@
+-- compat.cpptrace — stack traces for C++11 and up, from source.
+--
+-- Here because `compat.libassert` cannot exist without it: libassert's whole
+-- value proposition is an assertion that prints a stack trace, and upstream
+-- gets that by FetchContent-ing this repository at a pinned commit. This index
+-- does not run FetchContent, so the dependency becomes an ordinary package —
+-- which is better anyway: one cpptrace in the graph rather than one per
+-- consumer that vendored it.
+--
+-- ── Whole-source glob, because every backend guards itself ─────────────────
+--
+-- Shape E without the config header. cpptrace supports six symbol backends,
+-- six unwinders and three demanglers, and CMake compiles only the selected
+-- ones. That selection is unnecessary here: EVERY backend file opens with its
+-- own `#ifdef` (`symbols_with_libdwarf.cpp` → `#ifdef
+-- CPPTRACE_GET_SYMBOLS_WITH_LIBDWARF`, and so on down the list), so an
+-- unselected backend compiles to an empty translation unit exactly the way
+-- curl's `vtls/gtls.c` does. The source list is therefore a plain glob and the
+-- whole configuration lives in the defines below.
+--
+-- ── The backends chosen, and what they cost ────────────────────────────────
+--
+-- The criterion is ZERO EXTERNAL DEPENDENCIES on every platform, because a
+-- diagnostic library that drags in libdwarf, libunwind or libbacktrace makes
+-- itself harder to adopt than the problem it solves.
+--
+--   unix     `_Unwind_Backtrace` from libgcc (always present, it is what the
+--            C++ runtime already uses to unwind), `dladdr` for symbols, and
+--            `abi::__cxa_demangle` for names.
+--   windows  DbgHelp for all three. `dbghelp.dll` is part of Windows itself,
+--            so `-ldbghelp` needs nothing installed.
+--
+-- ⚠️ THE COST IS LINE NUMBERS. `dladdr` resolves an address to a symbol name
+-- and the object it came from — it does NOT read DWARF, so traces carry
+-- function names without file:line. That is the price of not depending on
+-- libdwarf, and it is the right trade for this index today: the alternative is
+-- vendoring libdwarf (which upstream itself FetchContents) as a fourth
+-- package, for information that matters to a developer at a debugger rather
+-- than to CI. A future `libdwarf` feature can add it without changing anything
+-- a consumer writes.
+--
+-- ── Two generated pieces ───────────────────────────────────────────────────
+--
+--   * `cpptrace/version.hpp` is a `configure_file` of `cmake/in/version-hpp.in`
+--     whose only inputs are the three version numbers in `project()`. Snapshot,
+--     not a build step.
+--   * `CPPTRACE_STATIC_DEFINE` is upstream's own switch (it is checked in
+--     `include/cpptrace/basic.hpp`, not generated), and it is required: without
+--     it every declaration carries `__declspec(dllexport)` /
+--     `visibility("default")` for a shared library this package does not build.
+--
+--     ⚠️ AND A FLAG CANNOT DELIVER IT, WHICH ONLY WINDOWS SAYS OUT LOUD. The
+--     macro decorates DECLARATIONS, so it has to reach every TU that INCLUDES
+--     the headers — not just this package's own. As `cxxflags` Linux stayed
+--     green, because there the difference is `visibility("default")` versus
+--     nothing and the link is unaffected. On the MSVC ABI it is `dllimport`
+--     versus nothing, which is an ABI difference, and `compat.libassert` —
+--     whose TUs include these headers — failed to link:
+--
+--         lld-link: warning: locally defined symbol imported:
+--             cpptrace::v1::runtime_error::runtime_error(...) [LNK4217]
+--         lld-link: error: undefined symbol: __declspec(dllimport)
+--             cpptrace::v1::stacktrace_frame::operator!=(...) const
+--
+--     ⚠️⚠️ MOVING IT TO `defines` DOES NOT FIX THAT, and this was measured
+--     rather than assumed: `defines` is package-private too. Read the compile
+--     database of a build that has both packages in it and libassert's eight
+--     TUs carry `-DLIBASSERT_STATIC_DEFINE` (its OWN package define) and zero
+--     `-DCPPTRACE_STATIC_DEFINE`, while cpptrace's 45 carry the reverse.
+--     `docs/repository-and-schema.md` says the same thing about a feature's
+--     `defines`. THERE IS NO INTERFACE-DEFINE KEY IN THIS GRAMMAR.
+--
+--     So the delivery mechanism is a SHIM, the same lever `compat.gzip-hpp` and
+--     `compat.catch2` use: `basic.hpp` is the only header that reads the macro,
+--     and every public header funnels through it (`cpptrace.hpp`,
+--     `exceptions.hpp`, `formatting.hpp`, `from_current.hpp`, `gdb_jit.hpp`,
+--     `io.hpp`, `utils.hpp` — all of them include it), so ONE shim in front of
+--     it serves this package's TUs, libassert's, and any consumer's alike.
+--     `mcpp_generated` therefore sorts FIRST in include_dirs.
+--
+--     The BACKEND macros below stay in `cxxflags` on purpose: those select
+--     which .cpp compiles to something and are nobody else's business.
+--
+-- Upstream also ships `src/cpptrace.cppm` (`export module cpptrace;`). It is
+-- deliberately NOT built here: this entry is `compat.*`, which in this index
+-- promises header consumption and nothing else, and libassert — the reason
+-- this package exists — consumes the headers. A module entry under the owning
+-- namespace can be added later without disturbing this one.
+--
+-- CN mirror: `gitcode.com/mcpp-res/cpptrace`, the upstream tarball re-hosted
+-- BYTE-IDENTICALLY (verified: the mirror's sha256 equals the one declared
+-- here, which is what lets one `sha256` serve both arms). GLOBAL stays the
+-- default; CN is the fallback `mcpp self config --mirror CN` selects.
+package = {
+    spec        = "1",
+    namespace   = "compat",
+    name        = "cpptrace",
+    description = "cpptrace — simple, portable stack traces for C++",
+    licenses    = {"MIT"},
+    repo        = "https://github.com/jeremy-rifkin/cpptrace",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["1.0.4"] = {
+                url    = {
+                    GLOBAL = "https://github.com/jeremy-rifkin/cpptrace/archive/refs/tags/v1.0.4.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/cpptrace/releases/download/1.0.4/cpptrace-1.0.4.tar.gz",
+                },
+                sha256 = "5c9f5b301e903714a4d01f1057b9543fa540f7bfcc5e3f8bd1748e652e24f9ea",
+            },
+        },
+        macosx = {
+            ["1.0.4"] = {
+                url    = {
+                    GLOBAL = "https://github.com/jeremy-rifkin/cpptrace/archive/refs/tags/v1.0.4.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/cpptrace/releases/download/1.0.4/cpptrace-1.0.4.tar.gz",
+                },
+                sha256 = "5c9f5b301e903714a4d01f1057b9543fa540f7bfcc5e3f8bd1748e652e24f9ea",
+            },
+        },
+        windows = {
+            ["1.0.4"] = {
+                url    = {
+                    GLOBAL = "https://github.com/jeremy-rifkin/cpptrace/archive/refs/tags/v1.0.4.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/cpptrace/releases/download/1.0.4/cpptrace-1.0.4.tar.gz",
+                },
+                sha256 = "5c9f5b301e903714a4d01f1057b9543fa540f7bfcc5e3f8bd1748e652e24f9ea",
+            },
+        },
+    },
+
+    mcpp = {
+        language     = "c++23",
+        import_std   = false,
+        c_standard   = "c11",
+
+        -- `*/src` carries private headers the sources include as `utils/…`,
+        -- `binary/…`; `mcpp_generated` carries the version header at the path
+        -- `<cpptrace/version.hpp>` upstream's public headers open.
+        -- ORDER MATTERS: mcpp_generated FIRST, so the basic.hpp shim below is
+        -- found before upstream's, which it then reaches with #include_next.
+        include_dirs = { "mcpp_generated", "*/include", "*/src" },
+
+        generated_files = {
+            -- Delivers CPPTRACE_STATIC_DEFINE to every TU that opens a cpptrace
+            -- header, which no descriptor key can do. See the header note.
+            ["mcpp_generated/cpptrace/basic.hpp"] = [==[
+// mcpp-index shim: cpptrace is built as objects here, not as a shared library,
+// so every declaration must be plain rather than dllimport/visibility-default.
+// Upstream reads CPPTRACE_STATIC_DEFINE in this header and nowhere else, and
+// every public cpptrace header includes this one.
+#ifndef MCPP_COMPAT_CPPTRACE_STATIC_SHIM
+#define MCPP_COMPAT_CPPTRACE_STATIC_SHIM
+#ifndef CPPTRACE_STATIC_DEFINE
+#  define CPPTRACE_STATIC_DEFINE
+#endif
+#include_next <cpptrace/basic.hpp>
+#endif
+]==],
+            ["mcpp_generated/cpptrace/version.hpp"] = [==[
+/* configure_file() of cmake/in/version-hpp.in for cpptrace 1.0.4. */
+#ifndef CPPTRACE_VERSION_HPP
+#define CPPTRACE_VERSION_HPP
+
+#define CPPTRACE_VERSION_MAJOR 1
+#define CPPTRACE_VERSION_MINOR 0
+#define CPPTRACE_VERSION_PATCH 4
+
+#define CPPTRACE_TO_VERSION(MAJOR, MINOR, PATCH) ((MAJOR) * 10000 + (MINOR) * 100 + (PATCH))
+#define CPPTRACE_VERSION CPPTRACE_TO_VERSION(CPPTRACE_VERSION_MAJOR, CPPTRACE_VERSION_MINOR, CPPTRACE_VERSION_PATCH)
+
+#endif
+]==],
+        },
+
+        sources = { "*/src/**/*.cpp" },
+        targets = { ["cpptrace"] = { kind = "lib" } },
+        deps    = { },
+
+        -- Belt and braces for this package's OWN TUs; the shim above is what
+        -- reaches everyone else's.
+        defines = { "CPPTRACE_STATIC_DEFINE" },
+
+        linux = {
+            cxxflags = {
+                "-DCPPTRACE_UNWIND_WITH_UNWIND",
+                "-DCPPTRACE_GET_SYMBOLS_WITH_LIBDL",
+                "-DCPPTRACE_DEMANGLE_WITH_CXXABI",
+            },
+            -- dladdr lives in libdl on glibc.
+            ldflags = { "-ldl" },
+        },
+
+        macosx = {
+            cxxflags = {
+                "-DCPPTRACE_UNWIND_WITH_UNWIND",
+                "-DCPPTRACE_GET_SYMBOLS_WITH_LIBDL",
+                "-DCPPTRACE_DEMANGLE_WITH_CXXABI",
+            },
+        },
+
+        windows = {
+            cxxflags = {
+                "-DCPPTRACE_UNWIND_WITH_DBGHELP",
+                "-DCPPTRACE_GET_SYMBOLS_WITH_DBGHELP",
+                "-DCPPTRACE_DEMANGLE_WITH_WINAPI",
+            },
+            ldflags = { "-ldbghelp" },
+        },
+    },
+}