                Installation instructions for Gambit-C
                ======================================

              [Time-stamp: <2007-08-21 10:58:51 feeley>]


This directory contains a release of the Gambit-C Scheme programming
system (see the file configure.ac for the version number).  Gambit-C
includes a Scheme interpreter and a Scheme compiler which can be used
to build standalone executables.  Because the compiler generates
portable C code it is fairly easy to port to any platform with a
decent C compiler.


1) Quick-install instructions
=============================

On most Unix platforms the system can be easily built, tested and
installed using the following commands:

  % ./configure
  % make
  % make check
  % make install
  % make bootstrap

The configure script, which was generated by the "autoconf" tool,
accepts command line options that control various features.  It is
***highly*** recommended to use the --enable-single-host option to
improve the execution speed and compactness of the executables:

  % ./configure --enable-single-host

By using the --enable-single-host option, the speed of the Gambit-C
interpreter improves by roughly a factor of 2.

It is also ***highly*** recommended to use the GCC compiler to build
the system as the source code can take advantage of some GCC
extensions.  Notably the use of GCC's computed gotos reduces the
execution time by roughly 35%.

When using the GCC compiler it is recommended to use the
--enable-gcc-opts option to further improve the execution speed and
compactness of the executables:

  % ./configure --enable-single-host --enable-gcc-opts

These options are not used by default because compilation is much
longer and requires more RAM.  In fact some platforms may not have
enough resources to build the system this way.  With
--enable-single-host the build takes roughly 500 megabytes and 2 to 4
minutes on a 2 GHz Intel Core Duo based MacBook Pro with the GCC 4.0.1
compiler instead of 300 megabytes and 1 to 2 minutes when
--enable-single-host is not used.  With --enable-single-host and
--enable-gcc-opts the build takes roughly 2 gigabytes and over 10
minutes.

We recommend that users build Gambit-C with GCC 3.1 or later; GCC 3.1
will compile C code generated by the Gambit-C compiler faster than
previous versions of GCC, and will generally produce faster code than
previous versions of GCC.  For example, the interpreter is about 5%
faster than when it is compiled with GCC 2.95.3.

The compile time varies greatly from one version of GCC to the next
(usually a more recent version is better, but not always).  This is
because the algorithms used to implement the optimizations performed
by the compiler evolve and vary in computational complexity.  Since
the C files are so large, the compile time is very sensitive to the
computational complexity of the optimization algorithms.


2) Other options of the "configure" script
==========================================

The detailed list of options accepted by the "configure" script can be
obtained with:

  % ./configure --help

Most options are the same as for other autoconf generated configure
scripts.  For example, you can select the installation directory with
the option --prefix:

  % ./configure --prefix=/u/feeley/my-gambit
  % make install
  % ~/my-gambit/current/bin/gsi
  Gambit v4.0.0
  ...

If the --prefix option is not used, the default is to install all
files in /usr/local/Gambit-C and its subdirectories.

The configure options which are specific to the Gambit-C system are:

  --enable-single-host    compile each Scheme module as a single C function
  --enable-inline-jumps   Generate inline code for jumps
  --enable-gcc-opts       use expensive GCC optimizations
  --enable-char-size=N    define Scheme character size in bytes (N = 1, 2 or 4)
  --enable-cplusplus      compile using C++ compiler
  --enable-guide          include the Gambit Universal IDE
  --enable-shared         build the Scheme runtime system as a shared library
  --enable-debug          build system so that it can be debugged
  --enable-profile        build system so that it can be profiled

The option --enable-cplusplus should be used when applications
developped with the Gambit-C compiler are to be linked with code or
libraries written in C++.  This will compile all of the Gambit-C
source code with a C++ compiler instead of a C compiler (this is
possible because the code generated by the Gambit-C compiler conforms
both to C and C++).

[NOTE: Due to some last-minute makefile problems, GUIDE is not supported
in this release.]
The option --enable-guide will include the Gambit Universal IDE in the
Gambit-C runtime system.  The option --enable-cplusplus must be used
when the option --enable-guide is used.  The Gambit Universal IDE
requires the Qt GUI library version 3.3.  To include GUIDE it is
necessary to first build the system without including GUIDE (to have a
working Gambit-C compiler) and then rebuild the system with GUIDE
enabled.  For instance:

  % ./configure --enable-cplusplus
  % make bootstrap
  % make clean
  % ./configure --enable-cplusplus --enable-guide
  % make

The option --enable-shared will build a shared library for the
Gambit-C runtime system.  This is not supported on all platforms.

The option --enable-debug and --enable-profile are useful for
debugging the system.

