This directory contains 

 - solution files and project files for building MzScheme and MrEd
    with Microsoft Visual Studio 8.0 and up (which work with the
    Express 2005 version of Visual Studio);

 - mzconfig.h which is a manual version of information that is
    gathered automatically when using the "configure" script;

 - scripts for building 3m variants of MzScheme and MrEd using
    Visual Studio command-line tools; and

 - solution files and project files for building MzCOM and MysterX
    with Microsoft Visual Studio 8.0 (not Express, which doesn't
    support ATL and MFC).

Visual Studio Express is available for free from Microsoft, and it is
the recommended compiler for building MzScheme and MrEd.

MzScheme and MrEd also compile with Cygwin gcc (a free compiler from
GNU and Cygnus Solutions), but the result is a Unix-style
installation, not a Window-style installation. To compile with gcc,
follow the instructions in plt\src\README (which contains a short
Windows-specific section).

With an MSVC-built MzScheme, compatible extensions can be built with
other compilers. Build with Cygwin and copy the installed plt\lib\gcc
to a MSVC-based build to support Cygwin-built extensions. To support
Borland-built extensions, cd to plt\src\mzscheme\dynsrc and run
mkbordyn.bat (which requires bcc23.exe, of course).

As always, 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

----------------------------------------------------------------------
Building MzScheme and MrEd
----------------------------------------------------------------------

