Show HN: Clx – Compile Lua to Native Executables Through C++20

Hacker News Top Tools
lua compiler ahead-of-time native-executable cpp20 cross-platform open-source

Summary

Clx is a cross-platform ahead-of-time Lua compiler that generates standalone native executables using C++20 toolchains, offering competitive performance, small binaries, and compatibility with Lua 5.5.

Hi HN,<p>clx is an ahead-of-time compiler for standard Lua that generates C++20 and produces standalone native executables through GCC, Clang or MSVC.<p>The project started as an experiment to see whether modern C++ could be used as a portable compiler backend instead of LLVM or direct machine code generation. The generated code is then compiled and optimized by the host toolchain.<p>The latest release replaces the previous NaN-tagged value representation with a new shadow-types implementation, adds full int64 support, improves native arithmetic code generation and adds ARM64 macOS coroutine support.<p>Performance is typically much faster than the Lua interpreter and can outperform LuaJIT on some computation-heavy workloads while remaining fully ahead-of-time compiled.<p>The repository also contains graphical examples written in Lua, including a Pong game and a Mandelbrot explorer using a Sokol binary module (using the clx C++ API)<p>I&#x27;d be very interested in feedback on clx :)
Original Article
View Cached Full Text

Cached at: 07/17/26, 01:54 AM

samyeyo/clx

Source: https://github.com/samyeyo/clx

CLX Logo

Cross-platform ahead-of-time Lua compiler

Lua 5.5 C++20 License: MIT ko-fi



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.

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 !

Features

  • 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

Examples built with clx

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

Pong

Pong

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

Mandelbrot viewer

Mandelbrot

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

Project status

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

Requirements

  • 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

POSIX

./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

Windows

./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

Usage

./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

Compatibility

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.

Known limitations

  • 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.

Test suite

./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.

Benchmarks

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

Scriptlua 5.5LuaJITclx --fast
fib.lua0.311s (1.00x)0.045s (6.91x)0.005s (62.20x)
arraysum.lua0.128s (1.00x)0.052s (2.46x)0.031s (4.13x)
spectralnorm.lua0.310s (1.00x)0.018s (17.22x)0.029s (10.69x)
canada.lua0.372s (1.00x)0.142s (2.62x)0.286s (1.30x)
warmup.lua0.006s (1.00x)0.005s (1.20x)0.005s (1.20x)

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

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

License

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

Similar Articles