By default the configure script will use the GCC compiler to build the
system, if it is available.  To override this choice or to use special
C compiler flags it is possible to set the environment variables CC,
CFLAGS, LDFLAGS, etc in the shell or on the configure command line.
Object file compilation options should go in CFLAGS, link options
should go in LDFLAGS, and options that apply to both can be next to
the name of the C compiler in CC.  Here are some examples.

  - To use cc instead of gcc:

      % ./configure CC=cc

  - On a Sun Sparc workstation, the following will use the Sun
    Workshop C/C++ compiler and generate 64 bit executables (the heap
    can grow beyond 4 Gbytes):

      % ./configure CC="cc -xtarget=native -xarch=v9"

  - On a Compaq Alpha workstation, the following will use the Compaq
    Tru64 UNIX C/C++ compiler and generate executables that use 32 bit
    addressing instead of the normal 64 bit addressing (the heap and
    code will be in the lower 4 GBytes of the address space):

      % ./configure CC=cc CFLAGS="-w -D___USE_32_BIT_ADDR" LDFLAGS=-taso

  - By default, Gambit-C's runtime system does not restrict 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.  This is not ideal for an educational
    environment where endless recursions are commonplace.  The symbol
    ___FORCE_MAX_HEAP can be defined to put a limit on the size of the
    heap.  To get a 5000 kilobyte limit (a reasonable amount for an
    educational environment) the system could be configured with:

      % ./configure CFLAGS="-D___FORCE_MAX_HEAP=5000"


3) Other "make" targets
=======================

Here is a description of the most useful "make" targets:

  % make bootstrap           Builds the system and copies the gsc
                             executable to gsc-comp in the root directory.
                             The makefiles call up gsc-comp to
                             compile the Scheme source files
                             in the system if they are modified.

  % make mostlyclean         Removes all the files that can be
                             regenerated using standard tools
                             (C compiler, TeX, etc).  The C files
                             generated by gsc, and the gsi and
                             gsc executables are not removed.

  % make clean               Removes all the files that can be
                             regenerated by a "make" (object files,
                             C files generated by gsc, etc) **except**
                             gsi and gsc.  This is useful to
                             bootstrap from the Scheme sources
                             after gsc has been built with an
                             initial "make bootstrap".

  % make realclean           Like "make clean", but also removes
                             gsi and gsc, and all the makefiles
                             generated by the configure script.

  % make check               Checks that gsi and gsc pass some
                             basic tests by running a few Scheme
                             programs with gsi and gsc.

  % make examples            Runs the programs in the "examples"
                             subdirectory.

  % make dist                Creates a compressed tar file of
                             the system.

  % make doc                 Builds the documentation.

  % make hg-setup            For initial setup of source code
                             management using Mercurial.  This should
                             only be performed by the Gambit maintainers.

  % make prebuilt            Builds installers for Mac OS X and Windows.
                             Note: this make target is very platform
                             specific and is intended for the Gambit
                             maintainers.

  % make release             Builds source tarball and installers and
                             uploads them to the Gambit web site.
                             Note: this make target is very platform
                             specific and is intended for the Gambit
                             maintainers.


4) Building on Microsoft Windows
================================

There are several alternatives for building the system on Microsoft
Windows:

  a) Use the free MSYS/MinGW development environment (Minimalist GNU
     for Windows, www.mingw.org).  Install MinGW and MSYS, then follow
     the instructions above (i.e. "./configure" followed by "make").

  b) Use the free Cygwin development environment
     (http://www.cygwin.com/).  Install Cygwin, then follow the
     instructions above (i.e. "./configure" followed by "make").

  c) Use the Open Watcom compiler which can be obtained at no charge
     from http://openwatcom.mirrors.pair.com/.  You must perform a
     full installation of the Open Watcom compiler in C:\WATCOM.  From
     the shell, execute the batch file "misc\openwatcom.bat".

  d) Use the Microsoft Visual C++ 2005 Express Edition which can be
     obtained at no charge from Microsoft at this URL:
     http://msdn.microsoft.com/vstudio/express/downloads/default.aspx .
     You must also install the Microsoft Platform SDK.  From the
     shell, execute the batch file "misc\vcexpress.bat".

  e) Use Microsoft Visual Studio .NET 2003.  You must unzip
     "misc\vstudio.zip" in the Gambit distribution's root directory.
     Then with Microsoft Visual Studio open "gambc.sln" and select
     "Build Solution" (Ctrl+Shift+B).


5) If you can't build the system on your platform
=================================================

The configure script tailors the build process to your platform.
Although it can adapt to a wide range of platforms there are cases
where it is not clever enough to do it completely automatically.

In this case you need to modify the configure script (the file
"configure.ac") and/or the source code of the Gambit-C system.  Most
of the system dependent code is located in the files
"include/gambit.h", "lib/os*.h" and "lib/os*.c".  Never modify the C
files generated by the Gambit-C compiler (these files usually have a
name that starts or ends with an underscore).

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.
