The engine is one Go package (package luapure) in lua/. Go requires a
package to live in a single directory, so — like PUC's flat src/ — the files
are not foldered; instead the l-prefix mirrors PUC's source names. To find the
Go file for a PUC source, the rule of thumb is lfoo.c → lfoo.go (split files
keep the parent name plus a suffix); the table below is the full PUC↔Go
correspondence, and the groups after it give a functional index.
| PUC source | Go file(s) | notes |
|---|---|---|
lapi.c / lapi.h |
lapi.go |
compile/load/call entry points (CompileString, DoString, CallProto) |
lauxlib.c / .h |
lauxlib.go |
luaL_* helpers, arg checking, traceback frame naming |
lbaselib.c |
lbaselib.go |
base library (print, pcall, setmetatable, load, …) |
lcode.c / .h |
lcode.go |
code generator (bytecode emit, constants, jumps) |
lcorolib.c |
lcorolib.go |
coroutine library (goroutine-per-coroutine model) |
lctype.c / .h |
(folded into llex.go) |
ASCII character classes (lisdigit, …) |
ldblib.c |
ldblib.go |
debug library (getinfo, getlocal, sethook, …) |
ldebug.c / .h |
ldebug.go |
symbolic names for errors (getobjname); call-name logic also in lauxlib.go |
ldo.c / .h |
ldo.go, ldo_hook.go |
call/return/pcall stack machinery; debug-hook firing |
ldump.c + lundump.c / .h |
ldump.go |
binary chunk dump and undump (combined) |
lfunc.c / .h |
lfunc.go |
closures and upvalues |
lgc.c / .h |
lgc.go, lgc_weak.go |
__gc finalizers; __mode weak tables (GC itself is delegated to the Go runtime) |
linit.c |
linit.go |
OpenLibs — standard library installation |
liolib.c |
liolib.go |
io library |
llex.c / .h |
llex.go |
lexer |
llimits.h |
(folded into callers) | limits/macros (MAXARG_*, intop, …) |
lmathlib.c |
lmathlib.go |
math library (xoshiro256** PRNG, bit-identical to PUC) |
lmem.c / .h |
(none — Go GC) | PUC's manual allocator has no counterpart |
loadlib.c |
loadlib.go |
load/require/package |
lobject.c / .h |
lobject.go, lobject_gc.go, lobject_num.go, lobject_proto.go |
Value core; GC-object accessors; number⇄string; Proto |
lopcodes.c / .h |
lopcodes.go |
opcode formats and decode/encode |
loslib.c |
loslib.go |
os library |
lparser.c / .h |
lparser.go, lparser_codegen.go |
parser; compiler/scope/register glue |
lstate.c / .h |
lstate.go |
LState (thread + global state fused), callInfo |
lstring.c / .h |
(folded into lobject.go/lcode.go) |
per-chunk literal interning instead of a global string table |
lstrlib.c |
lstrlib.go, lstrlib_pattern.go, lstrlib_pack.go |
string library; pattern matching; string.pack/unpack |
ltable.c / .h |
ltable.go |
tables (split array part + Go map) |
ltablib.c |
ltablib.go |
table library |
ltm.c / .h |
ltm.go |
tag methods / metamethods |
lutf8lib.c |
lutf8lib.go |
utf8 library |
lvm.c / .h |
lvm.go, lvm_execute.go, lvm_arith.go |
VM helpers (concat, index, compare); dispatch loop; raw arithmetic |
lzio.c / .h |
lzio.go |
buffered input stream (ZIO) — unifies string/file/reader load paths |
luac.c (print) |
disasm.go |
bytecode disassembler (PUC ships this in the luac tool, not the library) |
lua.c |
(repo cmd/) |
standalone interpreter — not part of this package |
| file | role |
|---|---|
lobject.go |
the tagged Value core, type tags, comparisons |
lobject_gc.go |
GC-object constructors/accessors (table/closure/userdata/thread), type names |
lobject_num.go |
number ⇄ string conversions, integer/float coercions |
lobject_proto.go |
Proto (compiled function): code, constants, line info |
ltable.go |
tables (array part + Go map), __mode weak handling |
lfunc.go |
closures and upvalues |
ltm.go |
tag methods / metamethods (luaT_*) |
| file | role |
|---|---|
llex.go |
lexer (+ folded lctype character classes) |
lparser.go |
single-pass recursive-descent parser |
lparser_codegen.go |
parser↔codegen glue (scopes, registers) |
lcode.go |
bytecode emit, constants, jump patching |
lopcodes.go |
opcode formats, encode/decode |
ldump.go |
precompiled-chunk dump and undump (PUC ldump.c+lundump.c) |
lzio.go |
buffered input stream (ZIO) unifying string/file/reader loads |
| file | role |
|---|---|
lvm.go |
VM helpers (concat, index, compare) |
lvm_execute.go |
the instruction dispatch loop |
lvm_arith.go |
raw arithmetic/bitwise ops |
ldo.go |
call/return/pcall stack machinery |
ldo_hook.go |
debug-hook firing (line/call/return/count) |
lstate.go |
LState (thread + global state), callInfo |
ldebug.go |
symbolic names for errors (getobjname) |
lgc.go |
__gc finalizers (delegated to the Go runtime) |
lgc_weak.go, lgc_weakkey.go |
weak tables (weak.Pointer), ephemeron keys |
| file | role |
|---|---|
lbaselib.go |
base (print, pcall, load, setmetatable, …) |
lauxlib.go |
luaL_* helpers, arg checking, traceback naming |
lstrlib.go, lstrlib_pattern.go, lstrlib_pack.go |
string library; patterns; pack/unpack |
lmathlib.go |
math (xoshiro256** PRNG) |
ltablib.go |
table library |
loslib.go |
os library |
liolib.go |
io library |
lcorolib.go |
coroutine library (goroutine-per-coroutine) |
lutf8lib.go |
utf8 library |
loadlib.go |
require / package |
ldblib.go |
debug library (getinfo, sethook, getlocal, …) |
linit.go |
OpenLibs — standard library installation |
| file | role |
|---|---|
lapi.go |
compile/load/call entry points (CompileString, DoString, CallProto) |
lapi_check.go |
luaL_check*/opt* argument helpers for Go callbacks |
lapi_table.go |
table create/read/write from Go |
lapi_load.go |
CompileReader, file loading |
lapi_sandbox.go |
NewSandbox, RunWith, SetContext |
lapi_userdata.go |
full userdata + metatables + uservalues (bind a Go type) |
lapi_debug.go |
Go-native debug hook (SetGoHook) + Frame inspection + Frame.Eval |
convert.go |
ToValue / FromValue Go⇄Lua conversion |
| file | role |
|---|---|
debug_session.go |
Debugger: breakpoints, step into/over/out, pause, OnStop |
debug_session_driver.go |
Session: synchronous facade + SourceResolver (source-on-server) for MCP/DAP front ends |
| file | role |
|---|---|
disasm.go |
bytecode disassembler (PUC ships this in luac) |
luaconf.go |
limits/macros (luaconf.h) |
doc.go |
package documentation |
Test files sit beside their subject (*_test.go); Go requires a package's
tests to live in its own directory. Unit tests that exercise engine internals
use package luapure and stay here in lua/; black-box tests and runnable
examples use package luapure_test. The conformance suite is public-API-only,
so it lives in its own conformance/ package (not in lua/), alongside the
cmd/conformance driver. The official fixtures are at repo root in
_lua5.4-tests/, and the extra self-asserting probes in _glue5.4-tests/
(reached from a sub-package via ../_lua5.4-tests/ and ../_glue5.4-tests/).