USAGE.adoc

Using luainstaller

Back to documentation index

Day-to-day packaging. Platforms and ABI: Platforms and native modules. Install and CLI/library overview: README.

Supports official Lua >= 5.1 and < 6.0. LuaJIT is rejected. The running interpreter defines the bundle Lua major/minor ABI; headers, libraries, discovery, native modules, and the linked runtime must match. Lua 5.5 needs LuaRocks >= 3.13.0.

The CLI has two grammars, luai and luainstaller: same features, different input and terminal output; do not mix them. Mapping is in the README. Command-line examples below use luai (use luainstaller logs for logs).

Table of Contents

• Workflow
• Directory bundle
• Single-file
• luai options
  • Output
  • Dependencies
  • Other
• Dependency discovery
  • static (default)
  • runtime
  • manual
• Native modules
• Logs
• Library API

Workflow

1. Run the entry with the same lua and module paths that will be packaged

2. luai -a / luai -t

3. luai -b --dir for a directory bundle

4. Run with LUA_PATH and LUA_CPATH cleared

5. Optionally luai -b --file for a single-file build

Directory first, then single-file, separates dependency issues from compile/extract issues.

lua app/main.lua --help

Repository fixture: lua test/runtime_bundle/main.lua direct (from the repo root).

Directory bundle

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

EMPTY_PATH=$(mktemp -d /tmp/luainstaller-empty-path-XXXXXX)
env -i PATH="$EMPTY_PATH" \
  build/runtime-demo/runtime-demo Grace
rmdir "$EMPTY_PATH"

find build/runtime-demo -type f -print | sort
sed -n '1,220p' build/runtime-demo/.luai/manifest.lua

The entry and pure-Lua modules live in the launcher. .luai/native/ holds Lua C modules (and the runtime library on shared-Lua profiles). Packaged modules win; undeclared names may still fall through to host searchers. That is same environment lookup, not a hermetic sandbox. The clean run exposes missing packaged dependencies.

Single-file

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

At runtime the payload is a content-addressed directory bundle extracted under the temporary directory, then the inner launcher starts. POSIX caches are keyed by effective UID. Cache reuse requires exact byte match. Layout and safety: Bundle format.

luai options

Output

--dir

Directory bundle (default).

--file

Single-file executable.

-o PATH

Output path.

User-owned content is never overwritten. A recognized generated directory bundle may rebuild via private staging. Only recursive v2 ownership markers are eligible for automatic replace; v1 requires manual removal once (one-time removal).

Dependencies

--include PATH

Add a .lua file discovery missed.

--exclude VALUE

Drop a dependency (path, basename, or path suffix).

-d MODE

static, runtime, or manual (default static).

--no-depscan

Same as manual.

--max-deps N

Pure-Lua dependency cap (default 36).

Other

--lua PATH

Interpreter for runtime discovery. It must be an official Lua 5.1-5.5 interpreter with the exact major/minor ABI of the active luainstaller process. When omitted, only verified interpreter candidates from the launcher argument vector or lua on PATH are accepted; otherwise pass --lua explicitly.

-- ARGS…​

Arguments only for the entry during discovery.

--target-os OS

Assert the detected host OS; mismatch fails. No cross-build.

--lua-prefix PATH

Headers/runtime prefix; an explicit choice does not fall back to another install.

--verbose

Extra trace/counts.

Dependency discovery

static (default)

Recognizes literal forms such as require("x"), require 'x', and pcall(require, "x"). String escapes are decoded. local require = require is followed; other aliases are not.

Resolution is entry-rooted: templates under the entry directory first, then package.path / package.cpath. Computed names → DynamicRequireError. Native module names must be literals.

runtime

luai -a app/main.lua -d runtime -- profile_a input.json

Only loads observed on this run are recorded. Do not use on entries that mutate data, open the network, or start services at import time. Native loaders and pre-trace cache limits: Troubleshooting.

manual

luai -b app/main.lua --no-depscan \
  --include app/core.lua \
  --include app/adapters/sqlite.lua \
  -o build/app

--include paths must keep structure relative to the entry.

Native modules

Use the same paths as the source program (5.x → actual ABI):

LUA_PATH='/opt/app/share/lua/5.x/?.lua;;' \
LUA_CPATH='/opt/app/lib/lua/5.x/?.so;;' \
luai -b --dir app/main.lua -o build/app --max-deps 250

find build/app/.luai/native -type f | sort
ldd build/app/app

On macOS use otool -L. Validate Windows builds on Windows.

Logs

Only luainstaller provides this:

luainstaller logs
luainstaller logs --level error --limit 20

Stored under ~/.luainstaller/. Compiler output and the current command’s structured errors remain the primary evidence.

Library API

local luainstaller = require("luainstaller")

local analysis = luainstaller.analyze({
    entry = "app/main.lua",
    discovery_mode = "static",
    max_deps = 120,
})
if not analysis.ok then
    io.stderr:write(analysis.error.type, ": ", analysis.error.message, "\n")
    os.exit(1)
end

local built = luainstaller.bundle({
    entry = "app/main.lua",
    mode = "onedir",
    out = "build/app",
    max_deps = 120,
})
assert(built.ok, built.error and built.error.message)
print(built.executable)

The structured result contract applies to analyze, trace, compatibility, and bundle only. Success: ok = true. Failure: ok = false with error.type / error.message. getLogs returns a list of log records; clearLogs returns a boolean. Unknown option keys for the structured operations → InvalidOptionsError. Version: luainstaller.VERSION.

Back to documentation index