mcpplibs capi-lua

Lua C API 的 C++23 模块化绑定 - import mcpplibs.capi.lua;

将 Lua C API（lua.h / lauxlib.h / lualib.h）封装为 C++23 模块，让其他 mcpplibs 模块可以通过 import 直接使用 Lua，无需手动 #include C 头文件。

特性

• C++23 模块 — import mcpplibs.capi.lua;
• 1:1 映射 — 接口与 Lua C API 完全对应，零额外抽象
• 零开销 — 所有封装均为 inline 函数和 constexpr 常量
• 双构建系统 — 同时支持 xmake 和 CMake
• CI/CD — GitHub Actions 多平台构建（Linux / macOS / Windows）
• 遵循 mcpp-style-ref — 标准化命名和项目结构

命名映射

在 mcpplibs::capi::lua 命名空间内，去掉 C API 前缀避免冗余：

C API	模块内	示例
lua_State	State	lua::State*
lua_gettop()	gettop()	lua::gettop(L)
luaL_newstate()	L_newstate()	lua::L_newstate()
LUA_OK	OK	lua::OK
luaopen_base()	open_base()	lua::open_base(L)

快速开始

import std;
import mcpplibs.capi.lua;
namespacelua= mcpplibs::capi::lua;
intmain() {
auto* L = lua::L_newstate();
lua::L_openlibs(L);
lua::L_dostring(L, "print('hello from Lua!')");
lua::close(L);
return0;
}

安装与配置

xlings install

构建与运行

使用 xmake

xmake build # 构建库
xmake run basic # 基本用法示例
xmake run table # 表操作示例
xmake run function# 函数注册示例
xmake run eval# 脚本求值示例
xmake run capi_lua_test # 运行测试

使用 CMake

cmake -B build -G Ninja
cmake --build build
ctest --test-dir build

项目结构

mcpplibs-capi-lua/
├── src/ # 模块源码
│ └── capi/
│ └── lua.cppm # 主模块接口 (export module mcpplibs.capi.lua)
├── tests/ # 测试
│ ├── main.cpp # Google Test 测试套件
│ └── xmake.lua
├── examples/ # 示例
│ ├── basic.cpp # 基本用法
│ ├── table.cpp # 表操作
│ ├── function.cpp # 函数注册与回调
│ ├── eval.cpp # 脚本求值
│ └── xmake.lua
├── docs/ # 文档
│ ├── architecture.md # 架构文档
│ └── pr/
│ ├── design.md # 设计文档
│ └── tasks.md # 任务清单
├── .github/workflows/ # CI/CD
│ └── ci.yml
├── xmake.lua # xmake 构建配置
├── CMakeLists.txt # CMake 构建配置
└── config.xlings # xlings 工具链配置

集成到构建工具

xmake

add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")
add_requires("capi-lua")
target("myapp")
set_kind("binary")
set_languages("c++23")
add_files("main.cpp")
add_packages("capi-lua")
set_policy("build.c++.modules", true)

mcpp

添加依赖

mcpp add mcpplibs.capi:lua@0.0.3

或在 mcpp.toml 中手动添加：

[dependencies]
"mcpplibs.capi:lua" = "0.0.3"

构建

mcpp build

代码示例

import mcpplibs.capi.lua;
// ... 参见上方"快速开始"

覆盖范围

封装了 Lua 5.4 C API 的核心功能：

• 类型 — State, Number, Integer, CFunction, L_Reg, L_Buffer 等
• 常量 — 状态码、类型标签、运算符、GC 选项、Hook 掩码等
• 状态管理 — L_newstate, close, newthread, version 等
• 栈操作 — gettop, settop, pop, pushvalue, rotate, insert, remove, replace 等
• 入栈/取值 — pushnil/number/integer/string/boolean, tonumber/tointeger/tostring/toboolean 等
• 表操作 — newtable, getfield/setfield, gettable/settable, rawget/rawset, next 等
• 函数调用 — call, pcall, pushcfunction, pushcclosure 等
• 辅助库 — L_dostring, L_dofile, L_loadstring, L_ref/L_unref, L_setfuncs, L_error 等
• 标准库 — open_base, open_math, open_string, open_table, open_io, open_os 等
• 调试 — getstack, getinfo, sethook, gethook 等

相关链接

• mcpp-style-ref | 现代C++编码/项目风格参考
• mcpplibs/templates | 项目模板
• mcpp社区官网
• mcpp | 现代C++爱好者论坛