LuaCangjia_api/doc/ADAPTATION-lua40.md

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

本分支已 vendor Lua 4.0.1 官方源码到 lib/lua/。 桥接层尚未适配——Lua 4.0 的 C API 与 5.x 存在代际差异，需要按本文档改造后方可使用。

当前状态

• ✅ Lua 4.0.1 源码就位
• ❌ lib/lua_runner.cpp / lib/lua_cj_api.cpp 未适配（仍为 Lua 5.4 API）
• ❌ 仓颉层 src/bridge.cj 无需改动（FFI 签名与版本无关）

移植要点

Lua 4.0 是第一个引入 lua_State* 的版本，但 API 与 5.x 有以下关键差异：

能力	Lua 5.4（当前桥接实现）	Lua 4.0	改造方案
创建状态机	luaL_newstate() + luaL_openlibs()	lua_open(stacksize) + lua_baselibopen() 等逐个打开	重写 init
加载文件	luaL_loadfile() + lua_pcall() 两步	lua_dofile(L, path) 一步完成	run() 重写；错误处理从 pcall 返回值改为 lua_dofile 返回码
执行字符串	luaL_dostring()	lua_dostring(L, s)	直接映射
调用栈顶函数	lua_pcall(L, nargs, MULTRET, 0)	lua_call(L, nargs, nresults)（无保护，出错直接 abort）	需包一层 lua_cpcall 或接受非保护语义
函数引用表	luaL_ref(L, LUA_REGISTRYINDEX)	lua_ref(L, lock) / lua_getref / lua_unref	loadFunction/callFunction 全套改名
压栈	lua_pushinteger(5.3+) / lua_pushnumber / lua_pushboolean	仅 lua_pushnumber / lua_pushstring（无 integer 类型、boolean 用 number 0/1）	typed interop 退化为 number-only
取值	lua_tointeger / lua_isinteger	无	capture_result() 统一 CJT_NUM
栈操作	lua_gettop / lua_settop / lua_remove / lua_pop	同名存在 ✅	兼容
extraspace I/O 重定向	lua_getextraspace()	不存在	改 Registry 存储 iopath*（参照 lua_5.1.5/lua_5.2.4 分支方案）
print/io 劫持	lua_pushcfunction + lua_setglobal("print")	lua_register(L, name, func)	可映射

预估工作量

• 桥接层 C++：~300 行改动（init/run/loadfunction/callfunction/I-O 重定向五大块）
• 测试：GTest 大部分可保留，PackagePathConfig 与 require 相关断言需按 4.0 语义重写
• 构建系统：CMakeLists 文件集需按 4.0 源码列表调整（无 loadlib.c/loslib.c 等）

结论

技术上可移植但性价比低：Lua 4.0 发布于 2000 年，语言本身无 integer 类型、 无保护调用、GC 与现代版本差异大。建议仅在确有历史脚本兼容需求时投入。