/
INSTALL.txt
370 lines (288 loc) · 16.2 KB
/
INSTALL.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
Installation instructions for Gambit-C
======================================
[Time-stamp: <2009-06-09 17:32:05 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
% 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-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
--enable-interpreter-name=INTERP
choose name for Gambit interpreter (default = gsi)
--enable-compiler-name=COMP
choose name for Gambit compiler (default = gsc)
--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 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
example:
% ./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
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.
Note that a simple "make" will also
copy the gsc executable to gsc-comp if
it does not exist.
% 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-comp 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.
% 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"
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.