336 lines
14 KiB
Plaintext
336 lines
14 KiB
Plaintext
= Release notes for the Microsoft Windows ports of OCaml =
|
|
:toc: macro
|
|
|
|
There are no fewer than three ports of OCaml for Microsoft Windows, each
|
|
available in 32 and 64-bit versions:
|
|
|
|
- native Windows, built with the Microsoft C/C++ Optimizing Compiler
|
|
- native Windows, built using the Mingw-w64 version of GCC
|
|
- Cygwin (http://www.cygwin.com[www.cygwin.com])
|
|
|
|
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 native-code generation | Microsoft Visual C++ | Cygwin | Cygwin
|
|
4+^| Features
|
|
| 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 Microsoft Visual C++ or
|
|
Mingw-w64 have no such restrictions.
|
|
|
|
[[tb2]]
|
|
(**):: The debugger is supported but the "replay" functions are not enabled.
|
|
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
|
|
link:INSTALL.adoc[] for full instructions.
|
|
|
|
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::[]
|
|
|
|
== 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
|
|
https://github.com/alainfrisch/flexdll. 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
|
|
|
|
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>>).
|
|
|
|
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.
|
|
|
|
|=====
|
|
| | `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 |
|
|
|=====
|
|
|
|
[[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
|
|
|
|
=== COMPILATION FROM THE SOURCES
|
|
|
|
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.
|
|
(Note: you should use cygwin's `tar` command to unpack this archive. If you
|
|
use WinZip, you will need to deselect "TAR file smart CR/LF conversion" in
|
|
the WinZip Options Window.)
|
|
|
|
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.
|
|
|
|
The details differ depending on whether you are using a Windows SDK to provide
|
|
the compiler or Microsoft Visual Studio itself.
|
|
|
|
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:
|
|
|
|
SetEnv /Release /x86
|
|
|
|
for 32-bit or:
|
|
|
|
SetEnv /Release /x64
|
|
|
|
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.
|
|
|
|
Unlike `SetEnv` for the Windows SDK, the architecture is selected by using a
|
|
different shortcut, rather than by running a 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.
|
|
|
|
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.
|
|
|
|
You cannot at present use a cross-compiler to compile 64-bit OCaml on 32-bit
|
|
Windows.
|
|
|
|
Once you have started a Command Prompt, you can verify that you have the
|
|
compiler you are expecting simply by running:
|
|
|
|
cl
|
|
Microsoft (R) C/C++ Optimizing Compiler Version 19.00.23506 for x86
|
|
...
|
|
|
|
You then need to start Cygwin from this Command Prompt. Assuming you have
|
|
installed it to its default location of `C:\cygwin`, simply run:
|
|
|
|
C:\cygwin\bin\mintty -
|
|
|
|
(note the space and hyphen at the end of the command).
|
|
|
|
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:
|
|
|
|
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
|
|
|
|
for 32-bit, or:
|
|
|
|
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 bootstrap opt opt.opt install
|
|
|
|
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`.
|
|
|
|
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.
|
|
|
|
* 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.
|
|
|
|
== Mingw-w64 Ports
|
|
|
|
=== REQUIREMENTS
|
|
|
|
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.
|
|
|
|
- Do not try to use the Cygwin version of flexdll for this port.
|
|
|
|
- The standalone mingw toolchain from the Mingw-w64 project
|
|
(http://mingw-w64.org/) is not supported. Please use the version packaged in
|
|
Cygwin instead.
|
|
|
|
=== COMPILATION FROM THE SOURCES
|
|
|
|
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.
|
|
(Note: you should use cygwin's `tar` command to unpack this archive. If you
|
|
use WinZip, you will need to deselect "TAR file smart CR/LF conversion" in
|
|
the WinZip Options Window.)
|
|
|
|
Now run:
|
|
|
|
cp config/m-nt.h config/m.h
|
|
cp config/s-nt.h config/s.h
|
|
|
|
followed by:
|
|
|
|
cp config/Makefile.mingw config/Makefile
|
|
|
|
for 32-bit, or:
|
|
|
|
cp config/Makefile.mingw64 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 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`.
|
|
|
|
* 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 `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
|
|
|
|
[[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`.
|
|
|
|
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:
|
|
|
|
* Extracting the sources from a tarball from
|
|
https://github.com/alainfrisch/flexdll/releases
|
|
* Cloning the git repository by running:
|
|
+
|
|
git clone https://github.com/alainfrisch/flexdll.git
|
|
|
|
* 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
|
|
|
|
OCaml is then compiled as normal for the port you require, except that before
|
|
compiling `world`, you must compile `flexdll`, i.e.:
|
|
|
|
make -f Makefile.nt flexdll world [bootstrap] opt opt.opt install
|
|
|
|
* `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
|
|
|
|
Microsoft, Visual C++, Visual Studio and Windows are registered trademarks of
|
|
Microsoft Corporation in the United States and/or other countries.
|