LuaCangjia_api/doc/ADAPTATION-lua32.md

Lua 3.2 分支移植评估（ADAPTATION.md）

本分支已 vendor Lua 3.2 官方源码到 lib/lua/（include/ 头文件 + src 平铺）。 桥接层尚未适配——Lua 3.x 是"前 lua_State 时代"的 API，与本项目桥接层不兼容。

当前状态

• ✅ Lua 3.2 源码就位（18 个 .c）
• ❌ lib/lua_runner.cpp / lib/lua_cj_api.cpp 未适配
• ❌ 构建系统未适配（CMakeLists 需按 3.2 文件集重写）

移植要点

Lua 1.0~3.2 均为全局唯一状态机设计：

能力	Lua 5.4 桥接实现	Lua 3.2	改造方案
状态机	luaL_newstate() 返回句柄，可多实例	lua_open(void) 全局单例，lua_close(void)	多实例语义丧失：仓颉侧多个 LuaRunner 共享同一状态机；handle 退化为哑指针
加载执行	luaL_loadfile + lua_pcall	lua_dofile(char*) / lua_dostring(char*) 一步式	run()/doString 重写；无编译/执行分离 → 管道模式（块压栈）不可实现
函数引用	luaL_ref + Registry	lua_ref(lua_Object) / lua_getref	loadFunction 可映射，但 lua_Object 是 unsigned int 句柄
栈模型	显式虚拟栈索引操作	隐式"对象栈"，lua_getparam(n) 取参	整个 pkgs[] 栈布局逻辑推倒重写
数据传递	栈上多值	单返回值 lua_getresult	typed interop 仅剩 string/number
I/O 重定向	extraspace/Registry 存 iopath	无对应机制，print 劫持需用 tag method 或改 lbuiltin.c 源码	成本高

结论

不建议移植。理由：

1. 全局单例状态机与本项目"多 runner 实例"的核心抽象冲突
2. 无编译/执行分离，管道模式（项目核心特性）无法实现
3. 1999 年的 API，无 integer 类型、无保护调用、tag method 机制与现代完全不同
4. 实际收益趋近于零——没有现存应用依赖 Lua 3.x 嵌入

本分支仅作为源码存档。若确需支持，建议以 lua_dofile+全局单例为边界 做一个极简 doString-only 的独立桥接，而非复用现有 Lua_runner 抽象。