Readme file for Gambit-C version 3.0 (May 6, 1998)
====================================


This software is Copyright (C) 1994-1998 by Marc Feeley, all rights reserved.


This directory contains release 3.0 of the Gambit-C Scheme programming
system.  Gambit-C includes a Scheme interpreter and a compiler which
can be used to build standalone executables.  Because the compiler
generates portable C code, it is fairly easy to port to any machine
with a decent C compiler.  This release of the Gambit-C system has
been built successfully on the following platforms:

- DEC Alpha workstation
- SUN Sparc workstation
- SGI Mips workstation
- Hewlett-Packard HP-PA workstation
- PC with Linux ELF
- PC with Microsoft Visual C++
- PC with Borland C++
- PC with Watcom C/C++
- PC with MSDOS and DJGPP
- Apple Macintosh with CodeWarrior C/C++
- Apple Macintosh with MkLinux

This release has not been tested on the following platforms but
previous releases of Gambit-C have been built successfully:

- IBM RS6000 workstation
- Apple Macintosh with Power MachTen
- PC with NetBSD/i386 1.0
- PC with FreeBSD

The Gambit-C system conforms to the R4RS and IEEE Scheme standards.
The full numeric tower is implemented, including: infinite precision
integers (bignums), rationals, inexact reals (floating point numbers),
and complex numbers.  Gambit-C supports a number of extensions to the
standards including:

 - a debugger with
    - a continuation inspection facility (i.e. "backtrace")
    - a single-stepping mode
    - error messages with location of error (file, line, and column number)
 - a foreign function interface for C
 - a memory management system that grows and shrinks the heap based on
   the program's needs
 - a linker that builds standalone executables and shared libraries
 - dynamic loading of compiled modules and libraries (supported on many
   platforms including Macintosh when CodeWarrior is installed)
 - Unicode support for characters, strings, I/O and source code
 - object finalization
 - pretty printing
 - string ports
 - bytevectors (uniform vectors of integers or floating point numbers)
 - record structures
 - keyword objects
 - optional and keyword parameters (with the syntax and semantics of DSSSL)
 - configurable reader with control over case sensitivity
 - write/read invariance of symbols, e.g. (string->symbol "B;123") => |B;123|
 - write/read invariance of floating point numbers
 - dynamic variables (i.e. variables with dynamic scope)
 - eval
 - Maclisp style macros

Installation instructions are given in the next section.

The user manual for the Gambit-C system is available in Postscript
format (the file "doc/gambit-c.ps"), in HTML format (the file
"doc/gambit-c.html") and in "info" format (the files
"doc/gambit-c.info*").

If you have any questions concerning Gambit-C please address them to:

    gambit@iro.umontreal.ca

The latest official release of the system can be obtained from the
Gambit web page at:

    http://www.iro.umontreal.ca/~gambit



Installation instructions for Gambit-C version 3.0
==================================================

STEP 1  "./configure"
------

If your machine/OS configuration appears in the tested platform list
shown below type "./configure".  This will create makefiles adapted to
your system in the current directory and subdirectories (the makefiles
are generated from the makefile.in files).

By default the "gcc" compiler is used if it is available.  To force
the use of the "cc" compiler, set the environment variable "FORCE_CC"
to a non-null string when you do the "./configure".  For example:

  FORCE_CC=yes ./configure

By default, Gambit-C's runtime system will not place any limit on the
size of the Scheme heap.  A heap overflow will only be signalled when
virtual memory is all used up, which can take a long time and cause
lots of paging.  To place a limit on the heap size, define the symbol
"FORCE_MAX_HEAP" in the environment variable CFLAGS when you do the
"./configure".  For example, to get a 5000 kilobyte limit (a reasonable
amount for an educational environment) do:

  CFLAGS="-DFORCE_MAX_HEAP=5000" ./configure

TESTED PLATFORMS:

- DEC Alpha workstation:

  uname -a = OSF1 raptor.IRO.UMontreal.CA V4.0 386 alpha
  C compiler = OSF1 cc compiler (version unknown)

- SUN Sparc workstation with SunOS 4.1.4:

  uname -a = SunOS saguenay 4.1.4 5 sun4m
  C compiler = gcc version 2.7.2

- SUN Sparc workstation with Solaris:

  uname -a = SunOS jazz01 5.5 Generic_103093-03 sun4u sparc SUNW,Ultra-1
  C compiler = gcc version 2.7.2

  uname -a = SunOS ungava 5.6 Generic sun4m sparc SUNW,SPARCstation-20
  C compiler = gcc version 2.8.1

