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.
OCaml requires Windows 8 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 the MSVC port of OCaml, 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).
The OCaml runtime requires C11 atomics, which are available in Visual Studio 2022 (starting from release 17.8). Earlier versions (either of Visual Studio 2022 17.7 and earlier or Visual Studio 2019 and earlier) cannot be used to compile OCaml. In addition to the paid versions of Visual Studio, OCaml can be compiled with either Visual Studio 2022 Community or Build Tools for Visual Studio 2022. The following components are needed (the precise version numbers may differ, but this should not matter):
-
MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest) for compiling with cl
-
C++ Clang Compiler for Windows (16.0.5) for compiling with clang-cl
-
C++/CLI support for v143 build tools (Latest)
-
Windows 11 SDK (10.0.22621.0)
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. The easiest way to access these is via the "Visual Studio 2022" group added to the Start Menu by the installer, for example using the "x64 Native Tools Command Prompt for VS 2022" shortcut.
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.38.33133 for x64 ...
You then need to start Cygwin from this Command Prompt. Assuming you have
installed it to its default location of C:\cygwin64, simply run:
C:\cygwin64\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.
For 64-bit, now run:
./configure --build=x86_64-pc-cygwin --host=x86_64-pc-windows
or, for 32-bit:
./configure --build=x86_64-pc-cygwin --host=i686-pc-windows
If you wish to compile with Clang, add CC=clang-cl.
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.)
For 64-bit, now run:
./configure --build=x86_64-pc-cygwin --host=x86_64-w64-mingw32
or, for 32-bit:
./configure --build=x86_64-pc-cygwin --host=i686-w64-mingw32
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:\cygwin64\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.