This directory contains the distribution of scm3c.  Scm conforms to
Revised^4 Report on the Algorithmic Language Scheme and the IEEE P1178
specification.  Scm runs under VMS, MS-DOS, 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.
  `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 the file for building scm using the `make'
	program.
  `makefile.msc' is the file for building scm on an IBM PC using
	Microsoft C.
  `makefile.qc' is the file for building scm on an IBM PC using
	Microsoft QuickC.
  `makefile.bor' is the file for building scm on an IBM PC using
	Borland C.
  `makefile.tur' is the file for building scm on an IBM PC using
	Turbo C.
  `makefile.djg' is the file for building scm on an i386 IBM PC using
	DJGPP (Gnu CC ported to MSDOS).
  `makefile.ast' is the file for building scm on a ATARI-ST using Gnu CC.
  `makefile.aztec' is the file for building scm on an AMIGA using
	Aztec C 5.2a.
  `compile.amiga' is the file for compiling scm on an AMIGA.
  `link.amiga' is the file for linking scm on an 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.h' and 'setjump.mar' provide setjmp and longjmp which do
	not use $unwind utility on VMS.

  `Init.scm' is Scheme initialization code.
  `config.h' is a C include file containing system dependent definitions.
  `patchlvl.h is the patchlevel of this release.
  `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.

		      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 config.h.  See config.h for more
information.

Makefile    config.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.

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 config.h.

define		note
------		--------
AZTEC_C		Aztec_C 5.2a
__GNUC__	Gnu CC (and DJGPP)
MWC		Mark Williams C on COHERENT
_QC		Microsoft QuickC
__STDC__	ANSI C compliant
__TURBOC__	Turbo C and Borland C
__ZTC__		Zortech C

AMIGA		SAS/C 5.10 on AMIGA
atarist		ATARI-ST under Gnu CC
GNUDOS		DJGPP
__GO32__	DJGPP (future?)
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
unix		most Unix and similar systems and DJGPP (!?)
__unix__	Gnu CC and DJGPP
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

			      TO COMPILE

under UNIX and similar systems:
      cp makefile.unix Makefile
  Edit Makefile to change CFLAGS, LIBS, and especially IMPLINIT.
      make
  If you want an exact number (integer) only version type
      make escm
  (`make both' makes both).
  Test scm
      scm
      (load "test.scm")
      (test-sc4)
      (test-cont)

under VMS:
  Edit CONFIG.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)

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)

under Think C 4.0 (or 4.1):
  Edit Config.h to set desired options and IMPLINIT.
  from Yasuaki Honda // honda@csl.SONY.co.jp:
  Make a project and add source files repl.c, scm.c, subr.c, sys.c,
  eval.c, and scl.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
    ----------
    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.

      make install

  If IMPLINIT is not correctly defined in Makefile or config.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:
      set SCM_INIT_PATH /usr/src/scm/Init.scm

  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
      set SCHEME_LIBRARY_PATH /usr/lib/scheme/

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.  However,
  memory available to the process is limited and episodes of file
  system damage when doing this have occured.  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 config.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 config.h

						edit <sys/types.h> to
						remove incompatability.
						
sys.c	statement not reached			ignore
	constant in conditional expression	ignore

scl.c	syntax error				define system type in
						config.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 config.h

					Reduce size of HEAP_SEG_SIZE
					in config.h

ERROR: Could not allocate ...		Check sizet definition.

					Get more memory.

					Don't try to run as subproccess

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

ERROR: Init.scm not found		Assign correct IMPLINIT in
					makefile or config.scm 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.

		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 config.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.

Newline or other characters don't	Check character defines in
print correctly.			config.h 

Newlines don't appear correctly in	Check file mode #define OPEN_...
output files.				in config.h

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

Negative numbers turn positive.		Check SRS in config.h

VMS: Couldn't unwind stack		#define CHEAP_CONTIUATIONS
					in config.h