Lua Wiki 部分翻译 — Lua Source

Lua Source

The section of the wiki allows anyone to document, explain, post questions, or make comments on the Lua source code. You may link to [1] or paste the code in question. Note: Please indicate which version of the source (e.g. 5.1.1) you are discussing so there will be no confusion upon future releases of Lua. Preferably, discussions should be on or updated to the latest release of Lua.

代码注释

概述
通过阅读Lua论文[2]以及Lua架构文档[The Lua Architecture]从不同角度了解Lua实现。
关于Lua虚拟机指令集有一个文档[A No-Frills Introduction to Lua 5.1 VM Instructions].
[Yueliang]项目（一个Lua虚拟机，移植c代码为Lua代码）有大量添加过注释的源代码，可以用来帮助理解相关的C语言代码。

模块结构

Lua源代码模块概要如下：

这些模块实现了应用功能：

ldebug.c – 调试接口。包括可以获取debug hooks的函数（lua_sethook, lua_gethook, lua_gethookcount），获取运行时栈信息的函数（lua_getstack / lua_getlocal / lua_setlocal），检查字节码的函数（luaG_checkopenop / luaG_checkcode），以及产生某些错误的函数（luaG_typeerror / luaG_concaterror / luaG_aritherror / luaG_ordererror / luaG_errormsg / luaG_runerror）

lzio.c – 一个通用的缓冲输入流接口。

lmem.c – 内存管理接口。实现了luaM_realloc / luaM_growaux_，这两个函数包装了内存分配函数。

lgc.c – 增量垃圾收集器（内存管理）。

以下模块实现了基本数据类型：

lstate.c – 全局状态。包括打开及关闭Lua states的函数（lua_newstate/lua_close）以及线程相关函数（luaE_newthread / luaE_freethread）。

lobject.c – Lua对象上的一些通用函数，包括数据类型<->字符串转换，原始相等测试（luaO_rawequalObj）和log base 2函数（luaO_log2）。

lstring.c – 字符串表（保存所有Lua处理过的字符串）

lfunc.c – 操作原型（prototypes）和闭包（closures）的辅助函数。

ltable.c – Lua表（哈希）

下面模块处理解析以及代码生成任务：

lcode.c – Lua代码生成器，被lparser.c使用。

llex.c – 词汇分析器，被lparser.c使用。

lparser.c – Lua分析器。

lundump.c – 载入编译好的Lua组块（chunks）。实现luaU_undump函数，可以载入预编译组块。也提供了luaU_header函数(luaU_undump内部使用)来解析函数头。

ldump.c – 保存编译好的组块。实现luaU_dump函数，可以转存（dump）一个函数对象为编译好的组块字符串。

下面模块处理Lua字节码的运行：

lopcodes.c – Lua虚拟机操作码。（通过luaP_opnames and luaP_opmodes表）定义关于所有操作码的名字和信息。

lvm.c – Lua virtual machine. Executes bytecodes (luaV_execute). Also exposes a few functions used by lapi.c (e.g. luaV_concat).
lvm.c – Lua虚拟机。运行字节码（luaV_execute)，也暴露出一些函数给lapi.c使用（比如luaV_concat）。

ldo.c – Lua堆栈和调用结构。处理了函数调用（luaD_call / luaD_pcall），增长栈、协程处理……

ltm.c – tag方法。实现了从对象中获取元方法。

下面模块实现了标准库:

lbaselib.c – (base functions)

lstrlib.c – string

ltablib.c – table

lmathlib.c – math

loslib.c – os

liolib.c – io

loadlib.c – package

ldblib.c – debug

下面模块定义了C API:

lapi.c – Lua API，实现了大量Lua C API（如lua_* 函数）。

lauxlib.c – 定义了Lua_L*函数。

linit.c – 实现了luaL_openlibs函数，在C语言中载入以上模块。

下面模块实现了Lua和Luac程序：

lua.c – Lua独立解释器

print.c – 定义了PrintFunction?函数来打印函数中的字节码（被luac.c "-l"选项使用）。

