This directory contains

  - solution files and project files for building minimal Racket and
    related executables with Microsoft Visual Studio 2008
    (a.k.a. version 9.0) and up, including the Express versions 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 Racket and GRacket using Visual
    Studio command-line tools;

  - solution files and project files for building "myssink.dll" with
    Microsoft Visual Studio 2008 (not Express), although the DLL is
    normally downloaded along with other pre-built DLLs.

Visual Studio Express is available for free from Microsoft.

Racket and GRacket also compile with MinGW.  To compile with MinGW,
follow the instructions in racket\src\README (which contains a short
Windows-specific section).

Finally, Racket and GRacket 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 racket\src\README (which contains
a short Windows-specific section).

With an MSVC-built Racket, compatible extensions can be built with other
compilers.  Build with Cygwin and copy the installed racket\lib\gcc to a
MSVC-based build to support Cygwin-built extensions.

As always, please report bugs via one of the following:
  - DrRacket's "submit bug report" menu          (preferred)
  - http://bugs.racket-lang.org/
  - the mailing list (users@racket-lang.org)     (last resort)

-PLT
 racket@racket-lang.org

---------------------------
Building Racket and GRacket
---------------------------

If you're using Visual Studio, and if `cl.exe' and `msbuild.exe'
is in your path, then you can just run
    racket\src\worksp\build.bat
from its own directory to perform all steps up to "Versioning",
including the MzCOM steps.

If `cl.exe' and `msbuild.exe' are not already in your path --- along
with many associated environment variables --- then you can run
"msvcprep.bat" to configure your environment, assuming that Visual
Studio is in one of its usual locations. The "msvcprep.bat" script
simply tries to find Visual Studio and run its "vcvarsall.bat". You
may need to provide an argument such as "x86" or "x86_amd64" to select
the build mode.

If your MSVC environment is configured for 64-bit builds (e.g., by
running "msvcprep.bat" or Microsoft's "vcvarsall.bat", with
"x86_amd64" or "amd64"), then a 64-bit build is created.

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


If you can't run "build.bat" or don't want to, you have to perform
several steps: first build RacketCGC, then build Racket3m, etc.

Building RacketCGC and GRacketCGC
---------------------------------

The CGC source code for RacketCGC and GRacketCGC is split into several
projects that are grouped into a few solutions.  To build the `X'
solution with Visual Studio, open the file racket\src\worksp\X\X.sln,
but add `9' before ".sln" if you're using Visual Studio 2008 (i.e.,
version 9.0). The solution files without a number are for Visual
Studio 2010, but they should upgrade immediately for later versions.

 [The .vcproj files are used by the ...9.sln solutions, while the
  .vcxproj files are used by the other .sln solutions. The latter are
  compatible with Visual Studio 2010. For Visual Studio versions later
  than 2010, "build.bat" script auto-upgrades projects in a copy whose
  file name ends with a literal "X" to match the current tool version,
  but you can also just upgrade them within your version of Visual
  Studio.]

To build RacketCGC, build the Racket solution in
  racket\src\worksp\racket - makes racket\RacketCGC.exe

  [When you open the solution, switch to a "Release" configuration
   before building.]

To build GRacketCGC, build the GRacket solution:
  racket\src\worksp\gracket - makes racket\GRacketCGC.exe

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

The build processes for RacketCGC and GRacketCGC automatically builds
  libmzgc    - makes racket\lib\libmzgcxxxxxxx.dll and
               racket\src\worksp\libmzgc\Release\libmzgcxxxxxxx.lib
  libracket  - makes racket\lib\libracketxxxxxxx.dll and
               racket\src\worksp\mzsrc\Release\mzsrcxxxxxxx.lib

In addition, building RacketCGC executes
    racket\src\racket\dynsrc\mkmzdyn.bat
which copies .exp, .obj, and .lib files into racket\lib\.

Downloading Pre-Built Binaries
-------------------------------

You must install some pre-built DLLs if you want text-encoding
conversion, OpenSSL support, `racket/draw', or `racket/gui' support.
In principle, you could build them from scratch, but since they are
(mostly) maintained by people and organizations other than PLT, we
supply them in binary form.

The DLLs are distributed in packages, but they are also available
from
 
    https://github.com/plt/libs

and they must be installed into

    racket\lib

Pre-built libraries use "msvcrt.dll", as opposed to the run-time
library for a particular version of MSVC. For more information on that
choice, in case you want to compile you own via MSVC, see

 http://kobyk.wordpress.com/2007/07/20/
  dynamically-linking-with-msvcrtdll-using-visual-c-2005/

See also "..\native-lib\README.txt".

Building Racket3m and GRacket3m
-------------------------------

After RacketCGC and GRacketCGC 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 "msvcprep.bat" here or "vcvarsall.bat"
     from your Visual Studio installation, so that PATH and other
     environment variables are set.

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

       ..\..\..\racketcgc.exe -c make.rkt

The resulting Racket.exe and GRacket.exe will appear in the top-level
"racket" directory, along with DLLs libracket3mxxxxxxx.dll in
racket\lib.  (There is no corresponding libmzgc3mxxxxxxx.dll.  Instead,
it is merged with libracket3mxxxxxxx.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 "raco.exe".  Build the
following solutions:

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

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

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

    racket.exe -l- 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 `raco setup', where "raco.exe" was created the first time.

Versioning
----------

[If you're going to build MzCOM, 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

    racket -l setup/winvers

in a shell.

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

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

Building MzCOMCGC is similar to building RacketCGC.  Building the 3m
variant is a little different.

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

Use the "Release" configuration.

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

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

       ..\..\..\racketcgc.exe -cu xform.rkt

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

  3. Build (in Visual Studio).

The result is racket\MzCOM.exe.

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

Since the DLL libracket3mxxxxxxx.dll (or libmzgcxxxxxxx.dll and
libracketxxxxxxx.dll) is installed into racket\lib\ instead of just
racket\, the normal search path for DLLs would not find them when
running "Racket.exe" or "GRacket.exe".  To find the DLLs, the
executables are "delayload" linked with the DLLs, and the executables
explicitly load the DLLs from racket\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
executable 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 Racket
----------------

The Racket DLLs can be used within an embedding application.

The libraries

    racket\lib\win32\msvc\libracket3mxxxxxxx.lib
    racket\lib\win32\msvc\libracketxxxxxxx.lib
    racket\lib\win32\msvc\libmzgcxxxxxxx.lib

which are created by the libracket and libmzgc projects, provide linking
information for using the libracket3mxxxxxxx.dll, libracketxxxxxxx.dll,
and libmzgcxxxxxxx.dll DLLs.  The versioning script adjusts the names,
as described above.

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

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

----------------------------
SenoraGC versus the Boehm GC
----------------------------

The "Release" and "Debug" solution configurations use SenoraGC (SGC),
while the "AltGCRelease" and "AltGCDebug" configurations use the
variant of the Boehm GC that is included with Racket.

In project files, "SRelease" and "SDebug" (as used by the "Release"
and "Debug" solution configurations) build against SGC, while
"BRelease" and "BDebug" (as used by the "AltGCRelease" and
"AltGCDebug" solution configurations) build against the Boehm GC.
