Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/CDSoft/luax
luax is a Lua interpreter and REPL based on Lua 5.4, augmented with some useful packages. It is also a "compiler" that produces standalone executables from Lua scripts.
https://github.com/CDSoft/luax
c cross-compiler interpreter lua
Last synced: 4 days ago
JSON representation
luax is a Lua interpreter and REPL based on Lua 5.4, augmented with some useful packages. It is also a "compiler" that produces standalone executables from Lua scripts.
- Host: GitHub
- URL: https://github.com/CDSoft/luax
- Owner: CDSoft
- License: gpl-3.0
- Created: 2022-07-31T22:26:40.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-09-18T20:14:06.000Z (about 2 months ago)
- Last Synced: 2024-09-19T01:24:59.204Z (about 2 months ago)
- Topics: c, cross-compiler, interpreter, lua
- Language: C
- Homepage: https://cdelord.fr/luax
- Size: 2.61 MB
- Stars: 159
- Watchers: 4
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Lua eXtended
`luax` is a Lua interpreter and REPL based on Lua 5.4, 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)
`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.
## Getting in touch
- [cdelord.fr/luax](https://cdelord.fr/luax)
- [github.com/CDSoft/luax](https://github.com/CDSoft/luax)
If you like LuaX and are willing to support its development, please
consider donating via [Github](https://github.com/sponsors/CDSoft?o=esc)
or [Liberapay](https://liberapay.com/LuaX/donate).
## Requirements
- [Ninja](https://ninja-build.org): 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` and compiles LuaX.
Once done, LuaX can be installed with `ninja install`. `git` must
already be installed, which is likely to be the case if LuaX has been
cloned with `git`…
``` sh
$ git clone https://github.com/CDSoft/luax
$ cd luax
$ ./bootstrap.sh
$ ninja install
```
Contributions on non supported platforms are welcome.
### Compilation options
| Option | Description |
|:---|:---|
| `bang -- fast` | Optimize for speed |
| `bang -- small` | Optimize for size |
| `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 -- nolto` | Disable LTO optimizations |
| `bang -- zig` | Compile LuaX with Zig |
| `bang -- gcc` | Compile LuaX with gcc |
| `bang -- clang` | Compile LuaX with clang |
`bang` must be run before `ninja` to change the compilation options.
`lua tools/bang.luax` can be used instead of
[bang](https://cdelord.fr/bang) if it is not installed.
The default compilation options are `fast` and `zig`.
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 small strip`.
### 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](https://clang.llvm.org/docs/AddressSanitizer.html) and
[UBSan](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html).
They run slower but this helps finding tricky bugs.
``` sh
$ git clone https://github.com/CDSoft/luax
$ cd luax
$ tools/bang.lua -- debug san # generate build.ninja in debug mode with sanitizers
$ ninja # compile LuaX
$ ninja test # run tests on the host
```
## Cross-compilation
`luax` can compile scripts and link them to precompiled libraries for
all supported targets.
E.g.: to produce an executable containing the LuaX runtime for the
current host and `hello.lua`:
``` sh
$ luax compile -t native -o hello hello.lua
```
E.g.: to produce an executable containing the LuaX runtime for
`linux-x86_64-musl` and `hello.lua`:
``` sh
$ 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:
``` sh
$ 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.
## Precompiled LuaX binaries
In case precompiled binaries are needed (GNU/Linux, MacOS, Windows),
some can be found at [cdelord.fr/pub](http://cdelord.fr/pub). 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
``` sh
$ 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 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/luax.lua`: a pure Lua reimplementation of some LuaX
libraries, usable in any Lua 5.4 interpreter.
- `$PREFIX/lib/luax.lar`: a compressed archive containing the
precompiled LuaX runtimes for all supported platforms
## 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
"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
-- stop handling options
- stop handling options and execute stdin
script [args] script to execute
"compile" options:
-t target name of the targetted platform
-t list list available targets
-o file name the executable file to create
-b compile to Lua bytecode
-s emit bytecode without debug information
-k key script encryption key
-q quiet compilation (error messages only)
scripts scripts to compile
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 is `require`’d before the main script is run
and stored in a global variable
- `--@LOAD=`: as `--@LOAD` but the module is
stored in a global variable with the given name
- `--@LIB`: library that must be explicitly `require`’d by the main
script
- `--@LIB=`: library that is `require`’d with
`` 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 is the file name.
**Note for Windows users**: since Windows does not support shebangs, a
script `script` shall be explicitly launched with `luax` (e.g.:
`luax script`). If `script` is not found, it is searched in the
installation directory of `luax` or in `$PATH`.
### Examples
``` bash
# Compilation (standalone executable script for LuaX)
$ luax compile -o executable main.lua lib1.lua lib2.lua
$ ./executable # equivalent to luax main.lua
# Compilation for Lua
$ luax compile -o executable -t lua main.lua lib1.lua lib2.lua
$ ./executable # equivalent to lua main.lua
# Compilation for Pandoc Lua
$ luax compile -o executable -t pandoc main.lua lib1.lua lib2.lua
$ ./executable # equivalent to pandoc lua main.lua
# Available targets
$ luax compile -t list
Target Interpeter / LuaX archive
--------------------- -------------------------
luax /path/to/luax
lua /path/to/lua
pandoc /path/to/pandoc
native /path/to/luax.lar
linux-x86_64 /path/to/luax.lar
linux-x86_64-musl /path/to/luax.lar
linux-aarch64 /path/to/luax.lar
linux-aarch64-musl /path/to/luax.lar
macos-x86_64 /path/to/luax.lar
macos-aarch64 /path/to/luax.lar
windows-x86_64 /path/to/luax.lar
```
## Built-in modules
The `luax` runtime comes with a few builtin modules.
Some modules are heavily inspired by [BonaLuna](http://cdelord.fr/bl)
and [lapp](http://cdelord.fr/lapp).
- [LuaX interactive usage](doc/repl.md): improved Lua REPL
- [package](doc/package.md): modified Lua package `package`
- [debug](doc/debug.md): modified Lua package `debug`
- [import](doc/import.md): import Lua scripts to user table instead of
`_G`
- [F](doc/F.md): functional programming inspired functions
- [fs](doc/fs.md): file system management
- [sh](doc/sh.md): shell command execution
- [mathx](doc/mathx.md): complete math library for Lua
- [imath](doc/imath.md): arbitrary precision integer and rational
arithmetic library
- [qmath](doc/qmath.md): rational number library
- [complex](doc/complex.md): math library for complex numbers based on
C99
- [ps](doc/ps.md): Process management module
- [sys](doc/sys.md): System module
- [term](doc/term.md): Terminal manipulation module
- [crypt](doc/crypt.md): cryptography module
- [lz4](doc/lz4.md): Extremely Fast Compression algorithm
- [lzip](doc/lzip.md): A compression library for the lzip format
- [lpeg](doc/lpeg.md): Parsing Expression Grammars For Lua
- [luasocket](doc/luasocket.md): Network support for the Lua language
- [argparse](doc/argparse.md): Feature-rich command line parser for Lua
- [serpent](doc/serpent.md): Lua serializer and pretty printer
- [cbor](doc/cbor.md): pure Lua implementation of the CBOR
- [lar](doc/lar.md): Simple archive format for Lua values
- [linenoise](doc/linenoise.md): A small, portable GNU readline
replacement with UTF-8 support
- [json](doc/json.md): JSON Module for Lua
## 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 libluax
Lua 5.4.7 Copyright (C) 1994-2024 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:
- [luax.lua](doc/luax.lua.md): LuaX modules reimplemented in pure Lua
(except LuaSocket and lpeg)
## 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 .
For further information about luax you can visit
http://cdelord.fr/luax
`luax` uses other third party softwares:
- **[Zig](https://ziglang.org/)**: General-purpose programming language
and toolchain for maintaining robust, optimal, and reusable software.
([MIT license](https://github.com/ziglang/zig/blob/master/LICENSE))
- **[Lua 5.4](http://www.lua.org)**: Copyright (C) 1994-2023 Lua.org,
PUC-Rio ([MIT license](http://www.lua.org/license.html))
- **[Lpeg](http://www.inf.puc-rio.br/~roberto/lpeg/)**: Parsing
Expression Grammars For Lua ([MIT
license](http://www.lua.org/license.html))
- **[luasocket](https://github.com/diegonehab/luasocket)**: Network
support for the Lua language ([LuaSocket 3.0
license](https://github.com/diegonehab/luasocket/blob/master/LICENSE))
- **[serpent](https://github.com/pkulchenko/serpent)**: Lua serializer
and pretty printer. ([MIT
license](https://github.com/pkulchenko/serpent/blob/master/LICENSE))
- **[LZ4](https://github.com/lz4/lz4)**: Extremely Fast Compression
algorithm ([License](https://github.com/lz4/lz4/blob/dev/lib/LICENSE))
- **[lzip](https://www.nongnu.org/lzip/)**: A compression library for
the lzip format ([License](http://www.gnu.org/licenses/gpl-2.0.html))
- **[Argparse](https://github.com/mpeterv/argparse)**: a feature-rich
command line parser for Lua ([MIT
license](https://github.com/mpeterv/argparse/blob/master/LICENSE))
- **[Linenoise](https://github.com/yhirose/linenoise/tree/utf8-support)**:
A minimal, zero-config, BSD licensed, readline replacement ([BSD
license](https://github.com/antirez/linenoise/blob/master/LICENSE))
- **[dkjson.lua](http://dkolf.de/dkjson-lua/)**: JSON Module for Lua
([MIT license](http://www.lua.org/license.html))
- **[CBOR](https://www.zash.se/lua-cbor.html)**: pure Lua implementation
of the CBOR
([License](https://code.zash.se/lua-cbor/file/tip/COPYING))
[^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.