# lua/lua architecture

> Architecture diagram of the GitHub repository lua/lua, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lua/lua
- Repository: https://github.com/lua/lua

## Overview

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`](https://github.com/lua/lua/blob/master/lapi.c) (C API), [`lfunc.c`](https://github.com/lua/lua/blob/master/lfunc.c) (Objects), [`lstate.c`](https://github.com/lua/lua/blob/master/lstate.c) (State), [`lvm.c`](https://github.com/lua/lua/blob/master/lvm.c) (VM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_lex["Lexer<br/>front-end<br/>[llex.c]"]
  node_parse["Parser<br/>front-end<br/>[lparser.c]"]
  node_codegen["Codegen<br/>compiler<br/>[lcode.c]"]
  node_bytecode["Chunk IO<br/>loader/dumper<br/>[lundump.c]"]
  node_vm["VM<br/>bytecode engine<br/>[lvm.c]"]
  node_state[("State<br/>[lstate.c]")]
  node_callflow["Call Flow<br/>execution control<br/>[ldo.c]"]
  node_objects["Objects<br/>value model<br/>[lfunc.c]"]
  node_tables["Tables<br/>data model<br/>[ltable.c]"]
  node_strings["Strings<br/>interning<br/>[lstring.c]"]
  node_metamethods["Metamethods<br/>semantics<br/>[ltm.c]"]
  node_gc[("GC<br/>memory manager<br/>[lgc.c]")]
end

subgraph group_api["Embedding boundary"]
  node_api["C API<br/>embedding api<br/>[lapi.c]"]
  node_aux["Auxlib<br/>helper api<br/>[lauxlib.c]"]
  node_cli["CLI<br/>host executable<br/>[lua.c]"]
end

subgraph group_libs["Standard libraries"]
  node_stdlib["Stdlib init<br/>library bootstrap<br/>[linit.c]"]
  node_libraries["Stdlibs<br/>built-in libraries<br/>[lbaselib.c]"]
end

subgraph group_tooling["Tooling"]
  node_build["Build"]
end

subgraph group_docs["Docs and validation"]
  node_tests["Tests<br/>validation suite<br/>[all.lua]"]
  node_manual["Manual<br/>documentation<br/>[README.md]"]
end

node_lex -->|"tokens"| node_parse
node_parse -->|"AST/semantics"| node_codegen
node_codegen -->|"chunks"| node_bytecode
node_bytecode -->|"loaded code"| node_vm
node_vm -->|"runs on"| node_state
node_state -->|"control"| node_callflow
node_callflow -->|"closures/stack"| node_objects
node_objects -->|"uses"| node_tables
node_objects -->|"uses"| node_strings
node_tables -->|"dispatch"| node_metamethods
node_strings -->|"operators"| node_metamethods
node_state -->|"roots/heap"| node_gc
node_gc -->|"collects"| node_objects
node_api -->|"creates/uses"| node_state
node_api -->|"exposes"| node_objects
node_aux -->|"builds on"| node_api
node_stdlib -->|"loads"| node_libraries
node_cli -->|"embeds"| node_api
node_cli -->|"initializes"| node_stdlib
node_build -->|"produces"| node_cli
node_tests -->|"exercises"| node_api
node_tests -->|"validates"| node_vm
node_manual -->|"documents"| node_api
node_manual -->|"documents"| node_vm

click node_lex "https://github.com/lua/lua/blob/master/llex.c"
click node_parse "https://github.com/lua/lua/blob/master/lparser.c"
click node_codegen "https://github.com/lua/lua/blob/master/lcode.c"
click node_bytecode "https://github.com/lua/lua/blob/master/lundump.c"
click node_vm "https://github.com/lua/lua/blob/master/lvm.c"
click node_state "https://github.com/lua/lua/blob/master/lstate.c"
click node_callflow "https://github.com/lua/lua/blob/master/ldo.c"
click node_objects "https://github.com/lua/lua/blob/master/lfunc.c"
click node_tables "https://github.com/lua/lua/blob/master/ltable.c"
click node_strings "https://github.com/lua/lua/blob/master/lstring.c"
click node_metamethods "https://github.com/lua/lua/blob/master/ltm.c"
click node_gc "https://github.com/lua/lua/blob/master/lgc.c"
click node_api "https://github.com/lua/lua/blob/master/lapi.c"
click node_aux "https://github.com/lua/lua/blob/master/lauxlib.c"
click node_cli "https://github.com/lua/lua/blob/master/lua.c"
click node_stdlib "https://github.com/lua/lua/blob/master/linit.c"
click node_libraries "https://github.com/lua/lua/blob/master/lbaselib.c"
click node_build "https://github.com/lua/lua/tree/master/makefile"
click node_tests "https://github.com/lua/lua/blob/master/testes/all.lua"
click node_manual "https://github.com/lua/lua/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lex,node_parse,node_codegen,node_bytecode,node_vm,node_state,node_callflow,node_objects,node_tables,node_strings,node_metamethods,node_gc toneBlue
class node_api,node_aux,node_cli toneAmber
class node_stdlib,node_libraries toneMint
class node_build toneRose
class node_tests,node_manual toneIndigo
```

