The developer team is currently preparing the release of OCaml 5.0. This release sports a full rewrite of its runtime system for shared-memory parallel programming using domains and native support for concurrent programming using effect handlers.
Owing to the large number of changes, the initial 5.0 release will be more experimental than usual. It is recommended that all users wanting a stable release use the 4.14 release which will continue to be supported and updated while 5.0 reaches feature and stability parity. Similarly, if you need one of the ports not yet supported in the 5.0 release you must use the 4.14 release.
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 (https://www.cygwin.com)
Here is a summary of the main differences between these ports:
Native Microsoft |
Native MinGW-w64 |
Cygwin |
|
Third-party software required |
|||
for base bytecode system |
none |
none |
none |
for |
Microsoft Visual C++ |
Cygwin |
Cygwin |
for native-code generation |
Microsoft Visual C++ |
Cygwin |
Cygwin |
Features |
|||
Speed of bytecode interpreter |
70% |
100% |
100% |
Replay debugger |
yes (**) |
yes (**) |
yes |
The Unix library |
partial |
partial |
full |
The Threads library |
yes |
yes |
yes |
Restrictions on generated executables? |
none |
none |
yes (*) |
- (*)
-
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-gccorx86_64-w64-mingw32-gcc) are not linked against this DLL. Prior to Cygwin 2.5.2 (the Cygwin version can be obtained withuname -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.
- (**)
-
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 INSTALL.adoc for full instructions.
The native ports require Windows Vista 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.
All the Windows ports require a Unix-like build environment. Although other methods are available, the officially supported environment for doing this is 64-bit (x86_64) 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 do not need the
gcc-core or flexdll packages.
In addition to Cygwin, FlexDLL must also be installed, which is available from
https://github.com/ocaml/flexdll. A binary distribution is available;
instructions on how to build FlexDLL from sources, including how to bootstrap
FlexDLL and OCaml are given 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 configure ocaml with the --with-flexdll option.
The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, …) of all three ports runs without any additional tools.
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 above).
Any edition (including Express/Community editions) of Microsoft Visual Studio 2008 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.
|
Express |
SDK/Build Tools |
|
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 |
Visual Studio 2022 |
19.37.x.x |
32/64-bit |
Build Tools for Visual Studio 2022 also provides 32/64-bit compilers |
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 2008-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 2008-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, 2017, and 2022 make the shortcuts even clearer by including the full name of the architecture.
The Build Tools for Visual Studio 2015, 2017, and 2022 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.37.32825 for x64 ...
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=x86_64-pc-cygwin --host=i686-pc-windows
for 32-bit, or:
./configure --build=x86_64-pc-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:
dynlink,num,str,threads, and large parts ofunix. -
The replay debugger is partially supported (no reverse execution).
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 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 Cygwin version of flexdll does not work with this port.
-
The standalone mingw toolchain from the MinGW-w64 project (https://www.mingw-w64.org/) is not supported. Please use the version packaged in Cygwin instead.
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=x86_64-pc-cygwin --host=i686-w64-mingw32
for 32-bit, or:
./configure --build=x86_64-pc-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:
dynlink,num,str,threads, and large parts ofunix. -
The replay debugger is partially supported (no reverse execution).
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.
You must extract 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/ocaml/flexdll/releases
-
Cloning the git repository by running:
git clone https://github.com/ocaml/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 normally for the port you require.
make make install
-
make installwill install FlexDLL by placingflexlink.exe(and the default manifest file for the Microsoft port) inbin/and the FlexDLL object files inlib/. -
If you have populated
flexdll/, the build will always use it, ignoring any externally installed FlexDLL. You can override this behaviour by either erasing the contents offlexdll/or passing the--without-flexdlloption toconfigure.
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_MODE environment variable when calling configure.
The default, or a value of compatible, enables the new "Unicode"
mode, while a value of ansi 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.