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

Overview

Scm is a portable Scheme implementation written in C. Scm provides a machine independent platform for [JACAL], a symbolic algebra system.

The most recent information about SCM can be found on SCM's WWW home page:

http://www-swiss.ai.mit.edu/~jaffer/SCM.html

Features

Authors

Aubrey Jaffer (jaffer@ai.mit.edu)
Most of SCM.
Radey Shouman
Arrays. gsubrs, compiled closures, and records.
Jerry D. Hedden
Real and Complex functions. Fast mixed type arithmetics.
Hugh Secker-Walker
Syntax checking and memoization of special forms by evaluator. Storage allocation strategy and parameters.
George Carrette
Siod, written by George Carrette, was the starting point for SCM. The major innovations taken from Siod are the evaluator's use of the C-stack and being able to garbage collect off the C-stack (see section Garbage Collection).

There are many other contributors to SCM. They are acknowledged in the file `ChangeLog', a log of changes that have been made to scm.

Bibliography

[IEEE]
IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming Language. IEEE, New York, 1991.
[Simply]
Brian Harvey and Matthew Wright. Simply Scheme: Introducing Computer Science MIT Press, 1994 ISBN 0-262-08226-8
[SICP]
Harold Abelson and Gerald Jay Sussman with Julie Sussman. Structure and Interpretation of Computer Programs. MIT Press, Cambridge, 1985.
[R4RS]
William Clinger and Jonathan Rees, Editors. Revised(4) Report on the Algorithmic Language Scheme. ACM Lisp Pointers Volume IV, Number 3 (July-September 1991), pp. 1-55.
[GUILE]
Tom Lord. The Guile Architecture for Ubiquitous Computing. Usenix Symposium on Tcl/Tk, 1995.
[SLIB]
Todd R. Eigenschink, Dave Love, and Aubrey Jaffer. SLIB, The Portable Scheme Library. Version 2a3, June 1995.
[JACAL]
Aubrey Jaffer. JACAL Symbolic Mathematics System. Version 1a5, April 1994.
`scm.texi'
`scm.info'
Documentation of scm extensions (beyond Scheme standards). Documentation on the internal representation and how to extend or include scm in other programs.

Invoking SCM

scm [-a kbytes] [-ibvqmu] [-p number] [-c expression] [-e expression] [-f filename] [-l filename] [-r feature] [-- | - | -s] [filename] [arguments ...]

Upon startup scm loads the file specified by by the environment variable SCM_INIT_PATH.

If SCM_INIT_PATH is not defined or if the file it names is not present, scm tries to find the directory containing the executable file. If it is able to locate the executable, scm looks for the initialization file (usually `Init.scm') in platform-dependent directories relative to this directory. See section File-System Habitat for a blow-by-blow description.

