
This is the source code distribution for PLT Scheme (MzScheme and/or
MrEd, possibly with DrScheme). For license information, please see the
file plt/notes/COPYING.LIB.

Compiled binaries, documentation, and up-to-date information are
available at
  http://www.cs.rice.edu/CS/PLT/packages/drscheme/
  http://www.cs.rice.edu/CS/PLT/packages/mzscheme/
  http://www.cs.rice.edu/CS/PLT/packages/mred/

The MzScheme source code should compile and execute on any Windows,
MacOS, Unix (Linux), or BeOS platform. The MrEd source code should
compile and execute on any Windows, MacOS, or Unix (Linux) platform,
but not on BeOS and not using Cygwin with Windows.

Per-platform instructions are below.

Please report bugs via one of the following:
  - Help Desk's "submit bug report" link  (preferred)
  - http://www.cs.rice.edu/CS/PLT/Bugs/
  - plt-bugs@cs.rice.edu                  (last resort)

-Matthew Flatt
 PLT
 mflatt@cs.utah.edu

========================================================================
 Compiling for Windows
========================================================================

Read the instructions in plt\src\worksp\README.

To compile MzScheme with Cygwin tools, follow the Unix instructions
below.

========================================================================
 Compiling for MacOS
========================================================================

Unpack the Stuffit archive plt:src:cw.sit.hqz to plt:src:cw, and then
see `README' in that folder.

========================================================================
 Compiling for Unix (including Linux), Cygwin, or BeOS
========================================================================

 1. Run the script `configure', which is in the same directory as
    this README.

    The `configure' script generates the makefiles for building
    MzScheme and/or MrEd. The current directory at the time
    `configure' is run will be used for building the executables. This
    build directory does not have to be in the plt/ tree, but if you
    are building for a single configuration, you can run `configure'
    from its own directory.

    The `configure' script accepts a number of flags that adjust the
    build process. Run `configure --help' for more information.  For
    details on the OSKit kernel configuration for MzScheme, see
    plt/src/mzscheme/README.

    To port MzScheme to a new platform, edit mzscheme/sconfig.h to
    provide a platform-specific compilation information. As
    dsitributed, mzscheme/sconfig.h contains configurations for the
    following platforms:

              Windows
              MacOS (PPC and 68k)
              Linux (x86, PPC, and 68k)
              Cygwin b20
              BeOS
              Solaris (x86 and Sparc)    [see notes below]
              SunOS4 (Sparc)
              IBM AIX (RS6000)
              SGI IRIX (Mips)
              DEC Ultrix
              HP/UX
              FreeBSD
              OpenBSD
              OSF1 (Alpha)
              SCO Unix (x86)

    If your platfrom is not supported by the Boehm garbage collector
    (distributed with PLT source), provide the `--enable-sgc' flag to
    `configure'. (For BeOS, this flag is inferred automatically.)

    [Solaris Note: To ensure that dynamic extensions work right, make
    sure your compiler uses the native Solaris `ld' rather than GNU's
    `ld'.]

    [Solaris 2.7 Note: gcc 2.8.1 does not work correctly under Solaris
    2.7, producing a MzScheme binary that crashes. Thanks to
    Stever Hall for figuring this out in a long--and presumably
    torturous--process.  Compiling under Solaris 2.6 or compiling
    without -O under Solaris 2.7 apparently solves the problem.]

 2. Run `make'.

    With Cygwin, use `make --unix'.

    Binaries and libraries are placed in subdirectories of the build
    directory. For example, the `mzscheme' binary appears in the
    `mzscheme' directory.

 3. Run `make install'.

    This step copies binaries and libraries into their normal places
    in the plt tree relative to the source directory. For example, the
    `mzscheme' binary is copied for Unix into the directory
    plt/.bin/<platform>/mzscheme, where <platform> depends on your
    platform.

 4. Unix (Linux) and BeOS: Run ./install in the plt directory (one
    directory up from here). Afterwards, plt/bin/setup-plt and
    plt/bin/mzc should work. If you move the plt tree, simply re-run
    plt/install.

    Cygwin: Create the other executables (besides mred.exe and
    mzscheme.exe) by running
       mzscheme.exe -mvqL- setup.ss setup
    in the plt directory (one directory up from here). The above makes
    the .zo files, too, but add -n to the end of the command to skip
    the .zo-compiling step. Afterwards, `plt/Setup PLT.exe' and
    `plt/mzc.exe' work.

    After installation, the plt/src directory is no longer needed, and
    can be safely deleted.

========================================================================
 Compiling the OSKit-based kernel
========================================================================

To build the OSKit-based MzScheme kernel, run the configure script
with the --enable-oskit or --enable-smalloskit flag. The result of
compiling will be `mzscheme.multiboot' in the `mzscheme' build
directory. It is a kernel in multiboot format.

