Overview
========

This is a re-packaging of the standard Lua 5.3.0 distribution using
the GNU autotools.

  * See the `INSTALL.autotool` file for generic information on using `configure`.
  * See below for specific instructions for this package.

Running `./configure --help` will list all of the available options
and their default values


Lua Configuration Options
=========================

Lua's configuration is done via C preprocessor macros in `src/luaconf.h`.

Some of that has been automated, other bits have been exposed via `configure` options


Automated Configuration
-----------------------

The following configuration options are determined automatically

* `LUA_USE_STRTODHEX`
* `LUA_USE_AFORMAT`
* `LUA_USE_DLOPEN`
* `LUA_USE_ULONGJMP`


`LUA_USE_POSIX`
---------------

`LUA_USE_POSIX` is an umbrella configuration option which enables a
number of POSIX features.

The _--enable-posix_ and _--disable-posix_ options are available to
enable or disable these features.

* if _--enable-posix_ is specified without an argument, POSIX features
are unconditionally enabled.

* if _--enable-posix = no_ or _--disable-posix_ is specified, POSIX
features are unconditionally enabled.

* if _--enable-posix = auto_ (the default), `LUA_USE_POSIX` 
is enabled if the host runs

    * GNU/Linux
    * Mac OS X
    * FreeBSD
    * OpenBSD


`LUA_32BITS`
------------
This configuration option is exposed via _--enable-32bits_ and
_--disable-32bits_.

`LUA_C89_NUMBERS`
-----------------

This configuration option is exposed via _--enable-c89-numbers_ and
_--disable-c89-numbers_.


`LUA_USE_C89`
-------------

By default Lua will use non-C89 features.  To disable this, specify
_--disable-non-C89_.

`LUA_COMPAT_5_2`
----------------

This configuration option is exposed via _--enable-compat-5.2_ and
_--disable-compat-5.2_.

`LUA_COMPAT_5_1`
----------------

This configuration option is exposed via _--enable-compat-5.1_ and
_--disable-compat-5.1_.


`LUA_PATH_DEFAULT`, `LUA_CPATH_DEFAULT`
---------------------------------------

These are the filesystem paths Lua searches for Lua and C libraries.

To change the default values, specify these as extra arguments to the
`configure` command line, e.g.

    ./configure LUA_PATH_DEFAULT="..."  LUA_CPATH_DEFAULT="..."

There are several C preprocesor macros defined which may be of use:

* `LUA_VDIR` - a path component based upon the Lua version and the
   optional argument to the `--enable-versioned-install` option

* `LUA_LDIR`  => `$(prefix)/share/LUA_VDIR/`
* `LUA_ELDIR` => `$(exec_prefix)/share/LUA_VDIR/`
* `LUA_CDIR`  => `$(exec_prefix)/lib/LUA_VDIR/`

To duplicate the default settings (minding the shell's expansion rules and quotes):

    ./configure \
      LUA_PATH_DEFAULT='LUA_LDIR"?.lua;" LUA_LDIR"?/init.lua;" LUA_CDIR"?.lua;" LUA_CDIR"?/init.lua;" "./?.lua;" "./?/init.lua"' \
      LUA_CPATH_DEFAULT='LUA_CDIR"?.so;" LUA_CDIR"loadall.so;" "./?.so"'


Additional Configuration
========================

Enabling `readline` in the standalone lua executable
----------------------------------------------------

By default if the `readline` library (or an API compatible library,
such as `edit` or `editline` ) is available, it is used in the `lua`
standalone interpreter.  To prevent this, specify _--disable-readline_.


Multiple concurrent installations
---------------------------------

The default directory layout doesn't lend itself well to multiple
concurrent versions of Lua.

If configure is passed the _--enable-versioned-install_ option it
provides a layout which allows easy cohabitance of multiple versions.

The difference between the two layouts is shown below; default
on the left, versioned on the right.

	{prefix}                                {prefix}
	|-- bin                                 |-- bin
	|   |-- lua                             |   |-- lua -> lua5.3
	|   `-- luac                            |   |-- lua5.3
	|                                       |   |-- luac -> luac5.3
	|                                       |   `-- luac5.3
	|-- include                             |-- include
	|   |                                   |   `-- lua5.3
	|   |-- lauxlib.h                       |       |-- lauxlib.h
	|   |-- luaconf.h                       |       |-- luaconf.h
	|   |-- lua.h                           |       |-- lua.h
	|   |-- lua.hpp                         |       |-- lua.hpp
	|   `-- lualib.h                        |       `-- lualib.h
	|-- lib                                 |-- lib
	|   |-- liblua-5.3.so                   |   |-- liblua5.3.a
	|   |-- liblua.a                        |   |-- liblua5.3.la
	|   |-- liblua.la                       |   |-- liblua5.3.so -> liblua5.3.so.0.0.0
	|   |-- liblua.so -> liblua-5.3.so      |   |-- liblua5.3.so.0 -> liblua5.3.so.0.0.0
	|   |                                   |   |-- liblua5.3.so.0.0.0
	|   `-- pkgconfig                       |   `-- pkgconfig
	|       `-- lua.pc                      |       `-- lua5.3.pc
	`-- share                               `-- share
		|-- doc                                 |-- doc
		|   `-- lua                             |   `-- lua5.3
		|       |-- ...                         |       |-- ...
		`-- man                                 `-- man
			`-- man1                                `-- man1
				|-- lua.1                               |-- lua.1
				`-- luac.1                              `-- luac.1


_--enable-versioned-install_ takes an optional value,
which will be appended to the version string.

For example, compare _--enable-versioned-install_ (on the left) to
_--enable-versioned-install=-compat_ (on the right)


	{prefix}                                         {prefix}
	|-- bin                                          |-- bin
	|   |-- lua -> lua5.3                            |   |-- lua -> lua5.3-compat
	|   |-- lua5.3                                   |   |-- lua5.3-compat
	|   |-- luac -> luac5.3                          |   |-- luac -> luac5.3-compat
	|   `-- luac5.3                                  |   `-- luac5.3-compat
	|-- include                                      |-- include
	|   `-- lua5.3                                   |   `-- lua5.3-compat
	|       |-- lauxlib.h                            |       |-- lauxlib.h
	|       |-- luaconf.h                            |       |-- luaconf.h
	|       |-- lua.h                                |       |-- lua.h
	|       |-- lua.hpp                              |       |-- lua.hpp
	|       `-- lualib.h                             |       `-- lualib.h
	|-- lib                                          |-- lib
	|   |-- liblua5.3.a                              |   |-- liblua5.3-compat.a
	|   |-- liblua5.3.la                             |   |-- liblua5.3-compat.la
	|   |-- liblua5.3.so -> liblua5.3.so.0.0.0       |   |-- liblua5.3-compat.so -> liblua5.3-compat.so.0.0.0
	|   |-- liblua5.3.so.0 -> liblua5.3.so.0.0.0     |   |-- liblua5.3-compat.so.0 -> liblua5.3-compat.so.0.0.0
	|   |-- liblua5.3.so.0.0.0                       |   |-- liblua5.3-compat.so.0.0.0
	|   `-- pkgconfig                                |   `-- pkgconfig
	|       `-- lua5.3.pc                            |       `-- lua5.3-compat.pc
	`-- share                                        `-- share
		|-- doc                                          |-- doc
		|   `-- lua5.3                                   |   `-- lua5.3
		|       |-- ...                                  |       |-- ...
		`-- man                                          `-- man
			`-- man1                                         `-- man1
				|-- lua.1                                        |-- lua.1
				`-- luac.1                                       `-- luac.1