[ANN] clx 0.3.0 released

[Samir Tine]

Hi,

clx is an open-source ahead-of-time (AOT) compiler that turns Lua programs into standalone native executables. Version 0.3.0 has now been released, with support for Linux, Windows, and macOS.

The main new feature is an optional embedded Lua 5.5 VM with a native bridge, enabling dynamic code execution through load(), loadfile(), and dofile() while seamlessly interacting with AOT-compiled code.

The VM is only included when requested with the --dynamic flag, so applications that don't need dynamic loading retain a minimal executable size and runtime footprint.

Compatibility has also improved significantly, with popular Lua libraries such as dkjson, serpent, middleclass, and lume now compiling and running out of the box.

This release also brings numerous optimizations, including native int64 code generation, escape-analysis-driven arena allocation, per-table inline caches, SIMD optimizations, faster coroutine switching, improved Lua 5.5 compatibility, and various runtime improvements. clx now matches or outperforms LuaJIT on several benchmark workloads.

https://samyeyo.github.io/clx

Regards,

Samir Tine

[Berwyn Hoyt]

Very impressive work.

--
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/aa3dce3a-7c11-401c-95d0-611a8385552en%40googlegroups.com.

[Martin Eden]

So what your program does?

Combines user's code and Lua interpreter into one executable file?

-- Martin

[Samir Tine]

Hi Martin,

Not exactly.
Clx compiles Lua source code to native code (via C++) and produces a standalone executable without the Lua VM: the generated program executes true native (and fast) compiled code, similarly to C, C++ or Rust.

The Lua VM is only optionally embedded when dynamic code execution (load(), loadfile(), dofile()) is required.

Samir

[Martin Eden]

Hi Samir,

On 2026-08-23 20:02, Samir Tine wrote:
> Clx compiles Lua source code to native code

Sorry I don't understand what "native code" means.

Let's consider this Lua code:

  return
    function(f, g)
      return f(g()) or g(f())
    end

To what it is compiled? There must be some sort of intermediate
representation.

-- Martin

[samir...@luart.org]

In this case, the Lua function is translated into a C++ lambda, which is then compiled by Clang/GCC/MSVC into machine code.

For example, the Lua f(g()) / g(f()) calls become clx::call_direct() calls. Arguments are passed through LValue arrays (args[]), while multiple return values are represented by clx::MultiValue.

So the pipeline is essentially:

Lua source → generated C++ → C++ compiler → machine code

This is essentially the same model used by other compiled languages: the source is transformed into an intermediate representation (here C++ code) and ultimately compiled to native machine code.

The result is a true standalone native and fast executable, without requiring lua55.dll, liblua5.5.so, or any embedded Lua 5.5 VM.

Samir

[Sean Conner]

It was thus said that the Great 'Martin Eden' via lua-l once stated:

If your computer is running with an Intel CPU, "native code" would be x86
machine code; if the computer is running on an ARM CPU, it would be ARM
machine code.

-spc

[Martin Eden]

On 2026-08-23 21:40, samir...@luart.org wrote:
>
> So the pipeline is essentially:
>
> Lua source → generated C++ → C++ compiler → machine code
>

Thanks for explanation.

So it's Lua to C++ source code transpiler.

Is that transpiling part your code or you're using existing module?

-- Martin

[samir...@luart.org]

Yes, the Lua-to-C++ transpiler is entirely part of clx itself; it has its own parser, optimizer and code generator.

Many projects use bytecode IR (LLVM, MIR,...). I used a similar approach in an earlier project, but the resulting dependencies were too large for my goal of producing very small executables.

So I chose C++ as the IR and let Clang/GCC/MSVC handle the final native compilation.

Samir

[Martin Eden]

On 2026-08-23 21:57, samir...@luart.org wrote:
>
> Yes, the Lua-to-C++ transpiler is entirely part of clx itself; it has
> its own parser, optimizer and code generator.
>
> Many projects use bytecode IR (LLVM, MIR,...). I used a similar
> approach in an earlier project, but the resulting dependencies were
> too large for my goal of producing very small executables.
>
> So I chose C++ as the IR and let Clang/GCC/MSVC handle the final
> native compilation.
>
> Samir
>

