lua Release Notes

Release 4-0

Major Changes

  • Lua language updated to 5.5.1 (from 5.4.6). The one incompatibility to note: global is now a reserved word and must not be used as a variable or parameter name. See the Lua 5.5 reference manual for language changes.

  • luaaa dependency removed. All libraries now use the standard Lua C API directly, restoring compatibility with older toolchains; the CXX11_SUPPORT build flag is gone.

  • Basic and main library versions unified. All platforms get the same full-featured library code.

New Features

  • Nine new DTYP “lua” record types: int64in, int64out, mbbiDirect, mbboDirect, lsi, lso, waveform, aai, and aao. int64in/int64out require EPICS base 7.0+ (omitted automatically on 3.15) and preserve full 64-bit integer precision.

  • Unified run/load command family: luaRunString, luaRunFile (with async=true option), and luaShell, available identically from iocsh, Lua, and the C API. See Deprecations for the old names.

  • LUA_SCRIPT_PATH unified with require() – one path registry feeds both script resolution and require().

  • luaAddPath/luaAddModule commands for registering directories with both require() and script resolution; luaAddModule wraps an EPICS module’s lib/<arch> and bin/<arch> paths.

  • luascript POPT/PCAL fields for conditional processing, with per-input changed flags (_A-_J, _AA-_JJ).

  • luascript IVOA/IVOV fields controlling output behavior on script error (standard menuIvoa).

  • luascript array (table) output (CODE returning a Lua table writes AVAL, element type from contents) and async rework (uses the EPICS callback system instead of a thread per process cycle).

  • luascript string fields expanded: AA-JJ, SVAL, PSVL to 256 chars; ERR to 256 chars.

  • epics library get/put enhancements: array support (Lua tables), an options table (timeout, count, string), integer-preserving returns, a local-PV fast path (direct dbGet/PutField), a shared process-wide CA context, and return conventions (nil, "error" / error-string-on-failure). epics.pv() is now proper userdata with pv:get/pv:put methods; epics.sleep is removed (use osi.sleep).

  • db.entry() method syntax (ent:findRecord(...) as well as db.findRecord(ent, ...)).

  • info() function in all Lua states to list a library’s functions or an object’s methods/properties.

  • New libraries: bytestream (scanf/printf-style device I/O over asyn.client, StreamDevice-style specifiers), event (inter-thread event flags), seq (Lua-native state-machine sequencer), and embedded lpeg 1.1.0 (with re).

  • osi time functions: osi.monotonic(), osi.time(), osi.timestr().

  • Per-client asyn timeouts: ReadTimeout/WriteTimeout on asyn.client and bytestream.client (default 1.0 s).

  • #- silent comments when hash comments are enabled.

  • Lua state reference counting (luaStateRef/luaStateUnref).

Deprecations

The following names are deprecated in favor of the unified vocabulary. They continue to work, and each emits a one-time warning (via the EPICS error log) on first use naming its replacement. They will be removed in a future release.

Deprecated Replacement
luaCmd luaRunString
luaLoadFile luaRunFile
luaSpawn luaRunFile with option async=true
luash / luashLoad luaShell
luaNamedState luaGetState
luaFindNamedState luaFindState
luaRegisterState luaNameState
luaStateIsRegistered luaStateIsNamed

luaRegisterFunction and luaRegisterLibrary are not deprecated – “Register” now exclusively means extension registration.

Bug Fixes

  • Concurrent shell sessions no longer interfere (each uses its own thread-local state).

  • Shared Lua state thread safety – states shared across DTYP device support, luascript records, and the shell are serialized with a per-state lock, with a consistent lock order that removes an AB-BA deadlock.

  • luascript record “On Change” output now detects value changes correctly.

  • luascript boolean return – true/false from CODE now sets VAL to 1/0.

  • luascript DBD fields corrected for 64-bit systems (OUTV default now “Ext PV OK”).

  • DTYP INP/OUT parsing is quote/paren aware – commas/spaces inside quotes and nested parentheses are parsed correctly.

  • Asyn octet read buffer increased from 256 to 1024 bytes.

  • asyn setTraceIO / client:traceio masks corrected (ascii, escape, hex keys set the right bits).

  • Various fixes for memory leaks, null-pointer and thread safety, GC cleanup of db.entry/db.record objects, error messages (routed to the EPICS error log, no longer truncated at colons), longer DTYP buffers, luascript numeric-array-input overruns and table-output typing, empty macro/parameter values, luaRegisterState name collisions, legacy port-driver parameter callbacks and octet bounds, and param.uint32digital parameter typing.

Release 3-1

Version Changes

  • Lua language version updated to 5.4.6
  • luaaa library version updated to 1.0

Library Changes:

Included libraries now have extended capabilities when built with a compiler that supports C++11. To enable these capabilities, define CXX11_SUPPORT=YES in a CONFIG_SITE.local file. Changes are noted below.

asyn

  • Added setOption function

  • New include file, ‘lasynlib.h’ to allow external creation of lua asynPortDriver and asynOctetClient classes

  • C++11 Only: asynOctetClient and asynPortDriver changed to be proper c++ classes. Use asynOctetClient.find and asynPortDriver.find to construct instead of client and driver functions.

