ocaml/README.win32.adoc

472 lines
16 KiB
Plaintext

= Release notes on the MS Windows ports of OCaml =
:toc: macro
There are no less than five ports of OCaml for MS Windows available:
- a native Win32 port, built with the Microsoft development tools;
- a native Win32 port, built with the 32-bit version of the gcc
compiler from the mingw-w64 project, packaged in Cygwin
(under the name mingw64-i686);
- a native Win64 port, built with the 64-bit version of the gcc
compiler from the mingw-w64 project, packaged in Cygwin
(under the name mingw64-x86_64);
- a port consisting of the Unix sources compiled under the Cygwin
Unix-like environment for Windows (both 32-bit and 64-bit).
- 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 or Win64 | Win32 or Win64
4+^| 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 <<tb2,(**)>> | yes <<tb2,(**)>> | 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 <<tb1,(*)>>
|=====
[[tb1]]
(*):: 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.
[[tb2]]
(**):: The debugger is supported but the "replay" functions are not enabled.
Other functions are available (step, goto, run...).
The remainder of this document gives more information on each port.
toc::[]
== The native Win32 port built with Microsoft Windows SDK
=== REQUIREMENTS
This port runs under MS Windows 7 (32 and 64 bits), Vista, XP, and 2000.
The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.
The native-code compiler (ocamlopt) requires the Microsoft Windows SDK
(item <<tps1,[1]>>) and the flexdll tool (item <<tps2,[2]>>).
Statically linking OCaml bytecode with C code (ocamlc -custom) also requires
items <<tps1,[1]>> and <<tps2,[2]>>.
=== INSTALLATION
The binary distribution is a self-installing executable archive.
Just run it and it should install OCaml automatically.
=== THIRD-PARTY SOFTWARE
[[tps1]]
[1]:: Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 Service Pack 1.
Can be downloaded for free from
http://www.microsoft.com/downloads/en/default.aspx
under the name "Microsoft Windows 7 SDK".
[[tps2]]
[2]:: flexdll version 0.31 or later.
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.YY.Z.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, Vista, or 7 (32 or 64 bits).
- Items <<tps1,[1]>> and <<tps2,[2]>> 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 (and their dependencies):
diffutils, dos2unix, gcc-core, make, ncurses.
First, you need to set up your cygwin environment for using the MS
tools. The following assumes that you have installed <<tps1,[1]>>,
<<tps2,[2]>>, and [3] in their default directories. If this is not
the case, you will need to adjust the paths accordingly.
. Open a Windows Command Prompt and enter the following command:
set PFPATH=C:\Program Files
. If you are compiling on the 64-bit version of Windows 7, enter the
following instead:
set PFPATH=C:\Program Files (x86)
. Then enter the following commands:
cd "%PFPATH%\Microsoft Visual Studio 9.0\VC\bin"
set FLEXDLLDIR=%PFPATH%\flexdll
vcvars32
echo VCPATH="`cygpath -p '%Path%'`" >C:\cygwin\tmp\msenv
echo LIB="%LIB%" >>C:\cygwin\tmp\msenv
echo LIBPATH="%LIBPATH%" >>C:\cygwin\tmp\msenv
echo INCLUDE="%INCLUDE%;%FLEXDLLDIR%" >>C:\cygwin\tmp\msenv
echo FLPATH="`cygpath '%FLEXDLLDIR%'`" >>C:\cygwin\tmp\msenv
echo PATH="$VCPATH:$FLPATH:$PATH" >>C:\cygwin\tmp\msenv
echo export PATH LIB LIBPATH INCLUDE >>C:\cygwin\tmp\msenv
echo export OCAMLBUILD_FIND=/usr/bin/find >>C:\cygwin\tmp\msenv
. Open a Cygwin shell and enter the following commands:
tr -d '\r' </tmp/msenv >.msenv32
echo '. $HOME/.msenv32' >>.bashrc
Now, close the Command Prompt and the shell and you're set up for
using the MS tools under Cygwin.
To recompile OCaml, start a new 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 variable that need to be changed is
PREFIX where to install everything
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
* 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`,
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 OCaml) to
Windows NT was done by Kevin Gallo at Microsoft Research, who kindly
contributed his changes to the OCaml project.
== The native Win32 and Win64 ports built with Mingw
=== REQUIREMENTS
Those ports run under MS Windows Seven, 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
OCaml 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 for
the 32-bit flavor (use the Setup tool from Cygwin):
mingw64-i686-binutils
mingw64-i686-gcc-core
mingw64-i686-runtime
and the following packages for the 64-bit:
mingw64-x86_64-binutils
mingw64-x86_64-gcc-core
mingw64-x86_64-runtime
=== NOTES
- Do not use the Cygwin version of flexdll for this port.
- There is another 32-bit gcc compiler, from the MinGW.org
project, packaged in Cygwin under the name mingw-gcc.
It is not currently supported by flexdll and OCaml.
- The standard gcc compiler shipped with Cygwin used to
support a `-mno-cygwin` option, which turned the compiler
into a mingw compiler. This option was used
by previous versions of flexdll and OCaml, but it is no
longer available in recent version, hence the switch
to another toolchain packaged in Cygwin.
- The standalone mingw toolchain from the MinGW-w64 project
(http://mingw-w64.org/) is not supported. Please use the
version packaged in Cygwin instead.
=== INSTALLATION
The binary distribution is a self-installing executable archive.
Just run it and it should install OCaml automatically.
=== RECOMPILATION FROM THE SOURCES
You will need the following software components to perform the recompilation:
- Windows NT, 2000, XP, Vista, or Seven.
- Cygwin: http://cygwin.com/
Install at least the following packages (and their dependencies, as
computed by Cygwin's setup.exe):
* For both flavor of OCaml (32-bit and 64-bit):
diffutils
make
ncurses
* For the 32 bit flavor of OCaml:
mingw64-i686-binutils
mingw64-i686-gcc-core
mingw64-i686-runtime
* For the 64 bit flavor of OCaml:
mingw64-x86_64-binutils
mingw64-x86_64-gcc-core
mingw64-x86_64-runtime
- The flexdll tool (see above). Do not forget to add the flexdll directory
to your PATH
The standalone mingw toolchain from the MinGW-w64 project
(http://mingw-w64.org/) is not supported. Please use the
version packaged in Cygwin instead.
Start a new Cygwin shell and unpack the source distribution
(ocaml-X.YY.Z.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
For a 32 bit OCaml:
cp config/Makefile.mingw config/Makefile
For a 64 bit OCaml:
cp config/Makefile.mingw64 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
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 default Makefile.mingw and Makefile.mingw64 pass `-static-libgcc` to
the linker.
For more information on this topic:
- http://gcc.gnu.org/onlinedocs/gcc-4.9.1/gcc/Link-Options.html#Link-Options
- http://caml.inria.fr/mantis/view.php?id=6411
== The Cygwin port of OCaml
=== 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
Before starting, make sure that the gcc version installed by cygwin
is not 4.5.3 (it has a bug that affects OCaml). If needed, use cygwin's
setup.exe to downgrade to 4.3.4.
You will need to recompile (and install) flexdll from source with
Cygwin's C compiler because the official binary version of flexdll
doesn't handle Cygwin's symbolic links and sometimes fails to
launch the C compiler.
In order to recompile flexdll, you first need to configure, compile,
and install OCaml without flexdll support (configure with options
-no-shared-libs), then modify the flexdll Makefile to change
line 51 from:
LINKFLAGS = -ccopt "-link version_res.o"
to:
LINKFLAGS = -cclib version_res.o
Then `make CHAINS=cygwin` and add the flexdll directory to your PATH.
Make sure to add it before '/usr/bin' or you will get cygwin's flexlink.
Then, in OCaml's source directory, type:
make clean
make distclean
and follow the instructions for Unix machines given in the file INSTALL.
=== NOTES
- There is a problem with cygwin's port of gcc version 4.5.3. You should
use cygwin's setup program to downgrade to 4.3.4 before compiling OCaml.
- The replay debugger is fully supported.
- In order to use the "graph" library, you will need to use Cygwin's
setup.exe to install the xinit, and libX11-devel packages before compiling
OCaml.
== The native Win64 port built with Microsoft Windows SDK
=== REQUIREMENTS
This port runs under MS Windows XP 64, Windows Server 64, and
Windows 7 64 on Intel64/AMD64 machines.
The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.
Statically linking OCaml bytecode with C code (ocamlc -custom) requires the
Microsoft Platform SDK compiler (item <<tps-native1,[1]>> in the section
"third-party software" below) and the flexdll tool (item <<tps-native2,[2]>>).
The native-code compiler (ocamlopt) requires the Microsoft compiler
and the Microsoft assembler MASM64 (item link:tps-native1[(1(])
and the flexdll tool (item <<tps-native2,[2]>>).
=== INSTALLATION:
There is no binary distribution yet. Please compile from sources as
described below.
=== THIRD-PARTY SOFTWARE
[[tps-native1]]
[1]:: Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 Service Pack 1.
Can be downloaded for free from
http://www.microsoft.com/downloads/en/default.aspx
under the name "Microsoft Windows 7 SDK".
[[tps-native2]]
[2]:: flexdll version 0.31 or later.
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, Windows Server 64, or Windows 7 64.
- Items <<tps-native1,[1]>> and <<tps-native2,[2]>> 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.
First, you need to set up your cygwin environment for using the MS
tools. The following assumes that you have installed <<tps-native1,[1]>>
and <<tps-native2,[2]>> in their default directories. If this is not
the case, you will need to adjust the paths accordingly.
. Open a Windows Command Prompt and enter the following commands:
set PFPATH=C:\Program Files (x86)
cd "%PFPATH%\Microsoft Visual Studio 9.0\VC\bin"
vcvars64
echo VCPATH="`cygpath -p '%Path%'`" >C:\cygwin\tmp\msenv
echo LIB="%LIB%" >>C:\cygwin\tmp\msenv
echo LIBPATH="%LIBPATH%" >>C:\cygwin\tmp\msenv
echo INCLUDE="%INCLUDE%" >>C:\cygwin\tmp\msenv
echo FLPATH="`cygpath '%PFPATH%\flexdll'`" >>C:\cygwin\tmp\msenv
echo PATH="$VCPATH:$FLPATH:$PATH" >>C:\cygwin\tmp\msenv
echo export PATH LIB LIBPATH INCLUDE >>C:\cygwin\tmp\msenv
echo export OCAMLBUILD_FIND=/usr/bin/find >>C:\cygwin\tmp\msenv
. Open a Cygwin shell and enter the following commands:
tr -d '\r' </tmp/msenv >.msenv64
echo '. $HOME/.msenv64' >>.bashrc
Now, close the Command Prompt and the shell and you're set up for
using the MS tools under Cygwin.
To recompile OCaml, start a new 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
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.