{"id":13537152,"url":"https://github.com/CDSoft/luax","last_synced_at":"2025-04-02T04:30:23.315Z","repository":{"id":51187737,"uuid":"519900143","full_name":"CDSoft/luax","owner":"CDSoft","description":"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.","archived":false,"fork":false,"pushed_at":"2025-03-31T20:06:34.000Z","size":3431,"stargazers_count":183,"open_issues_count":2,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T21:23:19.886Z","etag":null,"topics":["c","cross-compiler","interpreter","lua"],"latest_commit_sha":null,"homepage":"https://cdelord.fr/luax","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CDSoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"CDSoft"}},"created_at":"2022-07-31T22:26:40.000Z","updated_at":"2025-03-23T16:30:50.000Z","dependencies_parsed_at":"2023-02-14T01:31:23.251Z","dependency_job_id":"b999e807-5424-40fd-b85d-7bbec6192e23","html_url":"https://github.com/CDSoft/luax","commit_stats":null,"previous_names":[],"tags_count":343,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fluax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fluax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fluax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CDSoft%2Fluax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CDSoft","download_url":"https://codeload.github.com/CDSoft/luax/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246756718,"owners_count":20828751,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cross-compiler","interpreter","lua"],"created_at":"2024-08-01T09:00:55.694Z","updated_at":"2025-04-02T04:30:23.308Z","avatar_url":"https://github.com/CDSoft.png","language":"C","readme":"\u003cimg src=\"doc/luax-banner.svg\" style=\"width:100.0%\" /\u003e\n\n# Lua eXtended\n\n`luax` is a Lua interpreter and REPL based on Lua 5.4, augmented with\nsome useful packages. `luax` can also produce executable scripts from\nLua scripts.\n\n`luax` runs on several platforms with no dependency:\n\n- Linux (x86_64, aarch64)\n- MacOS (x86_64, aarch64)\n- Windows (x86_64, aarch64)\n\n`luax` can compile scripts from and to any of these platforms. It can\nproduce scripts that can run everywhere Lua or LuaX is installed as well\nas standalone executables containing the LuaX runtime and the Lua\nscripts. The target platform can be explicitly specified to\ncross-compile[^1] scripts for a supported platform.\n\nLuaX is available on GitHub: \u003chttps://github.com/CDSoft/luax\u003e\n\n## Pricing\n\nLuaX is a free and open source software. But it has a cost. It takes\ntime to develop, maintain and support.\n\nTo help LuaX remain free, open source and supported, users are cordially\ninvited to contribute financially to its development.\n\n| LuaX price         | Europe        | United States | Rest of the World |\n|--------------------|---------------|---------------|-------------------|\n| Personal usage     | Free donation | Free donation | Free donation     |\n| Academic usage     | €10 or more   | \\$20 or more  | \\$15 or more      |\n| Professional usage | €20 or more   | \\$40 or more  | \\$25 or more      |\n\nThese prices are per month and per tools (see [`PRICING`](PRICING)).\n\n\u003ca href='https://liberapay.com/LuaX/donate' target='_blank'\u003e\u003cimg height='36' style='border:0px;height:36px;' src='https://liberapay.com/assets/widgets/donate.svg' border='0' alt='Donate using Liberapay' /\u003e\u003c/a\u003e\n\u003ca href='https://ko-fi.com/K3K11CD108' target='_blank'\u003e\u003cimg 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' /\u003e\u003c/a\u003e\n\u003ca href='https://github.com/sponsors/CDSoft' target='_blank'\u003e\u003cimg height='36' style='border:0px;height:36px;' src='https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86' border='0' alt='Donate using Github' /\u003e\u003c/a\u003e\n\nFeel free to promote LuaX!\n\n## Requirements\n\n- [Ninja](https://ninja-build.org): to compile LuaX using the LuaX Ninja\n  file\n- a decent modern and programmer friendly OS…\n\nThe bootstrap script will try to install `ninja` on some known Linux\ndistributions (Debian, Fedora and Arch Linux) or on MacOS.\n\n## Compilation\n\n### Quick compilation\n\nThe script `bootstrap.sh` installs `ninja`, `zig` (if required) and\ncompiles LuaX. Once done, LuaX can be installed with `ninja install`.\n`git` must already be installed, which is likely to be the case if LuaX\nhas been cloned with `git`…\n\nThe installation path of Zig is defined in the `build.lua` file. On\nLinux or MacOS, the installation path is defined by the variable\n`ZIG_PATH` (`~` is replaced with `$HOME`). On Windows, the installation\npath is defined by the variable `ZIG_PATH_WIN` (`~` is replaced with\n`%LOCALAPPDATA%`).\n\n``` sh\n$ git clone https://github.com/CDSoft/luax\n$ cd luax\n$ ./bootstrap.sh\n$ ninja install\n```\n\nContributions on non supported platforms are welcome.\n\n### Compilation options\n\n| Option | Description |\n|:---|:---|\n| `bang -- fast` | Optimize for speed |\n| `bang -- small` | Optimize for size (default) |\n| `bang -- debug` | Debug symbols kept, not optimized |\n| `bang -- san` | Compile with ASan and UBSan (implies clang) and enable `LUA_USE_APICHECK` |\n| `bang -- lax` | Disable strict compilation options |\n| `bang -- strip` | Remove debug information from precompiled bytecode |\n| `bang -- lto` | Enable LTO optimizations |\n| `bang -- nolto` | Disable LTO optimizations (default) |\n| `bang -- lz4` | Add LZ4 support |\n| `bang -- nolz4` | No LZ4 support (default) |\n| `bang -- socket` | Add socket support via luasocket |\n| `bang -- nosocket` | No socket support via luasocket (default) |\n| `bang -- ssl` | Add SSL support via LuaSec and OpenSSL |\n| `bang -- nossl` | No SSL support via LuaSec and OpenSSL (default) |\n| `bang -- cross` | Generate cross-compilers (implies compilation with zig) |\n| `bang -- nocross` | Do not generate cross-compilers (default) |\n| `bang -- gcc` | Compile LuaX with gcc (no cross-compilation) (default) |\n| `bang -- clang` | Compile LuaX with clang (no cross-compilation) |\n| `bang -- zig` | Compile LuaX with Zig |\n\n`bang` must be run before `ninja` to change the compilation options.\n\n`lua tools/bang.luax` can be used instead of\n[bang](https://github.com/cdsoft/bang) if it is not installed.\n\nThe default compilation options are `small`, `notlo`, `nossl`, `nocross`\nand `gcc`.\n\nZig is downloaded by the ninja file or `bootstrap.sh`. gcc and clang\nmust be already installed.\n\nThese options can also be given to the bootstrap script. E.g.:\n`./bootstrap.sh fast lto strip`.\n\n`bootstrap.sh` also support options to choose a different build\ndirectory:\n\n| Option | Description |\n|:---|:---|\n| `-b dir` | Compile LuaX in the directory `dir` instead of the default one (`.build`) |\n| `-o dir/file.ninja` | Generate the ninja file in `dir/file.ninja` instead of the default one (`build.ninja`) |\n\n### Optional features\n\n| Option | Description |\n|:---|:---|\n| `lz4` | Add the LZ4 compression module to LuaX |\n| `socket` | Add the socket support (LuaSocket) to LuaX |\n| `ssl` | Add the HTTPS/SSL support (LuaSec + OpenSSL) to LuaX (`ssl` implies `socket`) |\n\nExample:\n\n``` sh\n$ git clone https://github.com/CDSoft/luax\n$ cd luax\n$ ./bootstrap.sh lz4 ssl\n$ ninja install\n```\n\nThese options are disabled by default.\n\nNote that LuaSocket and LuaSec can also be installed apart from Luax\n(e.g. with LuaRocks).\n\n### Compilation in debug mode\n\nLuaX can be compiled in debug mode (less optimization, debug symbols\nkept in the binaries). With the `san` option, the tests are executed\nwith [ASan](https://clang.llvm.org/docs/AddressSanitizer.html) and\n[UBSan](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html).\nThey run slower but this helps finding tricky bugs.\n\n``` sh\n$ git clone https://github.com/CDSoft/luax\n$ cd luax\n$ tools/bang.lua -- debug san # generate build.ninja in debug mode with sanitizers\n$ ninja                       # compile LuaX\n$ ninja test                  # run tests on the host\n```\n\n## Cross-compilation\n\n`luax` can compile scripts and link them to precompiled libraries for\nall supported targets.\n\nE.g.: to produce an executable containing the LuaX runtime for the\ncurrent host and `hello.lua`:\n\n``` sh\n$ luax compile -t native -o hello hello.lua\n```\n\nE.g.: to produce an executable containing the LuaX runtime for\n`linux-x86_64-musl` and `hello.lua`:\n\n``` sh\n$ luax compile -t linux-x86_64-musl -o hello hello.lua\n```\n\nE.g.: to produce an executable with the compiled Lua bytecode with no\ndebug information:\n\n``` sh\n$ luax compile -s -t linux-x86_64-musl -o hello hello.lua\n```\n\n`luax compile` can compile Lua scripts to Lua bytecode. If scripts are\nlarge they will start quickly but will run as fast as the original Lua\nscripts.\n\n## Installation\n\n``` sh\n$ ninja install                 # install luax to ~/.local/bin and ~/.local/lib\n$ PREFIX=/usr ninja install     # install luax to /usr/bin and /usr/lib\n```\n\n`luax` is a single autonomous executable. It does not need to be\ninstalled and can be copied anywhere you want.\n\n### LuaX artifacts\n\n`ninja install` installs:\n\n- `$PREFIX/bin/luax`: LuaX binary\n- `$PREFIX/bin/luax.lua`: a pure Lua REPL reimplementing some LuaX\n  libraries, usable in any Lua 5.4 interpreter (e.g.: lua, pandoc lua,\n  …)\n- `$PREFIX/bin/luax-pandoc.lua`: LuaX run in a Pandoc Lua interpreter\n- `$PREFIX/lib/libluax.so`: Linux LuaX shared libraries\n- `$PREFIX/lib/libluax.dylib`: MacOS LuaX shared libraries\n- `$PREFIX/lib/libluax.dll`: Windows LuaX shared libraries\n- `$PREFIX/lib/luax.lua`: a pure Lua reimplementation of some LuaX\n  libraries, usable in any Lua 5.4 interpreter.\n- `$PREFIX/lib/luax.lar`: a compressed archive containing the\n  precompiled LuaX runtimes for all supported platforms (if the\n  cross-compilation is enabled).\n\n## Usage\n\n`luax` is very similar to `lua` and adds more options to compile\nscripts:\n\n    usage: luax [cmd] [options]\n\n    Commands:\n      \"help\"    (or \"-h\")   Show this help\n      \"version\" (or \"-v\")   Show LuaX version\n      \"run\"     (or none)   Run scripts\n      \"compile\" (or \"c\")    Compile scripts\n      \"env\"                 Set LuaX environment variables\n\n    \"run\" options:\n      -e stat         execute string 'stat'\n      -i              enter interactive mode after executing 'script'\n      -l name         require library 'name' into global 'name'\n      -l g=name       require library 'name' into global 'g'\n      -l _=name       require library 'name' (no global variable)\n      -v              show version information\n      --              stop handling options\n      -               stop handling options and execute stdin\n      script [args]   script to execute\n\n    \"compile\" options:\n      -t target       name of the targetted platform\n      -t list         list available targets\n      -o file         name the executable file to create\n      -b              compile to Lua bytecode\n      -s              emit bytecode without debug information\n      -k key          script encryption key\n      -q              quiet compilation (error messages only)\n      scripts         scripts to compile\n\n    Environment variables:\n\n      LUA_INIT_5_4, LUA_INIT\n                    code executed before handling command line\n                    options and scripts (not in compilation\n                    mode). When LUA_INIT_5_4 is defined,\n                    LUA_INIT is ignored.\n\n      PATH          PATH shall contain the bin directory where\n                    LuaX is installed\n\n      LUA_PATH      LUA_PATH shall point to the lib directory\n                    where the Lua implementation of LuaX\n                    lbraries are installed\n\n      LUA_CPATH     LUA_CPATH shall point to the lib directory\n                    where LuaX shared libraries are installed\n\n    PATH, LUA_PATH and LUA_CPATH can be set in .bashrc or .zshrc\n    with \"luax env\".\n    E.g.: eval $(luax env)\n\n    \"luax env\" can also generate shell variables from a script.\n    E.g.: eval $(luax env script.lua)\n\nWhen compiling scripts (options `-t` and `-o`), the scripts shall\ncontain tags (e.g. in comments) showing how the script is used by LuaX:\n\n- `--@MAIN`: main script (must be unique)\n- `--@LOAD`: library that is `require`’d before the main script is run\n  and stored in a global variable\n- `--@LOAD=\u003cglobal variable name\u003e`: as `--@LOAD` but the module is\n  stored in a global variable with the given name\n- `--@LIB`: library that must be explicitly `require`’d by the main\n  script\n- `--@LIB=\u003cnew module name\u003e`: library that is `require`’d with\n  `\u003cnew module name\u003e` instead of the source filename.\n\nScripts without tags are classified using a simplistic heuristic:\n\n- if the last non empty line starts with `return` then it is a library\n  (as if it contained a `@LIB` tag)\n- otherwise it is the main script (as if it contained the `@MAIN` tag).\n\nThis heuristic should work for most of the Lua scripts but explicit tags\nare recommended.\n\nLuaX can also embed files that are not Lua scripts. These files are\nembedded as Lua modules that return the file content as a string. In\nthis case, the module name is the file name.\n\n**Note for Windows users**: since Windows does not support shebangs, a\nscript `script` shall be explicitly launched with `luax` (e.g.:\n`luax script`). If `script` is not found, it is searched in the\ninstallation directory of `luax` or in `$PATH`.\n\n### Examples\n\n``` bash\n# Compilation (standalone executable script for LuaX)\n$ luax compile -o executable main.lua lib1.lua lib2.lua\n$ ./executable      # equivalent to luax main.lua\n\n# Compilation for Lua\n$ luax compile -o executable -t lua main.lua lib1.lua lib2.lua\n$ ./executable      # equivalent to lua main.lua\n\n# Compilation for Pandoc Lua\n$ luax compile -o executable -t pandoc main.lua lib1.lua lib2.lua\n$ ./executable      # equivalent to pandoc lua main.lua\n\n# Available targets\n$ luax compile -t list\nTarget                Interpreter / LuaX archive\n--------------------- -------------------------\nluax                  ~/.local/bin/luax\nlua                   ~/.local/bin/lua\npandoc                ~/.local/bin/pandoc\nnative                ~/.local/lib/luax.lar\nlinux-x86_64          ~/.local/lib/luax.lar\nlinux-x86_64-musl     ~/.local/lib/luax.lar\nlinux-aarch64         ~/.local/lib/luax.lar\nlinux-aarch64-musl    ~/.local/lib/luax.lar\nmacos-x86_64          ~/.local/lib/luax.lar\nmacos-aarch64         ~/.local/lib/luax.lar\nwindows-x86_64        ~/.local/lib/luax.lar\n```\n\n## Built-in modules\n\nThe `luax` runtime comes with a few builtin modules.\n\nSome modules are heavily inspired by\n[BonaLuna](https://github.com/cdsoft/bonaluna) and\n[lapp](https://github.com/cdsoft/lapp).\n\n- [LuaX interactive usage](doc/repl.md): improved Lua REPL\n- [package](doc/package.md): modified Lua package `package`\n- [debug](doc/debug.md): modified Lua package `debug`\n- [import](doc/import.md): import Lua scripts to user table instead of\n  `_G`\n- [F](doc/F.md): functional programming inspired functions\n- [fs](doc/fs.md): file system management\n- [sh](doc/sh.md): shell command execution\n- [mathx](doc/mathx.md): complete math library for Lua\n- [imath](doc/imath.md): arbitrary precision integer and rational\n  arithmetic library\n- [qmath](doc/qmath.md): rational number library\n- [complex](doc/complex.md): math library for complex numbers based on\n  C99\n- [ps](doc/ps.md): Process management module\n- [sys](doc/sys.md): System module\n- [term](doc/term.md): Terminal manipulation module\n- [crypt](doc/crypt.md): cryptography module\n- [lz4](doc/lz4.md): Extremely Fast Compression algorithm\n- [lzip](doc/lzip.md): A compression library for the lzip format\n- [tar](doc/tar.md): A minimalistic tar archiving library\n- [lpeg](doc/lpeg.md): Parsing Expression Grammars For Lua\n- [luasocket](doc/luasocket.md): Network support for the Lua language\n- [luasec](doc/luasec.md): add secure connections to luasocket\n- [curl](doc/curl.md), [wget](doc/wget.md): simple curl and wget command\n  line interfaces\n- [argparse](doc/argparse.md): Feature-rich command line parser for Lua\n- [serpent](doc/serpent.md): Lua serializer and pretty printer\n- [cbor](doc/cbor.md): pure Lua implementation of the CBOR\n- [lar](doc/lar.md): Simple archive format for Lua values\n- [linenoise](doc/linenoise.md): A small, portable GNU readline\n  replacement with UTF-8 support\n- [json](doc/json.md): JSON Module for Lua\n\n## Shared libraries\n\nLuaX is also available as a shared library. This shared library is a Lua\nmodule that can be loaded with `require`. It provides the same modules\nthan the LuaX executable and can be used by a regular Lua interpreter\n(e.g.: lua, pandoc, …).\n\nE.g.:\n\n    $ lua -l libluax\n    Lua 5.4.7  Copyright (C) 1994-2024 Lua.org, PUC-Rio\n    \u003e F = require \"F\"\n    \u003e F.range(100):sum()\n    5050\n    \u003e F.show({x=1, y=2})\n    {x=1, y=2}\n    \u003e F.show({x=1, y=2}, {indent=4})\n    {\n        x = 1,\n        y = 2,\n    }\n\n## Pure Lua modules\n\nLuaX modules also provide pure Lua implementations (no LuaX dependency).\nThe script `lib/luax.lua` can be reused in pure Lua programs:\n\n- [luax.lua](doc/luax.lua.md): LuaX modules reimplemented in pure Lua\n  (except LuaSocket and lpeg)\n\n## License\n\n    luax is free software: you can redistribute it and/or modify\n    it under the terms of the GNU General Public License as published by\n    the Free Software Foundation, either version 3 of the License, or\n    (at your option) any later version.\n\n    luax is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with luax.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n    For further information about luax you can visit\n    https://github.com/cdsoft/luax\n\n`luax` uses other third party softwares:\n\n- **[Zig](https://ziglang.org/)**: General-purpose programming language\n  and toolchain for maintaining robust, optimal, and reusable software.\n  ([MIT license](https://github.com/ziglang/zig/blob/master/LICENSE))\n- **[Lua 5.4](http://www.lua.org)**: Copyright (C) 1994-2023 Lua.org,\n  PUC-Rio ([MIT license](http://www.lua.org/license.html))\n- **[Lpeg](http://www.inf.puc-rio.br/~roberto/lpeg/)**: Parsing\n  Expression Grammars For Lua ([MIT\n  license](http://www.lua.org/license.html))\n- **[luasocket](https://github.com/diegonehab/luasocket)**: Network\n  support for the Lua language ([LuaSocket 3.0\n  license](https://github.com/diegonehab/luasocket/blob/master/LICENSE))\n- **[luasec](https://github.com/lunarmodules/luasec)**: integrates with\n  LuaSocket to make it easy to add secure connections to any Lua\n  applications or scripts. ([LuaSec\n  license](https://github.com/lunarmodules/luasec/blob/master/LICENSE))\n- **[OpenSSL](https://www.openssl.org/)**: robust, commercial-grade,\n  full-featured toolkit for general-purpose cryptography and secure\n  communication ([Apache License\n  2.0](https://github.com/openssl/openssl/blob/master/LICENSE.txt))\n- **[serpent](https://github.com/pkulchenko/serpent)**: Lua serializer\n  and pretty printer. ([MIT\n  license](https://github.com/pkulchenko/serpent/blob/master/LICENSE))\n- **[LZ4](https://github.com/lz4/lz4)**: Extremely Fast Compression\n  algorithm ([License](https://github.com/lz4/lz4/blob/dev/lib/LICENSE))\n- **[lzip](https://www.nongnu.org/lzip/)**: A compression library for\n  the lzip format ([License](http://www.gnu.org/licenses/gpl-2.0.html))\n- **[Argparse](https://github.com/mpeterv/argparse)**: a feature-rich\n  command line parser for Lua ([MIT\n  license](https://github.com/mpeterv/argparse/blob/master/LICENSE))\n- **[Linenoise](https://github.com/yhirose/linenoise/tree/utf8-support)**:\n  A minimal, zero-config, BSD licensed, readline replacement ([BSD\n  license](https://github.com/antirez/linenoise/blob/master/LICENSE))\n- **[dkjson.lua](http://dkolf.de/dkjson-lua/)**: JSON Module for Lua\n  ([MIT license](http://www.lua.org/license.html))\n- **[CBOR](https://www.zash.se/lua-cbor.html)**: pure Lua implementation\n  of the CBOR\n  ([License](https://code.zash.se/lua-cbor/file/tip/COPYING))\n\n[^1]: `luax` uses `zig` to link the LuaX runtime with the Lua scripts.\n    The Lua scripts are actually compiled to Lua bytecode. `luax`\n    produces executables that do not require LuaX to be installed.\n","funding_links":["https://github.com/sponsors/CDSoft","https://liberapay.com/LuaX/donate'","https://liberapay.com/assets/widgets/donate.svg'","https://ko-fi.com/K3K11CD108'","https://github.com/sponsors/CDSoft'"],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCDSoft%2Fluax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCDSoft%2Fluax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCDSoft%2Fluax/lists"}