1= Release notes for the Microsoft Windows ports of OCaml = 2:toc: macro 3 4There are no fewer than three ports of OCaml for Microsoft Windows, each 5available in 32 and 64-bit versions: 6 7 - native Windows, built with the Microsoft C/C++ Optimizing Compiler 8 - native Windows, built using the Mingw-w64 version of GCC 9 - Cygwin (http://www.cygwin.com[www.cygwin.com]) 10 11Here is a summary of the main differences between these ports: 12 13|===== 14| | Native Microsoft | Native Mingw-w64 | Cygwin 154+^| Third-party software required 16| for base bytecode system | none | none | none 17| for `ocamlc -custom` | Microsoft Visual C++ | Cygwin | Cygwin 18| for native-code generation | Microsoft Visual C++ | Cygwin | Cygwin 194+^| Features 20| Speed of bytecode interpreter | 70% | 100% | 100% 21| Replay debugger | yes <<tb2,(**)>> | yes <<tb2,(**)>> | yes 22| The Unix library | partial | partial | full 23| The Threads library | yes | yes | yes 24| The Graphics library | yes | yes | no 25| Restrictions on generated executables? | none | none | yes <<tb1,(*)>> 26|===== 27 28[[tb1]] 29(*):: Executables generated by the native GCC package in Cygwin are linked with 30the Cygwin DLL and require this to be distributed with your programs. 31Executables generated by Microsoft Visual C++ or the Mingw-w64 compilers (even 32when run in Cygwin as `i686-w64-mingw32-gcc` or `x86_64-w64-mingw32-gcc`) are 33not linked against this DLL. Prior to Cygwin 2.5.2 (the Cygwin version can be 34obtained with `uname -r`) the Cygwin DLL is distributed under the GPL, requiring 35any programs linked with it to be distributed under a compatible licence. Since 36version 2.5.2, the Cygwin DLL is distributed under the LGPLv3 with a static 37linking exception meaning that, like executables generated by Microsoft Visual 38C++ or the Mingw-w64 compilers, generated executables may be distributed under 39terms of your choosing. 40 41[[tb2]] 42(**):: The debugger is supported but the "replay" functions are not enabled. 43Other functions are available (step, goto, run...). 44 45Cygwin aims to provide a Unix-like environment on Windows, and the build 46procedure for it is the same as for other flavours of Unix. See 47link:INSTALL.adoc[] for full instructions. 48 49The native ports require Windows XP or later and naturally the 64-bit versions 50need a 64-bit edition of Windows (note that this is both to run *and* build). 51 52The two native Windows ports have to be built differently, and the remainder of 53this document gives more information. 54 55toc::[] 56 57== PREREQUISITES 58 59All the Windows ports require a Unix-like build environment. Although other 60methods are available, the officially supported environment for doing this is 6132-bit (x86) Cygwin. 62 63Only the `make` Cygwin package is required. `diffutils` is required if you wish 64to be able to run the test suite. 65 66Unless you are also compiling the Cygwin port of OCaml, you should not install 67the `gcc-core` or `flexdll` packages. If you do, care may be required to ensure 68that a particular build is using the correct installation of `flexlink`. 69 70[[bmflex]] 71In addition to Cygwin, FlexDLL must also be installed, which is available from 72https://github.com/alainfrisch/flexdll. A binary distribution is available; 73instructions on how to build FlexDLL from sources, including how to bootstrap 74FlexDLL and OCaml are given <<seflexdll,later in this document>>. Unless you 75bootstrap FlexDLL, you will need to ensure that the directory to which you 76install FlexDLL is included in your `PATH` environment variable. Note: if you 77use Visual Studio 2015 or Visual Studio 2017, the binary distribution of 78FlexDLL will not work and you must build it from sources. 79 80The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...) of all three 81ports runs without any additional tools. 82 83== Microsoft Visual C/C++ Ports 84 85=== REQUIREMENTS 86 87The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with 88C code (`ocamlc -custom`) require a Microsoft Visual C/C++ Compiler and the 89`flexlink` tool (see <<bmflex,above>>). 90 91Any edition (including Express/Community editions) of Microsoft Visual Studio 922005 or later may be used to provide the required Windows headers and the C 93compiler. Additionally, some older Microsoft Windows SDKs include the 94Visual C/C++ Compiler. 95 96|===== 97| | `cl` Version | Express | SDK 98| Visual Studio 2005 | 14.00.x.x | 32-bit only <<vs1,(*)>> | 99| Visual Studio 2008 | 15.00.x.x | 32-bit only | Windows SDK 7.0 also provides 32/64-bit compilers 100| Visual Studio 2010 | 16.00.x.x | 32-bit only | Windows SDK 7.1 also provides 32/64-bit compilers 101| Visual Studio 2012 | 17.00.x.x | 32/64-bit | 102| Visual Studio 2013 | 18.00.x.x | 32/64-bit | 103| Visual Studio 2015 | 19.00.x.x | 32/64-bit | 104| Visual Studio 2017 | 19.10.x.x | 32/64-bit | 105|===== 106 107[[vs1]] 108(*):: Visual C++ 2005 Express Edition does not provide an assembler; this can be 109 downloaded separately from 110 https://www.microsoft.com/en-gb/download/details.aspx?id=12654 111 112=== COMPILATION FROM THE SOURCES 113 114The command-line tools must be compiled from the Unix source distribution 115(`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows. 116(Note: you should use cygwin's `tar` command to unpack this archive. If you 117use WinZip, you will need to deselect "TAR file smart CR/LF conversion" in 118the WinZip Options Window.) 119 120Microsoft Visual C/C++ is designed to be used from special developer mode 121Command Prompts which set the environment variables for the required compiler. 122There are multiple ways of setting up your environment ready for their use. The 123simplest is to start the appropriate command prompt shortcut from the program 124group of the compiler you have installed. 125 126The details differ depending on whether you are using a Windows SDK to provide 127the compiler or Microsoft Visual Studio itself. 128 129For the Windows SDK, there is only one command prompt called "CMD Shell" in 130versions 6.1 and 7.0 and "Windows SDK 7.1 Command Prompt" in version 7.1. This 131launches a Command Prompt which will usually select a `DEBUG` build environment 132for the operating system that you are running. You should then run: 133 134 SetEnv /Release /x86 135 136for 32-bit or: 137 138 SetEnv /Release /x64 139 140for 64-bit. For Visual Studio 2005-2013, you need to use one of the shortcuts in 141the "Visual Studio Tools" program group under the main program group for the 142version of Visual Studio you installed. For Visual Studio 2015 and 2017, you 143need to use the shortcuts in the "Windows Desktop Command Prompts" (2015) or 144"VC" (2017) group under the "Visual Studio Tools" group. 145 146Unlike `SetEnv` for the Windows SDK, the architecture is selected by using a 147different shortcut, rather than by running a command. 148 149For Visual Studio 2005-2010, excluding version-specific prefixes, these are 150named "Command Prompt" for 32-bit and "x64 Cross Tools Command Prompt" or 151"x64 Win64 Command Prompt" for 64-bit. It does not matter whether you use a 152"Cross Tools" or "Win64" version for x64, this simply refers to whether the 153compiler itself is a 32-bit or 64-bit program; both produce 64-bit output and 154work with OCaml. 155 156For Visual Studio 2012 and 2013, both x86 and x64 Command Prompt shortcuts 157indicate if they are the "Native Tools" or "Cross Tools" versions. Visual Studio 1582015 and 2017 make the shortcuts even clearer by including the full name of the 159architecture. 160 161You cannot at present use a cross-compiler to compile 64-bit OCaml on 32-bit 162Windows. 163 164Once you have started a Command Prompt, you can verify that you have the 165compiler you are expecting simply by running: 166 167 cl 168 Microsoft (R) C/C++ Optimizing Compiler Version 19.00.23506 for x86 169 ... 170 171You then need to start Cygwin from this Command Prompt. Assuming you have 172installed it to its default location of `C:\cygwin`, simply run: 173 174 C:\cygwin\bin\mintty - 175 176(note the space and hyphen at the end of the command). 177 178This should open a terminal window and start bash. You should be able to run 179`cl` from this. You can now change to the top-level directory of the directory 180of the OCaml distribution. 181 182The Microsoft Linker is provided by a command called `link` which unfortunately 183conflicts with a Cygwin command of the same name. It is therefore necessary to 184ensure that the directory containing the Microsoft C/C++ Compiler appears at 185the beginning of `PATH`, before Cygwin's `/usr/bin`. You can automate this from 186the top-level of the OCaml distribution by running: 187 188 eval $(tools/msvs-promote-path) 189 190If you forget to do this, `make world` will fail relatively 191quickly as it will be unable to link `ocamlrun`. 192 193Now run: 194 195 cp config/m-nt.h config/m.h 196 cp config/s-nt.h config/s.h 197 198followed by: 199 200 cp config/Makefile.msvc config/Makefile 201 202for 32-bit, or: 203 204 cp config/Makefile.msvc64 config/Makefile 205 206for 64-bit. Then, edit `config/Makefile` as needed, following the comments in 207this file. Normally, the only variable that needs to be changed is `PREFIX`, 208which indicates where to install everything. 209 210Finally, use `make` to build the system, e.g. 211 212 make world bootstrap opt opt.opt install 213 214After installing, it is not necessary to keep the Cygwin installation (although 215you may require it to build additional third party libraries and tools). You 216will need to use `ocamlopt` (or `ocamlc -custom`) from the same Visual Studio or 217Windows SDK Command Prompt as you compiled OCaml from, or `ocamlopt` will not 218be able to find `cl`. 219 220If you wish to use `ocamlopt` from Cygwin's bash on a regular basis, you may 221like to copy the `tools/msvs-promote-path` script and add the `eval` line to 222your `~/.bashrc` file. 223 224* The Microsoft Visual C/C++ compiler does not implement "computed gotos", and 225 therefore generates inefficient code for `byterun/interp.c`. Consequently, 226 the performance of bytecode programs is about 2/3 of that obtained under 227 Unix/GCC, Cygwin or Mingw-w64 on similar hardware. 228 229* Libraries available in this port: `bigarray`, `dynlink`, `graphics`, `num`, 230 `str`, `threads`, and large parts of `unix`. 231 232* The replay debugger is partially supported (no reverse execution). 233 234=== CREDITS 235 236The initial port of Caml Special Light (the ancestor of OCaml) to Windows NT 237was done by Kevin Gallo at Microsoft Research, who kindly contributed his 238changes to the OCaml project. 239 240== Mingw-w64 Ports 241 242=== REQUIREMENTS 243 244The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with 245C code (`ocamlc -custom`) require the appropriate Mingw-w64 gcc and the 246`flexlink` tool (see <<bmflex,above>>). Mingw-w64 gcc is provided by the 247`mingw64-i686-gcc-core` package for 32-bit and the `mingw64-x86_64-gcc-core` 248package for 64-bit. 249 250 - Do not try to use the Cygwin version of flexdll for this port. 251 252 - The standalone mingw toolchain from the Mingw-w64 project 253 (http://mingw-w64.org/) is not supported. Please use the version packaged in 254 Cygwin instead. 255 256=== COMPILATION FROM THE SOURCES 257 258The command-line tools must be compiled from the Unix source distribution 259(`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows. 260(Note: you should use cygwin's `tar` command to unpack this archive. If you 261use WinZip, you will need to deselect "TAR file smart CR/LF conversion" in 262the WinZip Options Window.) 263 264Now run: 265 266 cp config/m-nt.h config/m.h 267 cp config/s-nt.h config/s.h 268 269followed by: 270 271 cp config/Makefile.mingw config/Makefile 272 273for 32-bit, or: 274 275 cp config/Makefile.mingw64 config/Makefile 276 277for 64-bit. Then, edit `config/Makefile` as needed, following the comments in 278this file. Normally, the only variable that needs to be changed is `PREFIX`, 279which indicates where to install everything. 280 281Finally, use `make` to build the system, e.g. 282 283 make world bootstrap opt opt.opt install 284 285After installing, you will need to ensure that `ocamlopt` (or `ocamlc -custom`) 286can access the C compiler. You can do this either by using OCaml from Cygwin's 287bash or by adding Cygwin's bin directory (e.g. `C:\cygwin\bin`) to your `PATH`. 288 289* Libraries available in this port: `bigarray`, `dynlink`, `graphics`, `num`, 290 `str`, `threads`, and large parts of `unix`. 291 292* The replay debugger is partially supported (no reverse execution). 293 294* The default `config/Makefile.mingw` and `config/Makefile.mingw64` pass 295 `-static-libgcc` to the linker. For more information on this topic: 296 297 - http://gcc.gnu.org/onlinedocs/gcc-4.9.1/gcc/Link-Options.html#Link-Options 298 - http://caml.inria.fr/mantis/view.php?id=6411 299 300[[seflexdll]] 301== FlexDLL 302Although the core of FlexDLL is necessarily written in C, the `flexlink` program 303is, naturally, written in OCaml. This creates a circular dependency if you wish 304to build entirely from sources. Since OCaml 4.03 and FlexDLL 0.35, it is now 305possible to bootstrap the two programs simultaneously. The process is identical 306for both ports. If you choose to compile this way, it is not necessary to 307install FlexDLL separately -- indeed, if you do install FlexDLL separately, you 308may need to be careful to ensure that `ocamlopt` picks up the correct `flexlink` 309in your `PATH`. 310 311You must place the FlexDLL sources for Version 0.35 or later in the directory 312`flexdll/` at the top-level directory of the OCaml distribution. This can be 313done in one of three ways: 314 315 * Extracting the sources from a tarball from 316 https://github.com/alainfrisch/flexdll/releases 317 * Cloning the git repository by running: 318+ 319 git clone https://github.com/alainfrisch/flexdll.git 320 321 * If you are compiling from a git clone of the OCaml repository, instead of 322 using a sources tarball, you can run: 323+ 324 git submodule update --init 325 326OCaml is then compiled as normal for the port you require, except that before 327compiling `world`, you must compile `flexdll`, i.e.: 328 329 make flexdll world [bootstrap] opt opt.opt install 330 331 * `make install` will install FlexDLL by placing `flexlink.exe` 332 (and the default manifest file for the Microsoft port) in `bin/` and the 333 FlexDLL object files in `lib/`. 334 * If you don't include `make opt.opt`, `flexlink.exe` will be a 335 bytecode program. `make install` always installs the "best" 336 `flexlink.exe` (i.e. there is never a `flexlink.opt.exe` installed). 337 * If you have populated `flexdll/`, you *must* run 338 `make flexdll`. If you wish to revert to using an externally 339 installed FlexDLL, you must erase the contents of `flexdll/` before 340 compiling. 341 342== Trademarks 343 344Microsoft, Visual C++, Visual Studio and Windows are registered trademarks of 345Microsoft Corporation in the United States and/or other countries. 346