Go to the first, previous, next, last section, table of contents.

Installing SCM

Making SCM

The SCM distribution has Makefile which contains rules for making scmlit, a "bare-bones" version of SCM sufficient for running `build.scm'. `build.scm' is used to compile (or create scripts to compile) full featured versions.

Makefiles are not portable to the majority of platforms. If `Makefile' works for you, good; If not, I don't want to hear about it. If you need to compile SCM without build.scm, there are several ways to proceed:


[SLIB] is a portable Scheme library meant to provide compatibility and utility functions for all standard Scheme implementations. Although SLIB is not neccessary to run SCM, I strongly suggest you obtain and install it. Bug reports about running SCM without SLIB have very low priority. SLIB is available from the same sites as SCM:

Unpack SLIB (`tar xzf slib2c4.tar.gz' or `unzip -ao slib2c4.zip') in an appropriate directory for your system; both tar and unzip will create the directory `slib'.

Then create a file `require.scm' in the SCM implementation-vicinity (this is the same directory as where the file `Init5c4.scm' is installed). `require.scm' should have the contents:

(define (library-vicinity) "/usr/local/lib/slib/")
(load (in-vicinity (library-vicinity) "require"))

where the pathname string `/usr/local/lib/slib/' is to be replaced by the pathname into which you installed SLIB. Absolute pathnames are recommended here; if you use a relative pathname, SLIB can get confused when the working directory is changed (see section I/O-Extensions). The way to specify a relative pathname is to append it to the implementation-vicinity, which is absolute:

(define library-vicinity
  (let ((lv (string-append (implementation-vicinity) "../slib/")))
    (lambda () lv)))
(load (in-vicinity (library-vicinity) "require"))

Alternatively, you can set the (shell) environment variable SCHEME_LIBRARY_PATH to the pathname of the SLIB directory (see section Environment Variables). If set, the environment variable overrides `require.scm'. Again, absolute pathnames are recommended.

Building SCM

The file build.scm builds and runs a relational database of how to compile and link SCM executables. It has information for most platforms which SCM has been ported to (of which I have been notified). Some of this information is old, incorrect, or incomplete. Send corrections and additions to jaffer@ai.mit.edu.

Invoking Build

The all method will also work for MS-DOS and unix. Use the all method if you encounter problems with `build.scm'.

From the SCM source directory, type `build' followed by up to 9 command line arguments.
From the SCM source directory, type `./build.scm' followed by command line arguments.
From the SCM source directory, start `scm' or `scmlit' and type (load "build.scm"). Alternatively, start `scm' or `scmlit' with the command line argument `-ilbuild'.

Invoking build without the `-F' option will build or create a shell script with the arrays, inexact, and bignums options as defaults.

bash$ ./build.scm
rm -f scmflags.h
echo '#define IMPLINIT "/home/jaffer/scm/Init5c4.scm"'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
echo '#define ARRAYS'>>scmflags.h
gcc -O2 -c continue.c scm.c findexec.c script.c time.c repl.c scl.c \
        eval.c sys.c subr.c unif.c rope.c
gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \
        repl.o scl.o eval.o sys.o subr.o unif.o rope.o -lm -lc

To cross compile for another platform, invoke build with the `-p' or `---platform=' option. This will create a script for the platform named in the `-p' or `---platform=' option.

bash$ ./build.scm -p vms
$DELETE scmflags.h
$CREATE scmflags.h
#define IMPLINIT "/home/jaffer/scm/Init5c4.scm"
#define BIGNUMS
#define FLOATS
#define ARRAYS
$ cc continue scm findexec script time repl scl eval sys subr unif rope
$ macro setjump
$ link continue,scm,findexec,script,time,repl,scl,eval,sys,subr,unif,rope,setjump,sys$input/opt
$RENAME continue.exe scm.exe

Build Options

The options to build specify what, where, and how to build a SCM program or dynamically linked module. These options are unrelated to the SCM command line options.

Build Option: -p platform-name
Build Option: --platform=platform-name
specifies that the compilation should be for a computer/operating-system combination called platform-name. Note: The case of platform-name is distinguised. The current platform-names are all lower-case.

