ZNHOO Whatever you are, be a good one!

LuaRocks Tutorial

01 Mar 2024 • Leave Comments
  1. LuaRocks luarocks
  2. Build lua
  3. Build luarocks
  4. rocks
  5. rocks servers
  6. config
  7. luarocks pack
  8. luarocks upload
  9. luarocks-admin
  10. luarocks install

LuaRocks luarocks

"LuaRocks" refers to the project name, while "luarocks" and "luarocks-admin" refer to CLI tool.

Build lua

This sections show how to manually compile Lua 5.1.

# fetch source
~ $ curl -O https://www.lua.org/ftp/lua-5.1.4.tar.gz
~ $ tar -xf lua-5.1.4.tar.gz

# customization options
~ $ make echo
~ $ make pecho
~ $ make lecho

# determine the platform compatiblity
~ $ make

# make
~ $ make linux
~ $ make -n install

# install
~ $ sudo make install
~ $ /usr/local/bin/lua -v

Build luarocks

In this section, we will demonstrate how to install Luarocks from source.

Firstly, we install the dependency lib lua-devel as below. We can avoid this if we have manually built Lua.

[ec2-user@ip-172-31-16-59 tmp]$ sudo yum install lua-devel

Now compile Luarocks:

[ec2-user@ip-172-31-16-59 ~]$ cd /tmp

[ec2-user@ip-172-31-16-59 tmp]$ wget https://luarocks.org/releases/luarocks-3.9.0.tar.gz
[ec2-user@ip-172-31-16-59 tmp]$ tar -xzpvf luarocks-3.9.0.tar.gz
[ec2-user@ip-172-31-16-59 tmp]$ cd luarocks-3.9.0/
[ec2-user@ip-172-31-16-59 luarocks-3.9.0]$ ./configure --with-lua-include=/usr/include
[ec2-user@ip-172-31-16-59 luarocks-3.9.0]$ make
[ec2-user@ip-172-31-16-59 luarocks-3.9.0]$ sudo make install

[ec2-user@ip-172-31-16-59 luarocks-3.9.0]$ luarocks search lua-cassandra

[ec2-user@ip-172-31-16-59 luarocks-3.9.0]$ sudo -i
[root@ip-172-31-16-59 ~]# echo $PATH

# .bash_profile
PATH=$PATH:$HOME/bin:/usr/local/bin

[root@ip-172-31-16-59 ~]# exit
[ec2-user@ip-172-31-16-59 luarocks-3.9.0]$ sudo -i luarocks -h

For more details regarding configuring Luarocks, please check Emacs LSP.

rocks

The term rock refers to a ZIP archive in the ".rock" extention, containing two kinds of files as follows.

  1. .rockspec. We can generate a .rockspec template quickly with write_rockspec.
  2. Source code, mainly .lua and may include .c.

There are 3 types of rocks as shown below. They differ mainly in the format of the source code part. Please read the official doc for more details.

  1. Source Rock (.src.rock). The source code is ZIPped as it is.

    It is usually uploaded to rocks servers by luarocks upload or luarocks-admin, and then transformed to the other two types (ready for installation) by luarocks pack or luarocks build.

  2. Binary Rock (.<system-arch>.rock). The included .c code is compiled to the platform-specific format.

    Can be installed directly to the specific platform.

  3. Pure-Lua Rock (.all.rock). The ZIP organizes .lua code according to the rock tree structure, though it contains exactly the same set of files as Source Rock.

    Can be installed directly independent of platforms. However, it does not guarantee running everywhere as .lua might depend on external FFI C modules or os.execute(<cmd>).

rocks servers

We have two kinds of Rock Repository.

  1. rocks servers, can be an URL (e.g. Github repo) or a local pathname. For examle, the official (default) rocks server URL is https://luarocks.org.

    We can upload rocks to and download rocks from rocks servers

  2. rocks trees, is a local pathname, to where we install rocks.

    We can create rocks from rocks trees.

