INSTALL file for Gambit-C version 4.0 beta 20 (October 6, 2006) ============================================= This software is Copyright (C) 1994-2006 by Marc Feeley, all rights reserved. This directory contains release 4.0 beta 20 of the Gambit-C Scheme programming system. 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 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 4 minutes on a 2 GHz Intel Core Duo based MacBook Pro with the GCC 4.0.1 compiler instead of 300 megabytes and 2 minutes when --enable-single-host is not used. With --enable-single-host and --enable-gcc-opts the build takes roughly 2 gigabytes and 8 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 Version 4.0 beta 20 ... 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-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 % 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 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". % 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. 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++ Toolkit 2003 which can be obtained at no charge from Microsoft at this URL: http://msdn.microsoft.com/visualc/vctoolkit2003/. You must also get the Microsoft Platform SDK and install it in C:/Program Files/Microsoft Platform SDK/. From the shell, execute the batch file "misc\vctoolkit.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.