Before building the MzScheme kernel, you must first install OSKit,
which is available from the Flux Research Group at Utah:
     http://www.cs.utah.edu/projects/flux/oskit/

By default, configure assumes that OSKit is installed in
/usr/local. To specify a different location for OSKit, define the
OSKHOME environment variable.

For simplicity, the MzScheme kernel uses SGC rather than Boehm's
conservative garbage collector.

The --enable-smalloskit configuration produces a kernel without
networking or filesystem support. The kernel created by
--enable--oskit accepts filesystem and networking configuration
information on its multiboot command line via the --fs and --net
flags:

  --fs <drive> <partition> : mounts the given partition as the root
   directory. For example, to mount the seventh parition on main disk,
   supply: --fs hda f. Many filesystem formats are supported,
   including EXT2, MSDOS, and VFAT (all of the ones supported by
   Linux; see OSKit for details). The standard kernel can only mount
   one filesystem per run; hack main.c to get more.

  --net <address> <netmask> <gateway> : initializes ethernet support
   for MzScheme's TCP primitives. Example: --net 128.42.6.101
   255.255.255.0 128.42.6.254. Many types of ethernet cards are
   supported (the ones supported by FreeBSD; see OSKit for details).

Each of --fs and --net should be used once at most. The --fs and --net
flags must appear before any other command-line arguments, which are
handled by MzScheme in the usual way.

To access a filesystem or the network from non-multiboot kernels
(e.g., a LILO-compatible kernel), you must hardwire filesystem and
networking parameters in oskglue.inc when compiling the kernel; see
oskglue.inc for details (grep for `hardwire').

========================================================================
 Additional Compilation Notes
========================================================================

Garbage Collector
-----------------

The conservative garbage collector distributed with MzScheme (in the
gc directory) has been modified slightly from Boehm's standard
distribution. Mostly, the change modify the way that object
finalization is handled.

Precise GC
----------

MzScheme and MrEd can be compiled to an experimental form that uses
precise garbage collection (as opposed to "conservation garbage
collection") on some Unix platforms, including Linux, FreeBSD, and
Solaris. The precisely-collected forms are called MzScheme2k and
MrEd2k, repsectively.

To build MzScheme2k and MrEd2k, run `make 2k'. Building MzScheme2k and
MrEd2k first builds the normal MzScheme and MrEd executables, then
uses them to build the 2k versions.

Configuration Options
---------------------

By default, MzScheme is compiled:

 * without image dumps (since the application will probably be linked
   dynamically);

 * without using any OS-specific threads; and

 * without support for single-precision floating point numbers.

These options can be modified by setting flags in mzscheme/sconfig.h.
MrEd works only *without* OS-specific threads.

Modifying MzScheme
------------------

If you modify MzScheme and change any primitive syntax or the
collection of built-in identifers, be sure to turn off
USE_COMPILED_MACROS in schminc.h. Otherwise, MzScheme won't start.
See schminc.h for details.

Guile Compatibility Library
---------------------------

In the mzscheme/ directory, `make libguile' produces a libguile.a
library that implements the high-level guile interface. See
mzscheme/libguile/README.
