Clx: Ahead-of-Time Lua Compilation to Native Executables

Clx: Ahead-of-Time Lua Compilation to Native Executables

Clx is a cross-platform ahead-of-time (AOT) compiler and runtime that converts Lua 5.5 code into standalone native executables. By leveraging a C++20 backend and modern native toolchains (Clang, GCC, and MSVC), Clx removes the overhead of a bytecode interpreter, enabling predictable runtime performance and fast startup times.

Core Objectives and Performance

Clx is designed for deployability and predictability rather than being the absolute fastest implementation for every single workload. Its primary goals include producing standalone executables, providing fast startup, and enabling strong optimization opportunities through native compilers.

Performance benchmarks on an Intel® Core™ i5 Ultra 125U CPU (Linux, GCC 13.3.0) show significant speedups over the standard Lua 5.5 interpreter:

Script Lua 5.5 LuaJIT Clx --fast
fib.lua 1.00x 6.91x 62.20x
arraysum.lua 1.00x 2.46x 4.13x
spectralnorm.lua 1.00x 17.22x 10.69x
canada.lua 1.00x 2.62x 1.30x
warmup.lua 1.00x 1.20x 1.20x

Technical Implementation and Optimizations

Clx implements several low-level optimizations to reduce memory allocation and improve execution speed:

  • 16-byte Tagged Values: Uses an 8-byte payload with a separate type tag.
  • Inline String Optimization: Strings of 6 bytes or fewer are stored directly within the value, eliminating the need for heap allocation.
  • Fast-path Table Access: Implements caches to accelerate table lookups.
  • C++20 Backend: Generates native code that can be further optimized by the backend compiler (GCC, Clang, or MSVC).

Features and Compatibility

Clx targets compatibility with Lua 5.5, with the core language, tables, metatables, coroutines, and most standard libraries already implemented.

Key Capabilities

  • Small Binaries: Using the --minimal flag, Lua programs can be compiled into executables smaller than 100 KB.
  • Flexible Output: The compiler can generate native executables, object files (.o/.obj), static modules (.a/.lib), or raw C++ source code.
  • C++ API: Provides a value-oriented API for developing portable native modules.

Known Limitations

Because Clx is a pure AOT model, certain dynamic features of Lua are unsupported:

  • Dynamic Code Loading: Functions like load(), dofile(), and loadfile() are not supported as they require a runtime interpreter.
  • Debug Module: The debug module is not supported due to the complexity of implementing it in an AOT environment.
  • C API: The traditional Lua C API is not supported; developers must use the clx C++ API for native modules.

Getting Started and Build Requirements

Clx is currently in beta. To build and install it, users require CMake 3.15+ and a compatible C++ compiler:

  • Linux: g++ (recommended for Tail Call Optimization) or clang++.
  • macOS: clang++ (Xcode) or g++ (Homebrew).
  • Windows: g++ (LLVM) or MSVC.

Quick Start Command

git clone https://github.com/samyeyo/clx
cd clx
./build.sh install
clx examples/hello/hello.lua
./hello

Project Status and Licensing

Clx is released under the MIT License and is currently in beta, with ongoing work on compatibility and optimization improvements.

Sources