==========================================================================

libFAUDES Lua bindings 

==========================================================================


This plug-in provides bindings to access libFAUDES types and functions
from the Lua scripting language. It uses the tool SWIG to automatically
generate the actual bindings from so called interface files (*.i). The
luabindings plug-in is integrated in the libFAUDES build system such that
other plug-ins can fairly simple add their additional types and functions
to the interface definition.

The tutorial provides a simple command line interpreter to interactivly
access faudes functions in Lua syntax. If your target system is linux,
you really want to edit the Makefile.plug-in to have LBP_LUAGOAL=linux 
to activate advanced readline support.



==========================================================================
 
Files

==========================================================================

./libfaudes/libluafaudes.a
   Archive with Lua objects and all SWIG generated wrapper functions.        

./luabindings/lib/*
   Lua sources

./luabindings/src/registry/*.i        
   SWIG interface files for faudes core

./luabindings/src/lbp_load.*.template     
   Templates for the build system to generate header and cpp source of a function to
   load all SWIG based lua modules. This allows for other plug-ins to have their
   own SWIF module.

./luabindings/src/libluafaudes.h
   Header file to access lua and faudes add ons. Use this for your faudes/lua based
   application.      

./luabindings/obj/*
   Intermediate files generated by the build system, incl SWIG generated wrappers

./luabindings/tutorial/luafaudes.cpp
   Command line interpreter for faudes enhanced lua scripts. The executable is placed
   in libfaudes/bin 

./luabindings/tutorial/data/*.lua
   Example scripts.


==========================================================================
 
How to provide luabindings for your plug-in

==========================================================================

Notes:

*  Luabinding generation via the libfaudes build system in only supported for
   Linux/Unix/MacOs. Once the wrappers are generated, you can still compile libfaudes on
   other platforms.

*  The build system does currently not figure all interface dependencies. In partivular,
   you must "make luabindings-clean" after changing libfaudes header files.

*  We used SWIG version 1.3.36 and Lua 5.1.3. Other versions may not work with
   the provided interface definitions.

*  The example plug-in implements exactly one function on a generator and provides
   lua bindings. The interface file plug-ins/example/pex_interface.i is a good
   starting point for the Lua integration of your plug-in. The observer plug-in  
   integrates a new data-type in a very basic fashion.


Basic Strategy to use the luabindings plug-in build system

*  Have a file called xxx_interface.i in the plug-in source/registry
   directory, where xxx is the prefix used for the plug-in.

*  In xxx_interface.i, define a SWIG module with a name that
   matches your plug-in.

*  In xxx_interface.i, include faudesmodule.i to access the
   interface to core data types (EventSet, Generator, etc)

*  Define interfaces to your plug-in's data-types and functions
   in xxx_interface.i. You may also split your interface in multiple
   files xxx_yyyyyyy.i and include them in  xxx_interface.i. 

*  If the plug-in's C++ interface needs to be adapted, consider to do
   so in your plug-in. If you still want to adapt by defining 
   C++ data-types or functions via SWIG, use "Lua" prefix as naming
   convention to avoid confusion with the plug-in's original interface. 

*  Advertise your interface file in your Makefile.plugin by adding
   lines

    LBP_INTERFACES += $(xxx_SRCDIR)/registry/xxx_interface.i 
    LBP_LUAMODULES += <plugin_name>

