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 plt/lib. 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 plt/lib. 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. * The --enable-shared flag for `configure' must not be used, because builds create and use frameworks by default. Furthermore, --disable-shared is not supported. (Unless you use --enable-xonx...) * To build an X11-based MrEd, run `configure' with the --enable-xonx flag. Frameworks are not used for such builds, so --enable-shared is allowed. 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, the content of the "foreign" subdirectory may require GNU `make'. If the build fails with another variant of `make', please try using 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 parent of the directory containing this README will be used directly). Unless --enable-shared is used, the plt directory can be moved later; most system administrators would recommend that you use --enable-shared, but the PLT Scheme developers distribute binaries built without --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 source 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 the target machine's stack grows up, you'll have to supply --enable-stackup; if the target machine is big-endian, you may have to supply --enable-bigendian. 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'. To be even safer, run `configure' in a fresh build directory every time. 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 target installation. For example, the `mzscheme' binary is copied into the "bin" directory for an in-place build, or into the executable directory for a --prefix build. For a --prefix build, this step also creates a "config.ss" module in a "config" collection, so that various PLT tools and libraries can find the installation directories. At this stage, in case you are packaging an installation instead of installing directly, you can redirect the installation by setting the "DESTDIR" environment variable. For example, `make DESTDIR=/tmp/plt-build install' places the installation into "/tmp/plt-build" instead of the location originally specified with --prefix. The resulting installation will not work, however, until it is moved to the location originally specified with --prefix. Finally, the `make install' step compiles ".zo" bytecode files for installed Scheme source, and generates launcher programs like "DrScheme". Use `make plain-install' to install without compiling ".zo" files or creating launchers. 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 try repeating step 3 after runing `configure' again with a new --prefix value. That is, sometimes it is not necessary to repeat steps 1 or 2 (so try it and find out). On other platforms and configurations, it is necessary to start with a clean build directory when changing the --prefix value, because the path gets wired into shared objects. If you build frequently from the Subversion-based sources, beware that you may accumulate user- and version-specific information in your "add-ons" directory, which you can most easily find by evaluating (find-system-path 'addon-dir) in MzScheme. In addition, if you configure with --enabled-shared, you may accumlate many unused versions of the dynamic libraries in your installation target. 4. [Optional] Run `help-desk' to install missing documentation. The source distribution (or Subversion-based source) includes only the release notes, and not the rest of the core documentation. Run the newly installed `help-desk' and follow the "Manuals" link to install the rest of the documentation. For a Subversion-based build, the "Manuals" page includes a link to update previously installed documentation. 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 a "buildinfo" file in the installation. For a build without --prefix (or with --enable-origtree) and without --enable-shared, you can safely move the install tree, because all file references within the installation are relative. 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. ======================================================================== CGC versus 3m ======================================================================== MzScheme and MrEd have two variants: CGC and 3m. The CGC variant is older, and it cooperates more easily with extensions written in C. The 3m variant is now the default, and it usually provides better overall performance. The default build mode creates 3m binaries only. To create CGC binaries in addition, run `make cgc' in addition to `make', or run `make both'. To install both variants, use `make install-both' instead of just `make install'. Alternately, use just `make cgc' and `make install-cgc' to build and install just the CGC variants. CGC variants are installed with a "cgc" suffix. To swap the default build and install mode, supply --enable-cgcdefault to `configure'. In that case, CGC variants are built by default, `make 3m' creates 3m binaries, and `make install-both' installs CGC variants without a suffix and 3m variants with a "3m" suffix. ======================================================================== Embedded Paths in the Executables ======================================================================== On all platforms, the MzScheme and MrEd binaries embed a path to the main "collects" directory of library collections. This path can be relative to the executable. Multiple paths can be provided, in which case the first path is the main "collects" path, and additional paths are placed before the main path (but after a user-specific "collects" path) in the default collection path list. The paths are embedded in the binary immediately after a "coLLECTs dIRECTORy:" tag. Each path must be NUL terminated, the entire list of paths must end with an additional NUL terminator, and the overall list must be less than 1024 bytes long. As an alternative to editing an exeuctable directly, the `create-embedding-executable' procedure from `(lib "embed.ss" "compiler")' can be used to change the embedded path. For example, the following program clones the MzScheme executable to "/tmp/mz" and changes the embedded path in the clone to "/tmp/collects": (require (lib "embed.ss" "compiler")) (create-embedding-executable "/tmp/mz" #:collects-path "/tmp/collects") Similarly, `mzc' in `--exe' or `--gui-exe' mode accepts a `--collects' flag to set the collection path in the generated executable. Under Windows, executables also embed a path to DLLs. For more information, see worksp\README. Paths to all other installation directories are found through the "config.ss" library of the "config" collection. See "doc.txt" in the "config" collection (for search for "config.ss" in Help Desk) for more information. ======================================================================== 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 : 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
: 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 NetBSD 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. 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.