## Components

### Core runtime

Interpreter, compilation, state, and object model

- [Lexer](https://github.com/lua/lua/blob/master/llex.c): front-end · Tokenizes Lua source text · `llex.c`
- [Parser](https://github.com/lua/lua/blob/master/lparser.c): front-end · Builds syntax structures from tokens · `lparser.c`
- [Codegen](https://github.com/lua/lua/blob/master/lcode.c): compiler · Emits Lua bytecode instructions · `lcode.c`
- [Chunk IO](https://github.com/lua/lua/blob/master/lundump.c): loader/dumper · Loads and writes precompiled chunks · `lundump.c`
- [VM](https://github.com/lua/lua/blob/master/lvm.c): bytecode engine · Executes Lua bytecode · `lvm.c`
- [State](https://github.com/lua/lua/blob/master/lstate.c): runtime state · Manages threads, stacks, and VM state · `lstate.c`
- [Call Flow](https://github.com/lua/lua/blob/master/ldo.c): execution control · Protected calls, stack ops, and execution flow · `ldo.c`
- [Objects](https://github.com/lua/lua/blob/master/lfunc.c): value model · Closures, functions, and internal values · `lfunc.c`
- [Tables](https://github.com/lua/lua/blob/master/ltable.c): data model · Table implementation and array/hash behavior · `ltable.c`
- [Strings](https://github.com/lua/lua/blob/master/lstring.c): interning · String interning and hashing · `lstring.c`
- [Metamethods](https://github.com/lua/lua/blob/master/ltm.c): semantics · Tag method dispatch and operator behavior · `ltm.c`
- [GC](https://github.com/lua/lua/blob/master/lgc.c): memory manager · Allocation wrappers and incremental garbage collection · `lgc.c`

### Embedding boundary

Public C API and standalone entrypoint

- [C API](https://github.com/lua/lua/blob/master/lapi.c): embedding api · Public stack-based interface for embedding and extensions · `lapi.c`
- [Auxlib](https://github.com/lua/lua/blob/master/lauxlib.c): helper api · Convenience helpers and library support for the C API · `lauxlib.c`
- [CLI](https://github.com/lua/lua/blob/master/lua.c): host executable · Standalone command-line interpreter · `lua.c`

### Standard libraries

Built-in Lua libraries and package loading

- [Stdlib init](https://github.com/lua/lua/blob/master/linit.c): library bootstrap · Registers standard libraries in a Lua state · `linit.c`
- [Stdlibs](https://github.com/lua/lua/blob/master/lbaselib.c): built-in libraries · Core, coroutine, debug, I/O, math, OS, string, table, UTF-8, and package libraries · `lbaselib.c`

### Tooling

Build and single-file distribution support

- [Build](https://github.com/lua/lua/tree/master/makefile): build config · Build rules, portability settings, and amalgamated build option · `makefile`

### Docs and validation

Manual and regression tests

- [Tests](https://github.com/lua/lua/blob/master/testes/all.lua): validation suite · Language conformance and regression tests · `testes/all.lua`
- [Manual](https://github.com/lua/lua/blob/master/README.md): documentation · Reference manual and HTML conversion tooling · `README.md`

## Connections

- 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
