ax_lua
======

Synopsis
********

     AX_PROG_LUA[([MINIMUM-VERSION], [TOO-BIG-VERSION], [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])]
     AX_LUA_HEADERS[([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])]
     AX_LUA_LIBS[([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])]
     AX_LUA_READLINE[([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])]

Description
***********

Detect a Lua interpreter, optionally specifying a minimum and maximum version number. Set up important Lua paths, such as the directories in which to install scripts and modules (shared libraries).

Also detect Lua headers and libraries. The Lua version contained in the header is checked to match the Lua interpreter version exactly. When searching for Lua libraries, the version number is used as a suffix. This is done with the goal of supporting multiple Lua installs (5.1, 5.2, and 5.3 side-by-side).

A note on compatibility with previous versions: This file has been mostly rewritten for serial 18. Most developers should be able to use these macros without needing to modify configure.ac. Care has been taken to preserve each macro's behavior, but there are some differences:

1) AX_WITH_LUA is deprecated; it now expands to the exact same thing as AX_PROG_LUA with no arguments.

2) AX_LUA_HEADERS now checks that the version number defined in lua.h matches the interpreter version. AX_LUA_HEADERS_VERSION is therefore unnecessary, so it is deprecated and does not expand to anything.

3) The configure flag --with-lua-suffix no longer exists; the user should instead specify the LUA precious variable on the command line. See the AX_PROG_LUA description for details.

Please read the macro descriptions below for more information.

This file was inspired by Andrew Dalke's and James Henstridge's python.m4 and Tom Payne's, Matthieu Moy's, and Reuben Thomas's ax_lua.m4 (serial 17). Basically, this file is a mash-up of those two files. I like to think it combines the best of the two!

AX_PROG_LUA: Search for the Lua interpreter, and set up important Lua paths. Adds precious variable LUA, which may contain the path of the Lua interpreter. If LUA is blank, the user's path is searched for an suitable interpreter.

If MINIMUM-VERSION is supplied, then only Lua interpreters with a version number greater or equal to MINIMUM-VERSION will be accepted. If TOO-BIG-VERSION is also supplied, then only Lua interpreters with a version number greater or equal to MINIMUM-VERSION and less than TOO-BIG-VERSION will be accepted.

The Lua version number, LUA_VERSION, is found from the interpreter, and substituted. LUA_PLATFORM is also found, but not currently supported (no standard representation).

Finally, the macro finds four paths:

       luadir             Directory to install Lua scripts.
       pkgluadir          $luadir/$PACKAGE
       luaexecdir         Directory to install Lua modules.
       pkgluaexecdir      $luaexecdir/$PACKAGE

These paths are found based on $prefix, $exec_prefix, Lua's package.path, and package.cpath. The first path of package.path beginning with $prefix is selected as luadir. The first path of package.cpath beginning with $exec_prefix is used as luaexecdir. This should work on all reasonable Lua installations. If a path cannot be determined, a default path is used. Of course, the user can override these later when invoking make.

       luadir             Default: $prefix/share/lua/$LUA_VERSION
       luaexecdir         Default: $exec_prefix/lib/lua/$LUA_VERSION

These directories can be used by Automake as install destinations. The variable name minus 'dir' needs to be used as a prefix to the appropriate Automake primary, e.g. lua_SCRIPS or luaexec_LIBRARIES.

If an acceptable Lua interpreter is found, then ACTION-IF-FOUND is performed, otherwise ACTION-IF-NOT-FOUND is preformed. If ACTION-IF-NOT- FOUND is blank, then it will default to printing an error. To prevent the default behavior, give ':' as an action.

AX_LUA_HEADERS: Search for Lua headers. Requires that AX_PROG_LUA be expanded before this macro. Adds precious variable LUA_INCLUDE, which may contain Lua specific include flags, e.g. -I/usr/include/lua5.1. If LUA_INCLUDE is blank, then this macro will attempt to find suitable flags.

LUA_INCLUDE can be used by Automake to compile Lua modules or executables with embedded interpreters. The *_CPPFLAGS variables should be used for this purpose, e.g. myprog_CPPFLAGS = $(LUA_INCLUDE).

This macro searches for the header lua.h (and others). The search is performed with a combination of CPPFLAGS, CPATH, etc, and LUA_INCLUDE. If the search is unsuccessful, then some common directories are tried. If the headers are then found, then LUA_INCLUDE is set accordingly.

The paths automatically searched are:

       * /usr/include/luaX.Y
       * /usr/include/lua/X.Y
       * /usr/include/luaXY
       * /usr/local/include/luaX.Y
       * /usr/local/include/lua-X.Y
       * /usr/local/include/lua/X.Y
       * /usr/local/include/luaXY

(Where X.Y is the Lua version number, e.g. 5.1.)

The Lua version number found in the headers is always checked to match the Lua interpreter's version number. Lua headers with mismatched version numbers are not accepted.

If headers are found, then ACTION-IF-FOUND is performed, otherwise ACTION-IF-NOT-FOUND is performed. If ACTION-IF-NOT-FOUND is blank, then it will default to printing an error. To prevent the default behavior, set the action to ':'.

AX_LUA_LIBS: Search for Lua libraries. Requires that AX_PROG_LUA be expanded before this macro. Adds precious variable LUA_LIB, which may contain Lua specific linker flags, e.g. -llua5.1. If LUA_LIB is blank, then this macro will attempt to find suitable flags.

LUA_LIB can be used by Automake to link Lua modules or executables with embedded interpreters. The *_LIBADD and *_LDADD variables should be used for this purpose, e.g. mymod_LIBADD = $(LUA_LIB).

This macro searches for the Lua library. More technically, it searches for a library containing the function lua_load. The search is performed with a combination of LIBS, LIBRARY_PATH, and LUA_LIB.

If the search determines that some linker flags are missing, then those flags will be added to LUA_LIB.

If libraries are found, then ACTION-IF-FOUND is performed, otherwise ACTION-IF-NOT-FOUND is performed. If ACTION-IF-NOT-FOUND is blank, then it will default to printing an error. To prevent the default behavior, set the action to ':'.

AX_LUA_READLINE: Search for readline headers and libraries. Requires the AX_LIB_READLINE macro, which is provided by ax_lib_readline.m4 from the Autoconf Archive.

If a readline compatible library is found, then ACTION-IF-FOUND is performed, otherwise ACTION-IF-NOT-FOUND is performed.

Source Code
***********

Download the latest version of ax_lua.m4 (http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_lua.m4) or browse the macro's revision history (http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=history;f=m4/ax_lua.m4).

License
*******

Copyright © 2015 Reuben Thomas rrt@sc3d.org
 Copyright © 2014 Tim Perkins tprk77@gmail.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

As a special exception, the respective Autoconf Macro's copyright owner gives unlimited permission to copy, distribute and modify the configure scripts that are the output of Autoconf when processing the Macro. You need not follow the terms of the GNU General Public License when using or distributing such scripts, even though portions of the text of the Macro appear in them. The GNU General Public License (GPL) does govern all other use of the material that constitutes the Autoconf Macro.

This special exception to the GPL applies to versions of the Autoconf Macro released by the Autoconf Archive. When you make and distribute a modified version of the Autoconf Macro, you may extend this special exception to the GPL to apply to your modified version as well.