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

1.:     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.

        - The port will create the names of its temporary files using the
        template string "/dev/env/TMPDIR/luXXXXXX" instead of hard coded default
        template string "/tmp/lua_XXXXXX".  Please note that the Lua interpreter
        and compiler will not check if TMPDIR is set and if TMPDIR points to an
        existing directory.  If the directory does not exists, the .lua program
        will simply fail.

        - 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 environ-
        ment 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 environ-
        ment 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 libc function names that I
        have added.  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 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 2 files to demonstrate how this works with this port.  The
        files are stored in the /djgpp directory.  You can run these DJGPP
        specific test 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.


        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.


2.:     Installing the binary package.
        ==============================

2.1.:   Copy the binary distribution into the top DJGPP installation directory
        and unzip it running *ONE* of the following commands:
          unzip32 lua514b.zip      or
          djtarx lua514b.zip       or
          pkunzip -d lua514b.zip

        For further information about Lua please read the info docs and the
        NEWS file.


3.:     Building the binaries from sources.
        ===================================

3.1.:   To build the binaries you will need the following binary packages:
          djdev203.zip (patch level 2, see the djdev203.dsm or a later version)
          bsh205bbr3.zip (or a later but NOT a prior version)
          gccNNNb.zip, bnuNNNb.zip, makNNNb.zip, filNNNb.zip, shlNNNb.zip,
          txtNNNb.zip, txiNNNb.zip, grepNNNb.zip, sedNNNb.zip, difNNNb.zip,
          lsuppNNNa.zip and rdlnNNNb.zip

        All this packages can be found in the v2gnu directory of ftp.delorie.com
        and any mirror.  NNN stands for the newest port versions available when
        this port was build but older may do the work as well.

3.2.:   Create a temporary directory. Copy the source package: lua514s.zip
        into the directory and unzip it running ONE of the following commands:
          unzip32 lua514s.zip      or
          djtarx lua514s.zip       or
          pkunzip -d lua514s.zip

3.3.:   The sources do not need to be configured.

3.4.:   To compile the package run from the top srcdir the command:
          make djgpp

3.5.:   Now you can run the test suite by issuing the command:
          make test
        from the top srcdir. This will run a "hello world" type program.  To
        run the DJGPP specific test programs start the following command:
          make test_djgpp
        from the top srcdir.  This will create two .so libraries that compute
        sine and cosine values.  The first demostrate how a dynamic library is
        called directly from a Lua program using low level Lua functions.  The
        second demostrate the usual way to load modules in a Lua program using
        the "require" command.

3.6.:   To install the binary, library and man pages run the following command
        from the top srcdir:
          make install

        This will install the products into your DJGPP installation tree given
        by the default prefix "/dev/env/DJDIR". If you prefer to install them
        into some other directory you will have to set prefix to the appropriate
        value.
        Example:
          make install INSTALL_TOP=z:/some/other/dir




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

Enjoy.

          Guerrero, Juan Manuel <juan.guerrero@gmx.de>
