Emacs: This file contains English -*- Text -*-.
(last updated on 11/4/87)

	For information on installation, read INSTALL.

NOTE: In the following, a hierarchical file system (with multiple
subdirectories) is assumed.  Your copy may have all of the
subdirectories flattened into a "giant" directory.


	Some information on the implementation of Scheme and where
things are.

Scheme consists of two parts, the "microcode" and the runtime system:

- The microcode is the part implemented in C, and consists of the
virtual machine (interpreter), the primitives, and some support
routines.

- The runtime system is written in Scheme and contains the
read-eval-print loop and some debugging and programming tools.  There
are many possible runtime systems and two are generated when Scheme is
installed.  The various runtime systems live in the runtime
subdirectory of the Scheme hierarchy.  The runtime systems generated
are:

o The normal development system which is the one we (the development
group at MIT) use.  It lives in the file "scheme.bin".  It is an
extension of the scheme language described in "The Revised^3 Report on
Scheme" (R^3RS).  This version is the default.

o The student system which is used for MIT course 6.001 (Structure and
Interpretation of Computer Programs, text by Abelson, Sussman, and
Sussman).  This is a "smaller" dialect than the one defined by R^3RS,
with a lot of the features from the development system disabled.  It
lives in the file "sicp.bin".

To change the default to the student system, connect (change the
default directory, e.g. use cd under Unix) to the runtime
subdirectory, rename (e.g. mv) "scheme.bin" to "dev.bin" and
"sicp.bin" to "scheme.bin".


	Description of the Scheme directory hierarchy:

Assume in the following that /scheme is the Scheme root directory
(where this file is stored).

/scheme/microcode contains the C sources and object code for the
microcode.  It also contains some utility programs.  In particular, 
it contains Psbtobin, which is the program used to convert between
portable format Scheme binaries, and internal format Scheme binaries.

/scheme/runtime contains the scheme sources for the runtime system
(with file extension ".scm"), and the corresponding binaries, which can
be in one of two forms:

- Files with extension ".bin" are the binary ("fasloadable") versions
of the files with the ".scm" extension, and the complete runtime
systems.  The release tape contains no ".bin" files in the runtime
subdirectory, but these are created from the ".psb" files during the
installation process.

- Files with extension ".psb" are the portable version of the scheme
runtime binaries.  These are the same as the ".bin" files but in a
portable format independent of character set, machine word size, byte
order, and more easily transmitted over serial lines.  The programs
Psbtobin and Bintopsb can be used to translate between both formats,
although complete runtime system images cannot be translated to
portable format.

/scheme/sf contains the sources and binaries for sf, the scode
optimizer.  Read "/scheme/documentation/user.txt" for a short
description of its capabilities.

/scheme/etc contains some utilities for generating the runtime system,
and some GNU Emacs libraries which make editing scheme sources, and
manipulating inferior Scheme processes simpler.

/scheme/makefiles contains utilities for generating machine and
operating system dependent files for the supported configurations.

/scheme/documentation contains what little documentation there is.
The r3rs subdirectory contains the LaTEX sources for the report.  It
is a as close to a manual as we can provide at this moment.

	What to keep

If space is at a premium on your machine, you can get rid of most of
the scheme directory hierarchy once Scheme has successfully booted.

These are the files you need to run Scheme under Unix:

	microcode/scheme	(the executable image)
	runtime/scheme.bin	(normal runtime system)
	runtime/sicp.bin	(student runtime system)
	runtime/utabmd.bin	(microcode tables)

Under VMS, the corresponding files are

	[-.BIN]SCHEME.EXE	(the executable image)
	[-.RUNTIME]SCHEME.BIN	(normal runtime system)
	[-.RUNTIME]SICP.BIN	(student runtime system)
	[-.RUNTIME]UTABMD.BIN	(microcode tables)

If you use only one of the runtime system files, you can delete the
unused one (e.g. if you only use the normal runtime system, you can
delete "sicp.bin").

Everything else can be removed.  Note that unless you recompile the
scheme microcode with a different default, "utabmd.bin" and
"scheme.bin" must stay in the runtime subdirectory.


	Some Interesting variations

NOTE: If you write modifications that you feel other people might be
interested in, please send them to us so that we can include them in a
later release.

1) New primitives

a) Write C procedures which will work as Scheme primitives.  See the
file "documentation/prims.txt" for more information.

b) 

Under Unix:

- Change Makefile in the microcode subdirectory so that the Scheme
system will know about the new primitive files: change the following
"make" macros to be lists with all the relevant files (there are
comments showing typical usage):

	USER_PRIM_SOURCES
	USER_PRIM_OBJECTS
	D_USER_PRIM_OBJECTS
	F_USER_PRIM_OBJECTS

- Execute "make scheme" in the microcode directory.  If there are no
compilation errors, a new Scheme microcode will be linked.

Under VMS or other operating systems:

- Change the files "make.com" and "usrdef.txt" to compile and declare
the relevant files.  For example, if the new primitives are defined in
the files "xdebug.c" and "Xgraph.c", replace the line

"$ Findprim -o usrdef.c -l usrdef.txt"

by the lines

"$ Findprim -o usrdef.c -l usrdef.txt"
"$ cc xdebug.c"
"$ cc Xgraph.c"

and add the lines

xdebug.c
Xgraph.c

to the file "usrdef.txt".

