
This is the source code distribution for PLT Scheme (MzScheme and/or
MrEd 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.drscheme.org/
  http://www.plt-scheme.org/software/mzscheme/
  http://www.plt-scheme.org/software/mred/

The MzScheme and MrEd source code should compile and execute on
Windows, Mac OS X, or any Unix/X platform (including Linux). It
may also work udner Mac OS 9.

Per-platform instructions are below.

Please report bugs via one of the following:
  - Help Desk's "submit bug report" link  (preferred)
  - http://bugs.plt-scheme.org/
  - bugs@plt-scheme.org                   (last resort)

-Matthew Flatt
 mflatt@plt-scheme.org

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

To compile with Microsoft Visual C, read the instructions in
plt\src\worksp\README.

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

To compile MzScheme with Borland C, read the instructions in
plt\src\borland\README. MrEd does not compile with Borland.

Regardless of the compiler used to build MzScheme, compatible
extensions can be built with any of the other compilers. For example,
to support Borland-built extensions after compiling MzScheme with MSVC
or Cygwin, cd to plt\src\mzscheme\dynsrc and run mkbordyn.bat. (The
mkbordyn.bat script requires bcc23.exe.)

========================================================================
 Compiling for Mac OS
========================================================================

Mac OS X:

 First, install the Mac OS X Developer Tools from Apple. After
 installing, run `fixPrecomps' to speed up compilations. (You can
 safely run `fixPrecomps' multiple times. You may need to run it as
 root or with `sudo'.)

 Then, follow the Unix instructions below, but note the following:

   * The MzScheme build creates a framework, PLT_MzScheme.framework,
     which is installed into ~/Library/Frameworks. This framework is
     used by the executable `mzscheme' that goes into plt/bin.

   * The MrEd build creates a framework, PLT_MrEd.framework, which is
     installed into ~/Library/Frameworks. This framework is used by the
     executable bundle MrEd.app that goes into the `plt' directory.
     Installation creates a script, plt/bin/mred, that runs the bundle.

   * If you build frequently from the CVS-based sources, beware that
     you may accumlate many old, unused versions of the framework in
     ~/Library/Frameworks.

   * The --enable-shared flag for `configure' is redundant (i.e.,
     builds create and use frameworks by default), and
     --disable-shared is not supported.

   * To build an X11-based MrEd, run `configure' with the
     --enable-xonx flag. Frameworks are not used for such builds. The
     --enable-xonx flag also affects the MzScheme build so that
     `system-type' reports 'unix.

