This directory contains the distribution of scm4e.  Scm conforms to
Revised^4 Report on the Algorithmic Language Scheme and the IEEE P1178
specification.  Scm runs under VMS, MS-DOS, OS2, MacOS, Amiga,
Atari-ST, NOS/VE, Unix and similar systems.

The author can be reached at jaffer@ai.mit.edu or
Aubrey Jaffer, 84 Pleasant St., Wakefield MA 01880.

			       MANIFEST

  `README' is this file.  It contains a MANIFEST, INSTALLATION
	INSTRUCTIONS, hints for EDITING SCHEME CODE, and a TROUBLE
	SHOOTING GUIDE.
  `COPYING' details the LACK OF WARRANTY for scm and the conditions
	for distributing scm.
  `scm.1' is the unix style man page in nroff format.
  `scm.doc' is the text man page generated from scm.1.
  `QUICKREF' is a Quick Reference card for IEEE and R4RS.
  `MANUAL' details feature support and enhancements to Scheme and
	contains a SCHEME BIBLIOGRAPHY.
  `ChangeLog' documents changes to the scm.
  `code.doc' describes the internal representations and algorithms.
	Also describes how to modify scm.

  `test.scm' is Scheme code which tests conformance with Scheme
	specifications.
  `example.scm' is Scheme code from Revised^4 Report on the
	Algorithmic Language Scheme which uses inexact numbers.
  `pi.scm' is Scheme code for computing digits of pi [type (pi 100 5)]
	which can be used to test the performance of scm against
	compiled C code [cc -o pi pi.c;time pi 100 5].
  `pi.c' is C code for computing digits of pi.

  `makefile.unix' is for building scm using the `make'program.
  `makefile.msc' is for building scm on IBM PC using Microsoft C.
  `makefile.qc' is for building scm on IBM PC using Microsoft QuickC.
  `makefile.bor' is for building scm on IBM PC using Borland C.
  `makefile.tur' is for building scm on IBM PC using Turbo C.
  `makefile.wcc' is for building scm on IBM PC using Watcom C.
  `makefile.djg' is for building scm on i386 IBM PC using DJGPP
	(Gnu CC ported to MSDOS).
  `makefile.emx' is for building scm on i386 IBM PC using EMX port
	of Gnu CC to OS/2. 
  `makefile.ast' is for building scm on a ATARI-ST using Gnu CC.
  `makefile.prj' is the project file for scm on a ATARI-ST using Turbo C.
  `makefile.aztec' is for building scm on AMIGA using
	Aztec C 5.2a.
  `makefile.acorn' is for building scm on an Acorn Achimedes using Huw
	Rogers free unix function call library.
  `dmakefile' is for building scm on AMIGA using DICE C.
  `compile.amiga' is for compiling scm on AMIGA.
  `link.amiga' is for linking scm on AMIGA.
  `VMSBUILD.COM' is the command file for building scm on a VMS
	machine.
  `VMSGCC.COM' is the command file for building scm using GCC on a
	VMS machine.
  `setjump.mar' provides setjmp and longjmp which do not use $unwind
	utility on VMS.
  `setjump.s' provides setjmp and longjmp for the Cray YMP.

  `Init.scm' is Scheme initialization code.
  `Transcen.scm' has Scheme code for inexact builtin procedures.
  `Link.scm' has Scheme code for compiling and dynamic linking.
  `scmfig.h' is a C include file containing system dependent definitions.
  `patchlvl.h is the patchlevel of this release.
  `setjump.h' is an include file dealing with continuations, stacks,
	and memory allocation.
  `scm.h' has the data type and external definitions of scm.

  `scm.c' has the top level and interrupt code.
  `time.c' has functions dealing with time.
  `repl.c' has error, read-eval-print loop, read, write and load code.
  `scl.c' has the code for utility functions which are not part of the
	IEEE Scheme spec or which are required for non-integer
	arithmetic.
  `eval.c' has the evaluator, apply, map, and foreach.
  `sys.c' has the code for call-with-current-continuation, opening and
	closing files, storage allocation and garbage collection.
  `subr.c' has all the rest of functions.
  `sc2.c' has code for procedures from R2RS and R3RS not in R4RS.
  `unif.c' has code for uniform vectors.
  `rgx.c' has code for string regular expression match.
  `crs.c' has code for interactive terminal control.
  `split.scm' sets up CURSCM (SCM with crs.c) so that input, output,
	and diagnostic output are each directed to separate windows.

		      INSTALLATION INSTRUCTIONS

If scm is already built (compiled) skip to secton INSTALL.

These #defines should be checked before compilation.  The first 2 can
be defined either in the Makefile or scmfig.h.  See scmfig.h for more
information.

Makefile    scmfig.h	note
------      ----	--------
-DIMPLINIT  IMPLINIT	directory and pathname where Init.scm will
			reside.
-DFLOATS    FLOATS	support for inexact numerical types.  On unix
			systems, FLOATS is automatically handled by
			makefile.unix.
-DENGNOT    ENGNOT	for engineering notation instead of scientific
			notation.

DEST			directory where `make install' will put the
			executable.  Unix only.
