MicroLua

Port Configuration

Port settings live in src/MLuaConfig.h. Use -Dport=generic64, generic32, cortex-m, riscv32, or ti84ce for bundled presets, or provide a board-specific header:

meson setup build-board -Dport_header=path/to/my_board_mlua.h

A port header can override pointer size, heap alignment, default stack and frame sizes, GC threshold, fixed-width type source, native float subtype and width, math hooks, compiler support, bytecode dumping, the string.pack format engine, VM dispatch style, and opcode profiling. MicroLua supports 64-bit NaN-boxing and a 32-bit alignment-tagging representation with boxed full-width integers.

Build Outputs

builddir/mlua

The command-line interpreter and REPL.

builddir/libmicrolua.a

The embeddable MicroLua static library.

builddir-release/libmicrolua.a

The freestanding release static library.

build-bytecode/mlua

The bytecode-only command-line runner.

build-bytecode/libmicrolua.a

The embeddable bytecode-only static library without the lexer or parser.

Command Line

./builddir/mlua script.lua
./builddir/mlua
./builddir/mlua -e 'print(1 + 2 * 3)'
./builddir/mlua -o chunk.mlu script.lua
./build-bytecode/mlua chunk.mlu

Running mlua with no file starts the interactive REPL. The REPL evaluates one line as one chunk, so local variables do not persist across lines. Put multi-line programs in a file.

Use -o on a compiler-enabled host build to create a portable .mlu bytecode file. Bytecode has a versioned header with an explicit endianness byte and fixed-width serialized fields, so it can be moved across supported endian and pointer-size targets with a compatible MicroLua bytecode version. Numeric constants are stored as canonical IEEE-754 binary64 values and are narrowed or widened at the boundary for targets using a narrower native MLUA_FLOAT. The current bytecode format is v4, which adds fused global and table-indexing opcodes.

Options

Small Example

local total = 0
for i = 1, 10 do
  total = total + i
end
print(total)

TI-84 Plus CE

platform/ti84ce/ is a complete board port for the TI-84 Plus CE: an eZ80 target with 24-bit int and pointers, binary32 double, a small C stack, and a tight RAM budget. It is built with the external CE C/C++ Toolchain makefiles, not Meson.

cd platform/ti84ce/repl && make
cd platform/ti84ce/runner && make

The CE preset disables string.dump and the string.pack family (MLUA_ENABLE_DUMP=0, MLUA_ENABLE_PACK=0) and enables GNU-C computed-goto dispatch (MLUA_VM_COMPUTED_GOTO=1). The full REPL is close to the calculator's practical decompressed image ceiling, so image size should be checked in bin/MLUA.map when core code grows.

The matched benchmark sources, calculator bindings, installation notes, and CEmu autotester workflow are documented in platform/ti84ce/README.md.

Language

MicroLua follows Lua syntax where that syntax fits its footprint. Supported statements include local declarations, assignments, function definitions, if, while, repeat, numeric for, generic for, do blocks, break, and return.

Supported values include nil, booleans, numbers, strings, tables, functions, C functions, and coroutines. Strings and source files are UTF-8. Numeric literals keep the Lua 5.3 integer/float distinction: math.type(1) is "integer" and math.type(1.0) is "float".

Supported operators include arithmetic +, -, *, /, %, exponentiation ^, length #, concatenation .., comparisons, and, or, and not.

Functions support lexical closures, upvalues, varargs, multiple return values, and tail-call frame reuse for plain fixed-arity return f(args) calls. Vararg and multiple-return call forms have the same language result but may allocate a fresh frame.

Tables

Tables have an array part and a hash part. Array keys must remain contiguous: assigning a value past #t + 1 is a runtime error because it would create a hole. Assigning nil past the end is a no-op.

MicroLua does not have metatables. It provides table.forward as a small table-delegation mechanism for lookup forwarding.

Base Globals

math

Available constants: pi, huge, maxinteger, and mininteger.

string

string.len, string.sub, string.byte, string.char, and string.reverse operate on codepoints. Pattern matching is byte-based, and case conversion is ASCII-only. string.dump is present when MLUA_ENABLE_DUMP is enabled. The string.pack, string.packsize, and string.unpack functions are present when MLUA_ENABLE_PACK is enabled; both knobs default on.

Supported pattern features include anchors ^ and $, classes such as %a, %d, %s, %w, %l, %u, %p, %c, and %x, character sets, captures, and the *, +, -, and ? quantifiers.

table

table.pack and table.unpack follow the Lua 5.2 naming. unpack is also available as a global compatibility alias.

coroutine

Coroutines can yield from nested Lua calls. Yielding across a C-call boundary is an error.

Optional io and os

These are not part of the freestanding core. They are available in the REPL build through src/extensions/MLuaStdLib.c.