Cosmopolitan Lua Embedded Binary

A portable, single-file binary that embeds the Lua interpreter and runs an embedded Lua script. Built using the Cosmopolitan toolchain for true write-once-run-anywhere compatibility.

Features

• Portable Binary: Runs on Linux, macOS, Windows, FreeBSD, and other supported platforms
• Embedded Lua 5.4.6: Full Lua interpreter statically linked
• Self-Contained: Lua script is embedded at build time
• Single File: No external dependencies required at runtime

Prerequisites

• Cosmopolitan toolchain installed (cosmocc must be on PATH, or set CC=/path/to/cosmocc)
• Standard build tools: make, wget, tar

Quick Start

# Build the portable binary
make

# Run it
./hello.lua.com

Build Targets

Target	Description
all (default)	Build the portable binary
lua	Download and build Lua library only
script-header	Generate embedded_script.h from embedded_script.lua
clean	Remove build artifacts (keeps downloaded Lua)
distclean	Remove everything including downloaded Lua

Project Structure

.
├── Makefile              # Build automation
├── README.md             # This file
├── main.c                # C program embedding Lua interpreter
├── embedded_script.lua   # Lua script to embed (edit this!)
├── embedded_script.h     # Auto-generated header (do not edit)
├── update_script.lua     # Tool: update binary's embedded script without recompiling
├── lua-5.4.6/            # Lua source (downloaded by make)
└── hello.lua.com         # Output binary

Customizing the Embedded Script

Edit embedded_script.lua to change the embedded Lua code:

-- embedded_script.lua
print('My custom script!')
-- Your Lua code here

Then rebuild:

make clean
make

How It Works

1. Build Time: The Makefile converts embedded_script.lua into a C string literal in embedded_script.h
2. Compile: The C code includes this header, embedding the script directly in the binary
3. Runtime: The binary creates a Lua state, loads standard libraries, and executes the embedded script

Script Update Mechanisms

1. Edit and Recompile (Simple)

The script is compiled into the binary. To update:

# Edit embedded_script.lua, then:
make clean && make

2. External Script Override (No Recompilation)

Run an external script file instead of the embedded one:

# Run embedded script (default)
./hello.lua.com

# Run external script instead
./hello.lua.com my_script.lua

# Execute inline Lua code
./hello.lua.com -e "print('Hello ' .. 'World')"

3. Append Script to Binary (Advanced - No Recompilation)

Update the embedded script in the binary without recompiling using update_script.lua:

# Update the binary (atomically replaces it in-place)
./hello.lua.com update_script.lua hello.lua.com new_script.lua

# Run - now uses the new script
./hello.lua.com

How it works: update_script.lua appends the new script with a magic marker (__LUA_SCRIPT_MARKER__) to the end of the binary. At runtime, the binary searches the last 1 MB for this marker and executes the appended script instead of the compiled-in default. The update writes to a temp file and renames atomically, so the running binary is never written to directly.

Notes:

• You can run update_script.lua multiple times; each run strips the previous appended script first
• To restore the original compiled-in script, rebuild with make clean && make

Technical Details

• Lua Version: 5.4.6
• Cosmopolitan: Creates APE (Almost Portable Executable) format
• Binary Size: ~1.5 MB (includes full Lua interpreter)
• Libraries: All standard Lua libraries are loaded

Troubleshooting

cosmocc: command not found

Ensure the Cosmopolitan toolchain is installed and on PATH, or set CC:

export CC=/path/to/cosmocc

Build fails with Lua errors

Run make distclean to force a fresh Lua download and build.

License

• Lua: MIT License
• Cosmopolitan: ISC License
• This project: MIT License