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).
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)
-PLT
scheme@plt-scheme.org
========================================================================
Compiling for Windows
========================================================================
To compile with Microsoft Visual C, read the instructions in
plt\src\worksp\README.
To compile with Cygwin tools, follow the Unix instructions below, and
be sure to configure with --enable-shared. The result is a Unix-style
build, not a Windows-style build (e.g., MzScheme's `system-type'
procedure returns 'unix, not 'windows, and MrEd uses X11).
========================================================================
Compiling for Mac OS X
========================================================================
First, install the Mac OS X Developer Tools from Apple. 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 Subversion-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.
========================================================================
Compiling for supported Unix variants (including Linux) or Cygwin
========================================================================
0. If you have an old PLT installation in the target directory,
remove it (unless you are using Subversion with an "in-place"
build as described below).
Also, make sure that you have libraries and header files for Xft
and Cairo (v1.23 and up) if you would like support for font
smoothing (Xft) and graphics smoothing (Cairo). These libraries
are not distributed with PLT Scheme. The configure process checks
automatically whether these libraries are available.
OpenGL support for MrEd sometimes requires special configuration
(though generally not under Linux). See the note at the end of
this section if OpenGL fails to work.
Finally, make sure that you are using GNU `make'. Specifically,
the content of the "foreign" subdirectory requires GNU `make'.
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, but most system administrators
would recommend that you use --enable-shared.
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. 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'. [As noted in step 0, this must be GNU `make'.]
With Cygwin, you may need to 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 Subversion-based sources with
--enabled-shared, beware that you may accumlate many old, unused
versions of the dynamic libraries in plt/lib.
4. ONLY Subversion 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 Subversion, 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.
OpenGL, Unix, and pthreads
--------------------------
On some Unix systems, programs that use the OpenGL library must also
link to pthreads. To use MrEd's OpenGL support on these systems, MrEd
must be configured with the --enable-pthread option. Unfortunately,
MzScheme's normal stack handling and use of signals (for its own
thread scheduling) do not interact well with pthreads. Thus, when
pthreads are enabled, MzScheme and MrEd cannot use interupt timers,
and the stack is limited to 1MB. These restrictions can degrade
performance and thread-responsiveness.
If `configure' detects that OpenGL requires -lpthread for linking,
and if --enable-pthread is not specified, `configure' prints a warning
and disables GL support. On some systems, including at least FreeBSD
with the MESA GL implementation (but not the NVIDIA implementation,
which does not need pthreads), `configure' cannot detect the need for
pthreads. On these platforms, GL support will be included in MrEd,
but it will not work properly unless --enable-pthread is specified.
========================================================================
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 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 that 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 support for single-precision
floating point numbers. This and other 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.
