<img src="doc/luax-banner.svg" style="width:100.0%" />

Lua eXtended

luax is a Lua interpreter and REPL based on Lua 5.5, augmented with some useful packages. luax can also produce executable scripts from Lua scripts.

luax runs on several platforms with no dependency:

• Linux (x86_64, aarch64)
• MacOS (x86_64, aarch64)
• Windows (x86_64, aarch64)

luax can compile scripts from and to any of these platforms. It can produce scripts that can run everywhere Lua or LuaX is installed as well as standalone executables containing the LuaX runtime and the Lua scripts. The target platform can be explicitly specified to cross-compile[^1] scripts for a supported platform.

LuaX is available on Codeberg: https://codeberg.org/cdsoft/luax

[^1]: luax uses zig to link the LuaX runtime with the Lua scripts. The Lua scripts are actually compiled to Lua bytecode. luax produces executables that do not require LuaX to be installed.

Releases

It is strongly recommended to build LuaX from source, as this is the only reliable way to install the exact version you need.

However, if you do require precompiled binaries, this page offers a selection for various platforms: https://cdelord.fr/pub.

Pricing

LuaX is a free and open source software. But it has a cost. It takes time to develop, maintain and support.

To help LuaX remain free, open source and supported, users are cordially invited to contribute financially to its development.

<a href='https://liberapay.com/LuaX/donate' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://liberapay.com/assets/widgets/donate.svg' border='0' alt='Donate using Liberapay' /></a> <a href='https://ko-fi.com/K3K11CD108' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>

Feel free to promote LuaX!

Requirements

• Ninja: to compile LuaX using the LuaX Ninja file
• a decent modern and programmer friendly OS…

The bootstrap script will try to install ninja on some known Linux distributions (Debian, Fedora and Arch Linux) or on MacOS.

Compilation

Quick compilation

The script bootstrap.sh installs ninja, zig (if required) and compiles LuaX. curl, minisign and tar are needed to compile LuaX with zig.

Once done, LuaX can be installed with ninja install. git must be installed to clone the LuaX repository but it can also be compiled from a source archive without git.

The installation path of Zig is defined in the build.lua file. On Linux or MacOS, the installation path is defined by the variable ZIG_PATH (~ is replaced with $HOME). On Windows, the installation path is defined by the variable ZIG_PATH_WIN (~ is replaced with %LOCALAPPDATA%).

$ git clone https://codeberg.org/cdsoft/luax
$ cd luax
$ ./bootstrap.sh
$ ninja install

Or from a source archive (LuaX 8.9.2 or later):

$ curl https://codeberg.org/cdsoft/luax/archive/X.Y.Z.tar.gz -o luax-X.Y.Z.tar.gz
$ tar xzf luax-X.Y.Z.tar.gz
$ cd luax
$ ./bootstrap.sh
$ ninja install

The latest source archives are available at https://codeberg.org/cdsoft/luax/tags.

Contributions on non supported platforms are welcome.

Compilation options

| Option | Description | |:---|:---| | bang -- fast | Optimize for speed | | bang -- small | Optimize for size (default) | | bang -- debug | Debug symbols kept, not optimized | | bang -- san | Compile with ASan and UBSan (implies clang) and enable LUA_USE_APICHECK | | bang -- lax | Disable strict compilation options | | bang -- strip | Remove debug information from precompiled bytecode | | bang -- lto | Enable LTO optimizations | | bang -- nolto | Disable LTO optimizations (default) | | bang -- ssl | Add SSL support to LuaSocket via LuaSec and OpenSSL | | bang -- nossl | No SSL support via LuaSec and OpenSSL (default) | | bang -- cross | Generate cross-compilers (implies compilation with zig) | | bang -- nocross | Do not generate cross-compilers (default) | | bang -- gcc | Compile LuaX with gcc (no cross-compilation) (default) | | bang -- clang | Compile LuaX with clang (no cross-compilation) | | bang -- zig | Compile LuaX with Zig |

bang must be run before ninja to change the compilation options.

lua tools/bang.luax can be used instead of bang if it is not installed.

The default compilation options are small, notlo, nossl, nocross and gcc.

Zig is downloaded by the ninja file or bootstrap.sh. gcc and clang must be already installed.

These options can also be given to the bootstrap script. E.g.: ./bootstrap.sh fast lto strip.

bootstrap.sh also support options to choose a different build directory:

