6.22. Using Lua

This section describes the status of the Lua libraries in the ports tree and its integration with the ports system.

6.22.1. Introduction

There are many versions of the Lua libraries and corresponding interpreters, which conflict between them (install files under the same name). In the ports tree this problem has been solved by installing each version under a different name using version number suffixes.

The obvious disadvantage of this is that each application has to be modified to find the expected version. But it can be solved by adding some additional flags to the compiler and linker.

Applications that use Lua should normally build for just one version. However, loadable modules for Lua are built in a separate flavor for each Lua version that they support, and dependencies on such modules should specify the flavor using the @${LUA_FLAVOR} suffix on the port origin.

6.22.2. Version Selection

A port using Lua should have a line of this form:

USES=	lua

If a specific version of Lua, or range of versions, is needed, it can be specified as a parameter in the form XY (which may be used multiple times), XY+, -XY, or XY-ZA. The default version of Lua as set via DEFAULT_VERSIONS will be used if it falls in the requested range, otherwise the closest requested version to the default will be used. For example:

USES=	lua:52-53

Note that no attempt is made to adjust the version selection based on the presence of any already-installed Lua version.


The XY+ form of version specification should not be used without careful consideration; the Lua API changes to some extent in every version, and configuration tools like CMake or Autoconf will often fail to work on future versions of Lua until updated to do so.

6.22.3. Configuration and Compiler flags

Software that uses Lua may have been written to auto-detect the Lua version in use. In general ports should override this assumption, and force the use of the specific Lua version selected as described above. Depending on the software being ported, this might require any or all of:

  • Using LUA_VER as part of a parameter to the software's configuration script via CONFIGURE_ARGS or CONFIGURE_ENV (or equivalent for other build systems);

  • Adding -I${LUA_INCDIR}, -L${LUA_LIBDIR}, and -llua-${LUA_VER} to CFLAGS, LDFLAGS, LIBS respectively as appropriate;

  • Patch the software's configuration or build files to select the correct version.

6.22.4. Version Flavors

A port which installs a Lua module (rather than an application that simply makes use of Lua) should build a separate flavor for each supported Lua version. This is done by adding the module parameter:

USES=	lua:module

A version number or range of versions can be specified as well; use a comma to separate parameters.

Since each flavor must have a different package name, the variable LUA_PKGNAMEPREFIX is provided which will be set to an appropriate value; the intended usage is:


Module ports should normally install files only to LUA_MODLIBDIR, LUA_MODSHAREDIR, LUA_DOCSDIR, and LUA_EXAMPLESDIR, all of which are set up to refer to version-specific subdirectories. Installing any other files must be done with care to avoid conflicts between versions.

A port (other than a Lua module) which wishes to build a separate package for each Lua version should use the flavors parameter:

USES=	lua:flavors

This operates the same way as the module parameter described above, but without the assumption that the package should be documented as a Lua module (so LUA_DOCSDIR and LUA_EXAMPLESDIR are not defined by default). However, the port may choose to define LUA_DOCSUBDIR as a suitable subdirectory name (usually the port's PORTNAME as long as this does not conflict with the PORTNAME of any module), in which case the framework will define both LUA_DOCSDIR and LUA_EXAMPLESDIR.

As with module ports, a flavored port should avoid installing files that would conflict between versions. Typically this is done by adding LUA_VER_STR as a suffix to program names (e.g. using USES=uniquefiles), and otherwise using either LUA_VER or LUA_VER_STR as part of any other files or subdirectories used outside of LUA_MODLIBDIR and LUA_MODSHAREDIR.

6.22.5. Defined Variables

These variables are available in the port.

Table 6.39. Variables Defined for Ports That Use Lua
LUA_VERThe Lua version that is going to be used (for example, 5.1)
LUA_VER_STRThe Lua version without the dots (for example, 51)
LUA_FLAVORThe flavor name corresponding to the selected Lua version, to be used for specifying dependencies
LUA_BASEThe prefix that should be used to locate Lua (and components) that are already installed
LUA_PREFIXThe prefix where Lua (and components) are to be installed by this port
LUA_INCDIRThe directory where Lua header files are installed
LUA_LIBDIRThe directory where Lua libraries are installed
LUA_REFMODLIBDIRThe directory where Lua module libraries (.so) that are already installed are to be found
LUA_REFMODSHAREDIRThe directory where Lua modules (.lua) that are already installed are to be found
LUA_MODLIBDIRThe directory where Lua module libraries (.so) are to be installed by this port
LUA_MODSHAREDIRThe directory where Lua modules (.lua) are to be installed by this port
LUA_PKGNAMEPREFIXThe package name prefix used by Lua modules
LUA_CMDThe name of the Lua interpreter (e.g. lua53)
LUAC_CMDThe name of the Lua compiler (e.g. luac53)

These additional variables are available for ports that specified the module parameter:

Table 6.40. Variables Defined for Lua Module Ports
LUA_DOCSDIRthe directory to which the module's documentation should be installed.
LUA_EXAMPLESDIRthe directory to which the module's example files should be installed.

6.22.6. Examples

Example 6.29. Makefile for an application using Lua

This example shows how to reference a Lua module required at run time. Notice that the reference must specify a flavor.

PORTNAME=	sample
CATEGORIES=	whatever

MAINTAINER=	john@doe.tld

RUN_DEPENDS=	${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR}

USES=		lua

.include <bsd.port.mk>

Example 6.30. Makefile for a simple Lua module
PORTNAME=	sample
CATEGORIES=	whatever

MAINTAINER=	john@doe.tld

USES=		lua:module


.include <bsd.port.mk>

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.