.. |gh-workflow| image:: https://img.shields.io/github/actions/workflow/status/luarocks/hererocks/test%2Eyml?branch=master :target: https://github.com/luarocks/hererocks/actions/workflows/test.yml :alt: GitHub Workflow Status
.. |codecov| image:: https://img.shields.io/codecov/c/github/luarocks/hererocks :target: https://app.codecov.io/gh/luarocks/hererocks :alt: Codecov
|gh-workflow| |codecov|
hererocks
is a single file Python 2.7/3.x script for installing Lua <http://http://www.lua.org/>
(or LuaJIT <http://luajit.org/>
or moonjit <https://github.com/moonjit/moonjit>
or RaptorJIT <https://github.com/raptorjit/raptorjit>
)
and LuaRocks <https://luarocks.org/>
_, its package manager, into a local directory.
It configures Lua to only see packages installed by that bundled version of LuaRocks, so that the installation is isolated.
.. code-block:: bash
hererocks lua53 -l5.3 -rlatest # Install Lua 5.3 with latest LuaRocks into 'lua53' directory. source lua53/bin/activate # Run activation script, adding 'lua53/bin' to $PATH. lua -v # Lua, LuaRocks, and programs luarocks install luacheck # installed using LuaRocks luacheck --version # can now be used. deactivate-lua # Remove 'lua53/bin' from $PATH. lua53/bin/lua -v # All the binaries can still be used directly.
For more info see below or run hererocks --help
for a complete listing of options.
Using pip <https://pypi.python.org/pypi/pip>
_: run pip install git+https://github.com/luarocks/hererocks
, using sudo
if necessary.
Manually: download hererocks with wget https://raw.githubusercontent.com/luarocks/hererocks/master/hererocks.py
, then use python hererocks.py ...
to run it.
Compiler:
gcc
in PATH, or Visual Studio 2008 or later (see help message for --target
).cc
.gcc
.hererocks
writes several activation scripts into bin
subdirectory of the installation directory.
When sourced (on Windows: simply executed) they add path to that subdirectory to PATH
environment variable.
This allows one to use lua
, luarocks
and other programs installed in the created environment directly.
Additionally, activation scripts make deactivate-lua
command available. It removes path to currently activated
environment from PATH
. Activating an environment deactivates the previous one automatically, if it exists.
Several versions of activation scripts are installed to support various shells:
Windows:
activate.bat
.activate.ps1
.Other systems:
activate
.activate.fish
.activate.csh
.Installation location ^^^^^^^^^^^^^^^^^^^^^
The first argument of hererocks
command should be path to the directory where Lua and/or LuaRocks should be installed. If it does not exist, it will be created.
If installation directory already has Lua installed, a new version of Lua or LuaRocks can be installed over it as a seamless upgrade (packages installed with LuaRocks will keep working) provided new and old Lua minor versions are same. E.g. Lua 5.1.5 and LuaJIT 2.1 can be installed over Lua 5.1.1, but not over Lua 5.2.1. Otherwise, when installing an incompatible Lua version, the installation directory should be removed prior to running hererocks
. If hererocks
detects that it has already installed requested version of Lua or LuaRocks built with same options into the directory, it will skip installation for that program, unless --ignore-installed/-i
is used.
After installation Lua and LuaRocks binaries will be in the bin
subdirectory of the installation directory. Scripts installed using LuaRocks will also turn up there. Lua binary is always named lua
, even if it's LuaJIT under the hood, and LuaRocks binary is named luarocks
as usual.
Version selection ^^^^^^^^^^^^^^^^^
--lua/-l
, --luajit/-j
, --moonjit/-m
, --raptorjit
and --luarocks/-r
options select versions of programs to install.
There are three ways to specify how to fetch the sources:
5.1.5
. If patch or minor versions are left out the latest possible version will be used, e.g. for Lua 5.2
is currently equivalent to 5.2.4
and for LuaJIT 2.1
is same as 2.1.0-beta3
. latest
or ^
can be used to select the latest stable version. hererocks
will fetch and unpack sources of the selected version from corresponding downloads location, verifying their SHA256 checksum.@
. Default reference is master
, and there are default git URIs for Lua (https://github.com/lua/lua), LuaJIT (https://github.com/luajit/luajit) and LuaRocks (https://github.com/luarocks/luarocks). For instance, --luajit @458a40b
installs from a commit at the LuaJIT git repository and --luajit @
installs from its master branch. hererocks
will use git
command for cloning.Compatibility flags ^^^^^^^^^^^^^^^^^^^
Lua and LuaJIT have some flags that add compatibility with other Lua versions. Lua 5.1 has several options for compatibility with Lua 5.0 (on by default), Lua 5.2 has 5.1 compatibility flag (on by default), Lua 5.3 - both 5.1 and 5.2 compatibility flags (only 5.2 compatibility is on by default), and LuaJIT has 5.2 flag (off by default). hererocks
can change these flags before building when using --compat
option. Possible arguments are default
, none
, all
, 5.1
and 5.2
.
Installing standard PUC-Rio Lua ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Available versions: 5.1 - 5.1.5, 5.2.0 - 5.2.4, 5.3.0 - 5.3.6, 5.4.0 - 5.4.7. latest
and ^
version aliases point to 5.4.7
.
Use 5.1.0
to install Lua 5.1
which was released without patch version for some reason.
When building Lua, hererocks
tries to emulate a sensible make
target. The default can be seen in the help message printed by hererocks --help
. To select another target use --target
option.
Installing LuaJIT ^^^^^^^^^^^^^^^^^
Available versions: 2.0.0 - 2.0.5, 2.1.0-beta1 - 2.1.0-beta3. latest
and ^
version aliases point to 2.0.5
.
The OpenResty <https://openresty.org/en/>
_ fork could be installed with the git URI option: --luajit https://github.com/openresty/luajit2.git@v2.1-agentzh
.
Installing moonjit ^^^^^^^^^^^^^^^^^^
Available versions: 2.1.1 - 2.2.0. latest
and ^
version aliases point to 2.1.2
.
Installing RaptorJIT ^^^^^^^^^^^^^^^^^^^^
Available versions: 1.0.0 - 1.0.3. latest
and ^
version aliases point to 1.0.3
.
Luarocks supports RaptorJIT since 3.2.0.
Installing LuaRocks ^^^^^^^^^^^^^^^^^^^
Available versions: 2.0.8 - 2.4.4, 3.0.0 - 3.11.1. latest
and ^
version aliases point to 3.11.1
.
Version 2.0.8 does not support Lua 5.2. Versions 2.0.8 - 2.1.2 do not support Lua 5.3.
Popular continuous integration services such as Travis-CI <https://travis-ci.org/>
and Drone.io <https://drone.io/>
do not support Lua out of the box. That can be solved using hererocks in just a couple of lines. Here is an example of Travis-CI configuration file (.travis.yml
) using hererocks to install a rock and run Busted <http://olivinelabs.com/busted/>
_ test suite under Lua 5.1, 5.2, 5.3, LuaJIT 2.0 and 2.1:
.. code-block:: yaml
language: python # Can use any language here, but if it's not 'python'
env:
LUA="luajit 2.1"
before_install:
luarocks install busted
install:
luarocks make # Install the rock, assuming there is a rockspec
script:
Equivalent configuration (appveyor.yml
) for Appveyor <http://www.appveyor.com/>
_ that allows testing on Windows:
.. code-block:: yaml
environment: matrix:
LUA: "luajit 2.1"
before_build:
luarocks install busted
build_script:
luarocks make
test_script: