Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

417 lines (325 sloc) 18.817 kB
Installation instructions for Gambit-C
This directory contains a release of the Gambit-C Scheme programming
system (see the file 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) Obtaining the Gambit source code
The Gambit source code can be obtained in different ways.
- You can get the most recent version of the sources directly from
the Gambit repository on github:
% git clone
% cd gambit
Note that the source code obtained may contain some stale .c files.
Up to date files can be obtained after the system is built using
the commands "make bootstrap; make bootclean; make". The last
"make" uses the Gambit compiler to generate up to date .c files.
- You can get a specific release, preferably the latest, in the form
of a compressed tar ball (.tgz extension). The simplest is to use
a browser to visit the Gambit wiki (
and click on "Development Sources" to download the compressed tar
ball. Alternatively, use wget or curl from the command line,
for example:
% wget
% tar zxf gambc-v4_6_5-devel.tgz
% mv gambc-v4_6_5-devel gambit
% cd gambit
Note that releases come in two flavors. The "developer" release,
which has a "-devel" suffix in its name, contains the complete git
history. It is a snapshot of the Gambit repository at a particular
point in time. The "plain" release, without the "-devel" suffix in
its name, does not contain the git history and is much more compact
than the developer release.
Obtaining a version of the sources with the git history is required if
you intend to contribute changes to the Gambit repository. In that
case you will need a github account. Please send a message with your
github user name to to request write
2) Quick-install instructions
On most Unix platforms the system can be easily built, tested and
installed using the following commands:
% ./configure
% make
% 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
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
3) 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.6.5
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
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 (, ...)
--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-coverage build system to accumulate coverage statistics
--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
choose name for Gambit interpreter (default = gsi)
choose name for Gambit compiler (default = gsc)
multiple installed versions are supported
shared libraries should be linked to using an
absolute path
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 options --enable-debug and --enable-profile are useful for
debugging the system.
The options --enable-feedback1 and --enable-feedback2 are useful for
building the system such that it is optimized for a particular use
case. The system should first be built with --enable-feedback1, then
one or more sample executions of the system should be performed, and
then finally the system should be built with --enable-feedback2. For
% ./configure --single-host --enable-feedback1
% make
% gsc/gsc -:=. my-favorite-program.scm
% gsi/gsi -:=. my-favorite-program.o1
% make mostlyclean
% ./configure --single-host --enable-feedback2
% make
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 options --enable-interpreter-name=INTERP and
--enable-compiler-name=COMP are useful when names different from the
defaults are needed (i.e. gsi and gsc respectively). These options
should be used only when absolutely necessary because users will
expect the defaults (from reading documentation, talking with users on
a different OS, etc). We strongly suggest that the names start with
gsi and gsc respectively, so that shell tab completion will help the
user discover the correct name.
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
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"
4) 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-boot in the root directory.
The makefiles call up gsc-boot to
compile the Scheme source files
in the system if they are modified.
% make mostlyclean Removes all the files that can be
regenerated using basic tools
(C compiler, sed, etc). The feedback
files are not removed.
% make clean Removes all the files that are created
from a pristine distribution during
a "make" (object files, libraries,
gsi, gsc, etc).
% make bootclean Like "make clean", but also removes the
C files that the gsc-boot compiler can
create from the Scheme source files. This
should only be used after a successful
"make bootstrap". The next "make" will
compile the whole system from scratch,
including compiling the Scheme sources
to C, using gsc-boot.
% make realclean Like "make bootclean", but also removes all
the files which can be created using the
configure script (this includes the makefiles).
% 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"
% 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 new-revision Changes the version number of the system,
% make new-minor by incrementing either the revision number,
% make new-major the minor number or the major number.
This should only be performed by the
Gambit maintainers after thorough testing.
% make release Builds source tarball and installers.
This is normally done after changing
the version number of the system.
Note: this make target is very platform
specific and is intended for the Gambit
% make prebuilt Builds installers for Mac OS X and Windows.
This is normally done after changing
the version number of the system.
Note: this make target is very platform
specific and is intended for the Gambit
5) Building on Microsoft Windows
There are several alternatives for building the system on Microsoft
a) Use the free MSYS/MinGW development environment (Minimalist GNU
for Windows, Install MinGW and MSYS, then follow
the instructions above (i.e. "./configure" followed by "make").
b) Use the free Cygwin development environment
( 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 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: .
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\" in the Gambit distribution's root directory.
Then with Microsoft Visual Studio open "gambc.sln" and select
"Build Solution" (Ctrl+Shift+B).
6) 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
"") 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
so that it can be added to the next release.
Jump to Line
Something went wrong with that request. Please try again.