README

Lua fiveq and fiveqplus
=======================

glue to ease the transition to (and use of) Lua 5.2


Lua 5.2 can be compiled with some backwards-compatibility features, and these
do come enabled by default, but developers cannot *rely* on their being
enabled in the Luas their end-users have installed. Other things being
equal, a library author shouldn't have to ask users to recompile Lua with
specific flags. Also, the backwards-compatibility features Lua provides by
default are less complete than they might be.

On the other hand, much of the functionality added to Lua 5.2 is in
principle available to Lua 5.1, but there is no systematic way to make it
available.

The fiveq libraries try to provide a common API base that's mostly the same
between Lua 5.1 and Lua 5.2. Developers can write against whichever of the two
APIs they wish, and deploy against either installation of Lua.

These libraries provide additional functionality to both the Lua and the C
API. To use the Lua features, end users need to first require "fiveq". To use
the C features, a library packager merely needs to compile against fiveq; it
does not need to be present on the end-user's system.

The fiveq*plus* libraries provide a superset of what fiveq does. For
specific benefits of each, see the files BENEFITS-C and BENEFITS-LUA.
The file LIMITATIONS details differences that persist between Lua 5.1 and 5.2.


Using fiveq
-----------

As we said, fiveq aims to provide the union of the Lua 5.1 and Lua 5.2 APIs,
compilable under both versions of Lua. As the LIMITATIONS file details, it's
not possible to do this 100%, but it is possible to go substantially towards
that target.

Sample use cases:

1. Suppose you have an older Lua C library that hasn't yet been ported to
Lua 5.2, but you want to make it available to end-users who do have Lua 5.2
installed. The packager just needs to (a) build and install fiveq for Lua 5.2.
(b) Add the line:

    #include "fiveq.h"

to the C library's source. And (c) change the library's Makefile from something
like this:

    foo.o: foo.c
        ${CC} ${CFLAGS} -o $@ -c $<

    foo.so: foo.o
        ${CC} ${LDFLAGS} -o $^

to this:

    foo.o: foo.c
        ${CC} ${CFLAGS} -o $@ -c $<

    foo.so: foo.o
        ${CC} ${LDFLAGS} -o $^ -L ${LIBDIR} -lfiveq

where ${LIBDIR} is the directory that contains your copy of libfiveq.a built
for Lua 5.2. (The provided Makefile installs this in the same directory as your
liblua.so.) Then most likely you'll be able to immediately compile the library
for Lua 5.2. If not, consult the LIMITATIONS file.

As we said above, for such use cases, the end user does *not* herself need to
have fiveq installed. It's used only during compilation.


2. Or, suppose you want to use some C code written for Lua 5.2 in a project you
need to compile under Lua 5.1. Just (a) build and install fiveq for Lua 5.1,
then follow analogs of steps (b) and (c) above. Then most likely you'll be able
to immediately compile the code for Lua 5.1, too.


3. What if you're writing all the C code yourself, but want it to work for both
versions of Lua? 

If you link against fiveq, you can rely on Lua 5.2's backwards-compatibility
options always being available, regardless of how Lua was compiled.
Additionally, you're not forced to write your library against the older Lua 5.1
API. If you prefer, you can instead write against the 5.2 API, and just follow
the instructions under use case 2 to make it build with Lua 5.1. (You just have
to keep an eye out for the few places where we can't backport Lua
5.2's functionality to Lua 5.1.)

If you prefer to explicitly manage the conditional compilation yourself, just
have a look at the relevant bits of fiveq's source and emulate it.


4. A different use case is where you want to use a library *written in Lua*,
but which targets a different version of Lua than you're using. For
such uses, the end user *does* need to have the fiveq libraries available
on her machine, compiled with the version of Lua she's using. If foo.lua is
written for the other version of Lua, she just needs to make sure she does:

        require "fiveq"

in her Lua source first, then she can go ahead and try:

        require "foo"

The fiveq library exposes as much as possible the union of the Lua 5.1 and Lua
5.2 APIs. As we said, this doesn't work 100%, but it comes close.


5. Or, as with use case 3, suppose *you're* writing new Lua code, and you want
your code to be usable with either version of Lua. Then consider adding
fiveq as a dependency, and just writing (mostly) against the Lua 5.2 API.



Using fiveqplus
---------------

Fiveqplus provides a superset of the functionality of fiveq. It adds in some
general-purpose extensions to the API that other C and Lua authors may want to
standardize on, including an improved module system. (Some of these extensions
are already used internally by fiveq, which is the reason for bundling
fiveqplus and fiveq in a single source distribution.) See the BENEFITS-LUA and
BENEFITS-C files for details.

To use fiveqplus in your Lua C libraries, merely add the line:

    #include "fiveq.h"

to your source, as above. But now define an extra macro when compiling your
object code, and link against the fiveqplus.a library instead of fiveq.a:

    foo.o: foo.c
        ${CC} -DLUA_FIVEQ_PLUS ${CFLAGS} -o $@ -c $<

    foo.so: foo.o
        ${CC} ${LDFLAGS} -o $^ -L ${LIBDIR} -lfiveqplus

If you like, you can can add the macro directly to your source instead of
compiling with -DLUA_FIVEQ_PLUS:

    #define LUA_FIVEQ_PLUS
    #include "fiveq.h"


To use fiveqplus in your Lua code, merely change your:

    require "fiveq"

to:

    require "fiveqplus"


Installing
----------

To build for both versions of Lua (which must already be installed):

    gmake clean
    gmake
    sudo gmake install

To build for only one version of Lua:

    gmake clean
    gmake fiveq fiveqplus LUA_VERSION_NUM=501
    gmake install-501 LUA_VERSION_NUM=501