385 lines
17 KiB
Plaintext
385 lines
17 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
|
|
| Restrictions on generated executables? | none | none | yes <<tb1,(*)>>
|
|
|=====
|
|
|
|
[[tb1]]
|
|
(*):: Executables generated by the native GCC package in Cygwin are linked with
|
|
the Cygwin DLL and require this to be distributed with your programs.
|
|
Executables generated by Microsoft Visual C++ or the Mingw-w64 compilers (even
|
|
when run in Cygwin as `i686-w64-mingw32-gcc` or `x86_64-w64-mingw32-gcc`) are
|
|
not linked against this DLL. Prior to Cygwin 2.5.2 (the Cygwin version can be
|
|
obtained with `uname -r`) the Cygwin DLL is distributed under the GPL, requiring
|
|
any programs linked with it to be distributed under a compatible licence. Since
|
|
version 2.5.2, the Cygwin DLL is distributed under the LGPLv3 with a static
|
|
linking exception meaning that, like executables generated by Microsoft Visual
|
|
C++ or the Mingw-w64 compilers, generated executables may be distributed under
|
|
terms of your choosing.
|
|
|
|
[[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. Note: binary
|
|
distributions of FlexDLL are compatible only with Visual Studio 2013 and
|
|
earlier; for Visual Studio 2015 and later, you will need to compile the C
|
|
objects from source, or build ocaml using the flexdll target.
|
|
|
|
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 as well as the Build Tools for Visual Studio.
|
|
|
|
|=====
|
|
| | `cl` Version | Express | SDK/Build Tools
|
|
| 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 | Build Tools for Visual Studio 2015 also provides 32/64-bit compilers
|
|
| Visual Studio 2017 | 19.10.x.x | 32/64-bit | Build Tools for Visual Studio 2017 also provides 32/64-bit compilers
|
|
| Visual Studio 2019 | 19.20.x.x | 32/64-bit | Build Tools for Visual Studio 2019 also provides 32/64-bit compilers
|
|
|=====
|
|
|
|
[[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 and 2017, you
|
|
need to use the shortcuts in the "Windows Desktop Command Prompts" (2015) or
|
|
"VC" (2017) 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 and 2017 make the shortcuts even clearer by including the full name of the
|
|
architecture.
|
|
|
|
The Build Tools for Visual Studio 2015 and 2017 provide shortcuts similar to
|
|
the ones of their respective Visual Studio version.
|
|
|
|
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` will fail relatively
|
|
quickly as it will be unable to link `ocamlrun`.
|
|
|
|
Now run:
|
|
|
|
./configure --build=i686-pc-cygwin --host=i686-pc-windows
|
|
|
|
for 32-bit, or:
|
|
|
|
./configure --build=x86_64-unknown-cygwin --host=x86_64-pc-windows
|
|
|
|
for 64-bit.
|
|
|
|
Finally, use `make` to build the system, e.g.
|
|
|
|
make
|
|
make 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 `runtime/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`, `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:
|
|
|
|
./configure --build=i686-pc-cygwin --host=i686-w64-mingw32
|
|
|
|
for 32-bit, or:
|
|
|
|
./configure --build=x86_64-unknown-cygwin --host=x86_64-w64-mingw32
|
|
|
|
for 64-bit.
|
|
|
|
Finally, use `make` to build the system, e.g.
|
|
|
|
make
|
|
make 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`, `num`,
|
|
`str`, `threads`, and large parts of `unix`.
|
|
|
|
* The replay debugger is partially supported (no reverse execution).
|
|
|
|
[[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 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
|
|
building the compiler itself, you must compile `flexdll`, i.e.:
|
|
|
|
make flexdll
|
|
make
|
|
make flexlink.opt
|
|
make install
|
|
|
|
* You should ignore the error messages that say ocamlopt was not found.
|
|
* `make 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 flexlink.opt`, `flexlink.exe` will be a
|
|
bytecode program. `make 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 flexdll`. If you wish to revert to using an externally
|
|
installed FlexDLL, you must erase the contents of `flexdll/` before
|
|
compiling.
|
|
|
|
== Unicode support
|
|
|
|
Prior to version 4.06, all filenames on the OCaml side were assumed
|
|
to be encoded using the current 8-bit code page of the system. Some
|
|
Unicode filenames could thus not be represented. Since version 4.06,
|
|
OCaml adds to this legacy mode a new "Unicode" mode, where filenames
|
|
are UTF-8 encoded strings. In addition to filenames,
|
|
this applies to environment variables and command-line arguments.
|
|
|
|
The mode must be decided before building the system, by tweaking
|
|
the `WINDOWS_UNICODE` variable in `Makefile.config`. A value of 1
|
|
enables the the new "Unicode" mode, while a value of 0 maintains
|
|
the legacy mode.
|
|
|
|
Technically, both modes use the Windows "wide" API, where filenames
|
|
and other strings are made of 16-bit entities, usually interpreted as
|
|
UTF-16 encoded strings.
|
|
|
|
Some more details about the two modes:
|
|
|
|
* Unicode mode: OCaml strings are interpreted as being UTF-8 encoded
|
|
and translated to UTF-16 when calling Windows; strings returned by
|
|
Windows are interpreted as UTF-16 and translated to UTF-8 on their
|
|
way back to OCaml. Additionally, an OCaml string which is not
|
|
valid UTF-8 will be interpreted as being in the current 8-bit code
|
|
page. This fallback works well in practice, since the chances of
|
|
non-ASCII string encoded in the a 8-bit code page to be a valid
|
|
UTF-8 string are tiny. This means that filenames
|
|
obtained from e.g. a 8-bit UI or database layer would continue to
|
|
work fine. Application written for the legacy mode or older
|
|
versions of OCaml might still break if strings returned by
|
|
Windows (e.g. for `Sys.readdir`) are sent to components expecting
|
|
strings encoded in the current code page.
|
|
|
|
* Legacy mode: this mode emulates closely the behavior of OCaml <
|
|
4.06 and is thus the safest choice in terms of backward
|
|
compatibility. In this mode, OCaml programs can only work with
|
|
filenames that can be encoded in the current code page, and the
|
|
same applies to ocaml tools themselves (ocamlc, ocamlopt, etc).
|
|
|
|
The legacy mode will be deprecated and then removed in future versions
|
|
of OCaml. Users are thus strongly encouraged to use the Unicode mode
|
|
and adapt their existing code bases accordingly.
|
|
|
|
Note: in order for ocaml tools to support Unicode pathnames, it is
|
|
necessary to use a version of FlexDLL which has itself been compiled
|
|
with OCaml >= 4.06 in Unicode mode. This is the case for binary distributions
|
|
of FlexDLL starting from version 0.37 and above.
|
|
|
|
== Trademarks
|
|
|
|
Microsoft, Visual C++, Visual Studio and Windows are registered trademarks of
|
|
Microsoft Corporation in the United States and/or other countries.
|