Lua Support

Jamplus contains a minimal distribution of LuaPlus. Any LuaBinaries capable module can run in the LuaPlus environment. Just drop it in the appropriate directory.

The scripts in the source:bin/scripts folder are written in Lua.

The Jamplus executable has Lua support built in, available for use during the rule parsing phase and when actions are running.

Using Lua in Rules

There are two Lua rules available for use during the rule parsing phase of Jamplus.

  • LuaString LUA_SCRIPT: Execute LUA_SCRIPT, returning any results back to the caller.
  • LuaFile LUA_FILENAME: Execute LUA_FILENAME.

Within a Lua script, it is possible to access Jam variables and execute Jam rules.

  • jam_getvar(VARIABLE_NAME): Retrieves VARIABLE_NAME from the active Jam globals and returns it as a table.
  • jam_getvar(TARGET_NAME, VARIABLE_NAME): Retrieves VARIABLE_NAME from TARGET_NAME as if an on TARGET_NAME had been issued. Returns the result as a Lua table.
  • jam_setvar(VARIABLE_NAME, VALUE): Sets VALUE into the active Jam global VARIABLE_NAME. VALUE can be a boolean, number, string, or table. Nested tables are collapsed.
  • jam_setvar(TARGET_NAME, VARIABLE_NAME, VALUE): Sets VALUE into VARIABLE_NAME as if an on TARGET_NAME had been issued. VALUE can be a boolean, number, string, or table. Nested tables are collapsed.
  • jam_evaluaterule(RULE_NAME [, PARAMETERS]): Executes rule RULE_NAME using any optional PARAMETERS specified. Returns the result as a Lua table.

Using Lua in Actions

Using the new lua modifier for an action, Lua script can be run in a thread within the Jam process.

actions lua RunLuaScript
{
    require 'iox'; iox.Sleep($(SLEEP)); print([[$(TEXT)]])
}

See source:tests/lua/testluaaction.jam for a more detailed example.