epics

  • New include file, ‘lepicslib.h’ to allow external creation of lua PV class
  • sleep function deprecated

db

  • All static database access functions implemented
  • Can specify callback function that is triggered whenever a database is loaded

osi

  • New library for os independent functions
  • sleep function moved here

Other Changes:

  • print function now uses epicsStdoutPrintf behind the scenes to allow output redirection
  • Added luaLoadLibrary function to trigger library load in a given lua_state

Release 3-0-2

  • Various bug fixes relating to proper link handling
  • Fixed another windows build issue relating to order of includes
  • Enum input field support added, fields are grabbed as string value.

Release 3-0-1

  • Fix issues for windows builds.

Release 3-0

  • Lua language version updated to 5.4.0
  • “db” library added. Allows users to generate records within lua scripts during IOC startup.
  • luaPortDriver added. Generates an asynPortDriver based off of a lua script. Each parameter is defined within lua and links to a snippet of lua code, with the code being run whenever the parameter is read or written (depending on how the parameter is defined).
  • Named lua states added. Can create lua_States that can be shared between instances of lua scripts by name.
  • The command exit in the lua shell changed from a specially recognized word to a lua function so that it can be properly parsed within a chunk. Allows it to be used in a conditional or loop.
  • luascriptRecord AA-JJ inputs can now take in arrays and the record can also write out to array records.
  • luaShell.h API changed, luashBegin renamed to luashLoad to match IOC shell naming conventions, C++ overloads of luash command to allow for lua_States to be given to shell to set the environment.
  • Added functions to luaEpics.h to provide scoped environment variables, changed luaLoadMacros to use scopes.
  • Fixed an issue with too many temp files being created and deleted by the iocsh library.

Release 2-1

  • LUA_SCRIPT_PATH now always includes the current directory. Makes more sense when using ‘<’ in the lua shell.
  • Previously, the “iocsh” library was used only to lookup ioc shell functions, now it will now also check for environment variables that match the given name.
  • “iocsh” library lookups now also fixed to return nil when it can’t find a matching element (in R2-0 it was returning functions that, when called, stated nothing was found).
  • Added setOption function to the “asyn” library. works the same way as asynSetOption. The asyn.client class received a matching function.
  • Fixed bug in “asyn” library where writeread requests were attempting to read twice, causing timeout waits.
  • Added luashCmd function to ioc shell. Useful for running one-liners of lua code.
  • lua shell now specially recognizes the line ‘#ENABLE_HASH_COMMENTS’, when put into a lua shell script, the shell will ignore lines where the first non-whitespace line is a ‘#’ character. Allowing scripts to appear more like regular ioc shell scripts.
  • lua shell now ignores leading whitespace on lines, was only an issue with the ‘exit’ and ‘<’ commands.
  • Fixed an issue where I was leaving a metatable reference on the lua stack when luaCreateState was called.
  • Documentation has been switched to use ReStructured text, now hosted on https://epics-lua.readthedocs.io/en/latest/

Release 2-0

  • “iocsh” library now available for any version of base
  • Calls to the “iocsh” library can omit the library name while within the luash interpreter, this makes the luash almost fully backwards compatible with iocsh scripts. The only problems come from comments (due to “#” being a command in lua) and macros being different than global variables.
  • Better error handling in “asyn” library
  • lua Script file location now allows full paths
  • loadRegistered function automatically triggered and no longer needed for lua startup scripts
  • Lua static library registration now setup to work with standard lua “require” functionality
  • ‘asyn’ lua library function “port” changed to “client” to better represent that it is creating an asynOctetClient not an asynPortDriver. InTerminator and OutTerminator changed to member fields rather than get/set functions.
  • ‘asyn’ lua library new function “driver” creates an object representing an asynPortDriver. Allows you to get/set the value of parameters in the paramList and trigger the read and write functions of parameters.
  • Parameters supplied in luaRecord CODE field and macros provided to luaSpawn are now evaluated using a lua sandbox environment rather than a custom parser.

Release 1-3

  • Fixes compilation issues for Visual Studio 2010
  • Dynamic library loading enabled for Linux architectures
  • C functions can now be registered into lua libraries that will automatically load on lua shell startup.
  • Also set up a quick way to bind functions already loaded into the IOC shell
  • All libraries loaded into shell, device support, and luascript record
  • luaEpics functions are now able to be used in C files
  • Added luaSpawn function to allow for running scripts in the background
  • Full Documentation

Release 1-2-2

  • Fixed a compilation bug on vxWorks
  • First official synApps release

Release 1-2-1

  • Fixed a bug where softChannel support wasn’t working
  • luascript’s CODE field is no longer saved by autosave on every luascript record, just for the user luascripts.

Release 1-2

  • Fixed building for Windows
  • Added global reference to the pdbbase variable, allows lua shell to be used as a full replacement for iocsh
  • Added ‘<’ command to luash to include the contents of other scripts
  • luaScript input fields now can have descriptions of their contents
  • Fixed a bug where forward link processing wasn’t happening

Release 1-1

  • luash function now runs as a command shell or an interpreter
  • Lua asyn library function to access ports as lua objects
  • LUASH_PS1 variable for lua shell prompt

Release 1-0

  • First public release on github
Suggestions and Comments to:
Keenan Lang