

	Scheme 9 from Empty Space
	A Simple and Comprehensible Scheme Interpreter
	By Nils M Holm, 2007,2008,2009

	WWW: http://www.t3x.org/s9fes/

	S9fES is an interpreter for a broad subset of R4RS Scheme.

	It is written in ANSI C (C89) and Scheme and it runs in many
	popular environments, including *BSD, Linux, Plan 9, and the
	unmentionable horror.

	The S9fES code strives to be simple and comprehensible. It is
	particularly interesting to people who want to (a) try Scheme
	without having to jump through too many hoops (b) study the
	implementation of Scheme (in a language other than Scheme). 

	There are two experimental extensions to the interpreter. S9E
	adds procedures implementing common Unix system calls. S9SC,
	the "Scheme 9 Scientific Calculator", adds a function plotter
	and vector graphics device that is mapped to an X11 window.


	QUICK START

	You can run the interpreter in its build directory without
	installing it. Just run "cc -Dunix -o s9 s9.c" and then "./s9".

	The S9 code is only loosely coupled to its Makefile, so in most
	cases running "cc -Dunix -o s9 s9.c" or "8c -Dplan9 -o s9 s9.c"
	will compile the interpreter just fine.

	On most systems of the Unix family (plus CygWin and MINGW),
	you can compile and install S9fES by running "make install".

	Once installed, typing "s9" will start the interpreter.

	(help) explains the online help system.
	(apropos) returns a list of all help topics.


	COMPILING AND INSTALLING

	Unix

	To compile S9fES, run "make test" (this will also run the test
	suite to make sure that the interpreter works properly).

	On 64-bit systems, you may want to add the -DBITS_PER_WORD_64
	define to the Makefile. Not doing so will probably still work,
	but result in slightly worse bignum performance.

	You can install S9fES (including the goodies) on a Unix system
	by typing "make install" as root, but before doing so, please
	edit at least the PREFIX variable at the beginning of Makefile.
	(Make sure to re-compile S9fES (make clean; make) after changing
	 PREFIX, because it is used to set up some internal paths).

	Plan 9

	To compile S9fES on Plan 9 from Bell Labs, just type "mk", but
	note that the Plan 9 port is rather experimental at this stage.
	Above all, there is currently no installation procedure.

	Manual Installation

	To install S9fES manually,

	- Compile s9 with a proper default library path (the one
	  hardwired in "s9.h" is probably not what you want). E.g.:

	  cc -Dunix -o s9 -DDEFAULT_LIBRARY_PATH="\"your-path\"" s9.c

	  A reasonable value for "your-path" would be, for example:

	  ".:~/s9fes:/usr/local/share/s9fes:/usr/local/share/s9fes/contrib"

	- Copy the "s9" binary to a location where it can be executed
	  (e.g. /usr/local/bin).

	- Copy the file "s9.scm" to a publically readable directory
	  (default: /usr/local/share/s9fes). This directory will be
	  referred to as LIBDIR in the following instructions.

	- Compile a heap image and copy it to LIBDIR. Typing
	  "s9 -d s9.image" will compile an image. You must name the
	  image "s9.image" or S9 will not load it. An image loads
	  significantly faster than source code.

	Optionally:

	- Copy the content of the "lib" directory to LIBDIR. This
	  directory contains lots of useful Scheme functions.

	- Create a subdirectory named "contrib" in LIBDIR and copy the
	  content of the "contrib" directory to LIBDIR/contrib. These
	  files contain additional Scheme functions contributed by other
	  authors or imported from various sources.

	- Create a subdirectory named "help" in LIBDIR and copy the
	  content of the "help" directory to LIBDIR/help. These files
	  are part of the interactive help system.

	- Copy the nroff(1) source code of the manual page "s9.1" to
	  section 1 of your online manual (e.g. /usr/local/man/man1).
	  In case you are not running Unix, there is a pre-formatted
	  copy in the file "s9.1.txt".


	CONFIGURATION

	You may create the S9FES_LIBRARY_PATH environment variable and
	make it point to LIBDIR as well as other directories that
	contain Scheme functions. The variable may contain a single
	directory or a colon-separated list of directories that will be
	searched in sequence for image files, library files and help
	pages (in "help" subdirectories of the given paths).

	S9FES_LIBRARY_PATH overrides DEFAULT_LIBRARY_PATH, so all
	directories listed in the latter should also be presend in
	the former.

	If you set up an rc file in your home directory ($HOME/.s9fes/rc),
	this file will be loaded after the library image file but before
	running any programs. It is an ordinary Scheme source file.

	To create an image file containing additional functionality,
	use the -f command line option in combination with -d. For
	example, the following command will compile an image containing
	the online help system and the pretty-printer:

	s9 -n -f contrib/help.scm -f contrib/pretty-print.scm -d s9.image

	(Note that this is done by default; see the EXTRA_STUFF variable
	 in the Makefile.)


	GETTING STARTED

	Typing "s9" will drop you into the read-eval-print loop of the
	interpreter. You can run Scheme programs non-interactively by
	typing "s9 -f program.scm" at your shell prompt.

	If you installed the extension library functions in LIBDIR,
	they can be loaded by the LOAD-FROM-LIBRARY procedure:

	> (load-from-library "draw-tree.scm")
	; loading from /usr/local/share/s9fes/draw-tree.scm
	> (draw-tree '(a b c))
	[o|o]---[o|o]---[o|/]
	 |       |       |
	 a       b       c
	> _

	Feel free to explore them.


	EXTENDED INTERPRETER

	There is an experimental extension containing some Unix system
	procedures. See the S9E(1) man page for details. To (attempt to)
	compile this extension, run "make all-s9e". To install the
	extended interpreter, type "make install-s9e" (as root).


	SCHEME 9 SCIENTIFIC CALCULATOR

	The experimental S9SC interpreter maps a vector graphics device
	to an X11 window on a Unix system and implements a function
	plotter in the style of a "scientific calculator" on top of that
	device. To (attempt to) compile S9SC, run "make all-s9sc" and to
	install it, run "make install-s9sc". See the S9SC(1) man page
	for further explanations. To see S9SC in action, just start it
	and then type, for instance, "(plot* -7 7 sin)".


	CONTACT

	Bug reports, patches, suggestions, questions, etc are welcome.

	Nils M Holm < nmh at t3x.org >

