👨‍💻 about me home CV/Resume News 🖊️ Contact Github LinkedIn I’m a Haskeller 🏆 Best of LuaX hey bang ypp panda lsvg Fizzbuzz Calculadoira TPG todo pwd rrpi

Lua eXtended

Lua eXtended

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

luax runs on several platforms with no dependency:

luax can « cross-compile1 » scripts from and to any of these platforms.

Getting in touch

Requirements

Compilation

luax is written in C and Lua. The build system uses Ninja and Zig (automatically downloaded by the Ninja file).

Just download luax (https://github.com/CDSoft/luax) and run ninja:

$ git clone https://github.com/CDSoft/luax
$ cd luax
$ ninja             # compile LuaX (all targets)
$ ninja test        # run tests on the host
$ ninja doc         # generate LuaX documentation

Note: ninja will download a Zig compiler.

Compilation options

Option Description
bang -- fast [upx] Optimized for speed, optionally compressed with UPX
bang -- small [upx] Optimized for size, optionally compressed with UPX
bang -- quick Faster compilation, not optimized
bang -- debug Debug symbols kept, tests with valgrind
bang -- zig Compile LuaX with Zig, for all supported targets (default)
bang -- gcc Compile LuaX with gcc (implies “host”)
bang -- clang Compile LuaX with clang (implies “host”)
bang -- host Compile LuaX for the current host only
bang -- upx Compress LuaX with UPX

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

The default compilation options are fast, zig, for all targets, with no compression.

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

Compilation in debug mode

LuaX can be compiled in debug mode (less optimization, debug symbols kept in the binaries). In this mode, the tests are executed with valgrind. They run much slower but this helps finding tricky bugs. Bang must be installed first to generate build.ninja:

$ git clone https://github.com/CDSoft/bang
$ ninja -C bang install
$ git clone https://github.com/CDSoft/luax
$ cd luax
$ bang -- debug     # generate build.ninja in debug mode
$ ninja             # compile LuaX (all targets)
$ ninja test        # run tests on the host

Precompiled LuaX binaries

In case precompiled binaries are needed (GNU/Linux, MacOS, Windows), some can be found at cdelord.fr/hey. These archives contain LuaX as well as some other softwares more or less related to LuaX.

Warning: There are Linux binaries linked with musl and glibc. The musl binaries are platform independent but can not load shared libraries. The glibc binaries can load shared libraries but may depend on some specific glibc versions on the host.

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:

Usage

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

usage: luax [options] [script [args]]

General options:
  -h                show this help
  -v                show version information
  --                stop handling options

Lua 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)
  -                 stop handling options and execute stdin
                    (incompatible with -i)

Compilation options:
  -t target         name of the targetted platform
  -t all            compile for all available LuaX targets
  -t list           list available targets
  -t list-luax      list available native LuaX targets
  -t list-lua       list available Lua/Pandoc targets
  -o file           name the executable file to create
  -q                quiet compilation (error messages only)

Scripts for compilation:
  file.lua          name of a Lua package to add to the binary.
  file.xxx          file embeded as a module
                    returning the content of the file.

Lua and Compilation options can not be mixed.

Environment variables:

  LUA_INIT_5_4, LUA_INIT
                    code executed before handling command line
                    options and scripts (not in compilation
                    mode). When LUA_INIT_5_4 is defined,
                    LUA_INIT is ignored.

  PATH              PATH shall contain the bin directory where
                    LuaX is installed

  LUA_PATH          LUA_PATH shall point to the lib directory
                    where the Lua implementation of LuaX
                    lbraries are installed

  LUA_CPATH         LUA_CPATH shall point to the lib directory
                    where LuaX shared libraries are installed

PATH, LUA_PATH and LUA_CPATH can be set in .bashrc or .zshrc
with « luax env ».
E.g.: eval $(luax env)

When compiling scripts (options -t and -o), the scripts shall contain tags (e.g. in comments) showing how the script is used by LuaX:

Scripts without tags are classified using a simplistic heuristic:

This heuristic should work for most of the Lua scripts but explicit tags are recommended.

LuaX can also embed files that are not Lua scripts. These files are embedded as Lua modules that return the file content as a string. In this case, the module name if the file name.

Examples

# Native compilation (luax is a symlink to the luax binary of the host)
$ luax -o executable main.lua lib1.lua lib2.lua
$ ./executable      # equivalent to luax main.lua

# « Cross compilation » to MacOS x86_64
$ luax -o executable -t x86_64-macos-none main.lua lib1.lua lib2.lua

# Available targets
$ luax -t list
Targets producing standalone LuaX executables:

    x86_64-linux-musl
    x86_64-linux-gnu
    aarch64-linux-musl
    aarch64-linux-gnu
    x86_64-windows-gnu
    x86_64-macos-none
    aarch64-macos-none

Targets based on an external Lua interpreter:

    lua
    lua-luax
    luax
    pandoc
    pandoc-luax

Built-in modules

The luax runtime comes with a few builtin modules.

Some modules are heavily inspired by BonaLuna and lapp.

Shared libraries

LuaX is also available as a shared library. This shared library is a Lua module that can be loaded with require. It provides the same modules than the LuaX executable and can be used by a regular Lua interpreter (e.g.: lua, pandoc, …).

E.g.:

$ lua -l luax-x86_64-linux-gnu
Lua 5.4.6  Copyright (C) 1994-2023 Lua.org, PUC-Rio
> F = require "F"
> F.range(100):sum()
5050
> F.show({x=1, y=2})
{x=1, y=2}
> F.show({x=1, y=2}, {indent=4})
{
    x = 1,
    y = 2,
}

Pure Lua modules

LuaX modules also provide pure Lua implementations (no LuaX dependency). The script lib/luax.lua can be reused in pure Lua programs:

License

luax is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

luax is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with luax.  If not, see <https://www.gnu.org/licenses/>.

For further information about luax you can visit
http://cdelord.fr/luax

luax uses other third party softwares:

This site is powered by LuaX, bang, ypp and Pandoc.