= 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 (https://www.cygwin.com[https://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 {cpp} 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
xref: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.

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
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.

[[bmflex]]
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 <<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 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.

== 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>>).

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)


=== 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.
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:

[source,console]
----
> 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:

[source,bat]
----
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:

[source,sh]
----
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:

[source,sh]
----
./configure --build=x86_64-pc-cygwin --host=x86_64-pc-windows
----

or, for 32-bit:

[source,sh]
----
./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.

[source,sh]
----
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" (also
  known as "labels as values"), and therefore generates inefficient code for the
  bytecode interpreter in `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. The clang-cl compiler supports the "computed
  gotos" extension.

* Libraries available in this port: `dynlink`, `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.

  - 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.

=== 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.)

For 64-bit, now run:

[source,sh]
----
./configure --build=x86_64-pc-cygwin --host=x86_64-w64-mingw32
----

or, for 32-bit:

[source,sh]
----
./configure --build=x86_64-pc-cygwin --host=i686-w64-mingw32
----

Finally, use `make` to build the system, e.g.

[source,sh]
----
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`, `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.

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:
+
[source,sh]
----
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:
+
[source,sh]
----
git submodule update --init
----

OCaml is then compiled normally for the port you require.

[source,sh]
----
make
make install
----

 * `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 have populated `flexdll/`, the build will always use it, ignoring
   any externally installed FlexDLL. You can override this behaviour by either
   erasing the contents of `flexdll/` or passing the `--without-flexdll` option
   to `configure`.

== 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_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.

== Trademarks

Microsoft, Visual C++, Visual Studio and Windows are registered trademarks of
Microsoft Corporation in the United States and/or other countries.