Overview

How to use Pointer size Numbers in a Euphoria-to-C Translated DLL
------------------------------------------------------------
Matt Lewis
matthewwalkerlewis@gmail.com

Modifications by Juergen Luethje 8/5/2006:
    No longer required to specify the file number on the command line for make_atom.exw.

LICENSE AND DISCLAIMER

This software is freeware.  You can modify any of the code, so long as you do not take credit for 
any of the original source, and any modifications must be marked as such.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT 
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFIT; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 


The process used here requires a little editing in your application code,
and an additional step between calling the Translator, and running emake
to build the library.  There are two included files that you'll need,
plus a couple of other files that work as demos (you'll need to change the
calls to open_dll() and possibly to c_proc() to make them work under Linux).

You should include the file make_atom.e in your code.  It should preferably be
the first include in your project, though this is not necessary.  In any global
routine that accepts 32-bit integers, you need to add a line at the top of
the routine for each 32-bit integer:

export procedure foo( atom a, atom b )
    make_atom( a )   -- a is a signed 32-bit integer
    make_atomu( b )  -- b is an unsigned 32-bit integer
    
    -- ...
end procedure

This routine should never be called by a routine inside your code.  If you need to
do this, you should wrap the real procedure with one designed to be used by the
outside world, and then call the real procedure.  The reason for this is that 
a call from a translated euphoria routine inside of your dll will already be
a real Euphoria atom (i.e., a pointer to a double).

-- Your routines inside the dll should call this instead of foo():
export procedure real_foo( atom a )
    -- do stuff
end procedure

export procedure foo( atom a )
    make_atom( a )
    real_foo( a )
end procedure

After you run the translator on your files, you need to run the included file,
"make_atom.exw".  This program will create some macros in your c files to convert
32-bit integers to atoms.  It will also remove the preceding Ref() call before the
'dummy' procedure call to make_atom[u]().  

You must pass a list of files that need to be converted.  You'll need to list all the
files that use the make_atom() procedures.  Only supply the base name of the file.  So,
if you needed to convert Win32Lib, for example, you would pass 'win32lib', and all the 
win32lib c files would be converted.  More than one file name may be passed in one 
run, but you should not convert a file more than once, or you could corrupt the source
code (because the line before the call to make_atom() will be deleted).

example:
    eui make_atom.exw win32lib my_app

To build the demo, first run the translator (this example uses gcc and GNU Make):

   > euc -dll -makefile -gcc test.ew

Then convert the file:

   > eui make_atom.exw test

And compile the dll:

   > make -f test.mak