Lua4z
A binary distribution of Lua for z/OS, with batteries

Installing

System requirements

Lua4z requires z/OS 1.12, or later.

Skills required

To install Lua4z, you need to know how to:

  • Transfer files to z/OS UNIX

  • Enter commands at a z/OS UNIX command prompt

To configure your system to run Lua programs on z/OS UNIX, you should understand symlinks and how to define environment variables: for example, to add the Lua4z bin directory to PATH.

To configure your system to run Lua programs on MVS (including TSO/E), you need to know how to:

  • Add data sets to LINKLIST or edit TSO/E logon procedures

  • Edit MVS data sets in the ISPF editor

To configure your system to run Lua programs from an ISPF command prompt without specifying the command prefix TSO, you need to know how to add verbs to an ISPF command table.

Overview

Lua4z is distributed as a single file, with file extension .bin, available from the Lua4z website. The .bin file is a self-extracting installation script.

More specifically, the .bin file is a z/OS UNIX shell script, encoded in EBCDIC code page 1047, that includes a compressed binary payload in pax.z format.

To install Lua4z, you transfer the .bin file to your z/OS UNIX file system and then run it. The script uncompresses its payload (the Lua4z distribution directories), and then runs a second installation script included in that payload.

Distribution directories

The installation script prompts you for the path of a Lua4z home directory in z/OS UNIX, and then uncompresses the following directories under that home directory:

Lua4z distribution directories
Name Contents
bin Executable programs.
doc Lua4z documentation in HTML format. Start browsing at the index.html file.

These files are also published on the Lua4z website. The website might contain more recent documentation than this downloaded distribution directory.

examples Example files, including example Lua programs.
include C/C++ header files.

These files are useful if you want to use the Lua C programming API.

If you just want to develop and run Lua programs, you do not need these files.

install The second installation script, written in Lua.
lib Shared object (.so) files, including the shared object for the Lua standard libraries (liblua.so) and files for Lua extensions.
loadmodules MVS-specific versions of the Lua interpreter, compiler, and standard libraries.
man UNIX man page directory. Empty.
share Lua programs (.lua files) for Lua extensions.

Some Lua extensions are shared object (.so) files; some are Lua program (.lua) files; some consist of both types of file. The .so files are distributed in the lib directory; the .lua files are distributed in this share directory.

MVS data sets

The installation script copies files from the distribution directories into the following MVS data sets. The data set names shown here are the names suggested by the installation script; you can specify your own names. If the data sets do not exist, the installation script allocates them.

Lua4z MVS data sets
Default data set name Contents
SYS1.LUA4Z.LOADLIB Library containing MVS-specific versions of the Lua interpreter, compiler, and standard libraries.

Copied from the loadmodules distribution directory.

SYS1.LUA4Z.SAMPLIB Partitioned data set (PDS) containing sample files, including Lua programs.

Copied from the examples distribution directory.

Configuration: paths, environment variables, and symlinks

After installing the Lua4z distribution directories on your z/OS UNIX file system, the installation script configures your system to make the Lua4z files accessible in various paths.

Summary of configuration requirements

Before installing Lua4z, you need to understand what files Lua4z uses and in what paths those files need to be accessible:

  • The executable programs in the Lua4z bin directory must be accessible via the PATH environment variable.

  • The Lua standard libaries shared object file in the Lua4z lib directory, liblua.so, must be accessible via the LIBPATH environment variable.

  • The .so files for Lua extensions must be accessible via the Lua package.cpath property. You can override the default value of package.cpath by defining a LUA_CPATH environment variable.

  • The Lua programs (.lua files) for Lua extensions must be accessible via the Lua package.path property. You can override the default value of package.path by defining a LUA_PATH environment variable.

For more details on how Lua uses package.path and package.cpath, see the Lua Reference Manual.

If you accept all the defaults suggested by the installation script, the files will be accessible in the required paths without defining or modifying any environment variables.

However, if you choose not to accept the defaults, you need to perform these configuration steps yourself.

PATH environment variable

To run Lua programs on z/OS UNIX, your PATH environment variable must refer to a directory that contains the Lua4z executable programs. The executable programs are supplied in the Lua4z bin directory.

Here are two methods to meet this requirement:

  • The method offered by the installation script: in a directory that is already in your PATH, such as /usr/local/bin, create symlinks that refer to each of the files in the Lua4z bin directory.

  • Add the Lua4z bin directory to PATH.

The PATH environment variable is only relevant when running Lua programs on z/OS UNIX. To run Lua programs on MVS (including TSO/E), Lua4z supplies MVS-specific versions of the Lua interpreter and the Lua standard libraries in the Lua4z loadmodules directory. The installation script copies these load modules to an MVS data set; you need to add this data set to your LINKLIST or STEPLIB concatenation.

