[ANN] CLX - Ahead-of-Time Lua 5.5 Compiler

[samir...@luart.org]

Hello,

CLX is a new open-source ahead-of-time compiler for Lua 5.5.
CLX compiles Lua source code to standalone native executables through modern C++20 toolchains (Clang, GCC, and MSVC).

Current features include:

• Native standalone executable compilation

• Support for most Lua 5.5 language features

• Cross-platform support (Linux, Windows, and macOS)

• Lightweight runtime designed for AOT compilation

• C++ API for native modules

• Example projects (a fully playable Pong game and a Mandelbrot fractal renderer)

Recent benchmarks show consistent speedups over the standard Lua interpreter and competitive performance with LuaJIT on a number of workloads.

The project is currently in beta and feedback is welcome.

Website:
https://samyeyo.github.io/clx

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

Thank you,

Samir Tine

[bil til]

Am So., 21. Juni 2026 um 17:17 Uhr schrieb <samir...@luart.org>:
> Support for most Lua 5.5 language features

Please excuse a "lazy question" (I did not look at your project in
detail, please excuse - currently too much different work):

Which are the main features your project does NOT support?

(because you do not like them / you think they are too cumbersome? or
because the produce any severe problems in your project?)

> --
> You received this message because you are subscribed to the Google Groups "lua-l" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to lua-l+un...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/lua-l/b37b13c2128d9a27a854da270db19608%40luart.org.

[Samir Tine]

That's a fair question.
The goal is not to intentionally exclude Lua features. In fact, CLX already supports essentially all Lua 5.5 syntax (including global, <const> and <close>) and most of the standard library.

The main unsupported areas today are features that fundamentally depend on runtime code generation or deep interpreter introspection, such as load(), loadfile(), dofile(), string.dump(), and most of the debug module.

The traditional Lua C API is also not supported, as CLX uses its own C++ API designed around the AOT execution model (CLX don't use any stack or VM internally)

Apart from these limitations, the goal is full Lua 5.5 compatibility.

[Pierre Chapuis]

Nice project.

FYI on an Arch Linux machine, out of the box, building and trying to use the result will fail:

```

/usr/bin/ld: /dcs/cwl/git/clx/build/libclx_size.a(runtime.cpp.o): plugin needed to handle lto object /usr/bin/ld: /dcs/cwl/git/clx/build/libclx_size.a(runtime.cpp.o): plugin needed to handle lto object /usr/bin/ld: /dcs/cwl/git/clx/build/libclx_size.a(openlibs.cpp.o): plugin needed to handle lto object /usr/bin/ld: /dcs/cwl/git/clx/build/libclx_size.a(openlibs.cpp.o): plugin needed to handle lto object /usr/bin/ld: /tmp/lto-llvm-d854bc.o: in function `luaopen_t(clx::LState*)': ld-temp.o:(.text._Z9luaopen_tPN3clx6LStateE+0x126): undefined reference to `clx::LTable::gettable(clx::LValue const&)' /usr/bin/ld: ld-temp.o:(.text._Z9luaopen_tPN3clx6LStateE+0x1bb): undefined reference to `clx::call_function(clx::LState*, clx::LValue const&, clx::LValue const*, unsigned long, char const*, int)' /usr/bin/ld: /tmp/lto-llvm-d854bc.o: in function `main': ld-temp.o:(.text.main+0x5): undefined reference to `clx::open(int, char**)' /usr/bin/ld: ld-temp.o:(.text.main+0x10): undefined reference to `clx::openlibs(clx::LState*)' /usr/bin/ld: ld-temp.o:(.text.main+0x20): undefined reference to `clx::close(clx::LState*)' /usr/bin/ld: ld-temp.o:(.text.main+0x6e): undefined reference to `clx::close(clx::LState*)' /usr/bin/ld: ld-temp.o:(.text.main+0xcc): undefined reference to `clx::close(clx::LState*)' clang++:

error:

linker command failed with exit code 1 (use -v to see invocation)

```

That is because it will build will GCC but compile the Lua program with clang and attempt to link with (GNU) ld.

Forcing it to use clang / lld for everything works.

-- 

Pierre Chapuis

To view this discussion visit https://groups.google.com/d/msgid/lua-l/a53347e9-2426-4f64-9dd9-b09b7d3c5b38n%40googlegroups.com.

[Samir Tine]

Thanks for testing CLX and for your detailed report !

You're absolutely right : CLX currently assumes a consistent toolchain throughout the build process, and the generated code was being linked against a runtime library built with GCC/LTO while the final executable was linked using clang/ld.
I'll investigate improving toolchain detection and handling mixed GCC/Clang environments more gracefully.

Thanks again for tracking this down.

[Sergey Zakharchenko]

Hello,

On Mon, Jun 22, 2026, 12:06 Samir Tine <samir...@luart.org> wrote:

Thanks for testing CLX and for your detailed report !

You're absolutely right :

Could you please comment on the current pace of development, consistency of documentation, relevance of commit messages to the corresponding changes, the tools that you use and the future code maintenance model?

Best regards,

-- 

DoubleF

[Samir Tine]

Thank you for your questions.

CLX is still a very young project, so development is currently moving quite fast, with the main focus on Lua 5.5 compatibility, performance, and testing.

Documentation is already available in the doc/ folder in Markdown format (and on the website too): covering architecture, CLI use, C++ API, modules management...
Documentation is being expanded alongside the implementation and will continue to improve as the project matures.

Some recent commits reflect rapid prototyping, but I intend to improve commit quality and project documentation as development stabilizes.

CLX is currently developed by a single author (me) using modern C++20 & CMake, and the project is fully open source. I hope to attract contributors as the architecture and APIs become more stable.

My immediate goal is to build a robust foundation before expanding the contributor base.

[eugeny gladkih]

> On 22 Jun 2026, at 10:58, Samir Tine <samir...@luart.org> wrote:
>
> That's a fair question.
> The goal is not to intentionally exclude Lua features. In fact, CLX already supports essentially all Lua 5.5 syntax (including global, <const> and <close>) and most of the standard library.
> The main unsupported areas today are features that fundamentally depend on runtime code generation or deep interpreter introspection, such as load(), loadfile(), dofile(), string.dump(), and most of the debug module.

what about meta tables and meta-methods? suddenly, a+b is not the same as b+a is :)