The CGC variants of MzScheme, MzCOM, MrEd, and MysterX can be built
via Visual Studio projects. The 3m variants are built by a Scheme
script that runs the MSVC command-line tools. (See "CGC versus 3m"
in plt\src\README if you don't know about the two variants.)

The 3m build requires some parts of the CGC build:
       plt\src\worksp\mzscheme
       plt\src\worksp\wxutils
       plt\src\worksp\jpeg
       plt\src\worksp\png
       plt\src\worksp\zlib
It's simplest to just build the main CGC solutions, which
automatically build all of the above projects, and then build
3m.

Building MzSchemeCGC and MrEdCGC
--------------------------------

The CGC source code for MzSchemeCGC and MrEdCGC is split into several
projects that are grouped into a few solutions. To build the `X'
solution with Visual Studio, open the file plt\src\worksp\X\X.sln.

To build MzSchemeCGC, build the MzScheme solution in
   plt\src\worksp\mzscheme - makes plt\MzSchemeCGC.exe

   [When you open the solution, it may default to "Debug"configuration.
    Switch to "Release" before building.]

To build MrEdCGC, build the MrEd solution:
   plt\src\worksp\mred - makes plt\MrEdCGC.exe

   [Again, switch to the "Release" configuration if necessary.]

The build processes for MzSchemeCGC automatically builds
   libmzgc - makes plt\lib\libmzgcxxxxxxx.dll and
             plt\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
   mzsrc - makes plt\lib\libmzschxxxxxxx.dll and
                 plt\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib

The build process for MrEdCGC automatically builds
   libmzgc - as above
   libmzsch - as above
   libmred - makes plt\lib\libmredxxxxxxx.dll and
                   plt\src\worksp\libmred\Release\libmredxxxxxxx.lib
   wxutils - makes plt\src\worksp\wxutils\Release\wxutils.lib
   wxwin - makes plt\src\worksp\wxwin\Release\wxwin.lib
   wxs  - makes plt\src\worksp\wxs\Release\wxs.lib
   wxme  - makes plt\src\worksp\wxme\Release\wxme.lib
   jpeg  - makes plt\src\worksp\jpeg\Release\jpeg.lib
   png  - makes plt\src\worksp\jpeg\Release\png.lib
   zlib  - makes plt\src\worksp\jpeg\Release\zlib.lib

In addition, building MzSchemeCGC executes
   plt\src\mzscheme\dynsrc\mkmzdyn.bat
which copies .exp, .obj, and .lib files into plt\lib\, and also copies
DLLs from the "extradlls" directory to to plt\lib\.

Building MzScheme3m and MrEd3m
------------------------------

After MzSchemeCGC and MrEdCGC are built, you can can build 3m
binaries:

 1. Ensure that the Visual Studio command-line tools are in your
    path. You may need to run "vsvars32.bat" from your Visual Studio
    installation, so that PATH and other environment variables are set.

 2. Change directories to plt\src\worksp\gc2 and run

      ..\..\..\mzschemecgc.exe -r make.ss

The resulting MzScheme.exe and MrEd.exe will appear in the "plt"
directory, along with DLLs libmzsch3mxxxxxxx.dll and
libmred3mxxxxxxx.dll in plt/lib. (There is no corresponding
libmzgc3mxxxxxxx.dll.  Instead, it is merged with
libmzsch3mxxxxxxx.dll.)

Building Collections and Other Executables
------------------------------------------

If you're building from scratch, you'll also want the starter programs
used by the launcher collection to create "Setup PLT.exe". Build the
following solutions:

   plt\src\worksp\mzstart - makes plt\collects\launcher\mzstart.exe
   plt\src\worksp\mrstart - makes plt\collects\launcher\mrstart.exe

   [The "mzstart" and "mrstart" programs have no CGC versus 3m
    distinction.]

Then, set up all the other executables (besides MrEd[CGC].exe and
MzScheme[CGC].exe) by running

   mzscheme.exe -mvqM- setup

This last step makes the .zo files, too. To skip compiling .zos, add
-n to the end of the above command.

If you've already built before, then this step can be simplied: just
re-run "Setup PLT.exe", which was created the first time.

Versioning
----------

[If you're going to build MzCOM and/or MysterX, do that before running
 the version-changing script. See instructions below.]

The obnoxious "xxxxxxx" in the DLL names is a placeholder for a
version number. Embedding a version number in a DLL name appears to
be the simplest and surest way to avoid version confusion.

For local testing, you can use the "xxxxxxx" libraries directly. For
any binaries that will be distributed, however, the placeholder should
be replaced with a specific version.

To replace the "xxxxxxx" with a specific version, run

  mzscheme -mvqL winvers.ss setup

in a shell.

The "winvers.ss" program will have to make a temporary copy of
mzscheme.exe and the "lib" sub-directory (into the temporary
directory), and it will re-launch MzScheme a couple of times. Every
".exe", ".dll", ".lib", ".def", ".exp", and ".pdb" file within the
"plt" tree is updated to replace "xxxxxxxx" with a specific version
number.

----------------------------------------------------------------------
Building MzCOM and MysterX
----------------------------------------------------------------------

Beware that MzCOM and MysterX do not build with Express versions of
Visual Studio. Otherwise, building MzCOMCGC and MysterXCGC is similar
to building MzSchemeCGC. Building the 3m variants is a little
different.

Building MzCOM
--------------

To build MzCOMCGC, make the MzCOM solution in
   plt\src\worksp\mzcom - makes plt\MzCOMCGC.exe

Use the "Release" configuration.

After building MzCOMCGC, you can build the 3m variant by 

 1. Change directories to plt\src\worksp\mzcom and run

      ..\..\..\mzschemecgc.exe -r xform.ss

 2. Switch to the "3m" configuration in the MzCOM solution
    (in Visual Studio).

 3. Build (in Visual Studio).

The result is plt\MzCOM.exe.

Building MysterX
----------------

To build MysterXCGC, make the MysterX solution in
   plt\src\worksp\libmysterx - makes plt\lib\myssink.dll,
          plt\lib\myspage.dll, and mxmain.dll in
          collects\mysterx\private\compiled\native\win32\i386

Use the "Release" configuration.

After building MysterXCGC, you can build the 3m variant by 

 1. Change directories to plt\src\worksp\libmysterx and run

      ..\..\..\mzschemecgc.exe -r xform.ss

 2. Switch to the "3m" configuration in the libmysterx solution
    (in Visual Studio).

 3. Build (in Visual Studio).

The result is mxmain.dll (no 3m suffix) in
  collects\mysterx\private\compiled\native\win32\i386\3m

----------------------------------------------------------------------
Finding DLLs
----------------------------------------------------------------------

Since the DLLs libmzsch3mxxxxxxx.dll (or libmzgcxxxxxxx.dll and
libmzschxxxxxxx.dll) and libmred3mxxxxxxx.dll (or libmredxxxxxxx.dll)
are installed into plt\lib\ instead of just plt\, the normal search
path for DLLs would not find them when running "MzScheme.exe" or
"MrEd.exe". To find the DLLs, the executables are "delayload" linked
with the DLLs, and the executables explicitly load the DLLs from
plt\lib\ on start-up.

The relative DLL path is embedded in each executable, and it can be
replaced with a path of up to 512 characters. The path is stored in
the exeuctable in wide-character format, and it is stored immediately
after the wide-character tag "dLl dIRECTORy:" with a wide NUL
terminator. The path can be either absolute or relative; in the latter
case, the relative path is resolved with respect to the
executable. Replacing the first character of the path with "<"
disables the explicit DLL load, so that the DLLs must appear in the
normal DLL search path.

See also ..\README for information on the embedded "collects" path in
the executables.

----------------------------------------------------------------------
Embedding MzScheme
----------------------------------------------------------------------

The MzScheme DLLs can be used within an embedding application.

The libraries

    plt\lib\win32\msvc\libmzsch3mxxxxxxx.lib
    plt\lib\win32\msvc\libmzschxxxxxxx.lib
    plt\lib\win32\msvc\libmzgcxxxxxxx.lib

which are created by the mzsrc and gc projects, provide linking
information for using the libmzsch3mxxxxxxx.dll, libmzschxxxxxxx.dll,
and libmzgcxxxxxxx.dll DLLs. The versioning script adjusts the names,
as described above.

See the "Inside PLT MzScheme" manual for more information about using
these libraries to embed MzScheme in an application.


If you need MzScheme to link to a DLL-based C library (instead of
statically linking to the C library within the MzScheme DLL), then
compile MzScheme with the /MD flag.
