Overhaul the Windows installation instructions.

Simplified the instructions by de-duplicating the 32/64-bit instructions
now that every port is available for both architectures.

Removed out-of-date Cygwin information.

Included details on the new FlexDLL bootstrapping procedure.
master
David Allsopp 2016-04-08 15:16:35 +01:00 committed by Gabriel Scherer
parent 0f3b843ba6
commit 2004348db6
1 changed files with 203 additions and 284 deletions

View File

@ -1,4 +1,4 @@
= Release notes on the Microsoft Windows ports of OCaml =
= Release notes for the Microsoft Windows ports of OCaml =
:toc: macro
There are no fewer than three ports of OCaml for Microsoft Windows, each
@ -14,7 +14,7 @@ Here is a summary of the main differences between these ports:
| | Native Microsoft | Native Mingw-w64 | Cygwin
4+^| Third-party software required
| for base bytecode system | none | none | none
| for ocamlc -custom | Microsoft Visual C++ | Cygwin | Cygwin
| for `ocamlc -custom` | Microsoft Visual C++ | Cygwin | Cygwin
| for native-code generation | Microsoft Visual C++ | Cygwin | Cygwin
4+^| Features
| Speed of bytecode interpreter | 70% | 100% | 100%
@ -26,8 +26,8 @@ Here is a summary of the main differences between these ports:
|=====
[[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
(*):: 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 Microsoft Visual C++ or
Mingw-w64 have no such restrictions.
@ -36,373 +36,292 @@ Mingw-w64 have no such restrictions.
Other functions are available (step, goto, run...).
Cygwin aims to provide a Unix-like environment on Windows, and the build
procedure for it is the same as for other flavours of Unix. See
procedure for it is the same as for other flavours of Unix. See
link:INSTALL.adoc[] for full instructions.
The four native Windows ports have to be built differently, and the remainder of
The native ports require Windows XP or later and naturally the 64-bit versions
need a 64-bit edition of Windows (note that this is both to run *and* build).
The two native Windows ports have to be built differently, and the remainder of
this document gives more information.
toc::[]
== The native Win32 port built with Microsoft Windows SDK
== PREREQUISITES
All the Windows ports require a Unix-like build environment. Although other
methods are available, the officially supported environment for doing this is
32-bit (x86) Cygwin.
Only the `make` Cygwin package is required. `diffutils` is required if you wish
to be able to run the test suite.
Unless you are also compiling the Cygwin port of OCaml, you should not install
the `gcc-core` or `flexdll` packages. If you do, care may be required to ensure
that a particular build is using the correct installation of `flexlink`.
[[bmflex]]
In addition to Cygwin, FlexDLL must also be installed, which is available from
http://alain.frisch.fr/flexdll.html. A binary distribution is available;
instructions on how to build FlexDLL from sources, including how to bootstrap
FlexDLL and OCaml are given <<seflexdll,later in this document>>. Unless you
bootstrap FlexDLL, you will need to ensure that the directory to which you
install FlexDLL is included in your `PATH` environment variable.
The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...) of all three
ports runs without any additional tools.
== Microsoft Visual C/C++ Ports
=== REQUIREMENTS
This port runs under MS Windows 7 (32 and 64 bits), Vista, XP, and 2000.
The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with
C code (`ocamlc -custom`) require a Microsoft Visual C/C++ Compiler and the
`flexlink` tool (see <<bmflex,above>>).
The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.
Any edition (including Express/Community editions) of Microsoft Visual Studio
2005 or later may be used to provide the required Windows headers and the C
compiler. Additionally, some older Microsoft Windows SDKs include the
Visual C/C++ Compiler.
The native-code compiler (ocamlopt) requires the Microsoft Windows SDK
(item <<tps1,[1]>>) and the flexdll tool (item <<tps2,[2]>>).
|=====
| | `cl` Version | Express | SDK
| Visual Studio 2005 | 14.00.x.x | 32-bit only <<vs1,(*)>> |
| Visual Studio 2008 | 15.00.x.x | 32-bit only | Windows SDK 7.0 also provides 32/64-bit compilers
| Visual Studio 2010 | 16.00.x.x | 32-bit only | Windows SDK 7.1 also provides 32/64-bit compilers
| Visual Studio 2012 | 17.00.x.x | 32/64-bit |
| Visual Studio 2013 | 18.00.x.x | 32/64-bit |
| Visual Studio 2015 | 19.00.x.x | 32/64-bit |
|=====
Statically linking OCaml bytecode with C code (ocamlc -custom) also requires
items <<tps1,[1]>> and <<tps2,[2]>>.
[[vs1]]
(*):: Visual C++ 2005 Express Edition does not provide an assembler; this can be
downloaded separately from
https://www.microsoft.com/en-gb/download/details.aspx?id=12654
=== INSTALLATION
=== COMPILATION FROM THE SOURCES
The binary distribution is a self-installing executable archive.
Just run it and it should install OCaml automatically.
The command-line tools must be compiled from the Unix source distribution
(`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows.
=== THIRD-PARTY SOFTWARE
Microsoft Visual C/C++ is designed to be used from special developer mode
Command Prompts which set the environment variables for the required compiler.
There are multiple ways of setting up your environment ready for their use. The
simplest is to start the appropriate command prompt shortcut from the program
group of the compiler you have installed.
[[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".
The details differ depending on whether you are using a Windows SDK to provide
the compiler or Microsoft Visual Studio itself.
[[tps2]]
[2]:: flexdll version 0.31 or later.
Can be downloaded from http://alain.frisch.fr/flexdll.html
For the Windows SDK, there is only one command prompt called "CMD Shell" in
versions 6.1 and 7.0 and "Windows SDK 7.1 Command Prompt" in version 7.1. This
launches a Command Prompt which will usually select a `DEBUG` build environment
for the operating system that you are running. You should then run:
=== RECOMPILATION FROM THE SOURCES
SetEnv /Release /x86
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.
for 32-bit or:
You will need the following software components to perform the recompilation:
SetEnv /Release /x64
- 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.
for 64-bit. For Visual Studio 2005-2013, you need to use one of the shortcuts in
the "Visual Studio Tools" program group under the main program group for the
version of Visual Studio you installed. For Visual Studio 2015, you need to use
the shortcuts in the "Windows Desktop Command Prompts" group under the
"Visual Studio Tools" group.
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.
Unlike `SetEnv` for the Windows SDK, the architecture is selected by using a
different shortcut, rather than by running a command.
. Open a Windows Command Prompt and enter the following command:
For Visual Studio 2005-2010, excluding version-specific prefixes, these are
named "Command Prompt" for 32-bit and "x64 Cross Tools Command Prompt" or
"x64 Win64 Command Prompt" for 64-bit. It does not matter whether you use a
"Cross Tools" or "Win64" version for x64, this simply refers to whether the
compiler itself is a 32-bit or 64-bit program; both produce 64-bit output and
work with OCaml.
set PFPATH=C:\Program Files
For Visual Studio 2012 and 2013, both x86 and x64 Command Prompt shortcuts
indicate if they are the "Native Tools" or "Cross Tools" versions. Visual Studio
2015 makes the shortcuts even clearer by including the full name of the
architecture.
. If you are compiling on the 64-bit version of Windows 7, enter the
following instead:
You cannot at present use a cross-compiler to compile 64-bit OCaml on 32-bit
Windows.
set PFPATH=C:\Program Files (x86)
Once you have started a Command Prompt, you can verify that you have the
compiler you are expecting simply by running:
. Then enter the following commands:
cl
Microsoft (R) C/C++ Optimizing Compiler Version 19.00.23506 for x86
...
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
You then need to start Cygwin from this Command Prompt. Assuming you have
installed it to its default location of `C:\cygwin`, simply run:
. Open a Cygwin shell and enter the following commands:
C:\cygwin\bin\mintty -
tr -d '\r' </tmp/msenv >.msenv32
echo '. $HOME/.msenv32' >>.bashrc
(note the space and hyphen at the end of the command).
Now, close the Command Prompt and the shell and you're set up for
using the MS tools under Cygwin.
This should open a terminal window and start bash. You should be able to run
`cl` from this. You can now change to the top-level directory of the directory
of the OCaml distribution.
The Microsoft Linker is provided by a command called `link` which unfortunately
conflicts with a Cygwin command of the same name. It is therefore necessary to
ensure that the directory containing the Microsoft C/C++ Compiler appears at
the beginning of `PATH`, before Cygwin's `/usr/bin`. You can automate this from
the top-level of the OCaml distribution by running:
To recompile OCaml, start a new Cygwin shell and change to the top-level
directory of the OCaml distribution. Then, do
eval $(tools/msvs-promote-path)
If you forget to do this, `make -f Makefile.nt world` will fail relatively
quickly as it will be unable to link `ocamlrun`.
Now run:
cp config/m-nt.h config/m.h
cp config/s-nt.h config/s.h
followed by:
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
for 32-bit, or:
PREFIX where to install everything
cp config/Makefile.msvc64 config/Makefile
for 64-bit. Then, edit `config/Makefile` as needed, following the comments in
this file. Normally, the only variable that needs to be changed is `PREFIX`,
which indicates 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
make -f Makefile.nt world bootstrap opt opt.opt install
=== NOTES
After installing, it is not necessary to keep the Cygwin installation (although
you may require it to build additional third party libraries and tools). You
will need to use `ocamlopt` (or `ocamlc -custom`) from the same Visual Studio or
Windows SDK Command Prompt as you compiled OCaml from, or `ocamlopt` will not
be able to find `cl`.
* 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.
If you wish to use `ocamlopt` from Cygwin's bash on a regular basis, you may
like to copy the `tools/msvs-promote-path` script and add the `eval` line to
your `~/.bashrc` file.
* Libraries available in this port: `num`, `str`, `threads`, `graphics`,
and large parts of `unix`.
* The Microsoft Visual C/C++ 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, Cygwin or Mingw-w64 on similar hardware.
* Libraries available in this port: `bigarray`, `dynlink`, `graphics`, `num`,
`str`, `threads`, 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 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
== Mingw-w64 Ports
=== REQUIREMENTS
Those ports run under MS Windows Seven, Vista, XP, and 2000.
The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with
C code (`ocamlc -custom`) require the appropriate Mingw-w64 gcc and the
`flexlink` tool (see <<bmflex,above>>). Mingw-w64 gcc is provided by the
`mingw64-i686-gcc-core` package for 32-bit and the `mingw64-x86_64-gcc-core`
package for 64-bit.
The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.
- Do not try to use the Cygwin version of flexdll for this port.
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):
- The standalone mingw toolchain from the Mingw-w64 project
(http://mingw-w64.org/) is not supported. Please use the version packaged in
Cygwin instead.
mingw64-i686-binutils
mingw64-i686-gcc-core
mingw64-i686-runtime
=== COMPILATION FROM THE SOURCES
and the following packages for the 64-bit:
The command-line tools must be compiled from the Unix source distribution
(`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows.
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
Now run:
cp config/m-nt.h config/m.h
cp config/s-nt.h config/s.h
For a 32 bit OCaml:
followed by:
cp config/Makefile.mingw config/Makefile
For a 64 bit OCaml:
for 32-bit, or:
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
for 64-bit. Then, edit `config/Makefile` as needed, following the comments in
this file. Normally, the only variable that needs to be changed is `PREFIX`,
which indicates 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
make -f Makefile.nt world bootstrap opt opt.opt install
After installing, you will need to ensure that `ocamlopt` (or `ocamlc -custom`)
can access the C compiler. You can do this either by using OCaml from Cygwin's
bash or by adding Cygwin's bin directory (e.g. `C:\cygwin\bin`) to your `PATH`.
=== NOTES
* Libraries available in this port: `num`, `str`, `threads`, `graphics`,
and large parts of `unix`.
* Libraries available in this port: `bigarray`, `dynlink`, `graphics`, `num`,
`str`, `threads`, 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:
* The default `config/Makefile.mingw` and `config/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 native Win64 port built with Microsoft Windows SDK
[[seflexdll]]
== FlexDLL
Although the core of FlexDLL is necessarily written in C, the `flexlink` program
is, naturally, written in OCaml. This creates a circular dependency if you wish
to build entirely from sources. Since OCaml 4.03 and FlexDLL 0.35, it is now
possible to bootstrap the two programs simultaneously. The process is identical
for both ports. If you choose to compile this way, it is not necessary to
install FlexDLL separately -- indeed, if you do install FlexDLL separately, you
may need to be careful to ensure that `ocamlopt` picks up the correct `flexlink`
in your `PATH`.
=== REQUIREMENTS
You must place the FlexDLL sources for Version 0.35 or later in the directory
`flexdll/` at the top-level directory of the directory of the OCaml
distribution. This can be done in one of three ways:
This port runs under MS Windows XP 64, Windows Server 64, and
Windows 7 64 on Intel64/AMD64 machines.
* Extracting the sources from a tarball from
http://alain.frisch.fr/flexdll.html#download
* Cloning the git repository by running:
+
git clone https://github.com/alainfrisch/flexdll.git
The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...)
runs without any additional tools.
* If you are compiling from a git clone of the OCaml repository, instead of
using a sources tarball, you can run:
+
git submodule update --init
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]>>).
OCaml is then compiled as normal for the port you require, except that before
compiling `world`, you must compile `flexdll`, i.e.:
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]>>).
make -f Makefile.nt flexdll world [bootstrap] opt opt.opt install
=== 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.
* `make -f Makefile.nt install` will install FlexDLL by placing `flexlink.exe`
(and the default manifest file for the Microsoft port) in `bin/` and the
FlexDLL object files in `lib/`.
* If you don't include `make -f Makefile.nt opt.opt`, `flexlink.exe` will be a
bytecode program. `make -f Makefile.nt install` always installs the "best"
`flexlink.exe` (i.e. there is never a `flexlink.opt.exe` installed).
* If you have populated `flexdll/`, you *must* run
`make -f Makefile.nt flexdll`. If you wish to revert to using an externally
installed FlexDLL, you must erase the contents of `flexdll/` before
compiling.
== Trademarks