--
Yours sincerely, Eugeny.

[samir...@luart.org]

Metatables and metamethods are supported and are an important part of Lua compatibility.

Optimizations are designed not to change observable Lua behavior.

If you have a specific metamethod edge case in mind, I'd be interested in testing it against CLX :)

[David Sicilia]

Does it attempt to do type inference on code (e.g. function parameters, return values) to increase efficiency of generated code, or does it leave those values as boxed/generic values?

--
You received this message because you are subscribed to the Google Groups "lua-l" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lua-l+un...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/lua-l/ec6008e19c538029c376616ea2724efc%40luart.org.

[samir...@luart.org]

Yes optimizations pass try to deduce types to generate more efficient C++ code. If inference is not possible then it uses boxed values.

You received this message because you are subscribed to a topic in the Google Groups "lua-l" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/lua-l/ingMSR7EZZU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to lua-l+un...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/lua-l/CAGW0ud1B5%3DKB%3DBZG32GapKBsBrth_gf4BZoxxuoMsoQptoCQnQ%40mail.gmail.com.

[Sewbacca]

What kind of optimizations do you have implemented and how do you infer parameter types? Are the resulting C++ signatures directly callable from C++? And is C API interop planned at some point (so one is not excluded from the already existing ecosystem?

A very interesting Project you have here =)

~ Sewbacca

23.06.2026 02:26:07 samir...@luart.org:

[samir...@luart.org]

Thank you for your questions !

Current optimizations include constant folding, constant propagation, dead code elimination, function inlining, native number fastpaths, and tail-call optimizations when applicable. CLX also performs a number of Lua-specific simplifications during code generation.

CLX does not currently perform full static type inference. It relies primarily on compile-time analysis and specialization when types can be determined with sufficient confidence.

Generated functions currently operate on CLX runtime values rather than directly exposing native C++ signatures.

The Lua C API is not supported today. CLX provides its own C++ module API, although some form of compatibility layer may be explored in the future.

--
You received this message because you are subscribed to a topic in the Google Groups "lua-l" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/lua-l/ingMSR7EZZU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to lua-l+un...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/lua-l/21da9b3e-7fe3-475e-92d6-b450904ebe91%40kolabnow.com.

[Viacheslav Usov]

On Sun, Jun 21, 2026 at 5:17 PM <samir...@luart.org> wrote:

> CLX is a new open-source ahead-of-time compiler for Lua 5.5.
> CLX compiles Lua source code to standalone native executables through modern C++20 toolchains (Clang, GCC, and MSVC).

Hi, some questions which I could not find good answers for yet.

1. GC. Is it based on some well known project? If so, could you
reference that? If not, well, where is its code?
2. Native multithreading. The original Lua VM ignores native OS
threads and keeps everything, including GC, in a Lua state. If
somebody wants to run a Lua state on multiple native threads it is
their problem. What about CLX? In particular, is GC shared or also per
state? What does "stop the world" mean then?
3. What is the strategic plan for dynamic Lua code?

Cheers,
V.

