luainstaller

luainstaller packages Lua applications into executable bundles for controlled runtime environments. It analyzes require dependencies, records resolution decisions, builds a manifest, generates a small C launcher, and can produce either an inspectable directory bundle or a self-extracting onefile wrapper.

Table of Contents

• Documentation Index
• Overview
• Quick Start
• Command Surfaces
• Repository Layout

Documentation Index

The documentation is intentionally split into six guides. Start with the usage guide when packaging an application. Use the implementation and bundling guides when changing internals. Use the platform, testing, and troubleshooting guides when native modules, target profiles, or failure diagnosis matter.

Need	Start here	Useful sections
Package an application	Usage Guide	Normal packaging session, first bundle, native module bundle, option reference.
Understand generated output	Bundling Guide	onedir layout, launcher startup, onefile runtime, output safety.
Work on implementation	Implementation Guide	end-to-end flow, module boundaries, manifest contract, errors and logging.
Choose or debug target platforms	Platforms, Native Modules, and Limits	compatibility model, target profiles, native modules, explicit limits.
Verify changes	Testing Guide	test tiers, full smoke coverage, remote matrix, release checklist.
Diagnose failures	Troubleshooting Guide	first diagnostic pass, common errors, native loader failures, issue data.

Overview

Important

The supported runtime contract is same OS family, same architecture, same system ABI, and same Lua ABI. Bundles can run without a separate lua command on the target machine, but native Lua C modules and their external shared libraries still have to match that environment.

luainstaller is aimed at Lua applications that need a repeatable same-environment executable, not a universal cross-platform binary. The normal workflow is to inspect dependencies, build an onedir bundle, verify the generated layout, and only then build a onefile wrapper.

Area	Behavior
Primary use	Ship Lua applications to machines that match the selected build profile: local deployment, lab machines, internal tooling, and controlled runtime images.
Command surfaces	luai is the compact script-friendly CLI. luainstaller is the full-word CLI with log inspection. Both call the same Lua API.
Dependency discovery	Static literal-require scanning, manual include/exclude mode, and runtime require tracing are implemented.
Bundle modes	--dir / --onedir builds an inspectable directory. --file / --onefile builds a self-extracting wrapper around the same staged directory layout.
Target profiles	Linux shared-Lua profile, macOS static-Lua-prefix profile, and Windows-from-Linux MinGW profile are covered by the current sample matrix.
Explicit non-goals	Universal cross-platform output, native ABI conversion, automatic external shared-library closure, no-extract native module loading, codesigning, and native installers.

Quick Start

Install with LuaRocks:

luarocks install luainstaller
luai -h

Install from a source checkout when LuaRocks is not available:

sh tools/install-source.sh --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
luai -v
luainstaller version

Analyze a sample, inspect the trace, build a directory bundle, then try a onefile bundle after the directory version works:

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 world

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

The same workflow through the full-word CLI:

luainstaller analyze test/runtime_bundle/main.lua --max-deps 120
luainstaller trace test/runtime_bundle/main.lua --max-deps 120
luainstaller build --dir test/runtime_bundle/main.lua -o build/runtime-demo --max-deps 120

Command Surfaces

Action	Compact CLI	Full-word CLI
Help	luai -h	luainstaller help
Version	luai -v	luainstaller version
Analyze	luai -a app/main.lua	luainstaller analyze app/main.lua
Trace	luai -t app/main.lua	luainstaller trace app/main.lua
Build	luai -b app/main.lua	luainstaller build app/main.lua
Logs	Not exposed	luainstaller logs

Command forms intentionally do not cross over. luai build app.lua and luainstaller -b app.lua are rejected so scripts can depend on a small stable compact surface while human-facing commands remain explicit.

Repository Layout

Path	Purpose
src/	Implementation modules for analysis, compatibility diagnostics, manifest creation, launcher generation, bundling, onefile wrapping, logging, and CLI rendering.
docs/	The six documentation pages linked from the documentation index. Each page links back to the index near the top and at the end.
test/	Sample applications, documentation-derived contract tests, and smoke tests that exercise pure Lua, native module, runtime-discovery, onedir, onefile, installed-CLI, and release safety behavior.
tools/	Source installer and remote Linux, macOS, and Windows verification scripts.
luainstaller.1	Manual page source installed for both luai(1) and luainstaller(1).

Project repository: Water-Run/luainstaller.