# 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 与现代版本差异大。建议仅在确有历史脚本兼容需求时投入。