Lua project setup with LuaRocks
Coming from the moon
Even though I already wrote an overview of how to set up a Lua project, this article, part of the longer Lua series, will go into more detail on specific aspects with greater focus. Going through this, the goal is to have a solid foundation to further increment on in later articles of this series, or for any project to come.
Running a first Lua program, using LuaRocks for dependency management, code formatting and linting, and setting up an editor or IDE, to support Lua development as good as possible. Remark, this is how I set up my projects, maybe not by the books, but the way it works best for me on all environments, repeatedly.
A note about versions. The latest Lua version as of writing is 5.4 (released ). Generally everything in this article series will work with Lua 5.1 (released ) and up. If this is not the case, a callout as the following will signal that a higher version is required.
For instance, in a later article I will use the meta-method
__close, added in Lua 5.4, for a simple profiling tool.
An overview of the versions and there respective main features can be found on the official Lua versions history page.
First things first, let's check if Lua is already installed on the
system, by running Lua's version command
lua -v in a
If it prints something similar to the above it's already good to go. If not, Lua needs to be installed first.
Brew on macOS can be used to install an up-to-date version of Lua.
On Linux, installing Lua is as straight forward as using the systems package manager. For example, on Debian, Ubuntu, and Mint:
Have a look at Lua's installation guide to build a more recent version from source if needed.
On Windows there is a list of available Lua binaries, offering pre-compiled Lua versions ready to be used. Scrolling down on that page to the History section the latest available pre-compiled versions can be found. Choosing one, for example version 5.4.2, will lead to SourceForge, clicking the Tools Executables folder next.
Here is the option of picking either the 32-bit or the 64-bit version, depending on the used system.
After the download, the archive contents can be extracted, finding,
depending on the downloaded version, an executable. For version
5.4.x this is called
Double clicking that file will open a terminal, from which Lua can be run. Alternatively, this file can be placed in a folder that is part of the PATH variable, or made available through it.
With Lua installed, it's time to
create a small test program to verify everything
works as expected. Creating a source file inside the dedicated
src/main.lua, saying hello to
Executing that file via the terminal from inside the project directory will print the greeting.
Dependency management with LuaRocks
LuaRocks, the de facto standard package manager for Lua, will be used to manage project dependencies. First, the LuaRocks command line tool needs to be installed on the system.
Again, using brew on macOS, LuaRocks can be installed with a single command.
Same for Linux, a single command does the job, using the systems package manager.
First the LuaRocks executable needs to be downloaded, either 32-bit
or 64-bit. The downloads are at the top of the
LuaRocks download page
on GitHub. After downloading and extracting the files, the
luarocks.exe needs to be
added to the PATH
to make it available as
luarocks command from the
Project folder setup
With LuaRocks installed, the
init command helps to set
up a project, including
local dependency management. This means
dependencies will be installed inside the project folder in a
init command will do a couple of things, some of
lua_modulefolder, storing all installed dependencies.
src/main.luaas main entry point of the program.
Add two shortcuts that can be used for executing
luarocksfrom inside the project, though, I won't use them and rather depend on my system installation.
.luarocksfolder, containing some configuration files, and marking the directory as root folder for LuaRocks.
And two more I'll have a more detailed look at:
Creating or adding to an existing
.rockspecfile with the base project settings and name, taken from the folder name LuaRocks was executed in.
luarocks init command auto generates a
.gitignore, if not already present, or
appends its entries to an existing
.gitignore file. The
following entries are added.
The first two files are local shortcuts to execute
luarocks — I'll remove both
entries as I also remove the local shortcuts, using my system
installations. Then comes the dependency folder
lua_modules and the config folder
.luarocks, both entries I'll keep in, to be ignored by
.rockspec file defines the projects properties,
like name, version, and used dependencies. A complete list of the
supported options can be found on the
official LuaRocks wiki page for build rules.
At the top of the file the rockspec format will be defined, indicating the format version, the latest being version 3.
source.url can be many things, I usually point it
to the projects git repository, but it can also be other repository
types or URLs.
description can contain a summary, the project home
page, a license and more.
Next comes the list of dependencies. This will hold all necessary
project dependencies and one special dependency from the start,
lua. Less an actual dependency and more the projects
supported Lua versions or version range.
And at last, the project build settings and modules, not yet utilised.
To ensure all changes to a
.rockspec file are valid the
command can be used, giving it the filename to validate.
And here the final
Install a module
Let's install something, finally! The inspect module is handy in general, giving an easy way to print any value in Lua for inspection or debugging.
The new dependency also needs to be added to the
.rockspec file to keep it on later installs.
On a fresh checkout of the project this will ensure that
inspect is installed again when running
luarocks install --deps-only on the
inspect to print a test table.
Oh no, running this code will give an error.
Resolve module paths
Having a way to manage dependencies, Lua still needs to be told
where to find modules for the project. This is done
package.cpath variables. My preferred way is to have a
src/setup.lua file defining those.
In that file I can also put other project setup options later, as it will be loaded before running any Lua script.
Now, there are two ways using this setup; one is via the
-l option of the
Another option is to set the
variable. This variable can either execute Lua code before running a
script, or load a file when the value starts with
By defining the environment variable inside the terminal, Lua can be
run without the
Optionally, to not pollute the environment or re-set the variable
every time, I use
.envrc with my projects environment
variables that will only be loaded when working inside the
respective project folder.
There are releases for all platforms, including Windows*, and a comprehensive documentation, so I won't go into detail here as this is an optional setup step.
Having that done, one way or another, I assume from here the
LUA_INIT variable is set, the test script with the
inspect module can be run again.
Enable local scripts
Before continuing adding more tools to the project setup, it is
quite handy to enable the execution of local scripts. When
installing an executable with LuaRocks those binaries are installed
To execute a script the full path needs to be used.
To simplify this, the local bin folder can be added to the system PATH, especially handy when already using direnv.
The same example command above then becomes the following when executed inside the project directory.
Auto format code
the tool of choice, installed via LuaRocks and afterwards available
Custom format options can be defined in a
YAML file inside the project root. I'll only change a
few options for my projects.
With the local script setup enabled, or using the path to the executable, the formatter can be run, and all Lua files auto formatted.
To lint the project code base
can be used, an executable installed via LuaRocks into the
Keeping the default options it can be run on all files inside
src. A full list of all options can be found in the
official Luacheck documentation.
No project setup complete without setting up an editor environment. To have some options I picked two well known ones, IntelliJ IDE from JetBrains (paid) and VSCode from Microsoft (free).
Using any JetBrains product (e.g. CLion) for Lua development, I use the plugin Luanalysis, a EmmyLua fork. It comes with Luacheck bundled and offers many convenient functions like Find Usage, Refactor, Go To, Parameter Hints, and Documentation support, to name a few.
I could not find a way to auto format code on save with LuaFormatter, though.
Visual Studio Code
For VSCode three plugins do the heavy lifting — the Lua language server plugin, the plugin for Luacheck, and another plugin for LuaFormatter.
The only plugin that really needs configuration is the LuaFormatter
plugin, setting the path to the LuaFormatter executable and to the
VSCode's setting "Format on Save" can be used to auto format the code.
Even though I focused on those two editors, I wanted to mention some more options for Lua development.
One of those options is ZeroBrane Studio, an IDE focused on Lua development. It has a lot of features focused on Lua, including resources to learn the language.
Neovim is another option that comes with Lua support out-of-the-box. Lua is even built-in and plugins for the editor are written in it.
Close to my heart, Sublime Text is a great options for development in general. For Lua, I use the LuaExtended plugin, bringing even better support to the editor.
What comes next
This article was specifically focused on getting a good environment running to develop with Lua. Everything shown here can be found in the companion repository, branch part-1.
The next article will focus on dependency management; how to use different LuaRock trees, keeping track of dependencies installed from different sources, but also how to create and publish a package.
Until then 👋🏻