
Plug-in (dynamic library loading) support for Lua
====================================================

This library enables to load and initialize dynamic support libraries for Lua.
It is inspired by loadlib by Renato Ferreira Borges (which can be found
at http://www.tecgraf.puc-rio.br/~rborges/loadlib/). My library supports 
Lua 4.0, it has slightly different interface and behavior and it is tested on Win32
only currently.


Copying
=========

Lualoadlib is distributed under the terms of Lua license, ie. it can
be used freely in both free and commercial projects, it can be studied, tweaked and
changed to suit your needs (for licensing details see loadlib.c).

What is new 2001-08-02
=========================
The library has been ported to Linux.


Compiling lualoadlib on Windows
=================================

you need to have lua.h on your INCLUDE path and link with lua.lib.


Compiling lualoadlib on Linux
=================================

There is Makefile included. Please check this Makefile and update the variables
according to your environment. Then run 'make'.


Using lualoadlib
=====================

Lualoadlib is initialized by calling lua_loadlibopen( L );

It provides two functions, loadlib and unloadlib. It will also register its own global
variable (table) named _LOADLIB. In this table it stores the names and handles of all
the loaded modules.

status,errstr = loadlib( dll_name, init_fun_name, 'x' );

dll_name is the name of the dynamic link library. It can be just the name or the full path.
The library is searched for according to the operating system dynamic loading behavior.
init_fun_name is the name of the Lua initialization function present in the library. These
two parameters are obligatory. The last parameter suggests what to do in case of error.
It is similar to 'call' function. Value 'x' means that errors are non-fatal. In case of 
failure status is nil and errstr holds the error string. By default the loadlib errors are
fatal and will result in call to lua_error.

The loadlib checks the dll_name first. If there is such a name in the _LOADLIB field,
the appropriate library handle is used. Otherwise it tries to load the library. If the load
is successful, the library is added to the _LOADLIB table. Once the library handle is obtained,
it searches for init_fun_name within the library. If it is not found, 
the error is reported. Else the function is carried out and success (status==1) is returned.

unloadlib( dll_name );

unloads the library and removes its entry from _LOADLIB table. I suggest NOT TO USE this
function unless you are really sure what you are doing. Lualoadlib sets the gc tag method
for the libraries and they are unloaded automatically in the right way upon the call
to lua_close().


Examples:
============

loadlib( 'luasimdb', 'lua_sqllibopen' ); -- loads simple_db adapter for Lua
loadlib( 'mylib.dll', 'lua_mylibopen', 'x' ); -- loads mylib (errors will not be fatal)
loadlib( './mylib.so', 'lua_mylibopen', 'x' ); -- loads mylib from current directory (errors will not be fatal)

unloadlib( 'mylib.dll' ) ; -- unloads mylib

Authors:
==========

Lualoadlib has been developed by Roman Vanicek <vanicek@xtg.cz> at XTG Systems, s.r.o. 
(http://www.xtgsystems.com).

The homepage of lualoadlib is http://www.xtgsystems.com/lua/.

The homepage of the original loadlib is http://www.tecgraf.puc-rio.br/~rborges/loadlib/.
