Skip to main content

Luarocks tutorial

Prosody's plugin installer is making use of Luarocks to get things working. Therefore, it makes sense that we look a bit into Luarocks to see how it works.


Here is what you need to know. Luarocks uses files, called rockspecs, to get things installed around. These are basically instruction files and they tell the program how to do the work. We can pack the sources and the rockspecs into a single file, called a rock. We can install libraries from both rocks and rockspec files. The code is installed in what is called a rock tree, which is a folder with a specific structure inside, organized in a way to help with the required management of libraries and servers.

Installing, removing and list

If you are working on debian you can just use:
  • sudo apt-get install luarocks
Now, there might be some trouble here and there, depending on your machine, or if you are in a different OS, but the guys at luarocks have tips for almost every possible situation, just check here:
Worst case scenario head over to their support section and surely you'll find someone to help you.

Now, with that out of the way, lets (The attentive reader will notice I misspelled "lets" at the beginning of the next video 😅) check how it works! Topics we are covering here:
  • luarocks help
  • configuration section
  • using the global and local trees
  • using install, remove and list

The --tree flag

We can use this flag to specify a custom path for a rock tree, without changing anything at the configuration file.

The --server flag

We can use this flag to specify the place from which we are getting our rocks. We can reference a rock tree, a repository or a server. These terms are used somehow interchangeably, so watch out! Here I'll show you how to use a remote source being served to us.

Writing rockspecs

Okay, so lets keep this simple. There is a number of things to take into account, but all of them lead to the same place. We need to write rockspecs related to the sources that we want to install. We can do this with the write_rockspec command, which will automatically create rockspecs and fill some fields for us. Most of them have to be filled by hand though. Notably, the source.url field must be filled if we want to deal with rocks/rockspecs from a remote server.

The make command

You can make a rockspec work locally with the make command though. The make command is your answer, in those cases where you have everything in your local machine.

Installing from our own repo/server

We need to write down some server in the source.url field. By default, luarocks is pointed to their official repository. But we can use any repository we want.  That's what we did when we used the --server flag, which overrides the default source. The difference is that we were using an already existing repository. What if we want to make our own?
Well, there are a couple of ways, but if you are inexperienced about luarocks and servers like I was/am, be warned, this thing might is the gift that keeps on giving!

But lets look at the easiest way, which turns out to be quite accessible, in my experience. We can make use of a traditional git/mercurial repository to use as a source for our own plugins. After that we'll want to make our rockspecs available at a local/remove server, in order to distribute stuff around. We can make use of the luarocs-admin make-manifest command to do some heavy lifting for us and setup everything we need =)
At the above image we can see the rockspecs available at my local server. If you are unfamiliar about how to get an apache server going, check this out.
And these are the basics about Luarocks. There is plenty more though, so be sure to check their docs if you need.