LIBPATH environment variable

To run Lua programs on z/OS UNIX, your LIBPATH environment variable must refer to a directory that contains the standard libraries shared object file, liblua.so. This file is supplied in the Lua4z lib directory.

Here are two methods to meet this requirement:

  • The method offered by the installation script: in a directory that is already in your LIBPATH, such as /usr/local/lib, create a symlink that refers to the Lua4z lib directory.

  • Add the Lua4z lib directory to LIBPATH.

    If you want to run Lua programs on z/OS UNIX, use the export command to modify LIBPATH.

    If you want to run Lua programs on MVS, define LIBPATH in a LUACONF member of the LUA ddname.

To run Lua programs on MVS, the MVS-specific version of the Lua interpreter uses the standard libraries DLL that is in the same MVS data set as the interpreter, not the liblua.so file in the lib directory. However, Lua extension shared object files refer to the liblua.so file in the lib directory regardless of whether the Lua program that requires the extensions is run by the MVS version of the Lua interpreter or the z/OS UNIX version.

package.cpath and the LUA_CPATH environment variable

Lua programs can use the require function to refer to shared object (.so) files, such as .so files supplied by Lua extensions.

To locate shared object files, the require function searches a list of file path patterns specified by the Lua package.cpath property. package.cpath can be initialized by the LUA_CPATH environment variable.

If LUA_CPATH is not defined, package.cpath has the following default value (line breaks shown here for presentation only):

./?.so;
/usr/local/lib/lua/5.1/?.so;
/usr/local/lib/lua/5.1/loadall.so;
//?

Tip: The //? pattern is a Lua4z-specific addition that enables the require function to search MVS data sets.

package.cpath must refer to the Lua4z lib directory.

Here are two methods to meet this requirement:

  • The method offered by the installation script: create a symlink that refers to the Lua4z lib directory.

    By default, the script creates the symlink in the /usr/local/lib directory.

  • Define a LUA_CPATH environment variable that refers to the Lua4z lib directory.

    For example, if the Lua4z home directory is /u/myid/install/lua4z:

    ./?.so;
    /u/myid/install/lua4z/lib/lua/5.1/?.so;
    /u/myid/install/lua4z/lib/lua/5.1/loadall.so;
    //?
    

    If you want to run Lua programs on z/OS UNIX, use the export command to define LUA_CPATH.

    If you want to run Lua programs on MVS, define LUA_CPATH in a LUACONF member of the LUA ddname.

package.path and the LUA_PATH environment variable

Lua programs can use the require function to refer to other Lua programs, such as programs supplied by Lua extensions.

To locate Lua programs, the require function searches a list of file path patterns specified by the Lua package.path property. package.path can be initialized by the LUA_PATH environment variable.

If LUA_PATH is not defined, package.path has the following default value (line breaks shown here for presentation only):

./?.lua;
/usr/local/share/lua/5.1/?.lua;
/usr/local/share/lua/5.1/?/init.lua;
/usr/local/lib/lua/5.1/?.lua;
/usr/local/lib/lua/5.1/?/init.lua;
//DD:LUA(?)

Tip: The //DD:LUA(?) pattern is a Lua4z-specific addition that enables the require function to refer to members in the concatenation specified by the LUA ddname, such as members of MVS partitioned data sets.

package.path must refer to the Lua4z share directory.

Here are two methods to meet this requirement:

  • The method offered by the installation script: create a symlink that refers to the Lua4z share directory. By default, the script creates the symlink in the /usr/local/share directory.

  • Define a LUA_PATH environment variable that refers to the Lua4z share directory (and also, to match the default value of package.path, the lib directory). For example:

    ./?.lua;
    /u/myid/install/lua4z/share/lua/5.1/?.lua;
    /u/myid/install/lua4z/share/lua/5.1/?/init.lua;
    /u/myid/install/lua4z/lib/lua/5.1/?.lua;
    /u/myid/install/lua4z/lib/lua/5.1/?/init.lua;
    //DD:LUA(?)
    

    If you want to run Lua programs on z/OS UNIX, use the export command to define LUA_PATH.

    If you want to run Lua programs on MVS, define LUA_PATH in a LUACONF member of the LUA ddname.

Example configuration

Suppose that you accept none of the configuration defaults offered by the script, and that your Lua4z home directory is /u/myid/install/lua4z. You need to perform the following configuration steps.

In the following examples, the home directory path is highlighted to make it easy for you to replace this path with your own home directory.

