The current scsh release is structured as follows.

Scsh is packaged up inside a standard S48 file tree.
The main directory contains a copy of Scheme 48 0.36.
However... we've made a few small mods to this copy of
0.36, so do not try to compile scsh with an off-the-shelf
0.39 or a newer release just yet.

In order for scsh's ports to be handled correctly by GC,
we have installed a call-out in the 0.36 vm's gc code that
is activated after every gc (it's post_gc_fdports()). This
means that you *must* use our 0.36 vm. There is machinery 
in the latest releases of S48 that makes this hackery unnecessary,
so we intend to drop this constraint in the future.

For this reason, the scsh vm is called "scshvm" not scheme48vm,
since it is not quite the same thing.

* S48
We intend to port scsh to the current release of S48. The
major difficulty here is that S48 now has threads and all
i/o is non-blocking. This greatly complicates the Unix services
scsh provides, since the details of the Unix system architecture do
not get along well with threads. We'll have to completely rewrite our i/o
subsystem, for example. For now, we use 0.36.

* DOC
The doc/ directory contains the scsh manual and a paper about scsh.
The paper is also available as MIT LCS and University of Hong Kong
tech reports; a revised version is due to appear in *Lisp and Symbolic
Computation*.

* CIG
Scsh uses a lot of foreign-function calls to interface to the Unix
system calls and other support routines. It uses a package called "cig"
(C Interface Generator) to do this. The code for cig lives in the
cig/ subdirectory. Cig is a system that processes a .scm file containing
(DEFINE-FOREIGN ...) forms, producing a C file of stub interfaces. The
C code manages the handoff to the C routine you were calling, converting
between Scheme and C representations, handling argument passing protocols,
nary function conventions, multiple-value return protocols, and so forth.
The C stub file is then compiled and linked in with the S48 vm (statically
or dynamically), and away you go.

There is a draft manual for cig in cig/doc, but be warned that it is
incomplete and out of date.

Although scsh uses cig-generated C stub files, we ship the source tree
with these files already generated, so you should not have to process
Scheme code with cig to make scsh unless you go and change the 
DEFINE-FOREIGN forms in the scsh source.

* SCSH
The source for scsh proper lives in the scsh/ directory. This directory
contains 
- the system-independent code

- the regexp/ subdirectory, containing Henry Spencer's regexp pattern
  matching library.

- A subdirectory for each type of system supported by scsh,
  e.g. sparc-sunos/, i386-linux/, hppa-hpux/, and so forth.
  These directories contain system-dependent code, such as
  definitions of the actual numeric values of the Unix errno codes
  (errno.h), operations that extend the stdio library, and so forth.

- A symlink to one of the system-specific subdirectories.
  This symlink is made when the top-level configure decides the system
  for which we are building scsh. For example, if we are building scsh for
  Sparcstations, then the scsh directory has the following symlink:
    machine 		->	sparc-sunos/
  The machine dependant files are:
    errno.scm
    fdflags.scm
    load-scsh.scm
    packages.scm
    signals.scm
    stdio_dep.c

The source code follows a convention that if a file foo.scm contains
some DEFINE-FOREIGN forms, then the stub C file produced by cig is
called foo.c, and any related support C code written by a human goes
in foo1.c.