X-Authentication-Warning:	delorie.com: mail set sender to djgpp-bounces using -f
Message-Id:	<201012271944.oBRJi5Nb022149@delorie.com>
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.1.4 uploaded.
Date:	Mon, 27 Dec 2010 20:43:20 +0100

This is a port of Lua 5.1.4 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.



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

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

  - The port only honors slashes as directory separators.  Backslashes are not
    supported nor allowed and will produce malfunction if used.

  - 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.1/" for the .lua or .lc
    files to be loaded at runtime.  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.1/" for the .so libraries
    to be loaded at runtime.  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 runtime using DJGPP's dlopen, dlclose and
    dlsym.  The .so libraries are created using DJGPP's dxe3gen util.  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 runtime 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 runtime 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 runtime.

  - There are 2 ways to load a .so library at runtime.
    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.1/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 rdln61b.zip.  I have not testet any previous version and I will
    not support any of those.  Also you will need lsupp64a.zip to provide a
    working popen() function for djdev204.


 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.

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


 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 consists of the usual three packages compiled with djdev204 that can
  be downloaded from ftp.delorie.com and mirrors as (timestamp 2010-12-27):

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

    Lua 5.1.4 html format documentation:
    ftp://ftp.delorie.com/pub/djgpp/beta/v2tk/lua514d.zip

    Lua 5.1.4 source:
    ftp://ftp.delorie.com/pub/djgpp/beta/v2tk/lua514s.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>

- Raw text -