LuaRocks Tutorial

01 Mar 2024 • Leave Comments

LuaRocks luarocks
Manual Installation
1. Build lua
2. Build luarocks
rocks
rocks servers
config
Create Rocks
Upload Rocks
1. Upload to Official Server
2. Upload to Custom Server
Install Rocks

LuaRocks luarocks

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

Manual Installation

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 the section config.

rocks

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

.rockspec. We can generate a .rockspec template quickly according to write_rockspec.
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.

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.

The next two types are for installation purpose.
Binary Rock (.<system-arch>.rock). This installation type include .c source code but compiled to the platform-specific C module.

Can be installed directly to the specific platform.
Pure-Lua Rock (.all.rock). This installation type contains only Lua code. The ZIP organizes the source rock according to the rock tree structure.

It can be installed directly independent of platforms, but does not guarantee running everywhere. The Lua code might depend on external FFI C modules or os.execute(<cmd>).

Please refer to the section Create Rocks on how to create rocks.

rocks servers

We have two kinds of Rock Repository.

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

We can upload rocks to and download rocks from rocks servers
rocks trees, is a local pathname, to where we install rocks.

A rock repository contains three types of files.

rock
.rockspec: optional as it is already in the rock.
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 official config file and Emacs LSP example.

Create Rocks

We create a rock using luarocks pack.

Firstly, make sure zip is available.

~ $ type zip

There are two methods listed as follows.

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

Given a module installed in a rocks tree, we can create a Binary Rock or a Pure-Lua Rock.

From the example below, we find dkjson is a Pure-Lua Rock (without C modules).
```
~ $ 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
```
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. This is a better way as it does not require the rock to be installed.

Upload Rocks

Upload to Official Server

Luarocks upload uploads both the .rockspec and the Source Rock to the official rocks_server. We must provide the .rockspec file. If the Source Rock is not provided, it would be create on the fly.

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 temporary 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.3.0]

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

Upload to Custom Server

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.

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/

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.

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.

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.
Sync the change from local repository to remote repository.
```
~ $ git add -A
~ $ git push -u origin head
```

The manual method described above is fairly flexibile. However, we can make use of luarocks-admin add and luarocks-admin remove as they automatically update the manifest file. The limitation is they handle only one rock at a time. See 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/ ~/misc/kong-openid-connect-2.5.6-2.rockspec
~ $ luarocks-admin add --server ~/workspace/kongrocks/rocks/ ~/misc/kong-openid-connect-2.5.6-2.src.rock
~ $ luarocks-admin add --server ~/workspace/kongrocks/rocks/ ~/misc/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.

Install Rocks

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.

luarocks build compiles Binary Rock or Pure-Lua Rock based on Source Rock downloaded from rocks servers, and then install it.
luarocks make differs from luarocks build in that it compiles Binary Rock or Pure-Lua Rock from the source code in current directory.
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.

ZNHOO Whatever you are, be a good one!