MANDEST			directory where `make install' will put the
			unix style manual page.  Unix only.

These #defines are automatically generated by various preprocessors.
Scm uses them to find include files and the proper names for system
functions.  If a define for your system type is missing on your
system, put -Dflag in the Makefile or #define flag in scmfig.h.

define		note
------		--------
AZTEC_C		Aztec_C 5.2a
_DCC		Dice C on AMIGA
__GNUC__	Gnu CC (and DJGPP)
__EMX__		Gnu C port (gcc/emx 0.8e) to OS/2 2.0
MWC		Mark Williams C on COHERENT
_QC		Microsoft QuickC
__STDC__	ANSI C compliant
__TURBOC__	Turbo C and Borland C
__WATCOMC__	Watcom C on MSDOS
__ZTC__		Zortech C

_AIX		AIX operating system
AMIGA		SAS/C 5.10 on AMIGA
atarist		ATARI-ST under Gnu CC
GNUDOS		DJGPP (obsolete in version 1.08)
__GO32__	DJGPP (future?)
hpux		HP-UX
linux		Linux
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.
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
vms		(and VMS) VAX-11 C under VMS.

hp9000s800	HP RISC processor
__i386__	DJGPP
i386		DJGPP
MULTIMAX	Encore computer
pyr		Pyramid 9810 processor
sparc		SPARC processor
sequent		Sequent computer
tahoe		CCI Tahoe processor

			      TO COMPILE

under UNIX and similar systems:
  From: bos@scrg.cs.tcd.ie
  New build and install scripts using GNU autoconf are available from
  scmconfig.tar.gz in the distribution directories.  See README.unix
  in scmconfig.tar.gz for further instructions.

  Alternatively:
      cp makefile.unix Makefile
  Edit Makefile to change CFLAGS, LIBS, and especially IMPLINIT.  If
  you are compiling under HP-UX, see comments in Makefile (fscm.o).
      make scm

  Once you have built scm (using either method) test it:
      make check

under VMS:
  Edit SCMFIG.H to set desired options and IMPLINIT.
  Execute VMSBUILD.COM or VMSGCC.COM (for Gnu C compiler).
      @VMSBUILD
  Test scm
      run scm
      (load "test.scm")
      (test-sc4)
      (test-cont)
      (test-inexact)

under MSDOS:
  Copy the appropriate makefile to MAKEFILE:
    MAKEFILE.MSC for Microsoft C,
    MAKEFILE.BOR for Borland C,
    MAKEFILE.TUR for Turbo C,
    MAKEFILE.QC for Quick C, or
    MAKEFILE.DJG for DJGPP (GCC port to i386 MSDOS).
      COPY MAKEFILE.xxx MAKEFILE
  Edit MAKEFILE to set desired options and IMPLINIT.
      MAKE
  Test scm
      SCM  (GO32 SCM for DJGPP)
      (load "test.scm")
      (test-sc4)
      (test-cont)
      (test-inexact)

under OS/2 2.0
  from: soravi@Athena.MIT.EDU
  use *EMX* port of GNU C/C++ to OS/2 2.0 (ftp from hobbes.nmsu.edu).
  Use makefile.unix.  Remove unix specific dir names.
  Remove IMPLINIT from Makefile as pre-processor will not take "" as
    part of "-DIMPLINIT" macro. (this is a bug with *EMX* ver 0.8d)
  Remove the DFLAGS macro.
  Specify all shell variables ie
    SCM_INIT_PATH
    SCHEME_LIBRARY_PATH
    HOME
  prior to running the executable.

under Think C 4.0 (or 4.1):
  Edit Scmfig.H to set desired options and IMPLINIT.
  from Yasuaki Honda // honda@csl.SONY.co.jp:
  Make a project and add source files repl.c, time.c, scm.c, subr.c,
  sys.c, eval.c, scl.c, sc2.c, and unif.c to it.
  Add libraries MacTraps, unix, ANSI to the project.
  The project should be segmented in the following way:
    ----------
    repl.c
    scm.c
    subr.c
    sys.c
    sc2.c
    unif.c
    time.c
    ----------
    MacTraps
    unix
    ----------
    ANSI
    ----------
    eval.c
    ----------
    scl.c
    ----------
  Choose 'Set Project Type' from 'Project' menu.
    Choose Application from radio buttons.
    Set Partition size to 600K. (The default 384K is not enough).

under Aztec C 5.2a on AMIGA:
  Edit makefile.aztec to set desired options and IMPLINIT.
    make

under SAS/C 5.10 on AMIGA:
  Edit compile.amiga to set desired options and IMPLINIT.
    compile.amiga

			       INSTALL

under UNIX:

  Edit Makefile to have appropriate destinations for scm and scm.1,
  DEST and MANDEST respectively.

      make install

  If IMPLINIT is not correctly defined in Makefile or scmfig.h then
  you will need to define the environment variable SCM_INIT_PATH to be
  the full pathname of Init.scm.  In a csh init file (.cshrc) this is
  done by:
      setenv SCM_INIT_PATH /usr/src/scm/Init.scm
  In a .profile file this should be:
      SCM_INIT_PATH=/usr/src/scm/Init.scm; export SCM_INIT_PATH

  Define the environment variable SCHEME_LIBRARY_PATH to be the full
  pathname of the Scheme Library directory if you have one.  In a csh
  init file (.cshrc) this is done by
      setenv SCHEME_LIBRARY_PATH /usr/lib/scheme/
  In a .profile file this should be:
      SCHEME_LIBRARY_PATH=/usr/lib/scheme/; export SCHEME_LIBRARY_PATH

under VMS:

  Put SCM.EXE, INIT.SCM, and COPYING someplace.  INIT.SCM and COPYING
  need to be in the same directory.  Either put SCM.EXE in a
  SYS$SYSTEM directory or, in your LOGIN.COM file, define the symbol
  SCHEME to be "$" appended to the full pathname of SCM.EXE.  For
  example:
      SCHEME == "$DKB100:[AGJ.SCM]SCM.EXE"

  In your LOGIN.COM file define the environment SCM_INIT_PATH to be
  the full pathname of INIT.SCM.  For example:
      DEFINE SCM_INIT_PATH DKB100:[AGJ.SCM]INIT.SCM
  Define SCHEME_LIBRARY_PATH to be the pathname of the Scheme Library
  if you have one.  For example:
      DEFINE SCHEME_LIBRARY_PATH DKB100:[AGJ.SLIB]

under MSDOS:

  If you are using DJGPP do:
      STRIP SCM.32
      COPY /B C:\DJGPP\BIN\STUB.EXE+SCM.32 SCM.EXE

  Put SCM.EXE, INIT.SCM, and COPYING someplace.  INIT.SCM and COPYING
  need to be in the same directory.  SCM.EXE needs to be in your
  search path.

  In AUTOEXEC.BAT define the environment variable SCM_INIT_PATH to be
  the full pathname of INIT.SCM.  For example:
      SET SCM_INIT_PATH=G:\AGJ\SCM\INIT.SCM

  In AUTOEXEC.BAT define the environment variable SCHEME_LIBRARY_PATH
  to be the full pathname of the Scheme Library directory if you have
  one.  For example:
      SET SCHEME_LIBRARY_PATH=G:\AGJ\SLIB\

			 EDITING SCHEME CODE

under Gnu Emacs:
  Editing of Scheme code is supported by emacs.  Buffers holding files
  ending in .scm are automatically put into scheme-mode.  However, the
  run-scheme (`xscheme.el') which comes included with Gnu Emacs will
  work only with MIT Cscheme.

  If your Emacs can run a process in a buffer you can use the
  run-scheme command with SCM when you get the emacs packages
  `cmuscheme.el' and `comint.el'.  Otherwise, see "under other
  systems" below.