On z/OS UNIX:

  1. Add the Lua4z bin directory to the PATH environment variable:

    /u/myid/install/lua4z/bin
    
  2. Add the Lua4z lib directory to the LIBPATH environment variable:

    /u/myid/install/lua4z/lib
    
  3. Define a LUA_CPATH environment variable that refers to the Lua4z lib directory:

    ./?.so;
    /u/myid/install/lua4z/lib/lua/5.1/?.so;
    /u/myid/install/lua4z/lib/lua/5.1/loadall.so;
    //?
    
  4. Define a LUA_PATH environment variable that refers to the Lua4z share directory:

    ./?.lua;
    /u/myid/install/lua4z/share/lua/5.1/?.lua;
    /u/myid/install/lua4z/share/lua/5.1/?/init.lua;
    //DD:LUA(?)
    

For example, you could add the following lines to your z/OS UNIX .profile file:

# Define a local variable for the Lua4z home directory
LUA_HOME=/u/myid/install/lua4z

# Append the Lua4z bin directory to PATH
export PATH="$PATH:$LUA_HOME/bin"

# Append the Lua4z lib directory to LIBPATH
export LIBPATH="$LIBPATH:$LUA_HOME/lib"

# Define LUA_CPATH
# Replace /usr/local in the default package.path
# with the Lua4z home directory
export LUA_CPATH="./?.so;\
$LUA_HOME/lib/lua/5.1/?.so;\
$LUA_HOME/lib/lua/5.1/loadall.so;\
//?"

# Define LUA_PATH
# Replace /usr/local in the default package.path
# with the Lua4z home directory
export LUA_PATH="./?.lua;\
$LUA_HOME/share/lua/5.1/?.lua;\
$LUA_HOME/share/lua/5.1/?/init.lua;\
$LUA_HOME/lib/lua/5.1/?.lua;\
$LUA_HOME/lib/lua/5.1/?/init.lua;\
//DD:LUA(?)"

On MVS:

  1. Add the program library containing the MVS versions of the Lua interpreter and shared libraries to the LINKLIST or STEPLIB concatenation; that is, the STEPLIB ddname in your TSO/E logon procedure and in batch JCL that invokes the Lua interpreter.

  2. Define a LUA ddname in your TSO/E logon procedure and batch JCL that refers to a partitioned data set.

  3. In a partitioned data set referred to by the LUA ddname, create a LUACONF member containing the following single line:

    LUA_HOME = "/u/myid/install/lua4z"
    

    LUA_HOME is a shortcut to defining individual values for LIBPATH, LUA_CPATH, and LUA_PATH. Defining LUA_HOME as shown is equivalent to the following definitions (line breaks between semicolons shown here for presentation only):

    LIBPATH = "/u/myid/install/lua4z/lib"
    LUA_CPATH = "./?.so;
    /u/myid/install/lua4z/lib/lua/5.1/?.so;
    /u/myid/install/lua4z/lib/lua/5.1/loadall.so;
    //?"
    LUA_PATH = "./?.lua;
    /u/myid/install/lua4z/share/lua/5.1/?.lua;
    /u/myid/install/lua4z/share/lua/5.1/?/init.lua;
    /u/myid/install/lua4z/lib/lua/5.1/?.lua;
    /u/myid/install/lua4z/lib/lua/5.1/?/init.lua;
    //DD:LUA(?)"
    

