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

> 本分支已 vendor Lua 4.0.1 官方源码到 `lib/lua/`。
> **桥接层尚未适配**——需要按本文档指引改造后方可有限使用。

## 支持范围

经过源码分析，Lua 4.0 可实现的有限支持：

| 功能 | 支持 | 说明 |
|------|------|------|
| `doString` | ✅ | `lua_dostring(L, s)` 直接映射 |
| `runScript`(单次) | ✅ | `lua_dofile` + `lua_call` 组合 |
| `loadFunction` | ✅ | 文件名→`lua_dofile`(返回函数)→`lua_ref` 锁定 |
| `callFunction` | ✅ | `lua_getref`→`lua_call` → `lua_settop` 取结果 |
| `unloadFunction` | ✅ | `lua_unref` |
| I/O 重定向 | ✅ | Registry 存 iopath（同 5.1/5.2 方案） |
| typed interop | ✅ | 全部映射为 number（无 boolean 类型） |
| **管道模式** | ❌ | 4.0 无 `luaL_loadfile`，无法分离编译与执行 |
| **`load_lib`** | ❌ | 同上，块压栈不可实现 |

## 关键 API 差异

| 5.x 函数 | 4.0 等价 | 备注 |
|----------|----------|------|
| `luaL_newstate()` | `lua_open(stacksize)` | 4.0 需指定栈大小（如 `lua_open(1024)`） |
| `luaL_openlibs()` | 逐库 `lua_*libopen` | 逐个调用 `lua_baselibopen`/`lua_iolibopen`/... |
| `lua_pcall` | `lua_call` | 4.0 的 `lua_call` 是**保护调用**，返回 status |
| `luaL_loadfile` | **不存在** | 无法预编译；管道模式不可实现 |
| `luaL_dostring` | `lua_dostring(L, s)` | 直接映射 |
| 错误信息 | `_ERRORMESSAGE` 全局 | 非栈顶，需取全局函数输出 |
| `LUA_REGISTRYINDEX` | `lua_ref` / `lua_getref` | 4.0 引用表机制不同 |
| `lua_pushboolean` | `lua_pushnumber` | 4.0 无 boolean 类型 |
| `lua_pushcfunction` | `lua_pushcclosure(L, fn, 0)` | 0 个闭包上值 |
| `luaL_ref`/`luaL_unref` | `lua_ref`/`lua_unref` | 4.0 的 `lua_ref(L, 1)` 锁定并返回 ref |
| `luaL_newmetatable` | 无 | 需 `lua_newtable` + `lua_settagmethod` |
| `lua_pushlightuserdata` | `lua_pushusertag` | 需分配 tag |

## 估算工作量

- 桥接层 C++ 重写：~400 行
- 测试：GTest 中管道相关测试（`MultipleLoadUnload`、管道链）无法运行
- 构建系统：CMakeLists 按 4.0 文件集重写（源码结构完全不同）
- 仓颉层：无需改动

## 结论

技术上可行但收益有限：
- 管道模式（项目核心特性）无法实现
- 无 `luaL_loadfile` 导致 `load`/`runScript` 语义与 5.x 版本不同
- 4.0 发布于 2000 年，实际使用场景极少
- 建议仅在需要加载特定 Lua 4.0 遗留脚本时投入适配