How to Use the RScheme Library

What is the RScheme Library?

RScheme is divided into three main sections:

the base system,
the packages, and
the library.

The first two come as part of the generic source distribution. The last is a separate source distribution, although it may be included in some binary distributions.

The base system is designed to the core RScheme language, and highly portable. It should work on any system that supports ANSI C. It is also enough of an environment to load and compile RScheme itself. (In fact, the generic source distribution includes a version of the base system that has been compiled to C code. The build proceeds by compiling the base system into a native executable, and using that RScheme executable to recompile the base system along as well as any packages.)

The packages are not part of the core system; RScheme is a fine language without them, and they are sometimes somewhat more dependent on the underlying operating system. For example, all the POSIX interface modules are located in packages, as well as the really hairy stuff like the persistent object store and the fast image loader.

The library is stuff that isn't stable, complete, or important enough to be included in the generic distribution. There's a whole lotta stuff in it.

What is in the Library?

See the RScheme Library Table of Contents for a complete listing. The dependencies between the modules in the library are drawn here, except for rs.util.msgs and rs.util.properties which almost everything depends on.

Installing the Library

First, obtain the library distribution (e.g., from the 0.7.3.3-b25 build)

Unpack it into a convenient location. RScheme by default will look for modules it doesn't already know about in ~/lib/rs/modules. So here's a good way to install it:

$ mkdir -p ~/lib/rs
$ cd ~/lib/rs
$ tar xvzf /tmp/rs-0.7.3.3-b25-lib.tar.gz
$ ln -s rs-0.7.3.3-b25-lib modules

Setting up a soft link from ~/lib/rs/modules to the actual library tree is a convenient way to switch out which version of the library you're point to.

Some of the modules will be immediately usable once the library has been installed like this. The Library Table of Contents indicates which modules require glue code. Those that do not should be usable right away.

Compiling the Library

For best results, the library can be loaded into a fast-loading RScheme image. The Makefile that is included loads a large portion of the library (though not all) and produces a fast-loading image (.fas). In fact, the fshell executable looks first for an image called [resource]/fshell.fas, which the make install target of the library produces (only if that image is not found does fshell load [resource]/fshell.orig.fas.)

Continuing with the example above...

$ cd ~/lib/rs/rs-0.7.3.3-b25-lib
$ ./configure --with-rs=/usr/local/lib/rs/0.7.3.3-b25u/bin/fshell
$ make
$ make install

Performing this step incorporates in the dynamic C code generator which is located in the library module rs.backend.c. The dynamic C code generator allows define-glue to be used interactively and in new loaded modules, which is important for many of the other library components such as rs.sys.compression, which defines interfaces to the native zlib library.

By the way, if you wind up trying to load something that needs define-glue but the dynamic C code generator isn't available, this is the error you get:

error: special-form description `*not-available*' unknown