Release notes on the MS Windows ports of Objective Caml
       -------------------------------------------------------

There are no less than four ports of Objective Caml for MS Windows available:
  - a native Win32 port, built with the Microsoft development tools;
  - a native Win32 port, built with the Cygwin/MinGW development tools;
  - a port consisting of the Unix sources compiled under the Cygwin
    Unix-like environment for Windows;
  - a native Win64 port (64-bit Windows), built with the Microsoft 
    development tools.

Here is a summary of the main differences between these ports:

                                      Native MS     Native MinGW        Cygwin

64 bits?                            Win32 or Win64    Win32 only      Win32 only

Third-party software required
  - for base bytecode system            none            none            none
  - for ocamlc -custom                  MSVC            Cygwin          Cygwin
  - for native-code generation          MSVC+MASM       Cygwin          Cygwin

Speed of bytecode interpreter           70%             100%            100%

Replay debugger                         yes (**)        yes (**)        yes

The Unix library                        partial         partial         full

The Threads library                     yes             yes             yes

The Graphics library                    yes             yes             no

Restrictions on generated executables?  none            none            yes (*)

(*) Cygwin-generated .exe files refer to a DLL that is distributed under
the GPL.  Thus, these .exe files can only be distributed under a license
that is compatible with the GPL.  Executables generated by MSVC or by
MinGW have no such restrictions.

(**) The debugger is supported but the "replay" function of it are not enabled.
Other functions are available (step, goto, run...).

The remainder of this document gives more information on each port.

------------------------------------------------------------------------------

           The native Win32 port built with Microsoft Visual C
           ---------------------------------------------------

REQUIREMENTS:

This port runs under MS Windows Vista, XP, and 2000.

The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.

Statically linking Caml bytecode with C code (ocamlc -custom) requires the
Microsoft Visual C++ compiler (items [1] and [2] in the section
"third-party software" below) and the flexdll tool (item [5]).

The native-code compiler (ocamlopt) requires Visual C++ (items [1], [2]),
the Microsoft assembler MASM (item [3]) and the flexdll tool (item [5]).

The LablTk GUI requires Tcl/Tk 8.5 (item [4]).


INSTALLATION:

The binary distribution is a self-installing executable archive.
Just run it and it should install OCaml automatically.

To run programs that use the LablTK GUI, the directory where the
DLLs tk85.dll and tcl85.dll were installed (by the Tcl/Tk
installer) must be added to the PATH environment variable.

To compile programs that use the LablTK GUI, the directory where the
libraries tk85.lib and tcl85.lib were installed (by the Tcl/Tk
installer) must be added to the library search path in the LIB
environment variable.  E.g. if Tcl/Tk was installed in C:\tcl, add
"C:\tcl\lib" to the LIB environment variable.

THIRD-PARTY SOFTWARE:

[1] Visual C++ version 2008, 2005, 2003, or 6.
    We use Visual C++ 2008 Express Edition, which can be downloaded for free
    from http://www.microsoft.com.

[2] Windows header files and development libraries.  They are included
    in the Visual C++ 2008 Express Edition distribution.
    Otherwise, you can find them in the Windows Platform SDK,
    which can be downloaded for free from http://www.microsoft.com/.

[3] MASM version 6.11 or later. The full distribution of Visual C++ 2005
    or 2008 contains MASM version 8.  Users of the Express Edition of Visual C++
    2005 can download MASM version 8 from
http://www.microsoft.com/downloads/details.aspx?FamilyID=7A1C9DA0-0510-44A2-B042-7EF370530C64&displaylang=en
    To obtain MASM version 6.11, see
    http://users.easystreet.com/jkirwan/new/pctools.html. 

[4] TCL/TK version 8.5.  Windows binaries are available as part of the
    ActiveTCL distribution at http://www.activestate.com/products/ActiveTcl/

[5] flexdll.
    Can be downloaded from http://alain.frisch.fr/flexdll.html

RECOMPILATION FROM THE SOURCES:

The command-line tools can be recompiled from the Unix source
distribution (ocaml-X.YZ.tar.gz), which also contains the files modified
for Windows.

