How lua/lua works
1. What this repo is
This is the full Lua language runtime and toolchain source tree. It includes the core interpreter, bytecode compiler, standard libraries, C API for embedding, command-line executable, test suite, and manual.
2. Top-level runtime boundary
The main architectural boundary is between host C code and Lua code. Lua is designed as an embeddable runtime: C programs can create a Lua state, load scripts, call functions, and register native functions via the C API.
3. Front-end: source parsing and compilation
The Lua source pipeline starts in the lexical and parsing layers:
- llex.c / llex.h tokenize source
- lparser.c / lparser.h build syntax structures
- lcode.c / lcode.h generate bytecode instructions
- lundump.c / lundump.h load precompiled chunks
- ldump.c writes bytecode chunks
This is the compile-time side of the architecture, turning Lua source into an internal bytecode format.
4. Core execution engine
The runtime core is centered on:
- lvm.c / lvm.h for bytecode execution
- lstate.c / lstate.h for VM state and thread management
- ldo.c / ldo.h for protected calls, stack operations, and execution flow
- lfunc.c / lfunc.h, lobject.c / lobject.h for closures, values, and internal object representation
This layer is the execution boundary where compiled chunks are interpreted.
5. Memory management and garbage collection
Lua uses its own managed heap and incremental GC:
- lmem.c / lmem.h for allocation wrappers
- lgc.c / lgc.h for garbage collection
- lstate.c ties allocation, state, and GC roots together
This is a core runtime subsystem, not delegated to the host application beyond basic allocation hooks.
6. Language semantics and operators
Several modules implement the semantic rules of the language:
- ltm.c / ltm.h for tag methods/metamethod dispatch
- ltable.c / ltable.h for tables
- lstring.c / lstring.h for string interning and hashing
- lctype.c / lctype.h and lutf8lib.c for character/UTF-8 support
- lopcodes.c / lopcodes.h / lopnames.h define the bytecode instruction set
These files form the language object model and operator behavior.
7. C API and embedding layer
The public API is defined in:
- lua.h, lauxlib.h, lualib.h
- implementation support in lapi.c, lauxlib.c
This is the stable boundary for embedding Lua in applications and for native extensions. It exposes stack-based interaction, function calls, userdata, metatables, and library registration.
8. Standard libraries
Built-in libraries are separated into dedicated modules:
- lbaselib.c core functions
- lcorolib.c coroutines
- ldblib.c debug library
- liolib.c I/O
- lmathlib.c math
- loslib.c OS interface
- lstrlib.c string operations
- ltablib.c table utilities
- loadlib.c package loading / dynamic library support
- lutf8lib.c UTF-8 support
These are loaded by the initialization layer and can be selectively included in embedded builds.
9. Initialization and the executable
- linit.c wires standard libraries into a Lua state
- lua.c is the standalone command-line interpreter
The CLI is a thin host over the runtime; the actual language behavior lives in the core modules above.
10. Build configuration and portability
- makefile drives the build
- luaconf.h contains platform/build configuration knobs
- lprefix.h, llimits.h and related headers centralize portability and size limits
- onelua.c is an amalgamated single-file build option
The repo is structured to build cleanly across platforms and also support embedded/monolithic distribution styles.
11. Testing and validation
The testes/ directory is the validation harness for language conformance and regression testing. It includes:
- language behavior tests like constructs.lua, math.lua, strings.lua, coroutine.lua
- stress and GC tests like gc.lua, gengc.lua, memerr.lua
- C extension tests under testes/libs/
This suite exercises both the interpreter core and the public API.
12. Documentation
- README.md gives repository-level guidance
- manual/ contains the language/reference manual and HTML conversion tooling
Documentation is part of the project’s architecture because Lua’s semantics and embedding contract are defined here as much as in code.
13. How data flows through the system
Typical flow is: source text or bytecode chunk enters through the loader, gets parsed/undumped, compiled if needed, then executed by the VM against the Lua state and heap. Standard libraries and C extensions attach to that state through the API, and GC continuously manages all runtime objects.
14. Key architectural takeaway
Lua is a small, self-contained, layered runtime: front-end compilation, bytecode VM, managed object system/GC, and embedded C API, with standard libraries and tooling built around that core.
Main entry points: lapi.c C API · lfunc.c Objects · lstate.c State · lvm.c VM
Components 20
Core runtime
Interpreter, compilation, state, and object model
- Lexer · Tokenizes Lua source text
llex.c - Parser · Builds syntax structures from tokens
lparser.c - Codegen · Emits Lua bytecode instructions
lcode.c - Chunk IO · Loads and writes precompiled chunks
lundump.c - VM · Executes Lua bytecode
lvm.c - State · Manages threads, stacks, and VM state
lstate.c - Call Flow · Protected calls, stack ops, and execution flow
ldo.c - Objects · Closures, functions, and internal values
lfunc.c - Tables · Table implementation and array/hash behavior
ltable.c - Strings · String interning and hashing
lstring.c - Metamethods · Tag method dispatch and operator behavior
ltm.c - GC · Allocation wrappers and incremental garbage collection
lgc.c
Embedding boundary
Public C API and standalone entrypoint
Standard libraries
Built-in Lua libraries and package loading
- Stdlib init · Registers standard libraries in a Lua state
linit.c - Stdlibs · Core, coroutine, debug, I/O, math, OS, string, table, UTF-8, and package libraries
lbaselib.c
Tooling
Build and single-file distribution support
- Build · Build rules, portability settings, and amalgamated build option
makefile
Connections 24
- Lexer → Parser: tokens · Lexer feeds parser
- Parser → Codegen: AST/semantics · Parser drives bytecode generation
- Codegen → Chunk IO: chunks · Generated code can be dumped as chunks
- Chunk IO → VM: loaded code · Precompiled chunks are executed by the VM
- VM → State: runs on · VM executes within a Lua state
- State → Call Flow: control · State and call machinery coordinate protected execution
- Call Flow → Objects: closures/stack · Execution flow manipulates runtime objects and closures
- Objects → Tables: uses · Value model includes tables as core objects
- Objects → Strings: uses · Value model includes interned strings
- Tables → Metamethods: dispatch · Table behavior participates in metamethod dispatch
- Strings → Metamethods: operators · String operations also follow semantic dispatch rules
- State → GC: roots/heap · State ties together managed heap and GC roots
- GC → Objects: collects · Garbage collector manages runtime objects
- C API → State: creates/uses · C API creates states and drives execution
- C API → Objects: exposes · C API exposes values, userdata, and metatables
- Auxlib → C API: builds on · Auxiliary helpers are layered on the core C API
- Stdlib init → Stdlibs: loads · Initialization layer registers built-in libraries
- CLI → C API: embeds · Standalone executable is a host over the public API
- CLI → Stdlib init: initializes · CLI boots standard libraries into the state
- Build → CLI: produces · Build system produces the interpreter and related artifacts
- Tests → C API: exercises · Regression tests cover the C API and extensions
- Tests → VM: validates · Language tests validate interpreter behavior
- Manual → C API: documents · Documentation describes the embedding contract
- Manual → VM: documents · Manual describes language semantics implemented by the runtime