| Option | Description | |:---|:---| | -b dir | Compile LuaX in the directory dir instead of the default one (.build) | | -o dir/file.ninja | Generate the ninja file in dir/file.ninja instead of the default one (build.ninja) |

Optional features

| Option | Description | |:-------|:------------------------------------------------------------------| | ssl | Add the HTTPS/SSL support to LuaSocket (LuaSec + OpenSSL) to LuaX |

OpenSSL is not included in LuaX source. It is downloaded and recompiled when needed. Hence an Internet connection is required to compile LuaX with the ssl option.

Example:

$ git clone https://codeberg.org/cdsoft/luax
$ cd luax
$ ./bootstrap.sh ssl
$ ninja install

These options are disabled by default.

Note that LuaSec can also be installed apart from Luax (e.g. with LuaRocks).

Compilation in debug mode

LuaX can be compiled in debug mode (less optimization, debug symbols kept in the binaries). With the san option, the tests are executed with ASan and UBSan. They run slower but this helps finding tricky bugs.

$ git clone https://codeberg.org/cdsoft/luax
$ cd luax
$ ./bootstrap.sh debug san    # generate build.ninja in debug mode with sanitizers
$ ninja test                  # run tests on the host

Cross-compilation

luax can compile scripts and link them to precompiled libraries for all supported targets.

There are two compilation methods:

• Lua payload (bytecode) appended to a precompiled LuaX loader (default method)
• Lua payload in a C source compiled and linked with LuaX libraries. This method requires a C compiler and is enabled by the -c option.

E.g.: to produce an executable containing the LuaX runtime for the current host and hello.lua:

$ luax compile -t native -o hello hello.lua

It seems on some platforms (e.g. MacOS) reading the payload in the executable file while being executed does not work. In this case, the payload can be added to be binary with the -c option. It requires a C compiler but should work better on MacOS.

$ luax compile -c -t native -o hello hello.lua

E.g.: to produce an executable containing the LuaX runtime for linux-x86_64-musl and hello.lua:

$ luax compile -t linux-x86_64-musl -o hello hello.lua

E.g.: to produce an executable with the compiled Lua bytecode with no debug information:

$ luax compile -s -t linux-x86_64-musl -o hello hello.lua

luax compile can compile Lua scripts to Lua bytecode. If scripts are large they will start quickly but will run as fast as the original Lua scripts.

Installation

$ ninja install                 # install luax to ~/.local/bin and ~/.local/lib
$ PREFIX=/usr ninja install     # install luax to /usr/bin and /usr/lib

luax is a single autonomous executable. It does not need to be installed and can be copied anywhere you want.

LuaX artifacts

ninja install installs:

• $PREFIX/bin/luax: LuaX binary
• $PREFIX/bin/luax.lua: a pure Lua REPL reimplementing some LuaX libraries, usable in any Lua 5.4 or 5.5 interpreter (e.g.: lua, pandoc lua, …)
• $PREFIX/bin/luax-pandoc.lua: LuaX run in a Pandoc Lua interpreter
• $PREFIX/lib/libluax.so: Linux LuaX shared libraries
• $PREFIX/lib/libluax.dylib: MacOS LuaX shared libraries
• $PREFIX/lib/libluax.dll: Windows LuaX shared libraries
• $PREFIX/lib/libluax.lua: a pure Lua reimplementation of some LuaX libraries, usable in any Lua 5.4 or 5.5 interpreter.
• $PREFIX/lib/libluax.lar: a compressed archive containing the precompiled LuaX runtimes for all supported platforms (if the cross-compilation is enabled).

Post installation command

The postinstall command can optionally be executed after LuaX is installed or updated.

It checks that all required files are actually installed and removes obsolete files if any.

$ path/to/luax postinstall [-f]

The -f option forces the removal of obsolete files without confirmation.

Usage

luax is very similar to lua and adds more options to compile scripts:

usage: luax [cmd] [options]

Commands:
  "help"    (or "-h")   Show this help
  "version" (or "-v")   Show LuaX version
  "run"     (or none)   Run scripts
  "compile" (or "c")    Compile scripts
  "env"                 Set LuaX environment variables
  "postinstall"         Post install updates

"run" options:
  -e stat         execute string 'stat'
  -i              enter interactive mode after executing 'script'
  -l name         require library 'name' into global 'name'
  -l g=name       require library 'name' into global 'g'
  -l _=name       require library 'name' (no global variable)
  -v              show version information
  -W              turn warnings on
  --              stop handling options
  -               stop handling options and execute stdin
  script [args]   script to execute

"compil