The platforms defined by table platform in `build.scm' are:

Table: platform
name              processor         operating-system  compiler          
symbol            processor-family  operating-system  symbol            
symbol            atom              symbol            symbol            
================= ================= ================= ================= 
*unknown*         *unknown*         unix              *unknown*         
acorn-unixlib     acorn             *unknown*         *unknown*         
aix               powerpc           aix               *unknown*         
alpha             alpha             osf1              cc                
alpha-elf         alpha             unix              *unknown*         
alpha-linux       alpha             linux             gcc               
amiga-aztec       m68000            amiga             aztec             
amiga-dice-c      m68000            amiga             dice-c            
amiga-gcc         m68000            amiga             gcc               
amiga-sas/c-5.10  m68000            amiga             sas/c             
atari-st-gcc      m68000            atari.st          gcc               
atari-st-turbo-c  m68000            atari.st          turbo-c           
borland-c-3.1     8086              ms-dos            borland-c         
cygwin32          i386              unix              gcc               
djgpp             i386              ms-dos            gcc               
freebsd           i386              unix              cc                
gcc               *unknown*         unix              gcc               
highc.31          i386              ms-dos            highc             
hp-ux             hp-risc           hp-ux             *unknown*         
irix              mips              irix              gcc               
linux             i386              linux             gcc               
linux-aout        i386              linux             gcc               
microsoft-c       8086              ms-dos            microsoft-c       
microsoft-c-nt    i386              ms-dos            microsoft-c       
microsoft-quick-c 8086              ms-dos            microsoft-quick-c 
ms-dos            8086              ms-dos            *unknown*         
os/2-cset         i386              os/2              c-set++           
os/2-emx          i386              os/2              gcc               
sun-svr4-gcc-sunl sparc             sunos             gcc               
sunos             sparc             sunos             *unknown*         
svr4              *unknown*         unix              *unknown*         
turbo-c-2         8086              ms-dos            turbo-c           
unicos            cray              unicos            *unknown*         
unix              *unknown*         unix              *unknown*         
vms               vax               vms               *unknown*         
vms-gcc           vax               vms               gcc               
watcom-9.0        i386              ms-dos            watcom            

Build Option: -o filename
Build Option: --outname=filename
specifies that the compilation should produce an executable or object name of filename. The default is `scm'. Executable suffixes will be added if neccessary, e.g. `scm' => `scm.exe'.

Build Option: -l libname ...
Build Option: --libraries=libname
specifies that the libname should be linked with the executable produced. If compile flags or include directories (`-I') are needed, they are automatically supplied for compilations. The `c' library is always included. SCM features specify any libraries they need; so you shouldn't need this option often.

