add-mcpp-index-package

Stars3

Forks7

UpdatedJuly 29, 2026 at 11:34

Use when adding a new third-party library/package to the mcpp-index repo — writing a pkgs/*/*.lua descriptor, setting up a GitCode CN mirror via gtc, adding a minimal example, and opening a green PR. Covers the four package shapes (C-source compat / header-only / C++23 module / external Form-A module repo), the GLOBAL+CN mirror table, lint rules, the feature (sources-only) gate, and local + CI verification.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

mcpplibs

mcpplibs/mcpp-index

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name

add-mcpp-index-package

description

向 mcpp-index 新增一个库(标准作业流程)

本文件定义将上游库收录进 mcpp-index 的标准流程。其产出包括:一个 pkgs/<x>/<name>.lua 描述符、一个 GitCode CN 镜像、一个位于 tests/examples/ 的最小工程、一条 README 记录, 以及一份设计文档。完整流程为:本地验证通过,提交 PR,CI 全部通过,由维护者合并。合并后,publish-artifact.yml 将自动重新发布 index artifact。

可直接参考的既有案例如下:

.agents/docs/2026-06-27-add-cjson-and-nlohmann-json-plan.md(C 源码 compat 与模块库)。
.agents/docs/2026-06-28-add-eigen-plan.md(header-only 库及 source-gated blas feature)。
既有 PR:#48(cjson 与 nlohmann.json)、#50(eigen)。

配套参考文档位于仓库 docs/ 目录(英文为默认版本,中文版在 docs/zh/,内容对等),供人工与 agent 共同使用, 可按需查阅(下列链接指向中文版):

docs/zh/package-types.md —— 四种库形态的描述符模板与样例路径。
docs/zh/cn-mirror.md —— CN 镜像闭环,含无 mcpp-res 权限时的回退方案。
docs/zh/repository-and-schema.md —— 仓库结构、schema、CI 行为、关键文件与注意事项。

适用范围

本流程适用于将一个新库(或库的新版本)加入 mcpp-index。被收录的库有两种来源,均适用本流程:

(a) 第三方上游库:其上游自身不提供 mcpp 支持(如 cJSON、Eigen、nlohmann),由本仓以 compat 形态适配。
(b) 基于 mcpp 开发的库:其上游已是 mcpp 工程(自带 mcpp.toml,可由 mcpp emit xpkg 产出描述符,且具备自有 release),仅需登记进索引(如 mcpplibs.*、tensorvia-cpu)。此类库通常采用 Form A,描述符只声明元数据与下载地址,无需内联构建信息。

本流程不适用于修改 mcpp 本体、修改 xlings 引擎或纯文档变更,上述内容不在本仓范围内。

总流程(十二步)

各步骤应按顺序执行,每一步的细节见对应参考文档。建议以 todo 跟踪进度。

调研来源与形态(决定模板,为最关键步骤)。
- 首先判定来源:属于 (a) 第三方上游库,还是 (b) 基于 mcpp 开发的库。
  - 对 (b),形态已确定(Form A 模块库),版本与 release 由上游提供,因此本步骤较为简单:可直接采用上游 mcpp emit xpkg 的描述符,或参照 pkgs/t/tensorvia-cpu.lua 编写;工作重心在镜像、登记与验证。
  - 对 (a),需按下文判定形态。
- 确定上游仓库与最新 tag/版本(git ls-remote --tags <repo> 配合 sort -V | tail;须注意大版本跳跃, 如 Eigen 由 3.4 跃迁至 5.x)。
- 确认 License 与源码布局:下载 tarball,以 tar -tzf 查看顶层 wrap 目录与子目录,据此判定其属于 纯头文件 / C 源码 / 自带 .cppm 模块 / 含可选组件(可实现 feature) 中的何种形态。
- 计算 sha256sum,并重复计算两次以确认稳定。GitLab 等部分归档源会重新打包,导致 sha 漂移,进而使 CI 经 GLOBAL 拉取时校验失败。
确定形态并选择模板:详见 docs/zh/package-types.md。四类形态为:C 源码 compat、 header-only、C++23 module(generated wrapper)、外部 Form-A 模块仓。
建立 CN 镜像:使用 gtc 在 gitcode mcpp-res 组织下建仓并发布 release,上传与 GLOBAL 相同的 tarball, 以保证字节一致(sha 相同)。在不具备 mcpp-res 写权限时,不应构造镜像表,而应使用纯字符串形式 url = "<GLOBAL 上游 release>"(lint 允许此形式,CN 用户将回退至上游源),镜像由维护者后续补充。详见 docs/zh/cn-mirror.md。
编写描述符 pkgs/<x>/<name>.lua。
- 目录 <x> 取完整包名首字母(compat.eigen 对应 pkgs/c/,nlohmann.json 对应 pkgs/n/), 而非短名。放置错误将导致本地 path index 报 not found in local index。
- xpm 须覆盖三平台(linux/macosx/windows),每个版本包含 url = { GLOBAL=…, CN=… } 与 sha256。
- 版本号采用裸版本(如 "1.2.3"),不含前导 v;下载 URL 中可保留上游的 …/v1.2.3.tar.gz 形式。
识别可门控的可选组件并实现 feature(参见下文“feature 机制”)。feature 仅能门控 sources。
编写测试工程(workspace 成员) tests/examples/<short>/(short 为包名去除 compat./mcpplibs. 前缀后的结果;公开模块包用 <name>-module),并把它加进仓根 mcpp.toml 的 [workspace].members。
- 包含 mcpp.toml 与 tests/*.cpp,后者须包含可失败的有效断言(return ok ? 0 : 1)。
- 成员声明恰好一条 [indices] <ns> = { path = "../../.." },把所消费命名空间重定向到本 checkout(公开模块包用 default,即内建 mcpplibs 命名空间;mcpp ≥ 0.0.97)。单条是硬约束:xlings 对 >1 个项目级 index repo 静默失败(mcpp#238);根级集中化待其修复。
- 非全平台包按 [target.'cfg(...)'.dependencies] 门控依赖,测试源码在被门控掉的平台上编译为 no-op main(#ifdef __linux__ … #else int main(){return 0;} #endif 模式)。
- 如需测试 feature,依赖采用长式声明 name = { version = "…", features = ["…"] }。
本地验证(使用与 CI 相同版本的 mcpp,详见下文“本地验证”)。必须实际执行 mcpp test -p <member> 并通过。
更新 README:在对应分类表中新增一条记录 —— README.md(英文,默认)与 README.zh-CN.md(中文)两份都要更新。
撰写设计文档 .agents/docs/<YYYY-MM-DD>-add-<lib>-plan.md,记录形态判定、镜像、feature 评估、验证结论与注意事项。
本地 lint:在本地复现 validate.yml 的 lint 检查(语法、必填字段、无前导 v、镜像表校验)。详见 docs/zh/repository-and-schema.md。
提交变更:由 main 切出新分支,依次 commit、push、开 PR(不应直接推送 main)。PR 描述应载明形态、镜像、 feature 与验证结论。
确认 CI 通过:workspace (linux|macos|windows) 的选择性成员测试应仅选中本库对应成员并通过 (日志中 selected members: <member>),lint(含 mcpp xpkg parse)与 mirror-cn-reachable 覆盖新增描述符与 CN url。合并由维护者执行。

feature 机制

mcpp 0.0.68 的包描述符 features 表仅能门控 sources;其余子字段会被解析器忽略(经 manifest.cppm 的 features 解析逻辑确认)。

mcpp = {
    sources  = { "*/core.c" },                 -- 默认始终编译
    features = {
        ["extra"] = { sources = { "*/extra.c" } },  -- 默认排除;请求 features=["extra"] 时编入同一 lib 目标
    },
}

