Lua - Module Versioning

Quiz

Module versioning is crucial in dependency management especially in large lua projects. Using versions, we can maintain compatability checks and can handle updates easily. In this chapter, we're discussion various options as how to create and manage versions of modules.

Simple Approach - Store Version within Module

It is most easier and commonly used technique to maintain modules version. A version identified by _VERSION is stored in the module table returned. We can choose other name as well but generally _VERSION is preferred.

Create module with _VERSION string.

my_module.lua

local my_module = {}

my_module._VERSION = "1.0.2"

function my_module.some_function()
   print("Performing some function in version:",my_module._VERSION)
end

return my_module

Now using version, we can decide the function to be called or arguments to be passed.

main.lua

local my_module = require("my_module")
print("Using my_module version:", my_module._VERSION)

-- Execute code based on version
if my_module._VERSION:match("^1%.") then
  -- execute code as per version 1.x.x
  my_module.some_function()
else
  -- execute code for higher version
  print("Using a newer version with new function")
end

Output

When we run the above program, we will get the following output−

Using my_module version:        1.0.2
Performing some function in version:    1.0.2

Simple Approach - Store Version within Module

Create module with _VERSION string.

my_module.lua

local my_module = {}

my_module._VERSION = "1.0.2"

function my_module.some_function()
   print("Performing some function in version:",my_module._VERSION)
end

return my_module

Now using version, we can decide the function to be called or arguments to be passed.

main.lua

local my_module = require("my_module")
print("Using my_module version:", my_module._VERSION)

-- Execute code based on version
if my_module._VERSION:match("^1%.") then
  -- execute code as per version 1.x.x
  my_module.some_function()
else
  -- execute code for higher version
  print("Using a newer version with new function")
end

Output

When we run the above program, we will get the following output−

Using my_module version:        1.0.2
Performing some function in version:    1.0.2

This approch is simple and straight forward but it does not provide any automated dependency management or version resolution capability.

Separate Version File for Module

We can create a separate version file with a naming convension like my-module-1.0-2.lua and read it using custom loader when a module is loaded or create a file like module.version and ship with my-module.lua. as shown below −

Create module version file

my_module.version

1.0.2

Now read the version in my-module.lua module file.

my_module.lua

local my_module = {}

local function get_version()
   local f = io.open("my_module.version", "r")
   print(f)
   if f then
      local version = f:read("*l")
      f:close()
      return version
   else
      return "unknown"
   end
end

my_module._VERSION = get_version()

function my_module.some_function()
   print("Performing some function in version:",my_module._VERSION)
end

return my_module

Now using version, we can decide the function to be called or arguments to be passed.

main.lua

local my_module = require("my_module")
print("Using my_module version:", my_module._VERSION)

-- Execute code based on version
if my_module._VERSION:match("^1%.") then
  -- execute code as per version 1.x.x
  my_module.some_function()
else
  -- execute code for higher version
  print("Using a newer version with new function")
end

Output

When we run the above program, we will get the following output−

Using my_module version:        1.0.2
Performing some function in version:    1.0.2

This approch separates version from module code and we can automate the versioning process.

External Dependency Management Tools

LuaRocks is an external dependency manager for Lua. It is used generally for large projects or while distributing libraries. LuaRocks provides a framework for −

To package the module with metadata like versions, release informations etc.
To install external dependencies and their management.
To handle versions like installing a specific version or a mininum version of a library.

Whenver we install any Lua library via LuaRocks, LuaRocks stores the version information in the metadata. LuaRocks is a robust dependency management and versioning tool. It provides a standardized way to handle multiple dependencies in a Lua project.

Print Page