Message-Id: <201308181854.r7IIs27x028304@delorie.com>
Date: Sun, 18 Aug 2013 20:30:21 +0200
From: Juan Manuel Guerrero <juan DOT guerrero AT gmx DOT de>
To: djgpp-announce AT delorie DOT com
Subject: ANNOUNCE: DJGPP port of Lua 5.2.2 uploaded.
Content-Type: text/plain; charset=ISO-8859-15; format=flowed
Reply-To: djgpp AT delorie DOT com

This is a port of Lua 5.2.2 to MSDOS/DJGPP.


   Lua is a powerful, light-weight programming language designed for extending
   applications. Lua is also frequently used as a general-purpose, stand-alone
   language. Lua is free software.



   To compile this port you will need to check out the libc sources from the
   CVS repository and compile your own c library.  This is required because
   gcc 4.5.X and later create .eh_frame sections in object files by default.
   When building DXE modules from object files containing .eh_frame sections,
   dxe3gen generates code that calls the __deregister_frame_info and
   __register_frame_info functions.  The dxe3gen program has been improved
   to detect this case and automatically resolve these both symbols. This
   will be the case if the used programing language has no exception handling
   support like C.  If C++ is used to code the .so library (DXE module), then
   the symbols will not be resolved and the .so library must be linked with
   libgcc.a that will provide working versions of both versions.
   Please note that even if gcc generates exception handling frames and dxe3gen
   emits those calls, the exception handling capability of DXE modules has _not_
   changed and improved in anyway.
   Please also note that you do not need to worry about all this if you use
   gcc 4.4.5 or a previous version to compile the sources.  Those compilers
   do not create .eh_frame sections by default so that all these difficulties
   do not appear and you can use your stock djdev204 libc.a.


   DJGPP specific changes.
   =======================

   - All DXE modules generated or used with this port must use the .so extension
     and not the usual .dxe one.  The .dxe extension is not honored by the port.

   - The port will honor the new platform "djgpp".  This means, to compile the
     port you must pass djgpp as argument to the Makefile in the top srcdir.

   - Instead of using the hard coded template string "/tmp/lua_XXXXXX", this
     port will create the names of its temporary files using the template string
     composed by "luXXXXXX" and a prefix pointing to a directory. The directory
     is determined by testing, in sequence, the directories defined by the values
     of environment variables TMPDIR, TEMP and TMP.  The first variable that is
     found to point to an existing directory will be used.  If none of these
     variables specify a valid directory, P_tmpdir will be used.

   - The port will search at "/dir/env/DJDIR/share/lua/5.2/" for the .lua or .lc
     files to be loaded at run time.  This path can be overwritten by setting the
     LUA_PATH environment variable.  To learn how the environment variable must
     look like, please read the docs.

   - The port will search at "/dir/env/DJDIR/lib/lua/5.2/" for the .so libraries
     to be loaded at run time.  This path can be overwritten by setting the
     LUA_CPATH environment variable.  To learn how the environment variable must
     look like, please read the docs.

   - The .so libraries are loaded at run time using DJGPP's dlopen, dlclose and
     dlsym functions.  The .so libraries are created using DJGPP's dxe3gen utility.
     This means that you are restricted to the limitations that are inherent to
     the DXE3 concept.  To understand what is possible and how to create DXE
     modules read the dxe3gen documentation.

   - The .so extension for dynamically loaded libraries is mandatory.  No other
     extension will be honored; especially not the .dxe extension that is
     supposed to be the dxe3gen default extension.

   - All functions inside a .so library must conform to the C-function API
     defined by Lua if they shall be accessed by a .lua or .lc program.  That
     means that every C function gets as only argument the Lua state.  This is
     a pointer to a lua_State structure.  This structure contains a stack from
     which the function arguments are pulled.  The results that the function
     shall return to the caller must be pushed back on the stack.  As return
     value the function must always return the number of objects pushed on the
     stack.  C-functions that do not conform to this API cannot be accessed by
     a Lua program and should not be exported.  For more information about this
     read the Lua docs.

   - .so libraries created by dxe3gen shall not be linked with the Lua library.
     This means you shold not pass "liblua.a" as argument to dxe3gen.  The
     loading of the .so library at run time is done by the ll_load() and ll_sym()
     functions in loadlib.c.  This is the place where the table with the symbols
     that shall be exported to the .so library is defined.  You must expand this
     table according to the symbols that are reported as unresolved by dxe3gen.
     Currently this table contains the names of all push and pop functions that
     the Lua library provides and that are intended to be used to manipulate
     the Lua stack from inside of a C-function.  Apart from those function names
     I have also added printf and puts to the list.  Those are the only function
     names that I have added from libc.  If you use other functions from libc
     you must either link your library against libc and see if this is enough to
     resolve all unresolved symbols or not link against libc at all and add all
     unresolved symbols to the table, in the same way as this issue has been
     handled for the Lua library.  Here you are alone and you must try out what
     the best solution would be.
     If your .so library contains unresolved symbols that are not defined by the
     table used by ll_load you will get at run time an error message like this:
       function_name: unresolved symbol in DXE module.
     where function_name stands for the function used in the .so library that
     does not appear in the symbol table.  In this case you must expand the
     table by adding an entry like this:
       DXE_EXPORT(function_name)
     and recompile the sources.  I have found no way to adapt the symbol table
     at run time.

   - There are 2 ways to load a .so library at run time.
     1) You can use the low-level Lua function called package.loadlib.  In this
        case you must pass as arguments to the function the absolute path to
        the .so library and the exact name of the function to be loaded.
        E.g.:
          package.loadlib("/dev/env/DJDIR/lib/lua/5.2/libmylib.so", "_my_function")
        Please note that you have to put an underscore before the function name.
        No search along any paths are done.  If the loading fails then the Lua
        program will fail.
     2) You can use the Lua function called "require".  In this case you must
        pass the name of the library without path and extension.  The library
        will be searched along the LUA_PATH and LUA_CPATH paths or its hard
        coded defaults if they are not set.
        I have added 4 files to demonstrate how this works with this port.
        The files are stored in the /djgpp directory.  You can run these DJGPP
        specific tests passing test_djgpp as argument to the makefile.

   - To compile the port you will need to install the latest readline port.
     This is rdln62b.zip.  I have not tested any previous version and I will
     not support any of those.

   - The port has been test with the test suite available as:
       http://www.lua.org/tests/5.2/lua-5.2.2-tests.tar.gz
     After having installed lua, run the test suite by cd-ing into lua-5.2.2-tests
     directory and starting the lua test script with the command:
       lua -e"_U=true" all.lua
     No check will fail.  The final output should look like this:

test done on 18/08/2013, at 18:05:05
Lua 5.2
final OK !!!
cleaning all!!!!
     ---- total memory: 27.7K, max memory: 1.6M ----



total time: 4.78

 >>> closing state <<<


   Because the dlfcn/dxe3 functionality is required to build this port, it can
   only be compiled using djdev204.  There will be no version compiled with
   djdev203.

   As usual, all djgpp specific files (diffs, README files, etc.) are located in
   the /djgpp directory.

   For further information about Lua please read the docs.


   Please note that I have only ported this package.  I do not use Lua at all so
   I will not be able to answer questions that are not related to porting issues.



----------------------------------------------------------------------------


   The port has been compiled using a freshly compiled version of the CVS
   repository and consists of the usual three packages that can be downloaded
   from ftp.delorie.com and mirrors as (time stamp 2013-08-18):

     Lua 5.2.2 binary, library and man format documentation:
     ftp://ftp.delorie.com/pub/djgpp/beta/v2tk/lua522b.zip

     Lua 5.2.2 html format documentation:
     ftp://ftp.delorie.com/pub/djgpp/beta/v2tk/lua522d.zip

     Lua 5.2.2 source:
     ftp://ftp.delorie.com/pub/djgpp/beta/v2tk/lua522s.zip



   Send Lua specific bug reports to <lua-l AT lists DOT lua DOT org>.
   Send suggestions and bug reports concerning the DJGPP port
   to comp.os.msdos.djgpp or <djgpp AT delorie DOT com>.

Enjoy.

       Guerrero, Juan Manuel <juan DOT guerrero AT gmx DOT de>