Lua Source

lua-users home
wiki

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.

Comments on Source

Overview

Module Structure

The modules in the Lua source are outlined below.

These modules implement utility functionality:

These modules implement basic data types:

These modules deal with parsing and code generation:

These modules deal with execution of Lua bytecodes:

These modules implement the standard libraries:

These modules define the C API:

These modules implement the lua and luac programs:

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

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.

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


RecentChanges · preferences
edit · history
Last edited January 2, 2011 3:00 am GMT (diff)