luainstaller

luainstaller turns a Lua entry script and its require dependencies into a native executable bundle. It is intended for deployment to a known target environment: the target must match the bundle’s operating-system family, architecture, system ABI, and Lua ABI.

The project provides two command names:

• luai is the short, flag-based interface for scripts and quick use.

• luainstaller is the descriptive interface for interactive use and logs.

Both commands call the same Lua API and produce the same bundles.

The supported interpreter range is official Lua >= 5.1 and < 6.0. LuaJIT is rejected. Analysis, headers, linked runtime, and native modules must all use the same Lua major/minor ABI as the interpreter running luainstaller. The project is tested with the upstream patch releases 5.1.5, 5.2.4, 5.3.6, 5.4.8, and 5.5.0. Those versions and the devices listed below are test coverage, not an allowlist.

Table of Contents

• Quick start
• Compatibility contract
• Command summary
• Documentation
• Development baseline

Quick start

Install from LuaRocks:

luarocks install luainstaller
luai -v

Lua 5.5 requires LuaRocks 3.13.0 or newer; earlier LuaRocks releases do not recognize the Lua 5.5 installation ABI.

Start with the small runtime sample. Build the directory form first because it keeps the manifest, generated C source, and copied native libraries visible. In shell examples, set LUA to the official interpreter being packaged.

LUA=${LUA:-lua}
$LUA test/runtime_bundle/main.lua direct
luai -a test/runtime_bundle/main.lua --max-deps 120
luai -t test/runtime_bundle/main.lua --max-deps 120
luai -b --dir test/runtime_bundle/main.lua \
  -o build/runtime-demo --max-deps 120
build/runtime-demo/runtime-demo Ada

After the directory bundle works, produce a self-extracting executable:

luai -b --file test/runtime_bundle/main.lua \
  -o build/runtime-demo-onefile --max-deps 120
build/runtime-demo-onefile Ada

Expected output begins with hello Ada.

Compatibility contract

A bundle does not contain an emulator or an ABI translation layer. Build and target environments must agree on all four of these boundaries:

• operating-system family;

• CPU architecture;

• system and compiler ABI;

• Lua major/minor ABI.

The generated launcher derives its compile-time guard and module paths from the active Lua ABI. Toolchain discovery verifies that headers, library, and linked runtime report the same ABI before publication. This is a native-host packager, not a cross-compiler or a hermetic sandbox: embedded modules win, but an undeclared module may fall through to the target host’s normal Lua/native searchers. Always run a release candidate once with LUA_PATH and LUA_CPATH cleared and without Lua on PATH.

Pure-Lua modules are embedded in the launcher. Lua C modules are copied into the bundle, but their dependent system libraries are not discovered recursively. Check them with ldd, otool -L, or a Windows dependency viewer before release.

The following physical devices are in the release test matrix:

Device	Tested system	Architecture
Local workstation	Windows 11 Pro for Workstations	x86_64
yynicepc	Debian 13	x86_64
localhost.localdomain	Rocky Linux 10.2	x86_64
NVIDIA DGX Spark (spark-49c8)	Ubuntu 24.04 LTS	ARM64
yymac06 Mac mini	macOS 26.5	ARM64
yymacstudio Mac Studio	macOS 26.5.1	ARM64

This matrix records where releases were exercised; it does not say that luainstaller can run only on these models, distributions, or OS versions. Every bundle is built on the native target OS and architecture. There is no cross-build mode.

See Platforms and native modules for toolchain requirements and unsupported combinations.

Command summary

Task	Short command	Descriptive command
Help	luai -h	luainstaller help
Version	luai -v	luainstaller version
Analyze	luai -a app/main.lua	luainstaller analyze app/main.lua
Trace resolution	luai -t app/main.lua	luainstaller trace app/main.lua
Build	luai -b app/main.lua	luainstaller build app/main.lua
Read logs	—	luainstaller logs

The syntaxes are deliberately separate. luai build app.lua and luainstaller -b app.lua are rejected.

Documentation

Choose the guide that matches the work in front of you:

• Usage — commands, options, discovery modes, and Lua API.

• Bundle format — onedir/onefile layout, startup, cache, and output replacement.

• Platforms and native modules — ABI rules, compilers, native dependencies, and explicit limits.

• Troubleshooting — diagnosis by symptom and error type.

• Implementation — internal data flow and module responsibilities.

• Testing — local checks, remote matrix, and release gate.

The installed manual page is available as luai(1) and luainstaller(1).

Development baseline

The repository follows a strict single-branch contract. main is the only branch. Development work is committed directly to main and pushed directly to main; persistent topic, development, release, and pull-request merge branches are not part of the project workflow. A temporary local worktree used by automation must be fast-forwarded into main and removed before release.

From the repository root:

LUA=${LUA:-lua}
LUAC=${LUAC:-luac}
find src -type f -name '*.lua' -print0 | xargs -0 -n1 "$LUAC" -p
for script in tools/*.sh; do sh -n "$script"; done
"$LUA" test/cli_split_smoke.lua
"$LUA" test/contract_docs.lua
"$LUA" test/production_edges.lua
"$LUA" test/smoke_all.lua
luarocks lint luainstaller-1.0.0-1.rockspec

test/contract_docs.lua checks promises made by the public documentation. test/production_edges.lua covers fail-closed filesystem behavior, source mutation, SHA-256 ownership, concurrency, ABI rejection, and reproducibility. test/smoke_all.lua exercises dependency discovery, generated launchers, native modules, installed commands, onedir, onefile, and output safety.

Project repository: github.com/Water-Run/luainstaller

License: LGPL-3.0-or-later.