anchor.diff:  |=====
   
   [[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
  +(*):: 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.
   
  
positive.code: = Release notes on the Microsoft Windows ports of OCaml =
  :toc: macro
  
  There are no fewer than three ports of OCaml for Microsoft Windows, each
  
negative.code: 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
  http://alain.frisch.fr/flexdll.html. 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.
  
  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.
  
  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
     http://alain.frisch.fr/flexdll.html#download
   * 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
  
  