A rock repository contains two types of files.

  1. rock and/or .rockspec file.
  2. manifest file.

config

To show current config.

# list all
~ $ luarocks config

# list only one entry
~ $ luarocks config rocks_servers

Here is an example to customize rocks_servers.

-- ~/.luarocks/config-5.4.lua
rocks_servers = {
    "https://dummy:" .. os_getenv("GITHUB_TOKEN") .. "@raw.githubusercontent.com/Kong/kongrocks/main/rocks",  -- internal rocks server
    "https://luarocks.org",    -- official rocks server
    "https://raw.githubusercontent.com/rocks-moonscript-org/moonrocks-mirror/master/",
    "https://luafr.org/luarocks/",
}

Please refer to config file.

luarocks pack

We create a rock using luarocks pack.

Firstly, make sure zip is available.

~ $ type zip

There are three methods listed as follows.

  1. Given a .rockspec file, we create a Source Rock based on source code downloaded.

    ~ $ luarocks pack ./lua-resty-session/lua-resty-session-4.0.5-1.rockspec

~ $ ls
lua-resty-session-4.0.5-1.src.rock
   
~ $ file lua-resty-session-4.0.5-1.src.rock
lua-resty-session-4.0.5-1.src.rock: Zip archive data, at least v2.0 to extract, compression method=deflate

  2. Given a module installed in local rocks tree, we can create a Binary Rock (with C modules) or a Pure-Lua Rock.

    ~ $ luarocks list dkjson
~ $ luarocks show dkjson

# version "2.6-1" is optional; default to latest.
~ $ luarocks pack [--verbose] dkjson [2.6-1]

~ $ ls
dkjson-2.6-1.all.rock

~ $ file dkjson-2.6-1.all.rock
dkjson-2.6-1.all.rock: Zip archive data, at least v2.0 to extract, compression method=deflate

    We can find dkjson is a Pure-Lua Rock, without C modules.

Apart from luarocks pack, we can also use luarocks build --pack-binary-rock to create a Binary Rock (with C modules) or a Pure-Lua Rock, given a .rockspec file or Source Rock. See example at luarocks-admin.

luarocks upload

Given a .rockspec file, luarocks upload firstly creates a Source Rock and then upload both the .rockspec and the Source Rock to the official rocks_server.

Offer API key on CLI.

# switch to temporary directory
16:11:41 zachary@Zacharys-MacBook-Pro ~/workspace/resty-redis-cluster
$ cd ~/misc/

16:15:30 zachary@Zacharys-MacBook-Pro ~/misc
$ luarocks upload --api-key xxxyyyzzz ~/workspace/resty-redis-cluster/kong-redis-cluster-1.3.0-0.rockspec

Alternatively, configure API key in the upload config.

11:11:00 zachary@Zacharys-MacBook-Pro ~
$ cat ~/.luarocks/upload_config.lua
key = "xxxyyyzzz"
server = "https://luarocks.org"

# switch to temporary directory
16:11:41 zachary@Zacharys-MacBook-Pro ~/workspace/resty-redis-cluster
$ cd ~/misc/

16:15:30 zachary@Zacharys-MacBook-Pro ~/misc
$ luarocks upload ~/workspace/resty-redis-cluster/kong-redis-cluster-1.3.0-0.rockspec

We can optionally, remove the created Source Rock.

16:15:30 zachary@Zacharys-MacBook-Pro ~/misc
$ rm kong-redis-cluster-1.3.0-0.src.rock

Verify the new rock is available from the official rocks server.

16:16:29 zachary@Zacharys-MacBook-Pro ~/misc
$ luarocks search kong-redis-cluster [1.5.3]

To upload rocks to custom rocks servers, please refer to luarocks-admin.

luarocks-admin

luarocks upload uploads only Source Rock to only the official rocks server. We can upload any type of rocks to any custom rocks servers, by luarocks-admin.

