custom/ReadMe
Copyright (c) 2004 Cadence Research Systems

This directory contains a configuration script, set of make files,
and C and Scheme files that are used to rebuild the Chez Scheme and
Petite Chez Scheme executable images and heap files with or without
local customizations.

-------------
Installation:

To install Chez Scheme or Petite Chez Scheme without local customizations,
simply type the following commands:

   ./configure
   make install

The configure script has several options you might wish to use to
customize the installation; type

   ./configure --help

for information.

If you wish to test the build before installing it, run make without
the install argument:

   ./configure
   make

To test the installation, you need to tell Scheme where to find its
boot or heap files by setting the SCHEMEHEAPDIRS variable.  Heap files
if created for this platform, are created in this directory, while boot
files are in the boot directory parallel to this directory.  The following
will set the heap and boot file search path to look in both directories:

sh/bash:
   SCHEMEHEAPDIRS=".:../boot/%m:" ; EXPORT SCHEMEHEAPDIRS

csh/tcsh:
   setenv SCHEMEHEAPDIRS ".:../boot/%m:"

Now you can start Petite Chez Scheme or Chez Scheme as follows:

   ./petite
   ./scheme

Either should print a greeting and a right-angle prompt.  Try typing a
Scheme expression at the prompt.  Hit ^D or enter (exit) when you
satisfied that the system build worked.

At this point, you can complete the install by typing

    make install

To test the installation, unset the SCHEMEHEAPDIRS variable:

sh/bash:
   unset SCHEMEHEAPDIRS

csh/tcsh:
   unsetenv SCHEMEHEAPDIRS

then run either /usr/bin/petite or /usr/bin/scheme:

   /usr/bin/petite
   /usr/bin/scheme

--------------------
Boot and Heap Files:

The boot files appearing in ../boot/%m for each distributed machine type
%m contain the compiled Scheme code that comprises the bulk of the Scheme
run-time system and (if present) the compiler.  The system loads these
files each time you run "petite" or "scheme".  More specifically, if you
run "petite" the system looks for petite.boot in the standard installation
directory, and if you run "scheme" the system looks for scheme.boot.
In the latter case, since scheme.boot depends on petite.boot, the system
will also look for petite.boot.

Heap files contain prebuilt heap images.  If you pass the --build-heaps
option to configure, the system will build heap files corresponding
to petite.boot and (if present) scheme.boot, and these heaps will be
used by the installation in leiu of the boot files.  Although larger,
heap files have two advantages over boot files: they load faster, and
most of heap is shared across Scheme processes on systems that support
memory-mapped files.  Unfortunately, heap files contain absolute addresses
and must always be loaded into the same address range, and the range
is never guaranteed to be available.  Changes in the operating system,
libraries, and even sometimes other loaded applications can affect the
availability of the required memory address range.  For this reason,
heap files are not built by default.

--------------
Customization:

To include custom C code in the executable image, edit the make file
"Makefile" generated by configure to add any C object files you would like
to include.  Edit custom_init in the C source file "custom.c" to add
foreign_symbol declarations for each of the procedures you wish to make
available to Scheme code, and edit "Makefile" to override use of the
standard "custom.o" object file.

Edit "Makefile" to list any Scheme object files you would like to have
built.  These will be loaded when saving a heap but will have to be loaded
explicitly otherwise.  You can also build your own custom boot files;
see the Chez Scheme Version 7 User's Guide for details.

You may wish to create a Scheme source file "custom.ss" containing
foreign procedure definitions for each of the C procedures you made
available in custom_init.  You may also wish to add "custom.so" to the
list of Scheme object to be created.

Make a backup copy of your modified Makefile so that it isn't destroyed
by a subsequent use of ./configure.

See the files crepl.c, sample.c, and sample.ss for sample C and Scheme
customization code.

More elaborate customizations may involve the creation of specialized
make files, patterned on the existing make files.

--------
Cleanup:

Type 'make clean' to remove build products or 'make distclean' to remove
build products and the make files generate by configure.