Mac OS Classic (PowerPC only):

 Mac OS Classic is no longer supported, but it might work anyway.

 MrEd compiles for Mac OS Classic using MPW.  Stand-alone MzScheme is
 not suported for Classic (use MrEd instead), but MzSchemeLib is
 available for embedding into other executables.

 To compile MrEd with MPW, set the working directory to the ":mac:mpw"
 subdirectory of this one, then execute

    set -e makefile makefile
    buildprogram all

 [MPW hints: Use the "Set Directory..." menu item to set the working
  directory.  Evaluate a command by first typing it in the worksheet,
  then hit Cmd-Return with the caret on the line containing the
  command.

  Depending on how you obtained the source, you may need to force the
  source code files to have the type TEXT. The "textify.ss" program in
  ":mac:mpw" will do this for you, but it requires a Mac OS X MrEd.]

 `buildprogram all' generates three files:

   plt:MrEd - the main application
   plt:netglue - used by MrEd when TCP is started
   plt:collects:launcher:GoMr - used to create "launchers"

 After `buildprogram all' completes, double-click the MrEd application
 with the command key pressed. In the dialog that appears, type

      -mvqM- setup

 and hit Return. The setup program will then run; it compiles Scheme
 source to .zo format, and also creates launchers, such as "DrScheme".

 To build plt:MzSchemeLib, run `buildprogram mz'. The resulting
 plt:MzSchemeLib needs plt:netglue if and only if TCP support is
 needed.

========================================================================
 Compiling for supported Unix variants (including Linux)
               or Cygwin (MzScheme only)
========================================================================

 0. If you have an old PLT installation in the target directory,
    remove it (unless you are using CVS with an "in-place" build as
    described below).

 1. Run the script `configure' (which is in the same directory as this
    README), usually with a --prefix=TARGETDIR command-line argument
    and optionally with --enable-shared.

    For example, if you want to install into /usr/local/plt using
    dynamic libraries, then run

        [here]configure --prefix=/usr/local/plt --enable-shared

    where "[here]" is the directory path containing the `configure'
    script (possibly unnecessary, or possibly just "./", depending on
    your shell and PATH setting.)

    If the --prefix flag is omitted, the binaries are built for an
    in-place installation (i.e., the plt directory containing this
    README will be used directly). Unless --enable-shared is used, the
    plt directory can be moved later.

    The `configure' script generates the makefiles for building
    MzScheme and/or MrEd. The current directory at the time
    `configure' is run will be used as working space for building the
    executables (independent of --prefix). This build directory does
    not have to be in the plt/ tree, even for an "in-place" build, as
    long as you use GNU make when building MrEd. It's ok to run
    `configure' from its own directory (as in the example above), but
    it's often better to pick a separate build directory that is
    otherwise empty.

    The `configure' script accepts many other flags that adjust the
    build process. Run `configure --help' for more information. In
    addition, a specific compiler can be selected through environment
    variables. For example, to select the SGI compilers for Irix
    instead of gcc, run configure as

         env CC=cc CXX=CC [here]configure

    For cross compilation, set the compiler variables to a compiler
    for the target platform compiler, but also set CC_FOR_BUILD to a
    compiler for the host platform (for building binaries to execute
    during the build process).

    If you re-run `configure' after running `make', then products of
    the `make' may be incorrect due to changes in the compiler command
    line. To be safe, run `make clean' each time after running
    `configure'.

    When building for multiple platforms or configurations out of the
    same source directory, beware of cached `configure' information in
    `config.cache'. Avoid this problem entirely by using a separate
    build directory (but the same source) for each platform or
    configuration.

 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 place within the plt
    tree. For example, the `mzscheme' binary is copied for Unix into
    the directory plt/bin/mzscheme. For a --prefix, build, the rest of
    the plt tree is also copied to the target directory.

    In addition, this step runs the plt/install script, which updates
    script paths and builds .zo files.

    If the installation fails because the target directory cannot be
    created, or because the target directory is not the one you
    wanted, then you can run `configure' again with a new --prefix
    value, then try step 3 again. After changing the --prefix value,
    it is sometimes not necessary to repeat steps 1 or 2. (Try it and
    find out...)

    If you build frequently from the CVS-based sources with
    --enabled-shared, beware that you may accumlate many old, unused
    versions of the dynamic libraries in plt/lib.

 4a. ONLY Cygwin: Create the other executables (besides mred.exe and
     mzscheme.exe) by running
        mzscheme.exe -mvqM- 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.

 4b. ONLY CVS users with in-place builds: the `make install' step does
    not run plt/install for an in-place build, because old .zo files
    typically need to be deleted, first. After an initial in-place
    build, manually run ./install in the plt directory. For later
    builds, manually run plt/bin/setup-plt.

After an "in-place" install without CVS, the plt/src directory is no
longer needed, and it can be safely deleted. Build information is
recorded in plt/lib/buildinfo.

If you move the plt tree (for a build without dynamic libraries), run
the script ./install in the relocated plt directory.

========================================================================
 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').

========================================================================
 Porting to New Platforms
========================================================================

At a mininum, 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
              Mac OS (PPC Classic and OS X)
              Linux (x86, PPC, 68k, Alpha)
              Cygwin
              Solaris (x86, Sparc)
              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'.

========================================================================
 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 a
mmemory-moving garbage collector with precise tracking of pointers (as
opposed to "conservation garbage collection"). The experimental forms
are called MzScheme3m and MrEd3m, repsectively, where the "3m" stands
for "moving memory manager".

* Building for Unix and Mac OS X

 Run `make 3m'. Building MzScheme3m and MrEd3m first builds the normal
 MzScheme and MrEd executables, then uses them to build the 3m
 versions. Run `make install-3m' to install the 3m binaries.

 Note on OS X (actually, PowerPC and gcc): gcc version 2.x has an
 optimizer bug tha prevents 3m from building. Either use gcc 3.x or
 supply --disable-opt to `configure'.

* Windows

 Build and install the normal MzScheme and MrEd executables using
 Micsrosoft Visual C, and make sure that cl.exe is in your shell
 path. Then, in a shell, change directories to plt\src\worksp\gc2 and
 run

   ../../../mzscheme.exe -r make.ss

 The resulting MzScheme3m.exe and MrEd3m.exe will appear in the "plt"
 directory, along with DLLs libmzsch3mxxxxxxx.dll and
 libmred3mxxxxxxx.dll. (There is no correspingd libmzgc3mxxxxxxx.dll.
 Instead, it is merged with libmzsch3mxxxxxxx.dll.)

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

By default, MzScheme is compiled:

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

 * without support for single-precision floating point numbers.

These options can be modified by setting flags in mzscheme/sconfig.h.

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.