You will need the following software components to perform the recompilation:
- Windows NT, 2000, XP, or Vista.
- Items [1], [2], [3], [4] and [5] from the list of recommended software above.
- The Cygwin port of GNU tools, available from http://www.cygwin.com/
  Install at least the following packages: diffutils, make, ncurses.

Remember to add the directory where the libraries tk84.lib and
tcl84.lib were installed (by the Tcl/Tk installer) to the LIB variable
(library search path).

To recompile, start a Cygwin shell and change to the top-level
directory of the OCaml distribution.  Then, do

        cp config/m-nt.h config/m.h
        cp config/s-nt.h config/s.h
        cp config/Makefile.msvc config/Makefile

Then, edit config/Makefile as needed, following the comments in this file.
Normally, the only variables that need to be changed are
        PREFIX      where to install everything
        TK_ROOT     where TCL/TK was installed

Finally, use "make -f Makefile.nt" to build the system, e.g.

        make -f Makefile.nt world
        make -f Makefile.nt bootstrap
        make -f Makefile.nt opt
        make -f Makefile.nt opt.opt
        make -f Makefile.nt install

Alternatively you can use the experimental build procedure using ocamlbuild:

        ./build/fastworld.sh
        ./build/install.sh

NOTES:

* The VC++ compiler does not implement "computed gotos", and therefore
generates inefficient code for byterun/interp.c. Consequently, the
performance of bytecode programs is about 2/3 of that obtained under
Unix/GCC or Cygwin or Mingw on similar hardware.

* Libraries available in this port: "num", "str", "threads", "graphics",
"labltk", and large parts of "unix". 

* The replay debugger is partially supported (no reverse execution).

CREDITS:

The initial port of Caml Special Light (the ancestor of Objective Caml)
to Windows NT was done by Kevin Gallo at Microsoft Research, who
kindly contributed his changes to the Caml project.

The graphical user interface for the toplevel was initially developed
by Jacob Navia, then significantly improved by Christopher A. Watford.

------------------------------------------------------------------------------

           The native Win32 port built with Mingw
           --------------------------------------

REQUIREMENTS:

This port runs under MS Windows Vista, XP, and 2000.

The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.

The native-code compiler (ocamlopt), as well as static linking of
Caml bytecode with C code (ocamlc -custom), require 
the Cygwin development tools, available at
        http://www.cygwin.com/
and the flexdll tool, available at
        http://alain.frisch.fr/flexdll.html
You will need to install at least the following Cygwin packages (use
the Setup tool from Cygwin):
binutils, gcc-core, gcc-mingw-core, mingw-runtime, w32-api.

Do *not* install the Mingw/MSYS development tools from www.mingw.org:
these are not compatible with this Caml port (@responsefile not
recognized on the command line).

The LablTk GUI requires Tcl/Tk 8.5.  Windows binaries are available 
as part of the ActiveTCL distribution at
http://www.activestate.com/products/ActiveTcl/

INSTALLATION:

The binary distribution is a self-installing executable archive.
Just run it and it should install OCaml automatically.

To run programs that use the LablTK GUI, the directory where the
DLLs tk85.dll and tcl85.dll were installed (by the Tcl/Tk
installer) must be added to the PATH environment variable.

To compile programs that use the LablTK GUI, the directory where the
libraries tk85.lib and tcl85.lib were installed (by the Tcl/Tk
installer) must be added to the library search path in the LIB
environment variable.  E.g. if Tcl/Tk was installed in C:\tcl, add
"C:\tcl\lib" to the LIB environment variable.


RECOMPILATION FROM THE SOURCES:

You will need the following software components to perform the recompilation:
- Windows NT, 2000, XP, or Vista.
- Cygwin: http://sourceware.cygnus.com/cygwin/
  Install at least the following packages: binutils, diffutils, 
    gcc-core, gcc-mingw-core, make, mingw-runtime, ncurses, w32-api.
- TCL/TK version 8.5 (see above).
- The flexdll tool (see above).

Do *not* install the standalone distribution of MinGW, nor the
companion MSYS tools: these have problems with long command lines.
Instead, use the version of MinGW provided by Cygwin.

Start a Cygwin shell and unpack the source distribution
(ocaml-X.YZ.tar.gz) with "tar xzf".  Change to the top-level
directory of the OCaml distribution.  Then, do

        cp config/m-nt.h config/m.h
        cp config/s-nt.h config/s.h
        cp config/Makefile.mingw config/Makefile