消费侧声明:dep = { version = "…", features = ["extra"] }。
既有实例:compat.gtest 的 main(gtest_main.cc)、compat.cjson 的 utils(cJSON_Utils.c)、compat.eigen 的 blas(*/blas/*.cpp 与 */blas/f2c/*.c)。
判定某可选组件能否实现为 feature 的准则:该组件是否为额外的可编译源码。若是,则可门控。纯头文件(如 Eigen 的 unsupported/,与核心共享 include 根,无法隐藏)不可门控;编译期 define(如 EIGEN_MPL2_ONLY、 EIGEN_USE_BLAS)当前无法由 feature 表携带,因而不可门控,应在描述符中加注释说明,待 mcpp 支持 define/cflags 后再实现。
glob 规则:支持 *(段内匹配)与 **(跨段匹配),因此 */blas/*.cpp、*/foo/**/*.c 均合法。
须进行负向验证:在不启用 feature 时,对应的符号或源码应确实缺失(表现为链接期 undefined reference 或编译期找不到),以此证明门控确实生效,而非默认即被编入。

本地验证(与 CI 同版本)

CI 所用 mcpp 版本由 .github/workflows/validate.yml 的 env.MCPP_VERSION 指定。本地验证应使用同一版本,而非本地恰好安装的其它版本。

MV=$(grep -oP 'MCPP_VERSION:\s*"\K[0-9.]+' .github/workflows/validate.yml)
curl -L -fsS -o mcpp.tgz "https://github.com/mcpp-community/mcpp/releases/download/v$MV/mcpp-$MV-linux-x86_64.tar.gz"
tar -xzf mcpp.tgz
root="$PWD/mcpp-$MV-linux-x86_64"
mkdir -p ~/.mcpp/registry && cp -a "$root/registry/." ~/.mcpp/registry/
export MCPP="$root/bin/mcpp"
export MCPP_VENDORED_XLINGS="$root/registry/bin/xlings"
export MCPP_INDEX_MIRROR=GLOBAL          # CI 使用 GLOBAL;CN 由 mirror-cn-reachable 单独校验
rm -rf "tests/examples/<member>/target" "tests/examples/<member>/.mcpp"   # 冷验证:自干净状态走完整管线
"$MCPP" test -p <member>

输出末尾应为 test result ok(测试二进制退出码非 0 即失败)。
如需查看头文件或源码,解包结果位于 tests/examples/<member>/.mcpp/.xlings/data/xpkgs/<idx>-x-<name>/<ver>/<wrap>/。

常见错误与规避

错误做法	正确做法
将 `compat.foo.lua` 置于 `pkgs/f/`	置于 `pkgs/c/`,目录取完整包名首字母
版本写作 `"v1.2.3"`	采用裸版本 `"1.2.3"`,lint 会拦截前导 v
CN 镜像上传经改动的包(与 GLOBAL 不一致)	上传与 GLOBAL 相同的 tarball,sha 一致,以维持 GLOBAL/CN 一致性
仅执行 `mcpp build` 而不 `run`,或示例缺少有效断言	实际运行,并以 `return ok ? 0 : 1` 断言
声称实现了 feature 却未做负向验证	验证默认构建确实不含该组件
未对齐 CI 的 mcpp 版本,本地通过而 CI 失败	读取 `MCPP_VERSION` 并使用同一版本
直接推送 `main`	切出分支并提交 PR

完成前应遵循 verification-before-completion:在声明“通过/完成”之前,须给出真实命令输出作为证据。

name

add-mcpp-index-package

description

向 mcpp-index 新增一个库(标准作业流程)

可直接参考的既有案例如下:

.agents/docs/2026-06-27-add-cjson-and-nlohmann-json-plan.md(C 源码 compat 与模块库)。
.agents/docs/2026-06-28-add-eigen-plan.md(header-only 库及 source-gated blas feature)。
既有 PR:#48(cjson 与 nlohmann.json)、#50(eigen)。

配套参考文档位于仓库 docs/ 目录(英文为默认版本,中文版在 docs/zh/,内容对等),供人工与 agent 共同使用, 可按需查阅(下列链接指向中文版):

docs/zh/package-types.md —— 四种库形态的描述符模板与样例路径。
docs/zh/cn-mirror.md —— CN 镜像闭环,含无 mcpp-res 权限时的回退方案。
docs/zh/repository-and-schema.md —— 仓库结构、schema、CI 行为、关键文件与注意事项。

适用范围

本流程适用于将一个新库(或库的新版本)加入 mcpp-index。被收录的库有两种来源,均适用本流程:

(a) 第三方上游库:其上游自身不提供 mcpp 支持(如 cJSON、Eigen、nlohmann),由本仓以 compat 形态适配。
(b) 基于 mcpp 开发的库:其上游已是 mcpp 工程(自带 mcpp.toml,可由 mcpp emit xpkg 产出描述符,且具备自有 release),仅需登记进索引(如 mcpplibs.*、tensorvia-cpu)。此类库通常采用 Form A,描述符只声明元数据与下载地址,无需内联构建信息。

本流程不适用于修改 mcpp 本体、修改 xlings 引擎或纯文档变更,上述内容不在本仓范围内。

总流程(十二步)

各步骤应按顺序执行,每一步的细节见对应参考文档。建议以 todo 跟踪进度。

调研来源与形态(决定模板,为最关键步骤)。
- 首先判定来源:属于 (a) 第三方上游库,还是 (b) 基于 mcpp 开发的库。
  - 对 (b),形态已确定(Form A 模块库),版本与 release 由上游提供,因此本步骤较为简单:可直接采用上游 mcpp emit xpkg 的描述符,或参照 pkgs/t/tensorvia-cpu.lua 编写;工作重心在镜像、登记与验证。
  - 对 (a),需按下文判定形态。
- 确定上游仓库与最新 tag/版本(git ls-remote --tags <repo> 配合 sort -V | tail;须注意大版本跳跃, 如 Eigen 由 3.4 跃迁至 5.x)。
- 确认 License 与源码布局:下载 tarball,以 tar -tzf 查看顶层 wrap 目录与子目录,据此判定其属于 纯头文件 / C 源码 / 自带 .cppm 模块 / 含可选组件(可实现 feature) 中的何种形态。
- 计算 sha256sum,并重复计算两次以确认稳定。GitLab 等部分归档源会重新打包,导致 sha 漂移,进而使 CI 经 GLOBAL 拉取时校验失败。
确定形态并选择模板:详见 docs/zh/package-types.md。四类形态为:C 源码 compat、 header-only、C++23 module(generated wrapper)、外部 Form-A 模块仓。
建立 CN 镜像:使用 gtc 在 gitcode mcpp-res 组织下建仓并发布 release,上传与 GLOBAL 相同的 tarball, 以保证字节一致(sha 相同)。在不具备 mcpp-res 写权限时,不应构造镜像表,而应使用纯字符串形式 url = "<GLOBAL 上游 release>"(lint 允许此形式,CN 用户将回退至上游源),镜像由维护者后续补充。详见 docs/zh/cn-mirror.md。
编写描述符 pkgs/<x>/<name>.lua。
- 目录 <x> 取完整包名首字母(compat.eigen 对应 pkgs/c/,nlohmann.json 对应 pkgs/n/), 而非短名。放置错误将导致本地 path index 报 not found in local index。
- xpm 须覆盖三平台(linux/macosx/windows),每个版本包含 url = { GLOBAL=…, CN=… } 与 sha256。
- 版本号采用裸版本(如 "1.2.3"),不含前导 v;下载 URL 中可保留上游的 …/v1.2.3.tar.gz 形式。
识别可门控的可选组件并实现 feature(参见下文“feature 机制”)。feature 仅能门控 sources。
编写测试工程(workspace 成员) tests/examples/<short>/(short 为包名去除 compat./mcpplibs. 前缀后的结果;公开模块包用 <name>-module),并把它加进仓根 mcpp.toml 的 [workspace].members。
- 包含 mcpp.toml 与 tests/*.cpp,后者须包含可失败的有效断言(return ok ? 0 : 1)。
- 成员声明恰好一条 [indices] <ns> = { path = "../../.." },把所消费命名空间重定向到本 checkout(公开模块包用 default,即内建 mcpplibs 命名空间;mcpp ≥ 0.0.97)。单条是硬约束:xlings 对 >1 个项目级 index repo 静默失败(mcpp#238);根级集中化待其修复。
- 非全平台包按 [target.'cfg(...)'.dependencies] 门控依赖,测试源码在被门控掉的平台上编译为 no-op main(#ifdef __linux__ … #else int main(){return 0;} #endif 模式)。
- 如需测试 feature,依赖采用长式声明 name = { version = "…", features = ["…"] }。
本地验证(使用与 CI 相同版本的 mcpp,详见下文“本地验证”)。必须实际执行 mcpp test -p <member> 并通过。
更新 README:在对应分类表中新增一条记录 —— README.md(英文,默认)与 README.zh-CN.md(中文)两份都要更新。
撰写设计文档 .agents/docs/<YYYY-MM-DD>-add-<lib>-plan.md,记录形态判定、镜像、feature 评估、验证结论与注意事项。
本地 lint:在本地复现 validate.yml 的 lint 检查(语法、必填字段、无前导 v、镜像表校验)。详见 docs/zh/repository-and-schema.md。
提交变更:由 main 切出新分支,依次 commit、push、开 PR(不应直接推送 main)。PR 描述应载明形态、镜像、 feature 与验证结论。
确认 CI 通过:workspace (linux|macos|windows) 的选择性成员测试应仅选中本库对应成员并通过 (日志中 selected members: <member>),lint(含 mcpp xpkg parse)与 mirror-cn-reachable 覆盖新增描述符与 CN url。合并由维护者执行。

feature 机制

mcpp 0.0.68 的包描述符 features 表仅能门控 sources;其余子字段会被解析器忽略(经 manifest.cppm 的 features 解析逻辑确认)。

mcpp = {
    sources  = { "*/core.c" },                 -- 默认始终编译
    features = {
        ["extra"] = { sources = { "*/extra.c" } },  -- 默认排除;请求 features=["extra"] 时编入同一 lib 目标
    },
}