Procedure

  1. Transfer the Lua4z .bin file from the Lua4z website to your z/OS UNIX file system (HFS or zFS).

    Here are two methods for transferring the file:

    • Click the Download button on the home page of the Lua4z website to download the .bin file to your PC (or whatever device you are using to browse the web). Then transfer the file, using binary transfer, to your z/OS UNIX file system.

    • Enter the following curl command at a z/OS UNIX command prompt to transfer the .bin file directly from the Lua4z website to the current z/OS UNIX directory:

      curl -O http://lua4z.com/download/lua4z-1.0.0.bin
      

      This method is only available to you if:

      • Your z/OS UNIX system has curl installed. curl is included in IBM Ported Tools for z/OS.
      • Your site security rules allow you to access public URLs.
  2. Verify that the checksum and size of the .bin file match the authentic published file.

    Enter the following command at a z/OS UNIX command prompt, in the directory containing the .bin file:

    cksum lua4z-1.0.0.bin
    

    The command output should match the two numbers shown next to the Download button on the Lua4z website.

  3. Check that your file system has enough free space.

    The installation script needs 23 megabytes of storage space to uncompress its payload.

    For example, to display the amount of free space in kilobytes in the directory /usr/local, enter the following command:

    df -kP /usr/local
    

    This example command reports available space in kilobytes: Lua4z needs 23000.

  4. Make the installation script executable.

    Enter the following command:

    chmod +x lua4z-1.0.0.bin
    
  5. Run the script.

    Enter the script file name:

    ./lua4z-1.0.0.bin
    

    Note: The ./ prefix ensures that you run the .bin file that is in the current directory.

    The script interactively prompts you to answer questions and specify z/OS paths or MVS data set names.

    To accept a default value that the script suggests (in parentheses), press Enter.

    Here is an example transcript showing user input and comments:

    MYID:/u/myid: >lua4z-1.0.0.bin
    
    The Lua4z software license agreement is available on the web at:
    
    http://lua4z.com/license
    
    Please read the license carefully.
    
    The installed software includes a copy of the license
    in the lua4z/doc directory.
    
    Have you read, understood, and accepted the terms of the license? (yes or no)
    yes
    Enter home directory (/usr/local/lua4z) : where to uncompress the distribution directories
    /u/myid/install/lua4z
    /u/myid/install/lua4z is not an existing directory, create it? (y/n) :
    y
    
    Enter new or existing target PDSE load module library name
    (SYS1.LUA4Z.LOADLIB) where to copy the MVS-specific load modules
    MYID.LUA4Z.LOADLIB
    /u/myid/install/lua4z/loadmodules/LIBLUA -> MYID.LUA4Z.LOADLIB(LIBLUA): executable
    /u/myid/install/lua4z/loadmodules/LUA -> MYID.LUA4Z.LOADLIB(LUA): executable
    
    Enter new or existing target PDS for samples (SYS1.LUA4Z.SAMPLIB)
    MYID.LUA4Z.SAMPLIB
    /u/myid/install/lua4z/examples/filename -> MYID.LUA4Z.SAMPLIB(member): type
    ...one line for each example file copied...
    
    Enter PATH directory in which to create command symlinks
    or 'none' (/usr/local/bin) a directory referred to by the PATH environment variable
    /u/myid/bin
    created symlink /u/myid/bin/lua -> /u/myid/install/lua4z/bin/lua
    created symlink /u/myid/bin/luac -> /u/myid/install/lua4z/bin/luac
    created symlink /u/myid/bin/ldoc -> /u/myid/install/lua4z/bin/ldoc
    created symlink /u/myid/bin/orbit -> /u/myid/install/lua4z/bin/orbit
    created symlink /u/myid/bin/wsapi -> /u/myid/install/lua4z/bin/wsapi
    
    Enter LIBPATH/LUA_CPATH directory in which to create shared object symlinks
    or 'none' (/usr/local/lib)
    /u/myid/lib
    created symlink /u/myid/lib/liblua.so -> /u/myid/install/lua4z/lib/liblua.so
    created symlink /u/myid/lib/lua -> /u/myid/install/lua4z/lib/lua
    The LIBPATH environment variable must refer to the location of liblua.so.
    LUA_CPATH must refer to the location of the lib/lua directory.
    
    Enter the LUA_PATH directory in which to create Lua module symlinks
    or 'none' (/usr/local/share)
    /u/myid/share
    created symlink /u/myid/share/lua -> /u/myid/install/lua4z/share/lua
    
    Enter the include directory in which to create header file symlinks
    or 'none' (/usr/local/include)
    none
    

    If you accepted all the default values, continue to the next step.

    Otherwise, before continuing, perform the configuration steps as described in the overview.

  6. If you want to run Lua programs on MVS (rather than only on z/OS UNIX), make the data set that contains the MVS version of the Lua interpreter available to users.

    Add the data set to either:

    • The LINKLIST concatenation
    • The STEPLIB ddname in your TSO/E logon procedure and in any JCL that invokes the Lua interpreter
  7. If you want to run Lua programs on ISPF, add the following two verbs to an ISPF command table:

    ISPF command table verbs for the Lua interpreter
    Verb Trunc Action Description
    LUA 0 SELECT SUSPEND CMD(LUA &ZPARM) Runs the Lua interpreter
    LUAP 0 SELECT SUSPEND CMD(LUA POSIX(ON)/&ZPARM) Runs the Lua interpreter with the Language Environment runtime option POSIX(ON)

    These verbs enable you to invoke the Lua interpeter from an ISPF command prompt without specifying the command prefix TSO.

    You can either add these verbs yourself using ISPF option 3.9 or you can copy the USERCMDS member from the Lua4z SAMPLIB library to a library in your ISPTLIB concatenation.

  8. Run the installation verification program supplied in the examples directory.

    Enter the following command at a z/OS UNIX command prompt. Replace home with your Lua4z home directory.

    lua home/examples/ivp.lua
    

    Enter the following command at an ISPF command prompt. If you specified your own data set name for the MVS sample library, replace SYS1.LUA4Z.SAMPLIB with your data set name.

    lua "//'SYS1.LUA4Z.SAMPLIB(IVP)'"
    

    If any path tests fail, run paths.lua to display the path values; for details on specifying correct path values, see the overview.

Next: learn more about running Lua programs on z/OS.