xpkg 包描述规范的 C++23 参考实现 —
import mcpplibs.xpkg;
libxpkg 是 xpkg 规范 的 C++23 标准库实现,让任何 C++ 工具都能读取、索引和执行 xpkg 格式的包定义,而无需依赖 xlings 本身。
libxpkg 由四个独立的 C++23 子模块组成,按依赖层级排列。可通过聚合 target xpkg 一次引入全部模块(add_deps("xpkg")),也可按需引用单个子模块:
| 模块 | 头文件 | 依赖 | 功能 |
|---|---|---|---|
mcpplibs.xpkg |
xpkg.cppm |
无外部依赖 | 数据模型:Package、PackageIndex 等核心类型 |
mcpplibs.xpkg.loader |
xpkg-loader.cppm |
model + lua | 解析 .lua 包定义文件,构建包索引 |
mcpplibs.xpkg.index |
xpkg-index.cppm |
model | 搜索、别名解析、索引合并 |
mcpplibs.xpkg.executor |
xpkg-executor.cppm |
model + lua | 执行包 Lua 钩子(install/config/uninstall) |
#include <iostream> import mcpplibs.xpkg; import mcpplibs.xpkg.loader; int main() { auto pkg = mcpplibs::xpkg::load_package("path/to/hello.lua"); if (pkg) { std::cout << "name: " << pkg->name << "\n"; std::cout << "desc: " << pkg->description << "\n"; } return 0; }
import mcpplibs.xpkg; import mcpplibs.xpkg.loader; import mcpplibs.xpkg.index; import mcpplibs.xpkg.executor; using namespace mcpplibs::xpkg; // 1. 加载包 auto pkg = load_package("pkgindex/pkgs/h/hello.lua"); // 2. 构建索引并搜索 auto idx = build_index("pkgindex/"); auto hits = search(*idx, "hello"); // 3. 创建执行器并运行钩子 auto exec = create_executor("pkgindex/pkgs/h/hello.lua"); ExecutionContext ctx{ .pkg_name = "hello", .version = "1.0.0", ... }; exec->run_hook(HookType::Install, ctx); exec->run_hook(HookType::Uninstall, ctx);
完整示例见 examples/lifecycle.cpp。
libxpkg/
├── src/
│ ├── xpkg.cppm # mcpplibs.xpkg — 数据模型
│ ├── xpkg-loader.cppm # mcpplibs.xpkg.loader
│ ├── xpkg-index.cppm # mcpplibs.xpkg.index
│ ├── xpkg-executor.cppm # mcpplibs.xpkg.executor
│ ├── xpkg-lua-stdlib.cppm # Lua 标准库封装(自动生成)
│ └── lua-stdlib/ # 嵌入式 Lua 脚本
├── tests/
│ ├── fixtures/pkgindex/ # 独立测试包索引(无外部依赖)
│ ├── test_model.cpp
│ ├── test_loader.cppm
│ ├── test_index.cpp
│ └── test_executor.cpp
├── examples/
│ ├── basic.cpp # 最小示例
│ └── lifecycle.cpp # 完整生命周期演示
├── build.mcpp # 构建期由 lua-stdlib/ 生成嵌入式 Lua stdlib
├── .agents/
│ ├── docs/ # 开发问题排查报告
│ ├── plans/ # 设计与实现方案
│ └── skills/ # 项目最佳实践
└── mcpp.toml
本库由 mcpp 构建。mcpp 自带受管沙箱(工具链由 mcpp.toml 固定),
不需要手工准备编译器,也不再有 xmake / CMake 构建入口。
xlings install -y # 装 .xlings.json 里固定的 mcpp mcpp build mcpp test
macOS 专用的 elfpatch 用例需要 install_name_tool,在 Linux 上跑不了,
CI 里按名字过滤:
mcpp test -- --gtest_filter=-ExecutorTest.ApplyElfpatchAuto_*
Lua stdlib 的生成
src/lua-stdlib/**.lua 是唯一的源码。它需要以裸字符串字面量的形式进二进制,
这一步由 build.mcpp 在构建期完成:生成的 xpkg-lua-stdlib.cppm 写进
MCPP_OUT_DIR,通过 generated= 交给构建,不进版本库。
所以改完 .lua 直接 mcpp build 即可,没有"忘记重新生成"这回事 ——
仓库里只有一份拷贝,两份拷贝对不上这种状态不存在。
(它曾经存在过:0.0.47 的 xvm.files 只改了生成物,源 .lua 一直没有。)
GitHub Actions 在 Linux 上构建并测试,工具链由 mcpp 沙箱提供:
| 平台 | 构建 | 状态 |
|---|---|---|
| Linux (ubuntu-latest) | mcpp(沙箱内 GCC) | CI |
在使用方的 mcpp.toml 里声明:
[dependencies] "mcpplibs.xpkg" = "0.0.48"