Then, edit config/Makefile as needed, following the comments in this file.
Normally, the only variables that need to be changed are
        PREFIX      where to install everything
        TK_ROOT     where TCL/TK was installed

Finally, use "make -f Makefile.nt" to build the system, e.g. 

        make -f Makefile.nt world
        make -f Makefile.nt bootstrap
        make -f Makefile.nt opt
        make -f Makefile.nt opt.opt
        make -f Makefile.nt install


NOTES:

* Libraries available in this port: "num", "str", "threads", "graphics",
  "labltk", and large parts of "unix". 

* The replay debugger is partially supported (no reverse execution).

------------------------------------------------------------------------------

                  The Cygwin port of Objective Caml
                  ---------------------------------

REQUIREMENTS:

This port requires the Cygwin environment from Cygnus/RedHat, which
is freely available at:
          http://www.cygwin.com/

It also requires the flexdll tool, available at:
          http://alain.frisch.fr/flexdll.html

This port runs under all versions of MS Windows supported by Cygwin.


INSTALLATION:

We do not distribute binaries for this port, but they can be found
in the Cygwin distribution (use the Setup tool from Cygwin and select
the OCaml packages).  Alternatively, recompile from the source distribution.


RECOMPILATION FROM THE SOURCES:

Just follow the instructions for Unix machines given in the file INSTALL.


NOTES:

The libraries available in this port are "num", "str", "threads",
"unix" and "labltk".  "graph" is not available.
The replay debugger is supported.

------------------------------------------------------------------------------

       The native Win64 port built with the Microsoft Platform SDK compilers
       ---------------------------------------------------------------------

REQUIREMENTS:

This port runs under MS Windows XP 64 and Server 64 on Intel64/AMD64 machines.

The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.

Statically linking Caml bytecode with C code (ocamlc -custom) requires the
Microsoft Platform SDK compiler (item [1] in the section
"third-party software" below) and the flexdll tool (item [2]).

The native-code compiler (ocamlopt) requires the Microsoft compiler
and the Microsoft assembler MASM64 (item [1]) and the flexdll tool (item [2]).


INSTALLATION:

There is no binary distribution yet.  Please compile from sources as
described below.


THIRD-PARTY SOFTWARE:

[1] Microsoft Windows Server 2003 R2 Platform SDK for AMD64 (PSDK-amd64.exe).
    Can be downloaded for free from http://www.microsoft.com/.
    Includes all we need, namely a C compiler, the masm64 assembler,
    Windows libraries and include files.

[2] flexdll.
    Can be downloaded from http://alain.frisch.fr/flexdll.html



RECOMPILATION FROM THE SOURCES:

The command-line tools can be recompiled from the Unix source
distribution (ocaml-X.YZ.tar.gz), which also contains the files modified
for Windows.

You will need the following software components to perform the recompilation:
- Windows XP 64 or Server 64.
- The Platform SDK (item [1] from the list of recommended software above).
- The Cygwin port of GNU tools, available from http://www.cygwin.com/
  Install at least the following packages: diffutils, make, ncurses.
- The flexdll tool (see above).

To recompile, start a Cygwin shell and change to the top-level
directory of the OCaml distribution.  Then, do

        cp config/m-nt.h config/m.h
        cp config/s-nt.h config/s.h
        cp config/Makefile.msvc64 config/Makefile

Then, edit config/Makefile as needed, following the comments in this file.
Normally, the only variable that need to be changed is
        PREFIX      where to install everything

If, for whatever reason, you want to use the Microsoft Visual C++ 2005
compiler for AMD64 instead of the Platform SDK compiler, replace the line
        EXTRALIBS=bufferoverflowu.lib
by
        EXTRALIBS=

Finally, use "make -f Makefile.nt" to build the system, e.g. 

        make -f Makefile.nt world
        make -f Makefile.nt bootstrap
        make -f Makefile.nt opt
        make -f Makefile.nt opt.opt
        make -f Makefile.nt install


NOTES:

* Libraries available in this port: "num", "str", "threads", "graphics",
  and large parts of "unix". 

* The replay debugger is partially supported (no reverse execution).

* The graphical browser ocamlbrowser is not supported.