Manuall method.

  1. Copy the .rockspec to the custom rocks server.

    ~ $ git clone git@github.com:Kong/kongrocks.git
~ $ git checkout -b FTI-5247
~ $ cd ~/workspace/kongrocks

~ $ cp ~/workspace/ce2ee/distribution/kong-openid-connect/kong-openid-connect-2.5.6-1.rockspec ./rocks/

  2. Create Source Rock and copy it to the custom rocks server.

    ~ $ cd ~/misc
~ $ luarocks pack ~/workspace/ce2ee/distribution/kong-openid-connect/kong-openid-connect-2.5.6-1.rockspec
   
~ $ ls
kong-openid-connect-2.5.6-1.src.rock
   
~ $ cp ~/misc/kong-openid-connect-2.5.6-1.src.rock ./rocks/

    This is optional but highly recommended.

  3. Create Binary Rock or Pure-Lua Rock and copy it to the custom rocks server.

    We pass the option --pack-binary-rock to luarocks build to skip rock installation.

    ~ $ cd ~/misc
   
~ $ luarocks build --pack-binary-rock ~/workspace/ce2ee/distribution/kong-openid-connect/kong-openid-connect-2.5.6-1.rockspec
# -or-
~ $ luarocks build --pack-binary-rock kong-openid-connect-2.5.6-1.src.rock

~ $ ls
kong-openid-connect-2.5.6-1.all.rock
   
~ $ cp ~/misc/kong-openid-connect-2.5.6-1.all.rock ./rocks/

    This is optional as Binary Rock or Pure-Lua Rock is mainly for installation to a specific platform. You are recommended to skip this part.

  4. Update manifest of the custom rocks server.

    ~ $ luarocks-admin make-manifest ./rocks/

    A rocks server has only one manifest file to record all available .rockspec and rocks.

  5. Sync the change from local repository to remote repository.

    ~ $ git add -A
~ $ git push -u origin head

The manual method is fairly flexibile, but luarocks-admin add and luarocks-admin remove will automatically update the manifest. The limitation is the two commands add/remove only one .rockspec file or rock file at a time.

Assume, we want to bump "2.5.6-1" to "2.5.6-2", check example below.

~ $ cd ~/misc
~ $ luarocks pack kong-openid-connect-2.5.6-2.rockspec
~ $ luarocks build --pack-binary-rock kong-openid-connect-2.5.6-2.src.rock
~ $ ls
kong-openid-connect-2.5.6-2.all.rock    kong-openid-connect-2.5.6-2.rockspec    kong-openid-connect-2.5.6-2.src.rock

~ $ cd ~/workspace/kongrocks
~ $ luarocks-admin add --server ~/workspace/kongrocks/rocks/ kong-openid-connect-2.5.6-2.rockspec
~ $ git status
~ $ luarocks-admin add --server ~/workspace/kongrocks/rocks/ kong-openid-connect-2.5.6-2.src.rock
~ $ git status
~ $ luarocks-admin add --server ~/workspace/kongrocks/rocks/ kong-openid-connect-2.5.6-2.all.rock
~ $ git status

Pay attention that, we explicitly set --server to overwrite the rocks_servers in config file.

luarocks install

We install a Binary Rock or Pure-Lua Rock to the rocks tree on local host.

We can either manually add .lua file to LUA_PATH, or invoke the following commands.

  1. luarocks build compiles Binary Rock or Pure-Lua Rock based on Source Rock downloaded from rocks servers, and then install it. Add option --pack-binary-rock to skip the installation. See example at luarocks-admin.
  2. luarocks make differs from luarocks build in that it compiles Binary Rock or Pure-Lua Rock from the source code in current directory.
  3. luarocks install installs a local Binary Rock or Pure-Lua Rock file, or falls back to luarocks build when given a .rockspec file.

See https://github.com/luarocks/luarocks/wiki/luarocks#overview-of-the-difference-between-make-build-install-and-pack.

Related Posts