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:
- Linux (x86_64, x86, aarch64)
- MacOS (x86_64, aarch64)
- Windows (x86_64, x86)
luax
can « cross-compile1 » scripts from and to any of these
platforms.
- Ninja: needed to compile LuaX using the LuaX Ninja file
- Bang: optional, only needed to update the Ninja file
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.
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.
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
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.
$ 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.
ninja install
installs:
$PREFIX/bin/luax
: symbolic link to the LuaX binary for the host$PREFIX/bin/luax-<ARCH>-<OS>-<LIBC>
: LuaX binary for a specific platform$PREFIX/bin/luax-pandoc
: LuaX run in a Pandoc Lua interpreter$PREFIX/bin/luax-lua
: a pure Lua REPL reimplementing some LuaX libraries, usable in any Lua 5.4 interpreter (e.g.: lua, pandoc lua, …)$PREFIX/lib/libluax-<ARCH>-<OS>-<LIBC>.so
: Linux LuaX shared libraries$PREFIX/lib/libluax-<ARCH>-<OS>-<LIBC>.dylib
: MacOS LuaX shared libraries$PREFIX/lib/libluax-<ARCH>-<OS>-<LIBC>.dll
: Windows LuaX shared libraries$PREFIX/lib/luax.lua
: a pure Lua reimplementation of some LuaX libraries, usable in any Lua 5.4 interpreter.
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)
« luax env » can also generate shell variables from a script.
E.g.: eval $(luax env script.lua)
When compiling scripts (options -t
and -o
), the scripts shall
contain tags (e.g. in comments) showing how the script is used by LuaX:
--@MAIN
: main script (must be unique)--@LOAD
: library that isrequire
’d before the main script is run and stored in a global variable--@LOAD=<global variable name>
: as--@LOAD
but the module is stored in a global variable with the given name--@LIB
: library that must be explicitlyrequire
’d by the main script--@LIB=<new module name>
: library that isrequire
’d with<new module name>
instead of the source filename.
Scripts without tags are classified using a simplistic heuristic:
- if the last non empty line starts with
return
then it is a library (as if it contained a@LIB
tag) - otherwise it is the main script (as if it contained the
@MAIN
tag).
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.
# 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
The luax
runtime comes with a few builtin modules.
Some modules are heavily inspired by BonaLuna and lapp.
- LuaX interactive usage: improved Lua REPL
- package: modified Lua package
package
- import: import Lua scripts to user table instead of
_G
- F: functional programming inspired functions
- L:
pandoc.List
module from the Pandoc Lua interpreter - fs: file system management
- sh: shell command execution
- mathx: complete math library for Lua
- imath: arbitrary precision integer and rational arithmetic library
- qmath: rational number library
- complex: math library for complex numbers based on C99
- ps: Process management module
- sys: System module
- term: Terminal manipulation module
- crypt: cryptography module
- lz4: Extremely Fast Compression algorithm
- lpeg: Parsing Expression Grammars For Lua
- luasocket: Network support for the Lua language
- argparse: Feature-rich command line parser for Lua
- inspect: Human-readable representation of Lua tables
- serpent: Lua serializer and pretty printer
- cbor: pure Lua implementation of the CBOR
- linenoise: A small, portable GNU readline replacement with UTF-8 support
- json: A lightweight JSON library for Lua
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,
}
LuaX modules also provide pure Lua implementations (no LuaX dependency).
The script lib/luax.lua
can be reused in pure Lua programs:
- luax.lua: LuaX modules reimplemented in pure Lua (except LuaSocket and lpeg)
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:
- Zig: General-purpose programming language and toolchain for maintaining robust, optimal, and reusable software. (MIT license)
- Lua 5.4: Copyright (C) 1994-2023 Lua.org, PUC-Rio (MIT license)
- Lpeg: Parsing Expression Grammars For Lua (MIT license)
- luasocket: Network support for the Lua language (LuaSocket 3.0 license)
- inspect: Human-readable representation of Lua tables (MIT license)
- serpent: Lua serializer and pretty printer. (MIT license)
- LZ4: Extremely Fast Compression algorithm (License)
- Argparse: a feature-rich command line parser for Lua (MIT license)
- Linenoise: A minimal, zero-config, BSD licensed, readline replacement (BSD license)
- json.lua: A lightweight JSON library for Lua (MIT license)
Footnotes
-
luax
is actually not a « cross compiler ».It just bundles Lua scripts with a precompiled LuaX runtime that can be run on the target with no dependency. ↩