Cross-platform ahead-of-time Lua compiler

clx is a cross-platform ahead-of-time Lua compiler and runtime that generates standalone native executables through modern C++ toolchains. clx is not trying to be the fastest Lua implementation in every workload.

Quick Start

git clone https://github.com/samyeyo/clx.git
cd clx
./build.sh install       # or build.bat install on Windows
clx examples/hello/hello.lua
./hello

Hello clx!

What makes clx useful

• Just write Lua. clx targets Lua 5.5, so your code works like ordinary Lua.
• Fast native speed — your scripts are compiled to native machine code.
• Efficient memory management — a generational garbage collector tuned for short-lived data.
• Standalone binaries — no interpreter or extra runtime to install alongside your program.
• Small outputs — size-friendly builds can create very compact executables.
• Cross-platform — works on Linux, macOS, and Windows.
• Extensible — Compatible with the Lua 5.5 C API: just recompile your existing binary modules and clx links them into the final executable seamlessly — no code changes.

Examples built with clx

clx ships real, runnable examples that show native desktop application development using standard Lua code.

Pong

A complete game written in Lua and compiled into a standalone native executable.

Mandelbrot viewer

A Mandelbrot viewer written in Lua and compiled into a standalone native executable.

Project status

clx is currently in beta. It can already compile real Lua applications, and compatibility and performance work continues.

Requirements

• Linux: g++ or clang++
• macOS: clang++ (Xcode) or g++ via Homebrew
• Windows: MSVC (cl), LLVM clang-cl, or g++ (MinGW)
• CMake 3.15+ to build from source

The compiler that builds clx is the same one used to compile your Lua scripts, keeping everything consistent. If you need a different compiler, just rebuild clx with it.

Using clx

The easiest way to use clx is to compile a Lua file into a runnable program:

clx file.lua          # compiles file.lua and produces an executable
./file                # run it

A few common options when you need more control:

clx file.lua --size        # optimize for size (default)
clx file.lua --fast        # optimize for speed
clx file.lua --output app  # give the output a custom name
clx file.lua --dynamic     # allow loading Lua code at runtime
clx --help                 # see all options

• load() / loadfile() / dofile() run on an embedded Lua engine and are only available when you compile with --dynamic. See Dynamic Lua.
• To write native modules, clx supports both its own clx C++ API and the standard Lua 5.5 C API (lua.h, lauxlib.h, lualib.h) — existing C modules compile and run unchanged and are linked into the executable with --modules. See Modules and the Lua C API.

Benchmarks

clx compares well against the reference Lua 5.5 interpreter:

Script	lua 5.5	LuaJIT	clx --fast
fib.lua	0.299s (1.00x)	0.049s (6.10x)	0.006s (49.83x)
arraysum.lua	0.305s (1.00x)	0.086s (3.55x)	0.090s (3.39x)
spectralnorm.lua	0.328s (1.00x)	0.021s (15.62x)	0.019s (17.26x)
canada.lua	0.356s (1.00x)	0.148s (2.41x)	0.244s (1.46x)
warmup.lua	0.008s (1.00x)	0.006s (1.33x)	0.004s (2.00x)

Measured on an Intel® Core™ Ultra 5 125U CPU @ 4.30GHz · Linux · GCC 15.2.0 · Average of 10 runs · clx --fast built with AVX2 (CLX_ARCH=avx2)

Full benchmarks are available in clx benchmarks

Documentation

Detailed guides live in the doc/ directory:

• Getting Started
• CLI Reference
• Dynamic Lua
• Compatibility
• Modules
• Clx C++ API
• Lua C API
• Migration Guide
• Benchmarks

Start at the Documentation Index.

License

clx is MIT Licensed — Copyright (c) 2026 Tine Samir