The section of the wiki allows anyone to document, explain, post questions, or make comments on the Lua source code. You may link to  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.
Comments on Source
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.
- 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)
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)
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)
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_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.
In src/luaconf.h (5.1.1), there is a
LUA_CDIR"loadall.dll", which is discussed in  .
src/lgc.h and lgc.c (garbage collector)
See GarbageCollection and the description in EmergencyGarbageCollector.
sec/ltable.h and ltable.c (tables)
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
RecentChanges · preferences
edit · history
Last edited January 2, 2011 3:00 am GMT (diff)