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

Overview

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

Key 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

clx comes with examples that use 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

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.

Prerequisites

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

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

CLI 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

Lua 5.5 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.

Not Supported

• 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

Running Tests

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

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

License

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