- Execute the commands in "make.com" to regenerate a scheme microcode.
There is no need to remake the scheme runtime binaries.

c) Once the microcode has been generated (step b above), load up a
Scheme, where the primitives can be obtained by using
MAKE-PRIMITIVE-PROCEDURE:

(MAKE-PRIMITIVE-PROCEDURE <symbol>) will return a procedure object
corresponding to a primitive named <symbol>, if there is one.  It can
then be used like any other procedure.  For examples, see the file
"Xgraph.scm" in the runtime subdirectory.

2) Executable image

When scheme starts up it loads a band (a "linked" runtime system is
called a band for historical reasons).  This may be an unreasonably
slow process, so you may want to circumvent it by dumping a Scheme
which has the runtime system already loaded (as described below).

The mechanism implementing this only works under unix, and uses
"unexec.c", a file from GNU-EMACS.  It is heavily conditionalized for
various machines and versions of unix, but we have only tried it on a
few configurations (VAX/Ultrix, VAX/BSD 4.2, Sun/BSD 4.2, and
HP9000s300/HPUX).  If you have GNU-EMACS on your machine, and it dumps
an executable image, you should be able to make this work.  Look at
"microcode/dumpworld.c" and "microcode/unexec.c".  The optional
primitive mechanism described in 1 above is used to add this primitive
to the system.

To obtain a version of scheme which can make an executable dump of
itself, add "dumpworld.c" and "dumpworld.oo" to the USER_PRIM... lines
of the makefile as specified above.  Link a new Scheme microcode.
Once this is done, start scheme (with a normal system, instead of a
student system) and, at scheme, type (dump-world "xscheme") This will
make a file called xscheme which when executed will start a scheme
with a normal runtime system already loaded.  You may want to make
this the default scheme that users get when they type scheme.

NOTE: GNU Emacs's unexec needs to open the original scheme executable
file to copy the symbol table into the new image.  Unfortunately many
"unices" do not provide processes with the full pathname where their
binary was found, but instead provide the trailing component of the
pathname.  Scheme tries (by looking at the connected directory and the
PATH environment variable) to find the correct binary from which to
copy the symbol table, but it may not always succeed.

3) bchscheme

bchscheme is a version of Scheme that uses a disk file as a temporary
(rather than memory) to garbage collect.  Thus if you have memory
limitations, you may be interested in using this version, for it
reduces your memory requirements by about 40% at the expense of making
garbage collection somewhat slower.  The microcode is generated by
doing "make bchscheme" in the microcode subdirectory, rather than
"make scheme", and the runtime system is shared, so it can be used
interchangeably with scheme.  Currently there is a bug in the
bchscheme version of the purify procedure.  If during the purification
process, scheme runs out of space, it does not back out, instead it
crashes.  This will be fixed in an upcoming release.

4) Scheme compiler

The compiler exists only for hp9000s300 (Motorola MC68020) and
hp9000s800 (spectrum) computers.  It is currently hard to use and not
fully debugged.  Within a few months we will advertise a beta release,
and also provide a Vax and Sun back end.  The full release should be
around January 1988, and the appropriate documentation will be
included then.  This is a completely new compiler (different from the
release 3 Vax compiler), and the compiled code interface is completely
incompatible with the previous one.

5) Edwin editor

Edwin is an editor written in Scheme, very similar to GNU Emacs.  As
soon as the compiler stabilizes, Edwin (the full editor, not the limited
subset of it that runs on the TI and IBM PCs under TI PC Scheme) will
be ported to CScheme.  Probably the initial version will only work on
top of the X window system, but a terminal independent version should
be provided soon afterwards.  It will probably be released at the same
time as the compiler.

6) X window system graphics

There is limited X window support in this release.  The files are not
part of the scheme system generated by default, so if you would like
to use it, you will have to install it using the user defined
primitive mechanism described above.  It consists of the following
files:

	microcode/Xgraph.c
	microcode/Xgraph.h
	runtime/Xgraph.scm

There is an alternative X interface which is an import of the Xlib
calls from C into Scheme.  This consists of the following files:

	microcode/Xrep.c
	microcode/Xlib.c
	microcode/Xlib.h
	runtime/Xlib.scm
	runtime/Xterm.scm

This second interface is only partially implemented and partially
debugged.  The basic structure is all defined, so finishing the
implementation is straightforward.  If you do so, we'd appreciate
getting the code back so we can give it out to others.


For bug reports send computer mail to

BUG-CSCHEME@ZURICH.AI.MIT.EDU (on the Arpanet/Internet)

or US Snail to

Scheme Team
c/o Prof. Hal Abelson
545 Technology Sq. rm 410
Cambridge MA 02139

Other relevant mailing lists:

INFO-CSCHEME@ZURICH.AI.MIT.EDU
	Questions, notices of bug fixes, etc.
	Send mail to INFO-CSCHEME-REQUEST to be added.

SCHEME@LCS.MIT.EDU
	Applications, mostly for educational uses.
	Note that this mailing list is NOT MIT C Scheme specific.  It
	covers general language issues, relevant to all the
	implementations of the scheme language (MIT's C Scheme, Yale
	University's T, Indiana University's Scheme84, Semantic
	Microsystems' MacScheme, and Texas Instruments' PC Scheme
	among others).
	Send mail to SCHEME-REQUEST to be added.
