Copyright 1988, 1989 Hans-J. Boehm, Vernon Lee, Alan J. Demers
Copyright Digital Equipment Corporation & INRIA 1988, 1989
Copyright (c) 1990, 1991 by Xerox Corporation.  All rights reserved.

THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.

Permission is hereby granted to copy this compiler for any non-commercial
purpose, provided the above notices are retained on all copies.  Further
restrictions apply to the DEC/INRIA BigNum package.  These are stated in
the file runtime/BigNum/doc/bnbody.tex.

This work uses the BigNum package developed jointly by INRIA and
Digital PRL.    It has been modified by Hans-J. Boehm in August 1990
at Xerox PARC.  When you receive this software, please send mail to
librarian@prl.dec.com to inform them that you have a copy of the
package.

THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.

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


This distribution includes a fair amount of only semi-portable code.
Thus installation may be tricky on some machines.  It probably will never
work on a machine not running UN*X, not having a real 32 bit word size.
80286s are probably a lost cause.  Machines using neither IEEE nor Vax
floating point will require significant hacking on runtime/float.c.
This may also apply to IEEE floating point with different byte orderings.

Most .c files in this directory were generated from Russell code.  As
such, they are not human readable, but relatively portable.

The runtime directory contains the Russell runtime system, which is likely
to be less portable.  It contains two subdirectories "gc" and "BigNum".
The former contains a conservative garbage collector, and is likely to
require some small amount of work to port to machines other than those
listed in the README file.  The latter is the DEC/INRIA bignum package.
It is very portable if the C version is used.  Significantly better
performance can however be obtained with one of the assembly language versions.

Installation procedure, assuming no real porting is required:
(Note that Makefiles in . ./runtime and ./runtime/gc may require
editing on some machines.)

0) On dual universe systems (e.g. MIPS), make sure that you are
   operating in a BSD environment.  If necessary, modify Makefiles
   to compile in a BSD environment.  Compiling in a system V environment
   will require hacking up a sigsetmask replacement, at a minimum.
   The Russell generated files will benefit a lot from an optimizing
   C compiler.  On Sun 3s, the GNU C compiler is highly recommended
   for compiling routines in the main directory.  It will produce a
   a significantly faster and smaller executable.  A nonoptimizing
   compiler that pays attention to register declarations is probably
   safer for the runtime directory.  If necessary, edit Makefiles to
   invoke the proper compiler.

1) Type "make machtype" in the runtime/BigNum directory.  Machtype
   is one of the following:

	    C32 - portable version
	    68K - Sun 3 or (very) similar machine
	    vax - A vax (under UN*X, of course)
	    ns  - A National 32K based machine
	    mips - a MIPS R/2000 compatible machine
	    sparc - Sun 4 (minimal assembly support)
	    rs6000 - An IBM RS/6000 (minimal assembly support)

   (Do NOT use the C16 option.)

2) (May be omitted by the (over)confident)
   Type "make test" in the runtime/gc directory.  This should finish
   by printing a message that "GC probably works".  If it doesn't,
   read the README file there for porting directions.  A few systems
   require editing of the Makefile in that directory.  See the Makefile
   for details.

3) Type "make" in the main directory.  (On a non-Sun system, first edit
   Makefile, as described there.  On a Vax, see note 6.)  This will first
   build a simple test program, run it, and then build "calc".

4) Run "calc", and make sure that it behaves reasonably.  If it fails on
   very low calculation precisions, it is likely that float.c is broken.
   If it gives incorrect answers at large precisions, it is probably advisable
   to run the test suites in the bignum package.  With any other behavior,
   you're on your own.  (But send mail to boehm@xerox.com to report it, in
   any case.)

Notes:

1) An attempt was made to tune this version for machines with relatively poor
extended precison arithmetic support.  (Unfortunately some of the new RISC
machines are known to fall into this category.  Machines for which no assembly
language implementation of the BigNum package exists also effectively
fall into this category.)  For example, the routine for converting large
numbers to decimal is fairly complex, but uses a subquadratic algorithm.
The same applies to the routine for computing PI.  This minimizes large
integer multiplication and division, but for reasonable sized numbers
(< 10000 digits or so) increases bookkeeping and storage management
overhead.  This version runs faster than the old one on a MIPS machine,
but often slower on a a 68020.

2) A number of files in the runtime directory are part of the standard
Russell runtime environment, but are not called by the calculator.  In
particular, sfloat.c (as opposed to float.c) is both difficult to port,
and not used.  Any replacement that defines functions with the right names
is sufficient.  Lazy_list.c is also not used.

3) On some machines, notably again a MIPS M/120, a SIGWINCH from a remote
login session wont make it all the way to the calculator.  This means
that the user needs to type ^L after changing the size of a window.

4) Some C compilers will issue warning messages about duplicate definitions
of TRUE and FALSE.  These may safely be ignored.  (They are all identical.)

5) Compiling the calculator on Suns with profiling enabled is tricky.
Many versions of the profiled C library distributed by Sun are known to be
broken.  Setjmp/longjmp are broken in the profiled, statically linked
version of the library on Sun 3s under 4.0.3.  This breaks signal handling
in the calculator.  Some older versions of the library contain incompatible
versions of brk and sbrk.  This completely breaks the calculator.

6) Some Vax/BSD implementations of longjmp try to walk the stack to
find the frame in which the setjmp occurred.  This breaks the generic
implementation of Call/cc, and thus signal handling.  On such a system,
replace runtime/callcc.[ch] by runtime/vax_callcc.[ch], repectively.
