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.

Its goal is to provide:

• ahead-of-time native compilation,
• deployable standalone executables,
• predictable runtime performance,
• fast startup times,
• integration with existing C++ toolchains,
• and strong optimization opportunities through modern native compilers.

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 !

• Competitive performance with strong results on many AOT-friendly workloads
• No bytecode interpreter overhead — compiles to standalone native executables
• Aggressive optimizations — leverages modern optimizations via Clang/GCC/MSVC
• Small binaries — size-oriented builds can produce very compact executables (Lua programs can be under 100 KB with --minimal)
• Targets Lua 5.5 compatibility — coroutines, metamethods, tables, and more
• 16-byte tagged values — 8-byte payload + separate type tag
• Inline string optimization (strings ≤ 6 bytes stored in value, no allocation)
• Fast-path table access caches
• Lightweight AOT-oriented runtime
• clx C++ API: develop portable native modules using a value-oriented API

clx comes with examples, that uses a Sokol clx binary module for graphics, and demonstrate native desktop application development with standard Lua code.

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

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

clx is currently in beta. The compiler is already capable of compiling non-trivial Lua applications, but compatibility work and optimization improvements are ongoing.

• Linux: g++ (recommended for TCO) or clang++
• macOS: clang++ (Xcode) or g++ via Homebrew (for TCO)
• Windows: g++ (LLVM) or MSVC
• CMake 3.15+ for building

Note: The compiler used to build clx is fixed at build time via CMake and used for all Lua script compilation. This ensures ABI compatibility between the runtime libraries and generated code. Rebuild clx with a different compiler if you need a different backend.

./build.sh              # Release (default)
./build.sh debug        # Debug
./build.sh clean        # Removes build/ + /usr/local install
./build.sh install      # Release + install to /usr/local
./build.sh uninstall    # Removes installed files in /usr/local

./build.bat              # Release (default)
./build.bat debug        # Debug
./build.bat clean        # Removes build/ + ./bin and ./lib
./build.bat install      # Release + install to /bin and ./lib
./build.bat uninstall    # Removes previously installed clx

Also works directly with CMake:

mkdir -p build && cmake -S . -B build && cmake --build build

Once compiled, you will find :

• build/clx — The compiler executable
• build/libclx.a — Static runtime library
• build/libclx_size.a — Static runtime library optimized for size

./build/clx file.lua                         # Compile to executable (default flags)
./build/clx --object file.lua                # Object file (.o/.obj)
./build/clx --static file.lua                # Static clx module (.a/.lib)
./build/clx --cpp file.lua                   # Generate C++ source, don't compile
./build/clx file.lua -O2                     # Forward unknown clx flags to the backend compiler
./build/clx file.lua --output f.exe          # Custom output name
./build/clx file.lua --debug                 # No optimizations, debug symbols
./build/clx file.lua --minimal               # base + package modules only
./build/clx file.lua --fast                  # Optimize for speed
./build/clx file.lua --size                  # Optimize for size (default)
./build/clx --version                        # Print version
./build/clx --help                           # Display help

clx targets Lua 5.5 compatibility.

Current status:

• Core language: largely implemented
• Tables and metatables: implemented
• Coroutines: implemented
• Modules: implemented
• Most standard libraries: implemented

See compatibility.md for detailed status.

• load() / dofile() / loadfile() / string.dump() — dynamic code loading requires a runtime interpreter
• debug module — very complex in a pure AOT model
• The traditional Lua C API is not supported.
• Binary modules should be written using the clx C++ API.

./tests/run.sh              # POSIX
./tests/run.bat             # Windows

Each .lua in tests/ is compiled to a binary and executed. Tests print [OK]/[FAIL] per assertion.

Results are expressed in speedup factor against standard Lua 5.5 interpreter :

Measured on Intel® Core™ i5 Ultra 125U CPU @ 4.30GHz · Linux · GCC 13.3.0 · Avg of 10 runs

Full benchmarks are available in clx benchmarks

Documentation is available in the doc/ directory, including :

• Getting Started
• CLI Reference
• Compatibility Status
• Modules and Migration Guide
• C++ API Reference
• Runtime Internals
• Architecture Overview
• Optimizations
• Benchmarks

See Documentation Index

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