Lua Source

wiki

Comments on Source

Overview

The Lua papers[2] 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.

Specific Files

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.

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

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."