https://github.com/luarocks/hererocks

Python script for installing Lua/LuaJIT and LuaRocks into a local directory
https://github.com/luarocks/hererocks

Last synced: about 2 months ago
JSON representation

Python script for installing Lua/LuaJIT and LuaRocks into a local directory

• Host: GitHub
• URL: https://github.com/luarocks/hererocks
• Owner: luarocks
• License: mit
• Fork: true (mpeterv/hererocks)
• Created: 2019-04-08T16:20:28.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2024-06-29T19:34:31.000Z (3 months ago)
• Last Synced: 2024-07-11T19:47:15.375Z (3 months ago)
• Language: Python
• Size: 327 KB
• Stars: 70
• Watchers: 8
• Forks: 12
• Open Issues: 6
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
hererocks

=========

.. |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 `_

(or `LuaJIT `_ or `moonjit `_ or `RaptorJIT `_)

and `LuaRocks `_, 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.

Basic usage

-----------

.. 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.

Installation

------------

Using `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.

Requirements

------------

* Python 2.7 or 3.x

* Git for installing from Git repositories.

* Compiler:

  * Windows: MinGW with tools such as ``gcc`` in PATH, or Visual Studio 2008 or later (see help message for ``--target``).

  * OS X: ``cc``.

  * Other systems: ``gcc``.

Activation scripts

------------------

``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:

  * Batch: ``activate.bat``.

  * PowerShell: ``activate.ps1``.

* Other systems:

  * Bash, Zsh, Dash: ``activate``.

  * Fish: ``activate.fish``.

  * Tcsh, csh: ``activate.csh``.

Command-line options

--------------------

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:

* Using version number, such as ``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.

* Using git URI plus reference to checkout, separated by ``@``. 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.

* Using path to a local directory.

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 `_ fork could be installed with the git URI option: ``--luajit https://github.com/openresty/[email protected]``.

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.

Using hererocks to set up automated testing

-------------------------------------------

Popular continuous integration services such as `Travis-CI `_ and `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 `_ 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'

                   # it becomes necessary to pass '--user' to pip when installing hererocks.

  env:

    - LUA="lua 5.1"

    - LUA="lua 5.2"

    - LUA="lua 5.3"

    - LUA="lua 5.4"

    - LUA="luajit 2.0"

    - LUA="luajit 2.1"

  before_install:

    - pip install hererocks

    - hererocks env --$LUA -rlatest    # Use latest LuaRocks, install into 'env' directory.

    - source env/bin/activate          # Add directory with all installed binaries to PATH.

    - luarocks install busted

  install:

    - luarocks make # Install the rock, assuming there is a rockspec

                    # in the root of the repository.

  script:

    - busted

Equivalent configuration (``appveyor.yml``) for `Appveyor `_ that allows testing on Windows:

.. code-block:: yaml

  environment:

    matrix:

    - LUA: "lua 5.1"

    - LUA: "lua 5.2"

    - LUA: "lua 5.3"

    - LUA: "lua 5.4"

    - LUA: "luajit 2.0"

    - LUA: "luajit 2.1"

  before_build:

    - set PATH=C:\Python27\Scripts;%PATH% # Add directory containing 'pip' to PATH

    - pip install hererocks

    - hererocks env --%LUA% -rlatest

    - call env\bin\activate

    - luarocks install busted

  build_script:

    - luarocks make

  test_script:

    - busted