mcpField
M
make-moonbit-c-bindings

make-moonbit-c-bindings

github.com/moonbitlang开发34201 次安装6 周前更新
代码仓库

关于 make-moonbit-c-bindings

make-moonbit-c-bindings 是用于端到端构建 MoonBit C 绑定的开发技能，面向封装 C/C++ 库的开发者，强调安全 API 设计、FFI 边界和可重复验证。

主要功能

  1. 01检查上游头文件与 ABI 类型
  2. 02设计安全的 MoonBit API
  3. 03生成 C 包装层与私有 FFI
  4. 04供应源码并生成配置头文件
  5. 05运行格式、测试与 ASan 验证

适用场景

  1. 01为 C 库创建 MoonBit 绑定
  2. 02将 C 内存所有权纳入包装层处理
  3. 03为原生目标配置可重复源码供应
  4. 04验证绑定的类型、测试与文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/moonbitlang/skills --skill make-moonbit-c-bindings

安装后在 Claude Code 中输入/make-moonbit-c-bindings确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
lifecycle-and-ownership.md
testing-and-documentation.md
vendoring-and-package-setup.md
templates/
api.mbt
ffi.mbt
moon.mod.json
moon.pkg
prepare.py
README.mbt.md
wrapper.c

详细介绍

构建 MoonBit C 绑定

将此技能用于端到端绑定项目。实现之前，还要阅读 moonbit-c-binding，了解底层 FFI 语法、所有权注解以及 moonbit.h 的详细信息。

快速开始

  1. 在临时目录中克隆或检查上游 C/C++ 项目。
  2. 找出公共头文件、生成的配置头文件、源代码布局、分配器 API 以及构建时的类型宽度。
  3. 确定安全的 MoonBit API 范围；不要机械地暴露每个 C API。
  4. 使用 templates/prepare.py 将源代码纳入项目；只有在明确需要时，才链接系统库。
  5. 编写精简的 C 封装、私有 MoonBit extern 以及安全的公共 MoonBit 封装。
  6. 使用 moon check、原生测试、ASan、moon info 和 vendoring 脚本幂等性检查进行验证。

绑定架构

优先采用以下布局，并根据库调整名称。请从捆绑模板开始，而不是从头重写脚手架：

scripts/prepare.py          # optional: pinned upstream download + generated stubs
moon.mod.json               # preferred/supported native targets
src/moon.pkg                # native-stub list and file target gates
src/wrapper.c               # ABI normalization and ownership boundaries
src/ffi.mbt                 # private extern "c" declarations
src/<domain>.mbt            # safe public MoonBit API
src/<domain>_test.mbt       # regression tests
src/README.mbt.md           # tested documentation examples
README.md -> src/README.mbt.md

模板映射：

  • templates/prepare.py -> scripts/prepare.py
  • templates/moon.mod.json -> moon.mod.json
  • templates/moon.pkg -> src/moon.pkg
  • templates/wrapper.c -> src/wrapper.c
  • templates/ffi.mbt -> src/ffi.mbt
  • templates/api.mbt -> src/<domain>.mbt
  • templates/README.mbt.md -> src/README.mbt.md

进行 ASan 验证时，将配套运行器从 moonbit-c-binding/scripts/run-asan.py 复制或调用为 scripts/run-asan.py；除非该运行器无法适配项目，否则不要另行编写 ASan 补丁脚本。

工作流

1. 调查上游项目
  • 先阅读公共头文件；它们定义了绑定契约。
  • 记录项目专用 typedef 的配置宽度：索引类型、标量类型、大小／计数类型、句柄类型、枚举底层类型以及回调。
  • 将库 API 与仅供 CLI 使用的 API、内部代码、生成代码或测试代码区分开。
  • 查找会分配内存、修改输入、存储回调或需要配对调用 destroy/free 的函数。
2. 设计 MoonBit API
  • 尽可能公开与当前 C 库相匹配的领域专用 MoonBit 类型，而不是裸指针和数组。
  • 在进入 C 之前验证形状和选项长度。
  • 如果安全封装无法保证其语义，就省略不安全或容易误导的 C 特性。
  • 将 C 状态码映射为 MoonBit 错误；对于输出参数，返回结构化结果记录。
3. 纳入源代码或链接库
  • 对于可移植的包，将 C 源代码纳入 native-stub，并固定修订版本、提供可重复运行的脚本。
  • 如果 MoonBit 要求存根位于单个包目录中，就将源文件拍平，并以确定性方式重写 include。
  • 生成配置头文件，而不是依赖临时编译器标志。
  • 确保 vendoring 脚本可重复运行，且不会产生受跟踪文件的差异。
4. 构建 FFI 边界
  • C 封装负责 ABI 规范化：类型宽度断言、可选指针转换、输出复制以及释放由 C 分配的内存。
  • ffi.mbt 应将 extern 保持为私有，并明确使用 #borrow / #owned。
  • 公共 MoonBit 文件应只调用安全的封装函数，绝不直接调用原始 C API。
  • 避免为可选数组增加额外的布尔哨兵参数；优先使用空的 MoonBit 数组，并在 C 中检查 Moonbit_array_length。
5. 验证

至少运行：

moon fmt
moon check --target all --warn-list +73
moon test --target native
python3 scripts/run-asan.py
moon info --target native
python3 scripts/prepare.py
git status --short

对于仅支持原生平台的包，在 moon.mod.json 中设置 "preferred-target": "native"，并将 "supported-targets" 设为最小且真实可用的值。

必需参考资料

生命周期与所有权； 纳入源代码与包设置； 测试与文档。

评论

支持 Markdown