Lua Source

wiki

Comments on Source

Overview

• The Lua papers[2] and [The Lua Architecture] document various aspects of the Lua implementation.
• The Lua VM instructions are documented in [A No-Frills Introduction to Lua 5.1 VM Instructions].
• The [Yueliang] project (a port of the Lua VM C code to Lua) has fairly heavily documented source code and can be used to help understand the corresponding C source code.
• LuaAnnotate - C code comments externally stored but displayed inline (intended for annotating Lua sources)
• [stevedonovan.github.com/lua-5.1.4] browsable Lua source code with LuaAnnotate annotations
• [www.lua.org/source/] - browsable Lua source code, on lua.org

Module Structure

The modules in the Lua source are outlined below.

These modules implement utility functionality:

• ldebug.c - debug interface. Includes functions for accessing debug hooks (lua_sethook, lua_gethook, lua_gethookcount), accessing run-time stack info (lua_getstack / lua_getlocal / lua_setlocal), checking bytecode (luaG_checkopenop / luaG_checkcode), and raising errors (luaG_typeerror / luaG_concaterror / luaG_aritherror / luaG_ordererror / luaG_errormsg / luaG_runerror)

• lzio.c - a generic buffered input stream interface.

• lmem.c - interface to the memory manager. This implements luaM_realloc / luaM_growaux_, which wrap the memory allocation functions.

• lgc.c - incremental garbage collector (memory management)

These modules implement basic data types:

• lstate.c - global state. Includes functions for opening and closing Lua states (lua_newstate/lua_close) and threads (luaE_newthread / luaE_freethread).

• lobject.c - some generic functions over Lua objects. Includes datatype <-> string conversions, raw equality test (luaO_rawequalObj), and log base 2 (luaO_log2)

• lstring.c - string table (keeps all strings handled by Lua)

• lfunc.c - auxiliary functions to manipulate prototypes and closures

• ltable.c - Lua tables (hash)

These modules deal with parsing and code generation:

• lcode.c - code generator for Lua. Used by lparser.c

• llex.c - lexical analyzer. Used by lparser.c.

• lparser.c - Lua parser.

• lundump.c - load precompiled Lua chunks. Implements luaU_undump, which loads a precompiled chunk. Also provides luaU_header (internally used by luaU_undump) for parsing a function header.

• ldump.c - save precompiled Lua chunks. Implements luaU_dump, which dumps a function object as a precompiled chunk string.

These modules deal with execution of Lua bytecodes:

• lopcodes.c - opcodes for Lua virtual machine. Defines names and information on all opcodes (via tables 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).

• ldo.c - stack and Call structure of Lua. Handles function calling (luaD_call / luaD_pcall), growing the stack, coroutine handling, ...

• ltm.c - tag methods. Implements accessing metamethods from objects.

These modules implement the standard libraries:

• 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

These modules define the C API:

• lapi.c - Lua API. Implements the bulk of the Lua C API (lua_* functions).

• lauxlib.c - defines the luaL_* functions

• linit.c - implements luaL_openlibs for loading the above modules from C

These modules implement the lua and luac programs:

• lua.c - Lua stand-alone interpreter

• print.c - defines "PrintFunction?" function that prints bytecodes in a function (used by luac.c "-l" option)

• luac.c - Lua compiler (saves bytecodes to files; also list bytecodes)

(5.1.3)

Code Conventions

The prefix of a external symbol indicates the module it comes from:

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

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)

See GarbageCollection and the description in EmergencyGarbageCollector.

sec/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.

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

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

See Also

• LuaList:2008-03/msg00015.html - "People have been asking for more comments in the source code."
• ModifyingLua - describes steps to custom patch Lua for __setindex