Scheme 9 from Empty Space

A Portable Scheme Interpreter with a Unix Interface

By Nils M Holm, 2007-2013

Introduction

S9fES is a mature, portable, and comprehensible public-domain interpreter for R4RS Scheme offering

decimal-based real number arithmetics;
support for low-level Unix programming;
cursor addressing with Curses;
basic networking procedures;
loads of useful library functions;
an experimental Scheme-centric full-screen editor.

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 (although the Plan 9 and Horror versions probably exclude most of the above goodies).

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

There is a book describing the implementation in detail. It is available in print and PDF format. See http://t3x.org/s9book/

S9fES supports the following SRFI's:

SRFI-0: feature-based conditional expansion (subset)
SRFI-2: and-let* (subset)
SRFI-22: running Scheme scripts on Unix
SRFI-23: error reporting mechanism
SRFI-30: nested multi-line comments
vector-copy and vector-append from SRFI-43

Note

If you are planning to use image files (which the S9 default setup does!), you will have to disable both address space layout randomization (ASLR) and position-independent code (PIE) for the S9 executable. This is because the image file contains pointers to functions in the interpreter executable, and either of the above techniques will invalidate these pointers, resulting in fatal "wrong interpreter" errors when the S9 system starts up.

Quick Start

You can run the interpreter in its build directory without installing it. Just type 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. (However, doing so will not include the RealNum/Unix/Curses/Networking extensions.)

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.

,h explains the online help system.

,a returns a list of all help topics (long!).

If the above commands do not work, try ,l contrib/help.scm first.

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). Running make tests will run even more tests.

On 64-bit systems, you may want to add the -DBITS_PER_WORD_64 definition 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. (Be 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 -o s9 -DDEFAULT_LIBRARY_PATH=""your-path"" s9.c

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

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

Security-sensitive people may consider removing the dot.
Copy the s9 binary to a location where it can be executed (e.g. /usr/local/bin).
Copy the file s9.scm to a publicly readable directory (default: /usr/local/share/s9fes). This directory will be referred to as LIBDIR in the following instructions. Note that this directory must be contained in DEFAULT_LIBRARY_PATH, as defined above.
Compile a heap image and copy it to LIBDIR:

s9 -d s9.image

The image file must have the same base name as the interpreter or it will not be loaded. 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.
Copy the content of the contrib directory to LIBDIR. 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 programs. 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 present in the former.

If you set up an rc-file in your home directory ($HOME/.s9fes/rc), this file will be loaded before entering the REPL. It will never be loaded when running programs non-interactively (with the -f option).

To create an image file containing additional functionality, add the desired options to the config.scm file and run

s9 -n -l config.scm -d s9.image

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 or the ,l (comma ell) meta-command:

> ,l draw-tree
; 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.

Running s9help topic on the shell prompt will print the S9fES online help page about the given topic.

Extended Interpreter

If compiled in, there are some extension procedures providing access to some Unix system calls, some networking procedures, and a Curses interface. To compile these extensions, uncomment the three EXTRA_ lines in the Makefile. (In fact, the Unix extensions are compiled in by default.)

Scheme Editor

The Scheme 9 Editor is started with the s9e command. The help page is loaded by pressing Ctrl + l and then h. See the Usage section at the end of the help file for instructions.

The most interesting feature of S9E is probably its interaction buffer. Type Ctrl + z s to open an interaction buffer, type any Scheme expression, move to its closing parenthesis and press Ctrl + j.

To compile an S9E image, run make s9e or make all. To install S9E, run make install-all. To try the editor without installing, create an image (make s9e) and then run

./s9 -i s9e-core prog/s9e1.scm

Note that S9E is experimental at this point. Bug reports and patches are welcome!

Acknowledgements

I would like to thank the following people and organisations for patches, bug reports, suggestions, hardware, access to hardware, etc:

Bakul Shah, Barak Pearlmutter, Blake McBride, Bsamograd (reddit), Dig1 (reddit), Dirk Lutzebaeck, Doug Currie, Mario Deilmann, Masaru KIMURA, Torsten Leibold, and the Super Dimension Fortress (sdf.org).

Contact

Nils M Holm < n m h @ t 3 x . o r g >

reflectionalist / S9fES