luac.c – Lua编译器，保存字节码到文件，也可以列出字节码。

(5.1.3)

代码规范

外部符号的前缀指明了它从哪个模块来的：

luaA_ – lapi.c
luaB_ – lbaselib.c
luaC_ – lgc.c
luaD_ – ldo.c
luaE_ – lstate.c
luaF_ – lfunc.c
luaG_ – ldebug.c
luaH_ – ltable.c
luaI_ – lauxlib.c
luaK_ – lcode.c
luaL_ – lauxlib.c/h, linit.c (public functions)
luaM_ – lmem.c
luaO_ – lobject.c
luaP_ – lopcodes.c
luaS_ – lstring.c
luaT_ – ltm.c
luaU_ – lundump.c
luaV_ – lvm.c
luaX_ – llex.c
luaY_ – lparser.c
luaZ_ – lzio.c
lua_ – lapi.c/h + luaconf.h, debug.c
luai_ – luaconf.h
luaopen_ – luaconf.h + libraries (lbaselib.c, ldblib.c, liolib.c, lmathlib.c,
loadlib.c, loslib.c, lstrlib.c, ltablib.c)
(5.1.3)

src/Makefile

In src/Makefile (5.1.1), the mingw target is unusual in that it only builds lua (not luac). A mingw-cygwin target could be added too. See mingw notes in BuildingLua for resolution.

In src/luaconf.h (5.1.1), LUA_PATH_DEFAULT refers to both LUA_LDIR and LUA_CDIR, but LUA_CPATH_DEFAULT refers only to the LUA_CDIR of these. RiciLake suggested this might be a security decision, where C modules require more trust than Lua modules.

src/luaconf.h

In src/luaconf.h (5.1.1), there is a LUA_CDIR"loadall.dll", which is discussed in [3] [4].

src/lgc.h and lgc.c (garbage collector)

可以参考GarbageCollection以及EmergencyGarbageCollector，来了解垃圾收集的部分。

src/ltable.h and ltable.c (tables)

See LuaSourceTable

src/lmathlib.c

This is described some in BindingCodeToLua.

Note: the line "#define lmathlib_c" (and similar lines in the other libraries) exist only for conditionals in luaconf.h (noted by lhf).

Comments on this Page

Notes on the purpose of this page: Some users have said the Lua source code should be better documented and particularly, as done here, to allow anyone to assist in that. This is also related to a suggestion for a more wiki-like approach to commenting on each function in the Lua API as done on the below sites. This would probably involve a new section of the wiki, possibly named LuaDoc?, DocLua?, or individual pages like DocLuaTostring? if there’s enough content.

I strongly disagree that a wiki is the right medium to do this for several reasons, the main one being that it won’t scale well. I suggest checking in a pristine copy of the Lua upstream source to a source control repository, and allowing people to check in comments directly onto the source code (e.g. you can put a comment on a specific function, struct member, etc.). This way there is some hope of carrying the comments (by merging) to future Lua releases. —JohnBelmonte

— This was following some discussion with Rici, Lhf, and Steinwookie. I think the understanding is that this documentation would not necessarily be the usual "doxygen"-like format on a function/parameter/line level and cluttering every function. Rather, Lhf suggested this documentation could be more in a literate programming format. This is not entirely unusual. For example, there are books explaining the linux kernel sources, and in Lua there are things like the No-frills Intro to Lua 5.1 VM. There was also a feeling that the chance this documentation, or anything, would get into the core is fairly low, or at least there is no current commitment to that.–DavidManura

None of the arguments seem related to wiki being the wrong medium for this. What will happen with Lua 6, 7, 8, etc. when the set of files and their content changes? –John

— Much of the same concerns apply to LuaPowerPatches. The wiki can be more convenient/open. The Lua source is strongly controlled and a slowly moving target (e.g. very few patches against a small Lua core). Questions on the source can be posted here as well. Keeping the wiki content in sync with different Lua versions affects most pages on the wiki–and that has been a problem, but the solution is a simple convention of wiki content noting which version of Lua it applies to. —DavidManura

宝贝孙秀楠