Lua Modules / Conventions / Unloading documentation

[Thomas Harning <harningt@...>]

I've been working a little bit w/ Lua extensions in OSX and found  
there's somewhat of a disparity in how modules are handled... also  
noticed this in Linux modules as well.

==== Problem/Issue A ====

It seems that the convention of not linking against Lua is not  
followed.  Where possible, Lua should not be linked against to improve  
module reuse between applications.

Some applications may pull in Lua, make a few mods but keep the API  
the same... some may decide to link dynamically against liblua...  
others may use LuaJit.

If you link against Lua, you tie your code to that specific liblua,  
risking problems if the 'Lua' runtime that is active doesn't use liblua.

In Linux, the solution is quite simple, don't link against Lua and it  
will definitely grab it from the current state due to 'ELF'.

In OSX, you need to use the -undefined dynamic_lookup option when  
linking the library.

In Windows... you're semi-hosed and have to figure out what mechanism  
you want, the general solution seems to be creating a proxy DLL and  
loading that in.  A useful trick is the fact that when Windows looks  
up DLLs, if there is one w/ the same 'base name' already loaded, it'll  
use that instead of hunting down one in the path.  For the case where  
Lua is linked directly in, I'm not entirely sure how this behaves when  
the EXE contains symbols.........

Semi convoluted example:
	LuaJit/lua.dll
	LuaBinaries/lua.dll

	Modules/*  all linked against a 'lua.dll'
	Application DLL - linked against a 'lua.dll'
	Application EXE - runtime loads Application DLL.
		Can choose whether to use luabinaries or luajit by LoadLibrary-ing  
the appropriate Lua.dll...
		Then loads application DLL which does the actual Lua work



In other OSes I'm not sure...

==== Issue B ====

On the lua users wiki, there appears to be a 'wrong' idea of using  
dylibs as Lua modules in Mac OSX.  Dylibs are libraries that aren't  
generally supposed to be unloaded (however in >= 10.5 it's now  
possible to dlclose them).
The idea of using bundles is correct, as they are intended to be  
loaded/unloaded.

Any thoughts on getting this corrected/discussed?

==== Issue C ====

It appears that it is not common knowledge that Lua modules loaded are  
in fact unloaded.  A proxy object is put in the registry w/ the __gc  
set to unload the DLL.

It may make sense to provide a symmetric function to luaopen_* ,   
luaclose_* to give the module the opportunity to perform cleanup.  One  
option it to have modules dump a proxy in the registry... though this  
is less obvious than if a luaclose_* were present (though  
documentation w/ example proxy+__gc regarding C modules might be  
effective).

This has bitten me in Lua Lanes where timing caused the module to be  
unloaded while a thread was starting up using code present in the  
module...