Build Option: -D definition ...
Build Option: --defines=definition
specifies that the definition should be made in any C source compilations. If compile flags or include directories (`-I') are needed, they are automatically supplied for compilations. SCM features specify any flags they need; so you shouldn't need this option often.

Build Option: --compiler-options=flag
specifies that that flag will be put on compiler command-lines.

Build Option: --linker-options=flag
specifies that that flag will be put on linker command-lines.

Build Option: -s pathname
Build Option: --scheme-initial=pathname
specifies that pathname should be the default location of the SCM initialization file `Init5c4.scm'. SCM tries several likely locations before resorting to pathname (see section File-System Habitat). If not specified, the current directory (where build is building) is used.

Build Option: -c pathname ...
Build Option: --c-source-files=pathname
specifies that the C source files pathname ... are to be compiled.

Build Option: -j pathname ...
Build Option: --object-files=pathname
specifies that the object files pathname ... are to be linked.

Build Option: -i call ...
Build Option: --initialization=call
specifies that the C functions call ... are to be invoked during initialization.

Build Option: -t build-what
Build Option: --type=build-what
specifies in general terms what sort of thing to build. The choices are:
executable program.
library module.
archived dynamically linked library object files.
dynamically linked library object file.

The default is to build an executable.

Build Option: -h batch-syntax
Build Option: --batch-dialect=batch-syntax
specifies how to build. The default is to create a batch file for the host system. The SLIB file `batch.scm' knows how to create batch files for:

Build Option: -w batch-filename
Build Option: --script-name=batch-filename
specifies where to write the build script. The default is to display it on (current-output-port).

Build Option: -F feature ...
Build Option: --features=feature
specifies to build the given features into the executable. The defined features are:

Lightweight -- no features
Normally, the number of arguments arguments to interpreted closures (from LAMBDA) are checked if the function part of a form is not a symbol or only the first time the form is executed if the function part is a symbol. defining `reckless' disables any checking. If you want to have SCM always check the number of arguments to interpreted closures define feature `cautious'.
Define this for extra checking of interrupt masking and some simple checks for proper use of malloc and free. This is for debugging C code in `sys.c', `eval.c', `repl.c' and makes the interpreter several times slower than usual.
Turns on features `cautious' `careful-interrupt-masking' `stack-limit' and uses -g flags for debugging SCM source code.
If your scheme code runs without any errors you can disable almost all error checking by compiling all files with `reckless'.
Use to enable checking for stack overflow. Define value of the C preprocessor variable STACK_LIMIT to be the size to which SCM should allow the stack to grow. STACK_LIMIT should be less than the maximum size the hardware can support, as not every routine checks the stack.
Large precision integers.
Use if you want arrays, uniform-arrays and uniform-vectors.
array-map! and array-for-each (arrays must also be defined).
Use if you want floating point numbers.
Use if you want floats to display in engineering notation (exponents always multiples of 3) instead of scientific notation.
Use if you want all inexact real numbers to be single precision. This only has an effect if SINGLES is also defined (which is the default). This does not affect complex numbers.
Use if you want to run code from: H. Abelson, G. J. Sussman, and J. Sussman, Structure and Interpretation of Computer Programs, The MIT Press, Cambridge, Massachusetts, USA (eq? '() '#f) is the major difference.
These procedures were specified in the Revised^2 Report on Scheme but not in R4RS.
The Record package provides a facility for user to define their own record data types. See SLIB for documentation.
Use if you want to use compiled closures.
make_gsubr for arbitrary (< 11) arguments to C functions.
Use if you want the ticks and ticks-interrupt functions.
Commonly available I/O extensions: exec, line I/O, file positioning, file delete and rename, and directory functions.
Turtle graphics calls for both Borland-C and X11 from sjm@ee.tut.fi.
For the curses screen management package.
interface to the editline or GNU readline library.
String regular expression matching.
BSD socket interface.
Posix functions available on all Unix-like systems. fork and process functions, user and group IDs, file permissions, and link.
Those unix features which have not made it into the Posix specs: nice, acct, lstat, readlink, symlink, mknod and sync.
Microsoft Windows executable.
Be able to load compiled files while running.
Convert a running scheme program into an executable file.
Use if you want segments of unused heap to not be freed up after garbage collection. This may increase time in GC for *very* large working sets.
If you only need straight stack continuations, executables compile with this feature will run faster and use less storage than not having it. Machines with unusual stacks need this. Also, if you incorporate new C code into scm which uses VMS system services or library routines (which need to unwind the stack in an ordrly manner) you may need to use this feature.
C level support for hygienic and referentially transparent macros (R4RS macros).

Compiling and Linking Custom Files

A correspondent asks:

How can we link in our own c files to the SCM interpreter so that we can add our own functionality? (e.g. we have a bunch of tcp functions we want access to). Would this involve changing build.scm or the Makefile or both?

(see section Changing Scm has instructions describing the C code format). Suppose a C file foo.c has functions you wish to add to SCM. To compile and link your file at compile time, use the `-c' and `-i' options to build:

bash$ build -c foo.c -i init_foo
rm -f scmflags.h
echo '#define IMPLINIT "/home/jaffer/scm/Init5c4.scm"'>>scmflags.h
echo '#define COMPILED_INITS init_foo();'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
echo '#define ARRAYS'>>scmflags.h
gcc -O2 -c continue.c scm.c findexec.c script.c time.c repl.c scl.c \
        eval.c sys.c subr.c unif.c rope.c foo.c
gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \
        repl.o scl.o eval.o sys.o subr.o unif.o rope.o foo.o -lm -lc

To make a dynamically loadable object file use the -t dll option:

bash$ build -t dll -c foo.c
rm -f scmflags.h
echo '#define IMPLINIT "/home/jaffer/scm/Init5c4.scm"'>>scmflags.h
echo '#define BIGNUMS'>>scmflags.h
echo '#define FLOATS'>>scmflags.h
echo '#define ARRAYS'>>scmflags.h
echo '#define DLL'>>scmflags.h
gcc -O2 -fpic -c foo.c
gcc -shared -o foo.so foo.o -lm -lc

Once `foo.c' compiles correctly (and your SCM build supports dynamic-loading), you can load the compiled file with the Scheme command (load "./foo.so"). See section Configure Module Catalog for how to add a compiled dll file to SLIB's catalog.

Installing Dynamic Linking

Dynamic linking has not been ported to all platforms. Operating systems in the BSD family (a.out binary format) can usually be ported to DLD. The dl library (#define SUN_DL for SCM) was a proposed POSIX standard and may be available on other machines with COFF binary format. For notes about porting to MS-Windows and finishing the port to VMS section Finishing Dynamic Linking.

DLD is a library package of C functions that performs dynamic link editing on Linux, VAX (Ultrix), Sun 3 (SunOS 3.4 and 4.0), SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and Atari ST. It is available from:


These notes about using libdl on SunOS are from `gcc.info':

On a Sun, linking using GNU CC fails to find a shared library and reports that the library doesn't exist at all.

This happens if you are using the GNU linker, because it does only static linking and looks only for unshared libraries. If you have a shared library with no unshared counterpart, the GNU linker won't find anything.

We hope to make a linker which supports Sun shared libraries, but please don't ask when it will be finished--we don't know.

Sun forgot to include a static version of `libdl.a' with some versions of SunOS (mainly 4.1). This results in undefined symbols when linking static binaries (that is, if you use `-static'). If you see undefined symbols `_dlclose', `_dlsym' or `_dlopen' when linking, compile and link against the file `mit/util/misc/dlsym.c' from the MIT version of X windows.

Configure Module Catalog

The SLIB module catalog can be extended to define other require-able packages by adding calls to the Scheme source file `mkimpcat.scm'. Within `mkimpcat.scm', the following procedures are defined.

Function: add-link feature object-file lib1 ...
feature should be a symbol. object-file should be a string naming a file containing compiled object-code. Each libn argument should be either a string naming a library file or #f.

If object-file exists, the add-link procedure registers symbol feature so that the first time require is called with the symbol feature as its argument, object-file and the lib1 ... are dynamically linked into the executing SCM session.

If object-file exists, add-link returns #t, otherwise it returns #f.

For example, to install a compiled dll `foo', add these lines to `mkimpcat.scm':

        (add-link 'foo
                  (in-vicinity (implementation-vicinity) "foo"

Function: add-alias alias feature
alias and feature are symbols. The procedure add-alias registers alias as an alias for feature. An unspecified value is returned.

add-alias causes (require 'alias) to behave like (require 'feature).

Function: add-source feature filename
feature is a symbol. filename is a string naming a file containing Scheme source code. The procedure add-source registers feature so that the first time require is called with the symbol feature as its argument, the file filename will be loaded. An unspecified value is returned.

Remember to delete the file `slibcat' after modifying the file `mkimpcat.scm' in order to force SLIB to rebuild its cache.

Saving Images

In SCM, the ability to save running program images is called dump (see section Dump). In order to make dump available to SCM, build with feature `dump'. dumped executables are compatible with dynamic linking.

Most of the code for dump is taken from `emacs-19.34/src/unex*.c'. No modifications to the emacs source code were required to use `unexelf.c'. Dump has not been ported to all platforms. If `unexec.c' or `unexelf.c' don't work for you, try using the appropriate `unex*.c' file from emacs.

Automatic C Preprocessor Definitions

These `#defines' are automatically provided by preprocessors of various C compilers. SCM uses the presence or absence of these definitions to configure include file locations and aliases for library functions. If the definition(s) corresponding to your system type is missing as your system is configured, add -Dflag to the compilation command lines or add a #define flag line to `scmfig.h' or the beginning of `scmfig.h'.

#define         Platforms:
-------         ----------
ARM_ULIB        Huw Rogers free unix library for acorn archimedes
AZTEC_C         Aztec_C 5.2a
__CYGWIN32__    cygwin32(?)
_DCC            Dice C on AMIGA
__GNUC__        Gnu CC (and DJGPP)
__EMX__         Gnu C port (gcc/emx 0.8e) to OS/2 2.0
__HIGHC__       MetaWare High C
__IBMC__        C-Set++ on OS/2 2.1
_MSC_VER        MS VisualC++ 4.2
MWC             Mark Williams C on COHERENT
__MWERKS__      Metrowerks Compiler; Macintosh and WIN32 (?)
_QC             Microsoft QuickC
__STDC__        ANSI C compliant
__TURBOC__      Turbo C and Borland C
__USE_POSIX     ??
__WATCOMC__     Watcom C on MS-DOS
__ZTC__         Zortech C

_AIX            AIX operating system
AMIGA           SAS/C 5.10 or Dice C on AMIGA
__amigados__    Gnu CC on AMIGA
atarist         ATARI-ST under Gnu CC
GNUDOS          DJGPP (obsolete in version 1.08)
__GO32__        DJGPP (future?)
hpux            HP-UX
linux           Linux
macintosh       Macintosh (THINK_C and __MWERKS__ define)
MCH_AMIGA       Aztec_c 5.2a on AMIGA
MSDOS           Microsoft C 5.10 and 6.00A
__MSDOS__       Turbo C, Borland C, and DJGPP
nosve           Control Data NOS/VE
SVR2            System V Revision 2.
__svr4__        SunOS
THINK_C         developement environment for the Macintosh
ultrix          VAX with ULTRIX operating system.
unix            most Unix and similar systems and DJGPP (!?)
__unix__        Gnu CC and DJGPP
_UNICOS         Cray operating system
vaxc            VAX C compiler
VAXC            VAX C compiler
vax11c          VAX C compiler
VAX11           VAX C compiler
_Windows        Borland C 3.1 compiling for Windows
_WIN32          MS VisualC++ 4.2 under Windows-NT
vms             (and VMS) VAX-11 C under VMS.

__alpha         DEC Alpha processor
__alpha__       DEC Alpha processor
hp9000s800      HP RISC processor
__i386__        DJGPP
i386            DJGPP
MULTIMAX        Encore computer
pyr             Pyramid 9810 processor
__sgi__         Silicon Graphics Inc.
sparc           SPARC processor
sequent         Sequent computer
tahoe           CCI Tahoe processor
vax             VAX processor

Problems Compiling

*.c: include file not found
Correct the status of STDC_HEADERS in `scmfig.h' fix #include statement or add #define for system type to `scmfig.h'.
*.c: Function should return a value in ...
*.c: Parameter '...' is never used in ...
*.c: Condition is always false in ...
*.c: Unreachable code in function ...
scm.c: assignment between incompatible types
change SIGRETTYPE in `scm.c'.
time.c: CLK_TCK redefined
incompatablility between <stdlib.h> and <sys/types.h>. remove STDC_HEADERS in `scmfig.h'. edit <sys/types.h> to remove incompatability.
subr.c: Possibly incorrect assignment in function lgcd
sys.c: statement not reached
sys.c: constant in conditional expression
sys.c: `???' undeclared, outside of functions
#undef STDC_HEADERS in `scmfig.h'.
scl.c: syntax error
#define SYSTNAME to your system type in `scl.c' (softtype)

Problems Linking

_sin etc. missing.
uncomment LIBS in makefile

Problems Running

Opening message and then machine crashes.
Change memory model option to C compiler (or makefile). Make sure sizet definition is correct in `scmfig.h'. Reduce size of HEAP_SEG_SIZE in `setjump.h'.
Input hangs
#define NOSETBUF
ERROR: heap: need larger initial
Need to increase the initial heap allocation using -a<kb> or INIT_HEAP_SIZE.
ERROR: Could not allocate ...
Check sizet definition. Use 32 bit compiler mode. Don't try to run as subproccess
remove ... in scmfig.h and recompile scm
add ... in scmfig.h and recompile scm
Do it and recompile files.
ERROR: `Init5c4.scm' not found
Assign correct IMPLINIT in makefile or `scmfig.h' or define environment variable SCM_INIT_PATH to be the full pathname of `Init5c4.scm' (see section Installing SCM).
WARNING: require.scm not found
define environment variable SCHEME_LIBRARY_PATH to be the full pathname of the scheme library [SLIB] or change library-vicinity in `Init5c4.scm' to point to library or remove. See section `Installation' in SLIB. Make sure the value of (library-vicinity) has a trailing file separator (like / or \).


Loading `r4rstest.scm' in the distribution will run an [R4RS] conformance test on scm.

> (load "r4rstest.scm")
;loading "r4rstest.scm"
 #<primitive-procedure boolean?>
    #<primitive-procedure char?>
       #<primitive-procedure null?>
          #<primitive-procedure number?>

Loading `pi.scm' in the distribution will enable you to compute digits of pi.

> (load "pi")
;loading "pi"
;done loading "pi.scm"
;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other
> (pi 100 5)
00003 14159 26535 89793 23846 26433 83279 50288 41971 69399
37510 58209 74944 59230 78164 06286 20899 86280 34825 34211
;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other

Loading `bench.scm' will compute and display performance statistics of SCM running `pi.scm'. `make bench' or `make benchlit' appends the performance report to the file `BenchLog', facilitating tracking effects of changes to SCM on performance.

Runs some and then machine crashes.
See above under machine crashes.
Runs some and then ERROR: ... (after a GC has happened)
Remove optimization option to C compiler and recompile. #define SHORT_ALIGN in `scmfig.h'.
Some symbol names print incorrectly.
Change memory model option to C compiler (or makefile). Check that HEAP_SEG_SIZE fits within sizet. Increase size of HEAP_SEG_SIZE (or INIT_HEAP_SIZE if it is smaller than HEAP_SEG_SIZE).
ERROR: Rogue pointer in Heap.
See above under machine crashes.
Newlines don't appear correctly in output files.
Check file mode (define OPEN_... in `Init5c4.scm'
Spaces or control characters appear in symbol names
Check character defines in `scmfig.h'.
Negative numbers turn positive.
Check SRS in `scmfig.h'.
VMS: Couldn't unwind stack
VAX: botched longjmp
#define CHEAP_CONTIUATIONS in `scmfig.h'.
Sparc(SUN-4) heap is growing out of control
You are experiencing a GC problem peculiar to the Sparc. The problem is that SCM doesn't know how to clear register windows. Every location which is not reused still gets marked at GC time. This causes lots of stuff which should be collected to not be. This will be a problem with any conservative GC until we find what instruction will clear the register windows. This problem is exacerbated by using lots of call-with-current-continuations.

Reporting Problems

Reported problems and solutions are grouped under Compiling, Linking, Running, and Testing. If you don't find your problem listed there, you can send a bug report to jaffer@ai.mit.edu. The bug report should include:

  1. The version of SCM (printed when SCM is invoked with no arguments).
  2. The type of computer you are using.
  3. The name and version of your computer's operating system.
  4. The values of the environment variables SCM_INIT_PATH and SCHEME_LIBRARY_PATH.
  5. The name and version of your C compiler.
  6. If you are using an executable from a distribution, the name, vendor, and date of that distribution. In this case, corresponding with the vendor is recommended.

Go to the first, previous, next, last section, table of contents.