under Epsilon (MSDOS):
  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.  One can also call out to the editor from SCM
  if RAM is at a premium; See "under other systems" below.

under other systems:
  Define the environment variable "EDITOR" to be the name of the
  editor you use.  The SCM procedure (ed arg1 ...) will then invoke
  that editor and return to SCM when you exit the editor.  I find the
  following definition very convenient:

  (define (e) (ed "work.scm") (load "work.scm"))

  Invoking (e) will then put me into the editor with the file I am
  working on and load this file after I have changed it.

			   TROUBLE SHOOTING

		Compiling:

FILE	ERROR or WARNING			HOW TO FIX

*.c	include file not found			Correct status of
						STDC_HEADERS

						fix #include statement
						or add #define for
						system type to scmfig.h

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.
						
sys.c	statement not reached			ignore
	constant in conditional expression	ignore

sys.c: `???' undeclared, outside of functions	#undef STDC_HEADERS
						in scmfig.h

scl.c	syntax error				define system type in
						scmfig.h and scl.c (softtype)

		Linking:

ERROR or WARNING			HOW TO FIX

_sin etc. missing.			uncomment LIBS in makefile

		Running:

PROBLEM					HOW TO FIX

Opening message and then machine	Change memory model option
crashes.				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: Could not allocate ...		Check sizet definition.

					Get more memory.

					Don't try to run as subproccess

... in scmfig.h and recompile scm	Do it and recompile files.

ERROR: Init.scm not found		Assign correct IMPLINIT in
					makefile or scmfig.h or
					define environment variable
					SCM_INIT_PATH to be the full
					pathname of Init.scm (see
					INSTALLATION instructions).

WARNING: require.scm not found		define environment variable
					SCHEME_LIBRARY_PATH to be the
					full pathname of the scheme
					library or change
					library-vicinity in Init.scm
					to point to library or remove.

					Make sure library-vicinity has
					a trailing file separator
					(like / or \).

		Testing: (load "test.scm") or (load "pi.scm") (pi 100 5)

Runs some and then machine crashes.	See above under machine
					crashes.

Runs some and then ERROR: ...		Remove optimization option
(after a GC has happened)		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	Check file mode (define OPEN_...
output files.				in Init.scm

Spaces or control characters appear	Check character defines in
in symbol names				scmfig.h

Negative numbers turn positive.		Check SRS in scmfig.h

VMS: Couldn't unwind stack		#define CHEAP_CONTIUATIONS
VAX: botched longjmp			in scmfig.h
