From e6ed756d40e5f308d7c5880967caf47d0c04fc52 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Tue, 5 May 2026 13:08:32 -0700 Subject: [PATCH 1/4] chore(A4): start plan --- .agents/plans/A4-preload-stdlib-modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/plans/A4-preload-stdlib-modules.md b/.agents/plans/A4-preload-stdlib-modules.md index edabf12b..7941949c 100644 --- a/.agents/plans/A4-preload-stdlib-modules.md +++ b/.agents/plans/A4-preload-stdlib-modules.md @@ -5,7 +5,7 @@ issue: 165 pr: null branch: fix/preload-stdlib-modules base: main -status: ready +status: in-progress direction: A unlocks: - attrib.lua From 5a865e267599346912e5ac90b0ccf4867b8224bc Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Tue, 5 May 2026 13:13:15 -0700 Subject: [PATCH 2/4] feat(stdlib): pre-populate package.loaded with installed stdlib modules Lua 5.3's runtime pre-populates package.loaded with all built-in libraries so that require("string"), require("math"), etc. return the existing global tables without triggering a filesystem search. Changes: - Added package.preload empty table to the package table (was missing) - Cache package itself in package.loaded as "package" - Added preload_stdlib_modules/1 as a forward-compatibility pass: iterates candidate module names and caches any that are already globals as a tref. The four installed libs (string, math, table, debug) are already cached by install_library/2; this function covers future stubs (os, io, coroutine). - New unit tests in test/lua/vm/stdlib/package_test.exs covering all four stdlib requires, the cache-hit (double require) path, package.loaded, package.preload, and package in package.loaded. Closes #165 Plan: A4 --- .agents/plans/A4-preload-stdlib-modules.md | 14 ++++- lib/lua/vm/stdlib.ex | 31 ++++++++++- test/lua/vm/stdlib/package_test.exs | 60 ++++++++++++++++++++++ 3 files changed, 102 insertions(+), 3 deletions(-) create mode 100644 test/lua/vm/stdlib/package_test.exs diff --git a/.agents/plans/A4-preload-stdlib-modules.md b/.agents/plans/A4-preload-stdlib-modules.md index 7941949c..c8e60c25 100644 --- a/.agents/plans/A4-preload-stdlib-modules.md +++ b/.agents/plans/A4-preload-stdlib-modules.md @@ -97,4 +97,16 @@ mix test --only lua53 ## Discoveries -(populated during implementation) +- `install_library/2` already calls `cache_module_result/3` for each of the four + installed libs (`string`, `math`, `table`, `debug`), so `require "string"` etc. + already worked before this plan. The `preload_stdlib_modules/1` function added + here is a forward-compatibility safety net — it deduplicates harmlessly and will + auto-populate any future stdlib globals (os, io, coroutine) once they're added. +- `package.preload` was missing from the package table. Added it as an empty table. +- `package` itself was not in `package.loaded`. Added as part of `install_package_table/1`. +- `io`, `os`, `coroutine` are `nil` in globals so `require "io"` still fails at + attrib.lua line 9. Those modules are out of scope per the plan — a future plan + should stub those globals so they survive the full attrib.lua require block. +- `attrib.lua` now prints "testing require" and passes the first three asserts + (`string`, `math`, `table`) before failing on `require "io"`, confirming it + progresses past line 1 of the require block. diff --git a/lib/lua/vm/stdlib.ex b/lib/lua/vm/stdlib.ex index 17b4fe30..cd076c7c 100644 --- a/lib/lua/vm/stdlib.ex +++ b/lib/lua/vm/stdlib.ex @@ -48,6 +48,7 @@ defmodule Lua.VM.Stdlib do |> install_library(Lua.VM.Stdlib.Math) |> install_library(Lua.VM.Stdlib.Table) |> install_library(Lua.VM.Stdlib.Debug) + |> preload_stdlib_modules() |> install_unpack_alias() |> install_global_g() end @@ -113,6 +114,25 @@ defmodule Lua.VM.Stdlib do state end + # Pre-load any stdlib table globals into package.loaded so that + # require("string"), require("math"), etc. resolve to the existing global + # tables without triggering a filesystem search. This mirrors Lua 5.3's + # behaviour where package.loaded is pre-populated by the runtime. + # + # install_library/2 already caches the four installed modules (string, math, + # table, debug), so this pass is a safety net for any future stdlib tables + # (e.g. os, io, coroutine) that may be added as globals before this call. + defp preload_stdlib_modules(state) do + modules = ["string", "math", "table", "os", "debug", "coroutine", "io"] + + Enum.reduce(modules, state, fn name, acc -> + case Map.get(acc.globals, name) do + {:tref, _} = tref -> cache_module_result(acc, name, tref) + _ -> acc + end + end) + end + # type(v) — returns the type of v as a string defp lua_type([value | _], state), do: {[Value.type_name(value)], state} defp lua_type([], state), do: {["nil"], state} @@ -506,15 +526,22 @@ defmodule Lua.VM.Stdlib do # Create package.loaded table (initially empty) {loaded_tref, state} = State.alloc_table(state) - # Create package table with loaded and path fields + # Create package.preload table (initially empty) + {preload_tref, state} = State.alloc_table(state) + + # Create package table with loaded, preload, and path fields package_data = %{ "loaded" => loaded_tref, + "preload" => preload_tref, "path" => "?.lua;?/init.lua" } {package_tref, state} = State.alloc_table(state, package_data) - State.set_global(state, "package", package_tref) + state = State.set_global(state, "package", package_tref) + + # Cache "package" itself in package.loaded + cache_module_result(state, "package", package_tref) end # require(modname) — loads a Lua module diff --git a/test/lua/vm/stdlib/package_test.exs b/test/lua/vm/stdlib/package_test.exs new file mode 100644 index 00000000..c76833ff --- /dev/null +++ b/test/lua/vm/stdlib/package_test.exs @@ -0,0 +1,60 @@ +defmodule Lua.VM.Stdlib.PackageTest do + use ExUnit.Case, async: true + + alias Lua.Compiler + alias Lua.Parser + alias Lua.VM + alias Lua.VM.State + alias Lua.VM.Stdlib + + defp eval(code) do + state = Stdlib.install(State.new()) + {:ok, ast} = Parser.parse(code) + {:ok, proto} = Compiler.compile(ast, source: "package_test.lua") + VM.execute(proto, state) + end + + describe "package.loaded pre-population" do + test "require 'string' returns the same table as the string global" do + assert {:ok, [true], _} = eval(~S[return require("string") == string]) + end + + test "require 'math' returns the same table as the math global" do + assert {:ok, [true], _} = eval(~S[return require("math") == math]) + end + + test "require 'table' returns the same table as the table global" do + assert {:ok, [true], _} = eval(~S[return require("table") == table]) + end + + test "require 'debug' returns the same table as the debug global" do + assert {:ok, [true], _} = eval(~S[return require("debug") == debug]) + end + + test "require 'string' twice returns the cached result without re-evaluating" do + code = """ + local s1 = require("string") + local s2 = require("string") + return s1 == s2 + """ + + assert {:ok, [true], _} = eval(code) + end + + test "package.loaded is a table" do + assert {:ok, ["table"], _} = eval(~S[return type(package.loaded)]) + end + + test "package.preload is a table" do + assert {:ok, ["table"], _} = eval(~S[return type(package.preload)]) + end + + test "package itself is in package.loaded" do + assert {:ok, [true], _} = eval(~s{return package.loaded["package"] == package}) + end + + test "package.loaded['string'] equals the string global" do + assert {:ok, [true], _} = eval(~s{return package.loaded["string"] == string}) + end + end +end From fabe8a4308fc34dc968de288f7d5c5cfcd663cac Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Tue, 5 May 2026 13:14:27 -0700 Subject: [PATCH 3/4] chore(A4): mark plan as review --- .agents/plans/A4-preload-stdlib-modules.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/.agents/plans/A4-preload-stdlib-modules.md b/.agents/plans/A4-preload-stdlib-modules.md index c8e60c25..d45ec836 100644 --- a/.agents/plans/A4-preload-stdlib-modules.md +++ b/.agents/plans/A4-preload-stdlib-modules.md @@ -2,10 +2,10 @@ id: A4 title: Pre-load Lua stdlib tables into package.loaded issue: 165 -pr: null +pr: 184 branch: fix/preload-stdlib-modules base: main -status: in-progress +status: review direction: A unlocks: - attrib.lua @@ -110,3 +110,16 @@ mix test --only lua53 - `attrib.lua` now prints "testing require" and passes the first three asserts (`string`, `math`, `table`) before failing on `require "io"`, confirming it progresses past line 1 of the require block. + +## What changed + +Files touched: +- `lib/lua/vm/stdlib.ex` — added `package.preload` table, cached `package` in + `package.loaded`, added `preload_stdlib_modules/1` helper +- `test/lua/vm/stdlib/package_test.exs` — new file, 9 tests covering all criteria + +Suite delta: no change to lua53 ready/skip split (attrib.lua still skipped — `io`/`os`/`coroutine` globals not yet stubbed). + +Tests: 1309 → 1318 passing, 0 failing. + +PR: https://github.com/tv-labs/lua/pull/184 From 363596f0be74ddfa90312ef9cfdba35683056f6e Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Tue, 5 May 2026 13:18:43 -0700 Subject: [PATCH 4/4] fix(stdlib): limit preload list to actually-installed modules Remove os, io, and coroutine from the preload_stdlib_modules/1 list. They are nil in globals so the function skipped them anyway, but listing them implied planned support for unimplemented modules. The four installed libs (string, math, table, debug) are the only correct entries. Future stdlib modules should be added here when they are actually installed. --- lib/lua/vm/stdlib.ex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/lua/vm/stdlib.ex b/lib/lua/vm/stdlib.ex index cd076c7c..c260a6cc 100644 --- a/lib/lua/vm/stdlib.ex +++ b/lib/lua/vm/stdlib.ex @@ -121,9 +121,9 @@ defmodule Lua.VM.Stdlib do # # install_library/2 already caches the four installed modules (string, math, # table, debug), so this pass is a safety net for any future stdlib tables - # (e.g. os, io, coroutine) that may be added as globals before this call. + # that may be added as globals before this call. defp preload_stdlib_modules(state) do - modules = ["string", "math", "table", "os", "debug", "coroutine", "io"] + modules = ["string", "math", "table", "debug"] Enum.reduce(modules, state, fn name, acc -> case Map.get(acc.globals, name) do