Avoid a deadlock when a trace is interrupted by the user with a ctrl-C.

[gambit-c.git] / INSTALL.txt

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

              [Time-stamp: <2009-02-11 11:12:55 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 bootstrap
  % make check
  % sudo make install

The configure script, which was generated by the "autoconf" tool,
accepts many 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 some versions of the GCC compiler it is possible 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

Note that this option might degrade the execution speed, so it is best
to build the system both ways and see which works best for your
version of GCC.

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.

Finally, in order to support installing multiple versions of Gambit,
it is recommended to use these options:

  % ./configure --enable-single-host --enable-multiple-versions


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 central installation
directory with the option --prefix:

  % ./configure --prefix=/Users/feeley/my-gambit
  % make install
  % ~/my-gambit/bin/gsi
  Gambit v4.4.0
  ...

If the --prefix option is not used, the default is to install all
files in /usr/local/Gambit-C and its subdirectories, namely "bin",
"lib", "include", etc.  The files that would normally go in these
subdirectories can be redirected to other directories using one of
the following configure options:

  --bindir=DIR            executables (gsi, gsc, ...)
  --libdir=DIR            libraries (libgambc.a, syntax-case.scm, ...)
  --includedir=DIR        C header files (gambit.h, ...)
  --docdir=DIR            documentation (gambit-c.pdf, gambit-c.html, ...)
  --infodir=DIR           info documentation (gambit-c.info, ...)
  --datadir=DIR           read-only architecture-independent data (gambit.el)

Note that the install target of the makefiles supports the DESTDIR
environment variable which allows staging an install to a specific
directory.  The command:

  % make install DESTDIR=/Users/feeley/stage

will install all the files in /Users/feeley/stage as though it was the
root of the filesystem.  Note that the use of DESTDIR is incompatible
with the combination of --enable-shared and
--enable-absolute-shared-libs options.

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-gcc-opts       use expensive GCC optimizations
  --enable-cplusplus      compile using C++ compiler
  --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
  --enable-feedback1      build system to accumulate trial run data
  --enable-feedback2      build system using trial run feedback
  --enable-inline-jumps   generate inline code for jumps
  --enable-char-size=N    Scheme character size in bytes (N = 1, 2 or 4)
  --enable-ansi-c         link only with ANSI C libraries
  --enable-symlinks       use symbolic links for installed files not in the
                          central installation directory
  --enable-multiple-versions
                          multiple installed versions are supported
  --enable-absolute-shared-libs
                          shared libraries should be linked to using an
                          absolute path
  --enable-help-browser=BROWSER
                          use the specified browser to view documentation
                          requested through the help procedure or REPL

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++).

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, --enable-feedback1, and
--enable-feedback2 are useful for debugging the system.

The option --enable-symlinks is useful when the --bindir, --libdir,
... options are used.  The files will actually be stored in the
central installation directory and symbolic links to those files will
be stored in the directories specified to --bindir, --libdir, ...

The option --enable-multiple-versions allows multiple versions of
Gambit to be installed.  When it is enabled the path of the central
installation directory (specified with --prefix) is automatically
extended with a subdirectory which is the version number, and a
"current" symbolic link points to the version subdirectory.  All
symbolic links created as a result of the --enable-symlinks option
will refer to the files indirectly through the "current" symbolic
link.  Switching to a different version of Gambit can be done by
simply redirecting the "current" symbolic link to another version
subdirectory.

When --enable-shared is used, the option --enable-absolute-shared-libs
will install executables (for gsi and gsc) which contain references to
the absolute paths of the libraries.  This is necessary when multiple
versions of Gambit are installed so that each executable refers to the
appropriate Gambit shared library.  This is the default behavior.
Note that this option is incompatible with the use of DESTDIR because
the executables can only be linked after the Gambit shared libraries
are installed in their final destination.

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 dist-devel          Creates a compressed tar file of
                             the system including all the source code
                             management files.

  % make doc                 Builds the documentation.

  % make rc-setup            For initial setup of source code
                             management using git.  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.
                             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.