[Samir Tine]

Thank you for the questions.

1. The GC is a custom implementation. It's an incremental mark-and-sweep collector designed specifically for CLX's runtime.

2. Garbage collection is per LState, not shared globally. "Stop the world" therefore only applies to the state being collected, not to all application threads. Native threads can/should run independent states concurrently.

3. Regarding dynamic Lua code, CLX currently takes a strict AOT approach. The current focus is on statically compiled Lua applications rather than interpreter/dynamic execution model (maybe in the future ?)

[samir...@luart.org]

Thanks for those questions :

1. The GC is a custom implementation. It's an incremental mark-and-sweep collector designed specifically for CLX runtime.

1. Garbage collection is per LState, not shared globally. "Stop the world" therefore only applies to the state being collected, not to all application threads. Native threads can/should run independent states concurrently.

1. Regarding dynamic Lua code, CLX currently takes a strict AOT approach. The current focus is on statically compiled Lua applications rather than hybrid AOT/interpreted execution model.

[Samir Tine]

Thank you for your questions : 

1. The GC is a custom implementation. It's an incremental mark-and-sweep collector designed specifically for CLX's runtime.

2. Garbage collection is per LState, not shared globally. "Stop the world" therefore only applies to the state being collected, not to all application threads. Native threads can run independent states concurrently. But there is no mechanism implemented for thread safety or for sharing values between LStates.

3. Regarding dynamic Lua code, the current focus is on statically compiled Lua applications rather than hybrid interpreter execution models. Maybe in the future, an embbedded Lua interpreter could be used for this dynamic code (but it seems very complex at first sight, specifically when yielding from/to the interpreter to/from the CLX runtime) 

Le mercredi 24 juin 2026 à 13:57:25 UTC+2, Viacheslav Usov a écrit :

[Sewbacca]

This peaks my interest: How did you implement yielding under the hood? Did you use longjmp or did you employ a different technique? And what does yielding mean for the C++ interface?

~ Sewbacca

[samir...@luart.org]

CLX coroutines are stackful.

Internally they use ucontext (POSIX) or Windows Fibers (Windows), so yielding is implemented as a context switch between execution contexts rather than via longjmp.

This means local state and call frames remain intact across yields.

For native C++ modules, yielding follows the same coroutine semantics as Lua: execution can be suspended and resumed without manually preserving state.

Le 26/06/2026 08:35, 'Sewbacca' via lua-l a écrit :

This peaks my interest: How did you implement yielding under the hood? Did you use longjmp or did you employ a different technique? And what does yielding mean for the C++ interface?

~ Sewbacca

--

You received this message because you are subscribed to the Google Groups "lua-l" group.

To unsubscribe from this group and stop receiving emails from it, send an email to lua-l+un...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/lua-l/1c10d7db-e7bb-4bc0-a39c-f1e83aca1995%40kolabnow.com.

[David Given]

Just so you're aware, eons ago I wrote a program which used ucontext-based coroutines, and it was a total disaster. While it worked on most platforms, there appear to be some (certain Linux architectures, I recall vaguely) where ucontext interacted very badly with pthreads. From what I remember the platform would do something like ALIGNUP(stackpointer, 10MB) to find the TLS data structure for the running thread. As you might image, when switching to a ucontext stack allocated from the heap, Very Bad Things happened. I eventually had to give up and use threads, with a semaphore to ensure that only one thread was executing at a time. (This was actually pretty helpful, as I could have individual threads enter thread-safe sections for doing certain long-running operations while allowing other threads to execute.)

I do note that C++20 now has a feature which it calls coroutines, except they don't actually appear to be coroutines by any normal definition of the word. Coroutines are apparently now called fibres. Sigh. At least there do appear to be a number of supported fibre libraries.

On another note: are you aware of the Luau strong-typing extension to Lua? It was written by Roblox and is pretty good. I recent migrated my word processor WordGrinder to it and found so many bugs. If I could run Luau-annoted Lua though CLX and end up with a native executable, I would be extremely happy.

To view this discussion visit https://groups.google.com/d/msgid/lua-l/9e9ffe99be701b46cc8eca4e861321de%40luart.org.

[Samir Tine]

Thanks for the feedback !

CLX currently uses ucontext on POSIX and Fibers on Windows for coroutines. I've heard similar reports about ucontext portability issues and it's something I'll keep in mind going forward.
For now it seems to work and I need more users feedback on it before changing coroutines implementation.

As for Luau, I agree that static typing can be very useful. However, CLX's goal is to compile standard Lua. Luau (and Nelua too) both introduce syntax that isn't valid Lua, which goes against that goal. I'd rather keep CLX focused on Lua itself and preserve compatibility with existing Lua code.