ocaml/README.win32

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

Starting with OCaml 3.05, there are no less than three 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.

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

                                      Native MS     Native MinGW        Cygwin
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                         no              no              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 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 NT, 2000 and XP.  
Windows 95, 98 and ME are also supported, but less reliably.

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.  Dynamic loading of DLLs is
supported out of the box, without additional software.

The native-code compiler (ocamlopt) requires Visual C++ and the
Microsoft assembler MASM version 6.11 or later.  MASM can be
downloaded for free from Microsoft's Web site; for directions, see
        http://www.easystreet.com/~jkirwan/pctools.html
    or  http://www2.dgsys.com/~raymoon/faq/masm.html
    or  the comp.lang.asm.x86 FAQ.

The LablTk GUI requires Tcl/Tk 8.3.  Windows binaries are
available from http://prdownloads.sourceforge.net/tcl/tcl832.exe.


INSTALLATION:

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

If you are using Windows 95, 98 or ME, you need to adjust environment
variables as follows:
  - add the "bin" subdirectory of the OCaml installation directory
    to the PATH variable;
  - set the OCAMLLIB variable to the "lib" subdirectory of the
    OCaml installation directory.
For instance, if you installed OCaml in C:\Program Files\Objective Caml,
add the following two lines at the end of C:\autoexec.bat:

    set PATH=%PATH%;"C:\Program Files\Objective Caml\bin"
    set OCAMLLIB=C:\Program Files\Objective Caml\lib

No such tweaking of environment variables is needed under NT, 2000 and XP.

To run programs that use the LablTK GUI, the directory where the
DLLs tk83.dll and tcl83.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 tk83.lib and tcl83.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:

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, or XP (we advise against compiling under Windows 95/98/ME)
- Visual C++ version 6 or 7
- MASM version 6.11 (see above)
- The Cygwin port of GNU tools, available from http://cygwin.com/
- TCL/TK version 8.3 (for the LablTK GUI) (see above).

Remember to add the directory where the libraries tk83.lib and
tcl83.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 install


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 not supported.

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 NT, 2000 and XP.  
Windows 95, 98 and ME are also supported, but less reliably.

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://sources.redhat.com/cygwin/

The LablTk GUI requires Tcl/Tk 8.3.  Windows binaries are
available from http://prdownloads.sourceforge.net/tcl/tcl832.exe.


INSTALLATION:

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

If you are using Windows 95, 98 or ME, you need to adjust environment
variables as follows:
  - add the "bin" subdirectory of the OCaml installation directory
    to the PATH variable;
  - set the OCAMLLIB variable to the "lib" subdirectory of the
    OCaml installation directory.
For instance, if you installed OCaml in C:\Program Files\Objective Caml,
add the following two lines at the end of C:\autoexec.bat:

    set PATH=%PATH%;"C:\Program Files\Objective Caml\bin"
    set OCAMLLIB=C:\Program Files\Objective Caml\lib

No such tweaking of environment variables is needed under NT, 2000 and XP.

To run programs that use the LablTK GUI, the directory where the
DLLs tk83.dll and tcl83.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 tk83.lib and tcl83.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, or XP (we advise against compiling under Windows 95/98/ME)
- Cygwin: http://sourceware.cygnus.com/cygwin/
- TCL/TK version 8.3 (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 that is installed along with 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 not supported.

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

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

REQUIREMENTS:

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

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


INSTALLATION:

For technical reasons, no binary distribution of this port is available.
You need to 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.