Pinning versions with a lock file

Pinning dependency versions is a way to get more predictable builds. As explained in this page:

The practice of “pinning dependencies” refers to making explicit the versions of software your application depends on (defining the dependencies of new software libraries is outside the scope of this document). Dependency pinning takes different forms in different frameworks, but the high-level idea is to “freeze” dependencies so that deployments are repeatable. Without this, we run the risk of executing different software whenever servers are restaged, a new team-member joins the project, or between development and production environments.

Pinning dependencies in LuaRocks

To pin dependencies in LuaRocks, you build a package as usual, using luarocks build or luarocks make, and add the --pin option. This will build the package and its dependencies, and will also create a luarocks.lock file in the current directory. This is a text file containing the names and versions of all dependencies (and its dependencies, recursively) that were installed, with the exact versions used when building.

Using pinned dependencies in LuaRocks

When building a package with luarocks build, luarocks make (or via luarocks install if there is not prebuilt binary package), without using --pin, if the current directory contains a luarocks.lock file, it is used as the authoritative source for exact version of all dependencies, both immediate and recursively loaded dependencies. For each dependency that is recursively scanned, LuaRocks will attempt to use the version in the luarocks.lock file, ignoring the version constraints in the rockspec.

When building a package using a lock file, luarocks.lock is copied to the package's metadata directory (e.g. /usr/local/luarocks/rocks/5.3/name/version/luarocks.lock) — if you later pack it as a binary rock with luarocks pack, the lock file will be packaged inside the rock, and will be used when that binary rock is installed with luarocks install.

Updating pinned dependencies

Building a package again with the --pin flag ignores any existing luarocks.lock file and recreates this file, by scanning dependency based on the dependency constraints specified in the rockspec.

It is also possible to edit the luarocks.lock by hand, of course, but there are no checks: if the versions you set for the various dependencies are not compatible with each other, LuaRocks won't be able to do anything about it and will blindly follow what is set on the luarocks.lock file.