twoface

The Problem

Lua C libraries built against Lua 5.1 expect the Lua 5.1 ABI, whereas C programs which use Lua 5.2 expect the Lua 5.2 ABI. These two ABIs are significantly different, meaning that 5.2 programs cannot a-priori load 5.1 C libraries unless they are recompiled for 5.2.

The Solution

twoface is a DLL which consumes the 5.2 ABI and presents a 5.1 style ABI, thereby allowing a 5.2 program to load most 5.1 C libraries without the need for any recompilation.

Known Limitations

• twoface is Windows-only, as it relies on there being a non-flat namespace for symbols.
• Some 5.1 C libraries, such as pluto, rely on the layout of Lua 5.1's internal data structures. Such libraries will not work with twoface.
• Lua bytecode and source code are not translated by twoface; if a library is mixed C and Lua, then the Lua part of the library still needs to be 5.2 compatible.
• In some areas, the language semantics have significantly changed between 5.1 and 5.2. twoface tries to patch over a lot of the differences, but it can't do too much.

Differences to the actual 5.1 ABI

• Emulation of LUA_GLOBALSINDEX can increase stack usage by one slot, which will cause problems for libraries which (wrongly) already used all of Lua's "internal" slots.
• Per-thread environments are gone; performing lua_getfenv/lua_setfenv on threads instead gets/replaces LUA_GLOBALSINDEX.
• lua_setfenv fails on C closures which weren't created by twoface, and on Lua functions which don't report an _ENV upvalue. For such functions, lua_getfenv will return something, but it might not be accurate.
• Due to sharing of upvalues between closures, lua_setfenv on a Lua function may affect more than just one closure.
• lua_load expects Lua 5.2 source code.
• lua_load and lua_dump work with Lua 5.2 bytecode rather than Lua 5.1 bytecode.
• The debug event LUA_HOOKTAILRET has been swapped for LUA_HOOKTAILCALL.
• Explicitly calling luaopen_base won't load the coroutine library.