As a last resort (if initialization file cannot be located), the C compile parameter IMPLINIT (defined in the makefile or `scmfig.h') is tried.

Unless the option -no-init-file or --no-init-file occurs in the command line, `Init.scm' checks to see if there is file `ScmInit.scm' in the path specified by the environment variable HOME (or in the current directory if HOME is undefined). If it finds such a file it is loaded.

`Init.scm' then looks for command input from one of three sources: From an option on the command line, from a file named on the command line, or from standard input.

This explanation applies to SCMLIT or other builds of SCM.

Scheme-code files can also invoke SCM and its variants. See section Syntax Extensions.

Options

The options are processed in the order specified on the command line.

Command Option: -a kb
specifies that scm should allocate an initial heapsize of kb kilobytes. This option, if present, must be the first on the command line. If not specified, the default is INIT_HEAP_SIZE in source file `setjump.h' which the distribution sets at 25000*sizeof(cell).

Command Option: -no-init-file
Command Option: --no-init-file
Inhibits the loading of `ScmInit.scm' as described above.

Command Option: -e expression
Command Option: -c expression
specifies that the scheme expression expression is to be evaluated. These options are inspired by perl and sh respectively. On Amiga systems the entire option and argument need to be enclosed in quotes. For instance `"-e(newline)"'.

Command Option: -r feature
requires feature. This will load a file from [SLIB] if that feature is not already supported. If feature is 2, 3, 4, or 5 scm will require the features neccessary to support [R2RS], [R3RS], [R4RS], or proposed [R5RS], respectively.

Command Option: -l filename
Command Option: -f filename
loads filename. Scm will load the first (unoptioned) file named on the command line if no -c, -e, -f, -l, or -s option preceeds it.

Command Option: -p level
sets the prolixity (verboseness) to level. This is the same as the scm command (verobse level).

Command Option: -v
(verbose mode) specifies that scm will print prompts, evaluation times, notice of loading files, and garbage collection statistics. This is the same as -p3.

Command Option: -q
(quiet mode) specifies that scm will print no extra information. This is the same as -p0.

Command Option: -m
specifies that subsequent loads, evaluations, and user interactions will be with [R4RS] macro capability. To use a specific [R4RS] macro implementation from [SLIB] (instead of [SLIB]'s default) put -r macropackage before -m on the command line.

Command Option: -u
specifies that subsequent loads, evaluations, and user interactions will be without [R4RS] macro capability. [R4RS] macro capability can be restored by a subsequent -m on the command line or from Scheme code.

Command Option: -i
specifies that scm should run interactively. That means that scm will not terminate until the (quit) or (exit) command is given, even if there are errors. It also sets the prolixity level to 2 if it is less than 2. This will print prompts, evaluation times, and notice of loading files. The prolixity level can be set by subsequent options. If scm is started from a tty, it will assume that it should be interactive unless given a subsequent -b option.

Command Option: -b
specifies that scm should run non-interactively. That means that scm will terminate after processing the command line or if there are errors.

Command Option: -s
specifies, by analogy with sh, that further options are to be treated as program aguments.

Command Option: -
Command Option: --
specifies that there are no more options on the command line.

Command Option: -d filename
loads SLIB database-utilities and opens filename as a database.

Command Option: -o filename
saves the current SCM session as the executable program `filename'. This option works only in SCM builds supporting dump (see section Dump).

If options appear on the command line after `-o filename', then the saved session will continue with processing those options when it is invoked. Otherwise the (new) command line is processed as usual when the saved image is invoked.

Command Option: --help
prints usage information and URL; then exit.

Command Option: --version
prints version information and exit.

Environment Variables

Environment Variable: SCM_INIT_PATH
is the pathname where scm will look for its initialization code. The default is the file `Init.scm' in the source directory.

Environment Variable: SCHEME_LIBRARY_PATH
is the [SLIB] Scheme library directory.

Environment Variable: HOME
is the directory where `Init.scm' will look for the user initialization file `ScmInit.scm'.

Scheme Variables

Variable: *argv*
contains the list of arguments to the program. *argv* can change during argument processing. This list is suitable for use as an argument to [SLIB] getopt.

Variable: *R4RS-macro*
controls whether loading and interaction support [R4RS] macros. Define this in `ScmInit.scm' or files specified on the command line. This can be overridden by subsequent -m and -u options.

Variable: *interactive*
controls interactivity as explained for the -i and -b options. Define this in `ScmInit.scm' or files specified on the command line. This can be overridden by subsequent -i and -b options.

Examples

% scm foo.scm
Loads and executes the contents of `foo.scm' and then enters interactive session.
% scm -f foo.scm arg1 arg2 arg3
Parameters arg1, arg2, and arg3 are stored in the global list *argv*; Loads and executes the contents of `foo.scm' and exits.
% scm -s foo.scm arg1 arg2
Sets *argv* to ("foo.scm" "arg1" "arg2") and enters interactive session.
% scm -e `(write (list-ref *argv* *optind*))' bar
Prints `"bar"'.
% scm -rpretty-print -r format -i
Loads pretty-print and format and enters interactive session.
% scm -r5
Loads dynamic-wind, values, and [R4RS] macros and enters interactive (with macros) session.
% scm -r5 -r4
Like above but rev4-optional-procedures are also loaded.

SCM Session

Editing Scheme Code

Gnu Emacs:
Editing of Scheme code is supported by emacs. Buffers holding files ending in .scm are automatically put into scheme-mode. If your Emacs can run a process in a buffer you can use the Emacs command `M-x run-scheme' with SCM. However, the run-scheme (`xscheme.el') which comes included with Gnu Emacs 18 will work only with MIT Cscheme. If you are using Emacs 18, get the emacs packages: ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/cmuscheme.el ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/comint.el These files are already standard in Emacs 19. If your Emacs can not run a process in a buffer, see "under other systems" below.
Epsilon (MS-DOS):
There is lisp (and scheme) mode available by use of the package `LISP.E'. It offers several different indentation formats. With this package, buffers holding files ending in `.L', `.LSP', `.S', and `.SCM' (my modification) are automatically put into lisp-mode. It is possible to run a process in a buffer under Epsilon. With Epsilon 5.0 the command line options `-e512 -m0' are neccessary to manage RAM properly. It has been reported that when compiling SCM with Turbo C, you need to `#define NOSETBUF' for proper operation in a process buffer with Epsilon 5.0. One can also call out to an editor from SCM if RAM is at a premium; See "under other systems" below.
other systems:
Define the environment variable `EDITOR' to be the name of the editing program you use. The SCM procedure (ed arg1 ...) will invoke your editor and return to SCM when you exit the editor. The following definition is convenient: 
(define (e) (ed "work.scm") (load "work.scm"))
Typing `(e)' will invoke the editor with the file of interest. After editing, the modified file will be loaded.

Debugging Scheme Code

The cautious and stack-limit options of build (see section Build Options) support debugging in Scheme.

CAUTIOUS
If SCM is built with the `CAUTIOUS' flag, then when an error occurs, a stack trace of certain pending calls are printed as part of the default error response. A (memoized) expression and newline are printed for each partially evaluated combination whose procedure is not builtin. See section Memoized Expressions for how to read memoized expressions. Also as the result of the `CAUTIOUS' flag, both error and user-interrupt (invoked by C-c) to print stack traces and conclude by calling breakpoint (see section `Breakpoints' in SLIB) instead of aborting to top level. Under either condition, program execution can be resumed by (continue). In this configuration one can interrupt a running Scheme program with C-c, inspect or modify top-level values, trace or untrace procedures, and continue execution with (continue).
STACK_LIMIT
If SCM is built with the `STACK_LIMIT' flag, the interpreter will check stack size periodically. If the size of stack exceeds a certain amount (default is HEAP_SEG_SIZE/2), SCM generates a segment violation interrupt. The usefulness of `STACK_LIMIT' depends on the user. I don't use it; but the user I added this feature for got primarily this type of error.

There are several SLIB macros which so useful that SCM automatically loads the appropriate module from SLIB if they are invoked.

Macro: trace proc1 ...
Traces the top-level named procedures given as arguments.
Macro: trace
With no arguments, makes sure that all the currently traced identifiers are traced (even if those identifiers have been redefined) and returns a list of the traced identifiers.

Macro: untrace proc1 ...
Turns tracing off for its arguments.
Macro: untrace
With no arguments, untraces all currently traced identifiers and returns a list of these formerly traced identifiers.

The routine I use most for debugging is:

Procedure: print arg1 ...
Print writes all its arguments, separated by spaces. Print outputs a newline at the end and returns the value of the last argument.

One can just insert `(print '<proc-name>' and `)' around an expression in order to see its value as a program operates.

Sometimes more elaborate measures are needed to print values in a useful manner. When the values to be printed may have very large (or infinite) external representations, section `Quick Print' in SLIB, can be used.

When trace is not sufficient to find program flow problems, SLIB-PSD, the Portable Scheme Debugger offers source code debugging from GNU Emacs. PSD runs slowly, so start by instrumenting only a few functions at a time. 

ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz
prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz
ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz
ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz

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