Now it's clear. Interesting project.

Btw is transpiler isolated step in pipeline?

F.e. is there command-line tool like "lua_to_cpp" to produce C++ source
code?

-- Martin

[Родион Горковенко]

Samir, Hi!

May I ask about your perceived "strategic goal"? I.e. do you aim to create replacement for LuaJIT (given that it drags behind the language standard) or is it for now just a project mainly driven by developer's curiosity?

As I understand CLX doesn't provide JIT behavior, so if some code is loaded and executed dynamically its performance should be that of typical "interpreted" code, not matched to native / JIT execution?

thanks in advance,

sincerely yours,

Rodion

--

[samir...@luart.org]

There is only the compiled executable, called clx.

You can see the emitted cpp file using the --cpp flag.

[Martin Eden]

On 2026-08-23 22:45, samir...@luart.org wrote:
>
> There is only the compiled executable, called clx.
>
> You can see the emitted cpp file using the --cpp flag.
>

Nice. Thanks for explanations! I'll try it.

-- Martin

[samir...@luart.org]

Hi Rodion,

Thanks for the question.

The goal of clx is mainly to provide a modern  compilation path for Lua 5.5, producing small standalone native executables. I wouldn't consider it a direct replacement for LuaJIT, since the target (Lua 5.1) and approaches are quite different (LuaJIT still uses an interpreter and dépends on lua51 Dynamic library).

And yes, you're correct: when using dynamically loaded code, it runs through the optional embedded Lua 5.5 VM, so its performance is that of the interpreter (minus the bridge overhead). The main application code remains compiled native code and interfaces with dynamic code seamlessly.

Regards,

Samir

To view this discussion visit https://groups.google.com/d/msgid/lua-l/CAL2n1txE45GT9UNKBAZ3ZGuveFMgdA9OejnHH3Y19M8tBuqibQ%40mail.gmail.com.

[Martin Eden]

On 2026-08-23 22:48, 'Martin Eden' via lua-l wrote:
> I'll try it.

I've cloned repo and build script produced 500 KB executable (I'm on
Linux Mint).

Trying to run it produces error:

  $ ./clx test.lua
  Illegal instruction (core dumped)

But at least it can print help:

  $ ./clx
  Usage: clx [options] <file.lua> [<compiler-options>]

  clx Compiler Options:
    -o, --output <name>   Specify output file name
    --executable          Build executable (default)
    --object              Compile to object file (.o/.obj)
    --static              Compile to static library (.a/.lib)
    --debug               Enable debug symbols
    --size                Optimize for size (default)
    --fast                Optimize for speed
    --cpp                 Generate C++ source file and exit
    --minimal             Exclude non-essential Lua modules; keeps base
+ package
    --dynamic             Link the embedded Lua 5.5 VM
(load/loadfile/dofile)
    --version             Print version and exit
    --help                Display this help message

  Compiler Options:
    Any options starting with '-' not recognized by clx are passed to
the C++ compiler.
    If no compiler options are provided, default optimization flags are
used.
    Example: clx file.lua -O3 -march=native

-- Martin

[samir...@luart.org]

Hi Martin,

Thanks for trying clx, and I'm sorry you've run into this issue.

To avoid cluttering the mailing list, could you please open an issue on GitHub and include your CPU model (or the output of lscpu) along with any other details about your system?

I'll investigate it there.

Samir

[Sérgio Medeiros]

Nice work, Samir. Congratulations.

At https://samyeyo.github.io/clx/ the result of benchmark arraysum for
clx is 0.07s, but it seems it should be 0.70s (as at
https://github.com/samyeyo/clx/blob/main/doc/benchmarks.md).

By the way, I'm reporting this typo here because I could not see how
to create a new documentation issue in the repository (only other
kinds of issues were available).

best,
Sérgio

> --
> 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/5e786e5377e0ddf72fedd2a7c0d5d417%40luart.org.



--
Sérgio

[samir...@luart.org]

Thank you Sergio !

I will fix the benchmark typo and create a new issue template for documentation errors.

Samir