- SGI Mips workstation:

  uname -a = IRIX derby 5.3 11091811 IP19 mips
  C compiler = IRIX cc compiler (version unknown)
  make command = make SHELL=/bin/sh

- Hewlett-Packard HP-PA workstation:

  uname -a = HP-UX stjean B.10.01 A 9000/755
  C compiler = gcc version 2.7.2.2

- IBM RS6000 workstation:

  uname -a = AIX diana 2 3 000005641800
  C compiler = AIX cc compiler (version unknown)

- PC running Linux:

  uname -a = Linux bronto 2.1.86 #13 Fri Feb 20 10:47:36 EST 1998 i686 unknn
  C compiler = gcc version 2.8.1

- Apple Macintosh with MkLinux:

  uname -a = Linux terram 2.0.30-osfmach3 #1 Wed Nov 12 16:06:55 PST 1997 ppc unknown
  C compiler = gcc version 2.7.2.1-ppclinux

- Apple Macintosh with MachTen:

  OS = MACOS System 7.5.3 and Power MachTen 4.0.2
  uname -a = powerpc-tenon-machten tops 4 0.1 Power Macintosh
  C compiler = gcc version 2.7.0

If you have one of the following machine/OS configurations, you need
to use the build procedure explained in the file "misc/readme":

- PC running Windows-NT/95 and Microsoft Visual C++
- PC running Windows-NT/95 and Borland C++
- PC running Windows-NT/95 and Watcom C/C++
- Apple Macintosh and Macintosh CodeWarrior C/C++

If your machine appears in the tested platform list but the OS version
or C compiler is not the same, you can still try a "configure" and go
to step 2.  There is a high likelihood that this will work.  If this
fails because of some problem with the C compiler (for example not
enough swap space available), modify the file "lib/gambit.h" so that
appropriate options are passed to the C compiler (such as removing
optimizations) or call up a different C compiler, and start back at
step 1 after a "make clean".

Otherwise, you will have to configure the files "lib/gambit.h",
"lib/os.h" and "lib/os.c" to suit your system.  The file
"lib/gambit.h" defines the endianess of the machine, the size of
"long" ints, etc as well as which C compiler to use and the options to
pass to the C compiler, linker, etc.  The files "lib/os.h" and
"lib/os.c" implements OS-dependent routines (filename expansion,
interrupt handling, dynamic loading, etc).

If you needed to modify any file to get Gambit-C to work properly on
your system, please send your modifications along with your machine/OS
specification to

    gambit@iro.umontreal.ca

so that it can be added to the next release.

STEP 2  "make"
------

Type "make".  This will build the following components:

  in "gsi" subdirectory: the Gambit-C interpreter
  in "gsc" subdirectory: the Gambit-C compiler
  in "lib" subdirectory: the Gambit-C runtime library

These components are built as shared libraries if this is supported by
the OS, otherwise they are statically linked.  To force static
linking, set the environment variable "FORCE_STATIC_LINK" to a
non-null string when you do the "make" such as:

  make FORCE_STATIC_LINK=yes

After a successful "make" you will have the following files:

   static link build  shared library build

   gsi/gsi            gsi/gsi                        interpreter
   gsc/gsc            gsc/gsc                        compiler
   lib/libgambc.a     lib/libgambc.so                (on most versions of UNIX)
   lib/libgambc.a     lib/libgambc.so.1.1            (SunOS)
   lib/libgambc.a     lib/libgambc.sl                (HP-UX)
   lib/libgambc.lib   lib/gambc.dll + lib/gambc.lib  (Windows-NT/95)

and also

   doc/gambit-c.dvi      the Gambit-C user manual in "dvi" format
   doc/gambit-c.info*    the Gambit-C user manual in "info" format

STEP 3  "make check"
------

You can check that the programs work properly by doing "make check".
This will run the interpreter and compiler on some benchmark programs
and compare the result with the expected result.  If everything is
fine there should be no differences signaled by "diff".

Other benchmarks are included in the file "misc/bench.tgz".

STEP 4  "make install"
------

On UNIX systems you can now type "make install" to get a permanent
installation of the system (assuming you have the required
permissions).  By default the files will go in

    /usr/local/bin
    /usr/local/lib
    /usr/local/info
    /usr/local/include
    /usr/local/share/gambc

Previous versions of Gambit-C installed the files

    /usr/lib/libgambc.so
    /usr/include/gambit.h

Make sure you remove these files otherwise they will conflict with
those installed in /usr/local/lib and /usr/local/include.
