Read Lua Source Code

Reading Lua code is fairly easy. The language is simple, well documented, has a official book, a package manager and plenty of resources online.

The thing is, there is not a lot of resources explaining how to read the lua source code, which is a work of art on its own and a great way to study low level software design. This project attempts to put together suggestions and material that might help you read the lua source code in a timely fashion.

The material available here is mostly the work and suggestions of other people compiled in a single place. Few free to point out if something is mentioned without a source or send merge requests with more material.

What Do You Need To Know

The Lua source code is written in ANSI C, a low level, statically typed programming language very common as a base for software that should live very close to the hardware.

So, the first thing you should learn is the C language. Below there are some resources you could try these:

Online material

• learn-c
• coursera c-programming
• guru99 c-programming-tutorial
• programiz c-programming
• tutorialspoint c programming
• ucam teaching C
• ravi lua5.3 bytecode reference
• ravi lua parsing and code generation

Books

• "C Programming Absolute Beginner's Guide" by Greg Perry and Dean Mille
• "The C Programming Language" by Brain W.
• "The C Programming Language" by Kernighan
• "C Programming: A Modern Approach" by Taschenbuch

List compiled from guru99.

Articles

• A No-Frills Introduction to Lua 5.1 VM Instructions
• The Implementation of Lua 5.0

Where To Start

Know where to start is very important, because you need to build the knowledge in your mind to put all the pieces together. Mimemike published a suggestion in this reddit post that I'll copy below:

• lmathlib.c, lstrlib.c: get familiar with the external C API. Don't bother with the pattern matcher though. Just the easy functions.
• lapi.c: Check how the API is implemented internally. Only skim this to get a feeling for the code. Cross-reference to lua.h and luaconf.h as needed.
• lobject.h: tagged values and object representation. skim through this first. you'll want to keep a window with this file open all the time.
• lstate.h: state objects. ditto.
• lopcodes.h: bytecode instruction format and opcode definitions. easy.
• lvm.c: scroll down to luaV_execute, the main interpreter loop. see how all of the instructions are implemented. skip the details for now. reread later.
• ldo.c: calls, stacks, exceptions, coroutines. tough read.
• lstring.c: string interning. cute, huh?
• ltable.c: hash tables and arrays. tricky code.
• ltm.c: metamethod handling, reread all of lvm.c now.
• You may want to reread lapi.c now.
• ldebug.c: surprise waiting for you. abstract interpretation is used to find object names for tracebacks. does bytecode verification, too.
• lparser.c, lcode.c: recursive descent parser, targetting a register-based VM. start from chunk() and work your way through. read the expression parser and the code generator parts last.
• lgc.c: incremental garbage collector. take your time.
• Read all the other files as you see references to them. Don't let your stack get too deep though.

Happy reading! Please, share your results and suggestions!