{"id":51834245,"url":"https://github.com/lus-lang/microlua","last_synced_at":"2026-07-22T19:02:16.850Z","repository":{"id":368526162,"uuid":"1125695713","full_name":"lus-lang/microlua","owner":"lus-lang","description":"A tiny, reasonably complete Lua runtime.","archived":false,"fork":false,"pushed_at":"2026-07-01T00:25:30.000Z","size":263,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T02:14:55.284Z","etag":null,"topics":["embedded","lua"],"latest_commit_sha":null,"homepage":"https://micro.lus.dev","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lus-lang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-31T07:17:45.000Z","updated_at":"2026-07-01T00:36:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lus-lang/microlua","commit_stats":null,"previous_names":["lus-lang/microlua"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lus-lang/microlua","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lus-lang%2Fmicrolua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lus-lang%2Fmicrolua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lus-lang%2Fmicrolua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lus-lang%2Fmicrolua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lus-lang","download_url":"https://codeload.github.com/lus-lang/microlua/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lus-lang%2Fmicrolua/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35773465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded","lua"],"created_at":"2026-07-22T19:02:16.140Z","updated_at":"2026-07-22T19:02:16.836Z","avatar_url":"https://github.com/lus-lang.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MicroLua\n\nMicroLua (`mlua`) is a tiny, reasonably complete Lua runtime. It is good for embedded systems and other places where portability and footprint are absolutely critical.\n\n```\n * Usage: mlua [options] [file [args]]\n *   -h, --help            List options\n *   -e, --eval EXPR       Evaluate EXPR\n *   -i, --interactive     Go to interactive mode\n *   -I, --include FILE    Include (require) FILE\n *   -d, --dump            Dump memory usage stats\n *       --memory-limit N  Limit memory to N bytes\n *       --no-column       No column in debug info\n *   -o FILE               Save bytecode to FILE\n *   -v, --version         Print version\n```\n\n## At a glance\n\n- Provides most of Lua within a tiny footprint.\n- The core static library has no dependence on the C standard library.\n- The core can run from a caller-provided pre-allocated heap without dynamic memory allocation[^1].\n- The interpreter is a compact stack machine whose instructions are always one or two bytes.\n- The parser is a single-pass Pratt compiler that emits bytecode directly and can be compiled out for bytecode-only embedded targets.\n- Port configuration covers value representation, fixed-width C types, native float width, optional dump/pack engines, computed-goto dispatch, and opcode profiling.\n- The garbage collector compacts the heap at safepoints to reclaim memory and remove fragmentation.\n- Table arrays reject holes at runtime to keep dense sequences compact.\n- Strings and scripts are UTF-8, with codepoint-aware core string operations and deliberately byte/ASCII-oriented pattern matching and case conversion.\n- The `math`, `table`, `string`, and `coroutine` libraries include the expected core APIs plus conveniences such as `table.pack`, `table.unpack`, integer math helpers, binary string packing, and coroutine close/yieldability support.\n\n## Memory benchmarks\n\nIn a local macOS size build with similar build flags, MicroLua's compiler/parser-less runtime artifacts total 218 KiB (259 KiB with the parser), around 2.8x smaller than Lua 5.5.0's runtime artifacts at 612 KiB. Re-run `python3 bench/bench.py` to regenerate local comparison results.\n\n`python3 bench/benchmarksgame/bench.py` compares MicroLua with Lua 5.5 on\nsmall standalone ports of relevant Lua examples, scaled down for local runs and\nadjusted to avoid unsupported MicroLua features such as metatables and generated\n`load`. Each row passed a byte-identical stdout correctness gate. Lua memory is\nexact peak Lua heap from a tracking `lua_newstate` allocator. MicroLua memory is\nexact constrained-heap high-water from a high-limit `--dump` run.\n\n| workload     | source example       | memory-pressure focus    | Lua exact peak | MicroLua exact peak | mlua/lua memory |\n| ------------ | -------------------- | ------------------------ | -------------: | ------------------: | --------------: |\n| binarytrees  | `binarytrees-lua-4`  | allocation churn         |       1.19 MiB |           546.1 KiB |           0.45x |\n| knucleotide  | `knucleotide-lua-2`  | substring table pressure |       76.9 KiB |            71.8 KiB |           0.93x |\n| revcomp      | `revcomp-lua-5`      | string builder pressure  |      115.4 KiB |           104.5 KiB |           0.91x |\n| spectralnorm | `spectralnorm-lua-1` | numeric arrays           |       25.9 KiB |            25.6 KiB |           0.99x |\n\n### Limitations\n\nSome compromises had to be made to keep the footprint small. Some features had to be removed while others had to be implemented differently:\n\n- All C functions are \"light\" C functions, meaning they do not get to have upvalues.\n- Function environments are not a thing in MicroLua, so `setfenv` and `getfenv` are not available.\n- `collectgarbage` is not available due to the tight integration of the garbage collector with the interpreter.\n- Metatables are not supported. Because of this, `rawequal`, `rawget` and `rawset` are not available. However, you can still forward table lookups with `table.forward` to replicate the functionality of `__index`.\n- `io` and `os` libraries are only available as optional extensions that require linking against the C standard library (`src/extensions/MLuaStdLib.c`). By default, they are not available and it isn't recommended to use them[^2].\n- `require` is only available if the embedding application provides the necessary callbacks through `MLuaSetRequirer`[^2].\n- Default Lua package behavior through `LUA_PATH` and `LUA_CPATH` is not available as `require` behavior is entirely contingent on the embedding application. This also means the `package` global table isn't available.\n- Functions emitting to `stdout` or `stderr` (e.g., `print`, `error`) will only have visible output if the embedding application provides the necessary callbacks through `MLuaSetOutput`[^2].\n\n## Building \u0026 testing\n\n```sh\nmeson setup builddir \u0026\u0026 ninja -C builddir     # debug build (libc allowed)\nmeson test -C builddir                        # internal C tests + interpreter suites\nmeson test -C builddir --suite smoke          # standalone smoke scripts\n./builddir/mlua script.lua                    # run a script / start the REPL\n```\n\nA freestanding release build (`meson setup builddir-release --buildtype=release`) compiles the core with `-ffreestanding -fno-builtin`.\n\nFor embedded deployments that do not need source parsing on the target, build a\nbytecode-only runtime:\n\n```sh\nmeson setup build-bytecode -Dcompiler=false --buildtype=release\nninja -C build-bytecode\n./builddir/mlua -o app.mlu app.lua            # host-side precompile step\n./build-bytecode/mlua app.mlu                 # target/runtime accepts bytecode\n```\n\nWhen `-Dcompiler=false`, `libmicrolua.a` omits the lexer and parser and exposes\n`MLuaLoadBytecode`/`MLuaDoBytecode` for embedded callers.\nMicroLua bytecode has a compatibility header, records endianness, serializes\nexecution-critical fields with fixed widths, and stores numeric constants as\ncanonical IEEE-754 binary64 values. A target may use a narrower native\n`MLUA_FLOAT`, with numeric values narrowed or widened at the bytecode boundary\nwhen the configured format supports it.\n\nPort-specific settings are centralized in `src/MLuaConfig.h`. A board port can\noverride pointer size, heap alignment, default stack/frame sizes, GC threshold,\nfixed-width type source, native float subtype/width, math hooks, and compiler\nsupport by providing one header. Size-sensitive ports can also disable\n`string.dump` (`MLUA_ENABLE_DUMP=0`) or `string.pack`/`packsize`/`unpack`\n(`MLUA_ENABLE_PACK=0`), enable GNU-C computed-goto dispatch\n(`MLUA_VM_COMPUTED_GOTO=1`), or turn on opcode profiling\n(`MLUA_PROFILE_OPS=1`) for diagnostics:\n\n```sh\nmeson setup build-board -Dport_header=path/to/my_board_mlua.h\n```\n\nBuilt-in presets are available with `-Dport=generic64`, `generic32`,\n`cortex-m`, `riscv32`, or `ti84ce`. See `src/ports/README.md` for the full\nport-knob reference and verification matrix.\n\n## Special ports\n\nSpecial ports are complete platform integrations that go beyond a Meson port\npreset. They may include board-specific build systems, host bindings, packaging\ntools, install notes, benchmarks, or emulator test flows.\n\n### TI-84 Plus CE\n\nA complete board port lives in `platform/ti84ce/`: MicroLua on the TI-84\nPlus CE (eZ80 — 24-bit `int` and pointers, binary32 `double`), built with\nthe CE C toolchain as two calculator programs with graphics/keypad/timer\nbindings.\n\n| Program | Directory | Contents |\n|---|---|---|\n| `MLUA.8xp` (~57 KB) | `platform/ti84ce/repl/` | Full build: runs source or bytecode appvars and includes an on-calc REPL |\n| `MLUAR.8xp` (~44 KB) | `platform/ti84ce/runner/` | Bytecode-only runner without lexer/parser/compiler |\n\nThe CE preset disables `string.dump` and `string.pack` (`MLUA_ENABLE_DUMP=0`,\n`MLUA_ENABLE_PACK=0`) and enables computed-goto dispatch because the full REPL\nis close to the calculator's practical code-size ceiling. Current CEmu\nbenchmarks on OS 5.7 show MicroLua beating matched TI-BASIC workloads from\n1.01x on list-heavy code to 8.1x on scalar integer loops; see\n`platform/ti84ce/README.md` for the full table and autotester workflow.\n\n## License\n\n```\nBSD Zero Clause License\n\nCopyright (c) 2026 Louka Ménard Blondin \u003chello@louka.sh\u003e\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY\nAND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\nPERFORMANCE OF THIS SOFTWARE.\n```\n\n[^1]: You can optionally choose to provide allocators for dynamic memory allocation.\n\n[^2]: These are provided in the repl.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flus-lang%2Fmicrolua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flus-lang%2Fmicrolua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flus-lang%2Fmicrolua/lists"}