vfox-lua plugin

Lua vfox plugin. Use the vfox to manage multiple lua versions on Linux, macOS, and Windows.

Documentation

中文 / English website · English

Requirements

• vfox 1.0.12 or newer (mise remains supported through the compatibility path)

• macOS / Linux

  • GNU Make
  • ANSI C compiler (gcc or clang)
  • readline development library (libreadline-dev on Debian/Ubuntu, readline via Homebrew on macOS)

• Windows (install via MSYS2)

  • GCC compiler
  • Make

Optional on Windows:

• Set VFOX_LUA_WINDOWS_LUABINARIES=1 to install a prebuilt LuaBinaries package instead of compiling from source
• Supported LuaBinaries versions: 5.5.0, 5.4.8, 5.3.6, 5.2.4

Usage

Install with vfox

# install plugin
vfox add --source https://github.com/yeshan333/vfox-lua/archive/refs/heads/main.zip lua

# search available versions
vfox search lua

# install a specific version
vfox install lua@5.4.7

# activate
vfox use -g lua@5.4.7

For CI, scripts, and IDE commands, use exec to run with an explicit Lua version:

vfox exec lua@5.4.7 -- lua -v
vfox exec lua@5.4.7 -- luarocks --version

Pin a project's Lua version with vfox use -p lua@5.4.7. vfox records the version in .vfox.toml and creates a stable .vfox/sdks/lua path for the project.

On Windows, you can opt into prebuilt LuaBinaries packages instead of the default MSYS2 source build:

$env:VFOX_LUA_WINDOWS_LUABINARIES=1
vfox install lua@5.5.0
vfox use -g lua@5.5.0
lua -v

Install with mise

The vfox-lua plugin can also be used through mise, which supports vfox plugins.

# install the plugin
mise plugin install lua https://github.com/yeshan333/vfox-lua/archive/refs/heads/main.zip

# search available versions
mise ls-remote lua

# install and activate
mise use -g lua@5.4.7

# run lua
lua -v

LuaRocks Integration

LuaRocks is installed alongside Lua by default on Linux and macOS for Lua 5.x+.

# vfox
vfox install lua@5.4.7

# mise
mise use -g lua@5.4.7

By default, the plugin will:

1. Fetch the latest LuaRocks release from GitHub (fallback: 3.13.0, including Lua 5.5 support)
2. Build and bootstrap LuaRocks into <install-dir>/luarocks/
3. Add luarocks to PATH and configure LUA_INIT so that installed rocks are immediately available

Downloads use the runtime's HTTP library. vfox uses its native archive and file operations; mise uses a compatible tar extraction and file cleanup path. Temporary build artifacts are cleaned up after success or failure. If LuaRocks cannot be installed, the plugin prints a warning and keeps the Lua installation usable.

With vfox, network timeouts can be configured using:

vfox config plugin.http.timeout 60s
vfox config plugin.http.downloadTimeout 45m

# verify
luarocks --version

# install a rock
luarocks install luacheck

Set VFOX_LUA_LUAROCKS=0 (or false) if you want to skip the LuaRocks install step.

Notice

1. Make sure build tools (gcc/clang, make) are in your system $PATH.

2. Lua 5.4+ on Linux/macOS is compiled with readline by default. Install the readline development library before building:

   • Debian/Ubuntu: sudo apt-get install libreadline-dev
   • macOS: brew install readline

3. On Windows, use PowerShell to install Lua.

4. VFOX_LUA_WINDOWS_LUABINARIES=1 is a Windows-only opt-in. If the requested version is not published by LuaBinaries, the install will fail and you should use the default source-build flow instead. The archive is downloaded from SourceForge's mirror autoselect over HTTPS; checksum verification is currently skipped because the redirected mirrors don't yield a stable hash. Prefer the default source-build flow if you require an integrity check.

Known Issues

• Lua versions 5.0 and earlier cannot be installed on Linux.
• LuaRocks integration is not available on Windows.

Acknowledgements

• Lua
• vfox
• LuaRocks
• asdf-lua