Expand description
Debug library — the debug Lua standard library module.
Exposes debug introspection APIs: stack inspection (getinfo, getlocal,
setlocal), upvalue access (getupvalue, setupvalue, upvalueid,
upvaluejoin), hook management (sethook, gethook), metatable overrides
(getmetatable, setmetatable), userdata values (getuservalue,
setuservalue), the registry (getregistry), and utilities (traceback,
debug, setcstacklimit).
§Graduation (Idiomatization Sprint 2, Phase 2 — P2-debug, 2026-06-14)
Most of this module is VM-introspection plumbing: getinfo/getlocal/
setlocal/getupvalue/setupvalue/upvalueid/upvaluejoin/sethook/
gethook/traceback/getregistry reach into lua-vm’s call stack,
activation records, upvalue cells, and registry. That cross-crate plumbing
is load-bearing — it is idiomatized AROUND (the cold arg-checking, the
getinfo result-table assembly, traceback formatting), never refactored in
how it reaches into the VM. The cross-thread lua_xmove TODOs and the
UpvalId pointer-identity TODO are genuine deferred behavior, kept verbatim.
Behavioral net (the only oracle — there is no structural one): the official
db.lua suite (5.4), multiversion_oracle, the version batteries
(specs/oracle/check.sh 5.1..5.5), and this crate’s reference-pinned
tests/debug_strengthen.rs. Strengthening that net FIRST caught two real
5.1 divergences (the 5.2+ getinfo 'u' nparams/isvararg fields and the
5.2+ function-argument getlocal form leaked onto 5.1); both fixed here in
the cold arg-handling surface. See crates/lua-stdlib/GRADUATED.md “debug”.
Functions§
- open_
debug - Open the
debuglibrary and push the module table onto the stack. Returns 1 (the table).