README for the pfe ieeefp module
--------------------------------
David N. Williams
30-Jun-2010

The ieeefp module is external to the pfe distribution.


How to build ieeefp-ext.c under linux and OS X
----------------------------------------------

1. The following three files contain source code for a pfe
   version 0.33.x loadable module.  Put them in a working
   directory.

     ieeefp-ext.c
     ieeefp-ext.h
     ieeefp-dll.c

2. Put the appropriate one of the following two scripts
   in the working directory.

     mkmod-linux
     mkmod-osx

3. Edit the PREFIX line in the script to correspond to that in
   your pfe build configuration.  For example:

     PREFIX=$HOME   or   PREFIX=/usr/local

4. Make the script executable.  For example:

     chmod +x mkmod-linux

5. Execute the script.  For example, while in the working
   directory:

     ./mkmod-linux ieeefp

   The script assumes an installed pfe tree.  It builds a
   dynamic library, ieeefp.so, and installs it in
   $PREFIX/lib/pfe-forth.  It also puts ieeefp.h in
   $PREFIX/include.

6. To load the module, start pfe and execute "loadm ieeefp". 
   For example:

     [jost:~] dnwills% pfe
     \ Portable Forth Environment 0.33.71 (Jun 24 2010 20:16:00)
     Copyright (C) Dirk Uwe Zoller  1993 - 1995.
     Copyright (C) Tektronix, Inc.  1998 - 2003.
     Copyright (C) Guido U. Draheim 2005 - 2008.
     ANS/ffa ITC Forth - Please enter LICENSE and WARRANTY. 
     Running on powerpc darwin9.8.0 - to quit say BYE. ok 
     loadm ieeefp ok 


How to run the tests
--------------------

1. Be sure that the following files are either in the working
   directory or in $PREFIX/share/pfe:

     ttester.fs
     ieeefp-ext-test.fs
     mixfloat.fs

2. Execute:

     pfe ieeefp-ext-test.fs

3. To test the stopping behavior of alternate exceptions,
   uncomment one of the lines at the end of ieeefp-ext-test.fs.

If you are running under linux, all tests should pass, including
correct error messages for the uncommentable alternate exception
stopping tests.  But gcc for the linux we use defaults to the
x87 fpu, which has imprecise exceptions, instead of the SIMD
fpu, where exceptions are precise.  With x87, situations where
the fp signal handler does not get called on an enabled
exception are practically unavoidable, resulting in an unrelated
error such as a segmentation fault.  The stopping tests
currently avoid that; so the fact that they give correct error
messages is misleading, for x87 systems.

If you are running under OS X, there will be many failures
unless you have installed a version of pfe that prevents
clobbering of the floating-point environemt.  Even if you have a
clobber-guarded pfe, tests for the persistence of the alternate,
stopping exception state will fail under Snow Leopard.  The
uncommentable stopping tests should stop and display the
appropriate error message.  Snow Leopard defaults to SIMD, with
precise exceptions, and ppc fpu exceptions are also precise, so
this is not misleading.


How to checkout and install a clobber-guarded pfe
-------------------------------------------------

1. Create a directory for an svn checkout.  For example:

     /usr/local/svn/pfe/dnw

2. Given the example directory, execute:

     cd /usr/local/svn/pfe/dnw
     svn co https://pfe.svn.sourceforge.net/svnroot/pfe/branches/dnw/

3. Change to the pfe-33 directory:

     cd /usr/local/svn/pfe/dnw/pfe-33

4. Execute ./configure with arguments appropriate for your
   system.  For example, when I do linux, I don't have access to
   /usr/local.  There I execute the following, but without line
   wrap:

     ./configure --prefix=$HOME --with-cflags=-DUNROLL_NEXT
       --with-regs=many --with-opt=3

   When I do OS X on a computer at home, I have access to
   /usr/local, and I execute the following:

     ./configure --with-regs=all --with-cflags=-DUNROLL_NEXT --with-opt=3

5. Still in the pfe-33 directory, execute

     make
     make check
     make install

   Currently "make check" gives an error for exceptn under OS X.
   I just ignore it.