消费侧声明:dep = { version = "…", features = ["extra"] }。
既有实例:compat.gtest 的 main(gtest_main.cc)、compat.cjson 的 utils(cJSON_Utils.c)、compat.eigen 的 blas(*/blas/*.cpp 与 */blas/f2c/*.c)。
判定某可选组件能否实现为 feature 的准则:该组件是否为额外的可编译源码。若是,则可门控。纯头文件(如 Eigen 的 unsupported/,与核心共享 include 根,无法隐藏)不可门控;编译期 define(如 EIGEN_MPL2_ONLY、 EIGEN_USE_BLAS)当前无法由 feature 表携带,因而不可门控,应在描述符中加注释说明,待 mcpp 支持 define/cflags 后再实现。
glob 规则:支持 *(段内匹配)与 **(跨段匹配),因此 */blas/*.cpp、*/foo/**/*.c 均合法。
须进行负向验证:在不启用 feature 时,对应的符号或源码应确实缺失(表现为链接期 undefined reference 或编译期找不到),以此证明门控确实生效,而非默认即被编入。

本地验证(与 CI 同版本)

CI 所用 mcpp 版本由 .github/workflows/validate.yml 的 env.MCPP_VERSION 指定。本地验证应使用同一版本,而非本地恰好安装的其它版本。

MV=$(grep -oP 'MCPP_VERSION:\s*"\K[0-9.]+' .github/workflows/validate.yml)
curl -L -fsS -o mcpp.tgz "https://github.com/mcpp-community/mcpp/releases/download/v$MV/mcpp-$MV-linux-x86_64.tar.gz"
tar -xzf mcpp.tgz
root="$PWD/mcpp-$MV-linux-x86_64"
mkdir -p ~/.mcpp/registry && cp -a "$root/registry/." ~/.mcpp/registry/
export MCPP="$root/bin/mcpp"
export MCPP_VENDORED_XLINGS="$root/registry/bin/xlings"
export MCPP_INDEX_MIRROR=GLOBAL          # CI 使用 GLOBAL;CN 由 mirror-cn-reachable 单独校验
rm -rf "tests/examples/<member>/target" "tests/examples/<member>/.mcpp"   # 冷验证:自干净状态走完整管线
"$MCPP" test -p <member>

输出末尾应为 test result ok(测试二进制退出码非 0 即失败)。
如需查看头文件或源码,解包结果位于 tests/examples/<member>/.mcpp/.xlings/data/xpkgs/<idx>-x-<name>/<ver>/<wrap>/。

常见错误与规避

错误做法	正确做法
将 `compat.foo.lua` 置于 `pkgs/f/`	置于 `pkgs/c/`,目录取完整包名首字母
版本写作 `"v1.2.3"`	采用裸版本 `"1.2.3"`,lint 会拦截前导 v
CN 镜像上传经改动的包(与 GLOBAL 不一致)	上传与 GLOBAL 相同的 tarball,sha 一致,以维持 GLOBAL/CN 一致性
仅执行 `mcpp build` 而不 `run`,或示例缺少有效断言	实际运行,并以 `return ok ? 0 : 1` 断言
声称实现了 feature 却未做负向验证	验证默认构建确实不含该组件
未对齐 CI 的 mcpp 版本,本地通过而 CI 失败	读取 `MCPP_VERSION` 并使用同一版本
直接推送 `main`	切出分支并提交 PR

完成前应遵循 verification-before-completion:在声明“通过/完成”之前,须给出真实命令输出作为证据。