FreeBSD Porter's Handbook
Prev | Chapter 6 Special Considerations | Next

# 6.20 Using Lua

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

## 6.20.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.

## 6.20.2 Version Selection

To make your port use a specific version of Lua there are two variables available for defining (if only one is defined the other will be set to a default value):

Table 6-36. Variables to Select Lua Versions

Variable | Description | Default value
--- | --- | ---
`USE_LUA` | List of versions the port can use | All available versions
`USE_LUA_NOT` | List of versions the port can not use | None

The following is a list of available Lua versions and the corresponding ports in the tree:

Table 6-37. Available Lua Versions

Version | Port
--- | ---
`4.0` | `lang/lua4`
`5.0` | `lang/lua50`
`5.1` | `lang/lua`

The variables in Table 6-36 can be set to one or more of the following combinations separated by spaces:

Table 6-38. Lua Version Specifications

Description | Example
--- | ---
Single version | `4.0`
Ascending range | `5.0+`
Descending range | `5.0-`
Full range (must be ascending) | `5.0-5.1`

There are also some variables to select the preferred versions from the available ones. They can be set to a list of versions, the first ones will have higher priority.

Table 6-39. Variables to Select Preferred Lua Versions

Name | Designed for
--- | ---
`WANT_LUA_VER` | the port
`WITH_LUA_VER` | the user

Example 6-11. Selecting the Lua Version

The following fragment is from a port which can use Lua version `5.0` or `5.1`, and uses `5.0` by default. It can be overridden by the user with `WITH_LUA_VER`.

    USE_LUA=	5.0-5.1
    WANT_LUA_VER=	5.0

## 6.20.3 Component Selection

There are other applications that, while not being Lua libraries, are related to them. These applications can be specified in the `LUA_COMPS` variable. The following components are available:

Table 6-40. Available Lua Components

Name | Description | Version restriction
--- | --- | ---
`lua` | main library | none
`tolua` | Library for accessing C/C++ code | `4.0-5.0`
`ruby` | Ruby bindings | `4.0-5.0`

> Note: There are more components but they are modules for the interpreter, not used by applications (only by other modules).

The dependency type can be selected for each component by adding a suffix separated by a semicolon. If not present then a default type will be used (see Table 6-42). The following types are available:

Table 6-41. Available Lua Dependency Types

Name | Description
--- | ---
`build` | Component is required for building, equivalent to `BUILD_DEPENDS`
`run` | Component is required for running, equivalent to `RUN_DEPENDS`
`lib` | Component is required for building and running, equivalent to `LIB_DEPENDS`

The default values for the components are detailed in the following table:

Table 6-42. Default Lua Dependency Types

Component | Dependency type
--- | ---
`lua` | `lib` for `4.0-5.0` (shared) and `build` for `5.1` (static)
`tolua` | `build` (static)
`ruby` | `lib` (shared)

Example 6-12. Selecting Lua Components

The following fragment corresponds to a port which uses Lua version `4.0` and its Ruby bindings.

    USE_LUA=	4.0
    LUA_COMPS=	lua ruby

## 6.20.4 Detecting Installed Versions

To detect an installed version you have to define `WANT_LUA`. If you do not set it to a specific version then the components will have a version suffix. The `HAVE_LUA` variable will be filled after detection.

Example 6-13. Detecting Installed Lua Versions and Components

The following fragment can be used in a port that uses Lua if it is installed, or an option is selected.

    WANT_LUA=	yes

    .include <bsd.port.pre.mk>

    .if defined(WITH_LUA5) || !empty(PORT_OPTIONS:MLUA5) || !empty(HAVE_LUA:Mlua-5.[01])
    USE_LUA=		5.0-5.1
    CONFIGURE_ARGS+=	--enable-lua5
    .endif

The following fragment can be used in a port that enables tolua support if it is installed or if an option is selected, in addition to Lua, both version `4.0`.

    USE_LUA=	4.0
    LUA_COMPS=	lua
    WANT_LUA=	4.0

    .include <bsd.port.pre.mk>

    .if defined(WITH_TOLUA) || !empty(PORT_OPTIONS:MTOLUA) || !empty(HAVE_LUA:Mtolua)
    LUA_COMPS+=		tolua
    CONFIGURE_ARGS+=	--enable-tolua
    .endif

## 6.20.5 Defined Variables

The following variables are available in the port (after defining one from Table 6-36).

Table 6-43. Variables Defined for Ports That Use Lua

Name | Description
--- | ---
`LUA_VER` | The Lua version that is going to be used (e.g., `5.1`)
`LUA_VER_SH` | The Lua shared library major version (e.g., `1`)
`LUA_VER_STR` | The Lua version without the dots (e.g., `51`)
`LUA_PREFIX` | The prefix where Lua (and components) is installed
`LUA_SUBDIR` | The directory under `${PREFIX}/bin`, `${PREFIX}/share` and `${PREFIX}/lib` where Lua is installed
`LUA_INCDIR` | The directory where Lua and tolua header files are installed
`LUA_LIBDIR` | The directory where Lua and tolua libraries are installed
`LUA_MODLIBDIR` | The directory where Lua module libraries (`.so`) are installed
`LUA_MODSHAREDIR` | The directory where Lua modules (`.lua`) are installed
`LUA_PKGNAMEPREFIX` | The package name prefix used by Lua modules
`LUA_CMD` | The path to the Lua interpreter
`LUAC_CMD` | The path to the Lua compiler
`TOLUA_CMD` | The path to the tolua program

Example 6-14. Telling the Port Where to Find Lua

The following fragment shows how to tell a port that uses a configure script where the Lua header files and libraries are.

    USE_LUA=	4.0
    GNU_CONFIGURE=	yes
    CONFIGURE_ENV=	CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"

## 6.20.6 Processing in `bsd.port.pre.mk`

If you need to use the variables for running commands right after including `bsd.port.pre.mk` you need to define `LUA_PREMK`.

> Important: If you define `LUA_PREMK`, then the version, dependencies, components and defined variables will not change if you modify the Lua port variables after including `bsd.port.pre.mk`.

Example 6-15. Using Lua Variables in Commands

The following fragment illustrates the use of `LUA_PREMK` by running the Lua interpreter to obtain the full version string, assign it to a variable and pass it to the program.

    USE_LUA=	5.0
    LUA_PREMK=	yes

    .include <bsd.port.pre.mk>

    .if exists(${LUA_CMD})
    VER_STR!=	${LUA_CMD} -v

    CFLAGS+=	-DLUA_VERSION_STRING="${VER_STR}"
    .endif

> Note: The Lua variables can be safely used in commands when they are inside targets without the need of `LUA_PREMK`.

Prev | Home | Next
Using wxWidgets | Up | Using Xfce

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.