Lua 原始碼

wiki

原始碼的註解

概觀

• Lua 論文[2] 和 [Lua 架構] 文件說明了 Lua 執行的各個面向。
• Lua 虛擬機器指令說明文件位於 [Lua 5.1 虛擬機器指令無刻畫簡介]。
• [岳良] 計畫（將 Lua 虛擬機器 C 碼移植到 Lua）的文件中記錄了大量的原始碼，可用來幫助了解對應的 C 原始碼。
• LuaAnnotate - C 碼註解外部儲存但內嵌顯示（專門用以註解 Lua 原始碼）
• [stevedonovan.github.com/lua-5.1.4] 可瀏覽的 Lua 原始碼，附有 LuaAnnotate 註解
• [www.lua.org/source/] - 可瀏覽的 Lua 原始碼，位於 lua.org

模組結構

以下列出 Lua 原始碼中的模組。

這些模組實作工具功能

• ldebug.c - 偵錯介面。包括存取偵錯掛鉤的函式 (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 狀態 (lua_newstate/lua_close) 和執行緒 (luaE_newthread / luaE_freethread) 的函式。

• lobject.c - 一些處理 Lua 物件的通用函式。包括資料型態 <-> 字串轉換、原始相等性測試 (luaO_rawequalObj) 和對數以 2 為底 (luaO_log2)

• lstring.c - 字串表（儲存 Lua 處理的所有字串）

• lfunc.c - 用於操作原型和閉包的輔助函式

• ltable.c - Lua 表格（雜湊）

這些模組用於分析和產生程式碼

• lcode.c - Lua 的程式碼產生器。lparser.c 使用。

• llex.c - 字彙分析器。lparser.c 使用。

• lparser.c - Lua 解析器。

• lundump.c - 載入預先編譯的 Lua 區塊，實作 luaU_undump，用於載入預先編譯的區塊。也提供 luaU_header（由 luaU_undump 內部使用），用於剖析函數標頭。

• ldump.c - 儲存預先編譯的 Lua 區塊，實作 luaU_dump，用於將函式物件轉儲成預先編譯的區塊字串。

這些模組處理 Lua 位元碼的執行

• lopcodes.c - Lua 虛擬機的 opcode，定義所有 opcode 的名稱和資訊（透過表格 luaP_opnames 和 luaP_opmodes）。

• lvm.c - Lua 虛擬機，執行位元碼（luaV_execute）。也揭露 lapi.c 使用的一些函式（例如 luaV_concat）。

• ldo.c - Lua 的堆疊和呼叫結構，處理函式呼叫（luaD_call / luaD_pcall），擴充堆疊、協程處理，...

• ltm.c - 標記方法，實作從物件存取 metatable。

這些模組實作標準函式庫

• lbaselib.c - （基礎函式）

• lstrlib.c - 字串

• ltablib.c - 表格

• lmathlib.c - 數學

• loslib.c - 作業系統

• liolib.c - I/O

• loadlib.c - 套件

• ldblib.c - 除錯

這些模組定義 C API

• lapi.c - Lua API，實作大部分的 Lua C API（lua_* 函式）。

• lauxlib.c - 定義 luaL_* 函式

• 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)

src/Makefile

在 src/Makefile （5.1.1）中，mingw 目標很特別，因為它只會建立 lua（不建立 luac）。也可以加入 mingw-cygwin 目標。請參考 BuildingLua 中的 mingw 標示，了解解決方法。

在 src/luaconf.h （5.1.1）中，LUA_PATH_DEFAULT 指 LUA_LDIR 和 LUA_CDIR，但 LUA_CPATH_DEFAULT 只指這些的 LUA_CDIR。 RiciLake 表示這可能是安全性考量，因為 C 模組需要比 Lua 模組更高的信任度。

src/luaconf.h

在 src/luaconf.h （5.1.1）中，有一個 LUA_CDIR"loadall.dll"，[3] [4] 中有相關討論。

src/lgc.h 和 lgc.c（垃圾回收器）

請參考 GarbageCollection，以及 EmergencyGarbageCollector 中的說明。

sec/ltable.h 和 ltable.c（表格）

請參考 LuaSourceTable

src/lmathlib.c

在 BindingCodeToLua 中有部分說明。

請注意，在其他函式庫中也有 "#define lmathlib_c"（以及類似行）的行，這些行純粹是為 luaconf.h 中的條件式而存在（由 lhf 標示）。

此頁面的評論

此頁面目的的註解：一些使用者表示 Lua 原始程式碼文件應該加上較詳細的文件，尤其是像此處所做的，開放讓任何人協助文件編寫。這也與在以下網站中針對 Lua API 中的每個函式的註解，例如 wiki 式方法的建議相關。這可能會需要 wiki 新的部分，其名稱可能是 LuaDoc?、DocLua? 或如果內容夠多，則有像是 DocLuaTostring? 等個別頁面。

• http://rpgstats.com/wiki/index.php?title=LlGetBoundingBox
• https://mysqldev.dev.org.tw/doc/refman/4.1/en/insert.html

我強烈反對使用 wiki 來執行這項工作，原因有幾個，最主要的原因是這項工作無法順利地擴展。我建議將 Lua 上游原始程式碼的核心版本簽入至原始碼控制回存庫，並允許其他人直接將註解簽入至原始碼中（例如您可以針對特定函式、結構成員等加入註解）。如此一來，便可將註解傳遞（透過合併）至未來的 Lua 發行版本。 --JohnBelmonte

-- 這是針對一些與 Rici、Lhf 和 Steinwookie 的討論後提出的看法。我認為這項文件的編修格式不一定是函式/參數/行層級中常見的「doxygen」格式，也不會讓每個函式變得雜亂不堪。Lhf 建議這份文件可以採用更接近於程式設計文件格式的格式。這並非全然不可能。舉例來說，有些書籍會用來解釋 linux 核心原始程式碼，而在 Lua 中，則有 No-frills Intro to Lua 5.1 VM 等教材。另外也認為此文件可能會內建至核心的機率很低，或至少目前沒有這種承諾。--DavidManura

這些論點似乎與 wiki 不是此文件適當媒介無關。到了 Lua 6、7、8 時，當檔案組及其內容變更時，發生什麼事？--John

-- 許多相同的顧慮也適用於 LuaPowerPatches。wiki 可能較為便利/開放。Lua 原始程式碼受到嚴格控制，變動也較為緩慢（例如只在 Lua 核心中的少部分程式碼上套用多個程式碼修補）。也可以在此張貼原始程式碼相關的問題。讓 wiki 內容與不同版本的 Lua 同步，會影響到 wiki 中的大部分頁面，而且這已經造成問題，但解決方式是採用一個簡單的慣例，說明 wiki 內容套用於哪個版本的 Lua。 --DavidManura

請參見

• LuaList:2008-03/msg00015.html - 「許多人要求在原始程式碼中加入更多註解。」
• ModifyingLua - 描述自訂程式碼修補 Lua 以加入 __setindex 的步驟