package / ocaml-base-compiler.4.10.0 / README.win32.adoc
1 = Release notes for the Microsoft Windows ports of OCaml =
2 :toc: macro
3
4 There are no fewer than three ports of OCaml for Microsoft Windows, each
5 available 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
11 Here is a summary of the main differences between these ports:
12
13 |=====
14 | | Native Microsoft | Native Mingw-w64 | Cygwin
15 4+^| 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
19 4+^| 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 | Restrictions on generated executables? | none | none | yes <<tb1,(*)>>
25 |=====
26
27 [[tb1]]
28 (*):: Executables generated by the native GCC package in Cygwin are linked with
29 the Cygwin DLL and require this to be distributed with your programs.
30 Executables generated by Microsoft Visual C++ or the Mingw-w64 compilers (even
31 when run in Cygwin as `i686-w64-mingw32-gcc` or `x86_64-w64-mingw32-gcc`) are
32 not linked against this DLL. Prior to Cygwin 2.5.2 (the Cygwin version can be
33 obtained with `uname -r`) the Cygwin DLL is distributed under the GPL, requiring
34 any programs linked with it to be distributed under a compatible licence. Since
35 version 2.5.2, the Cygwin DLL is distributed under the LGPLv3 with a static
36 linking exception meaning that, like executables generated by Microsoft Visual
37 C++ or the Mingw-w64 compilers, generated executables may be distributed under
38 terms of your choosing.
39
40 [[tb2]]
41 (**):: The debugger is supported but the "replay" functions are not enabled.
42 Other functions are available (step, goto, run...).
43
44 Cygwin aims to provide a Unix-like environment on Windows, and the build
45 procedure for it is the same as for other flavours of Unix. See
46 link:INSTALL.adoc[] for full instructions.
47
48 The native ports require Windows XP or later and naturally the 64-bit versions
49 need a 64-bit edition of Windows (note that this is both to run *and* build).
50
51 The two native Windows ports have to be built differently, and the remainder of
52 this document gives more information.
53
54 toc::[]
55
56 == PREREQUISITES
57
58 All the Windows ports require a Unix-like build environment. Although other
59 methods are available, the officially supported environment for doing this is
60 32-bit (x86) Cygwin.
61
62 Only the `make` Cygwin package is required. `diffutils` is required if you wish
63 to be able to run the test suite.
64
65 Unless you are also compiling the Cygwin port of OCaml, you should not install
66 the `gcc-core` or `flexdll` packages. If you do, care may be required to ensure
67 that a particular build is using the correct installation of `flexlink`.
68
69 [[bmflex]]
70 In addition to Cygwin, FlexDLL must also be installed, which is available from
71 https://github.com/alainfrisch/flexdll. A binary distribution is available;
72 instructions on how to build FlexDLL from sources, including how to bootstrap
73 FlexDLL and OCaml are given <<seflexdll,later in this document>>. Unless you
74 bootstrap FlexDLL, you will need to ensure that the directory to which you
75 install FlexDLL is included in your `PATH` environment variable. Note: binary
76 distributions of FlexDLL are compatible only with Visual Studio 2013 and
77 earlier; for Visual Studio 2015 and later, you will need to compile the C
78 objects from source, or build ocaml using the flexdll target.
79
80 The base bytecode system (ocamlc, ocaml, ocamllex, ocamlyacc, ...) of all three
81 ports runs without any additional tools.
82
83 == Microsoft Visual C/C++ Ports
84
85 === REQUIREMENTS
86
87 The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with
88 C code (`ocamlc -custom`) require a Microsoft Visual C/C++ Compiler and the
89 `flexlink` tool (see <<bmflex,above>>).
90
91 Any edition (including Express/Community editions) of Microsoft Visual Studio
92 2005 or later may be used to provide the required Windows headers and the C
93 compiler. Additionally, some older Microsoft Windows SDKs include the
94 Visual C/C++ Compiler as well as the Build Tools for Visual Studio.
95
96 |=====
97 | | `cl` Version | Express | SDK/Build Tools
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 | Build Tools for Visual Studio 2015 also provides 32/64-bit compilers
104 | Visual Studio 2017 | 19.10.x.x | 32/64-bit | Build Tools for Visual Studio 2017 also provides 32/64-bit compilers
105 | Visual Studio 2019 | 19.20.x.x | 32/64-bit | Build Tools for Visual Studio 2019 also provides 32/64-bit compilers
106 |=====
107
108 [[vs1]]
109 (*):: Visual C++ 2005 Express Edition does not provide an assembler; this can be
110 downloaded separately from
111 https://www.microsoft.com/en-gb/download/details.aspx?id=12654
112
113 === COMPILATION FROM THE SOURCES
114
115 The command-line tools must be compiled from the Unix source distribution
116 (`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows.
117 (Note: you should use cygwin's `tar` command to unpack this archive. If you
118 use WinZip, you will need to deselect "TAR file smart CR/LF conversion" in
119 the WinZip Options Window.)
120
121 Microsoft Visual C/C++ is designed to be used from special developer mode
122 Command Prompts which set the environment variables for the required compiler.
123 There are multiple ways of setting up your environment ready for their use. The
124 simplest is to start the appropriate command prompt shortcut from the program
125 group of the compiler you have installed.
126
127 The details differ depending on whether you are using a Windows SDK to provide
128 the compiler or Microsoft Visual Studio itself.
129
130 For the Windows SDK, there is only one command prompt called "CMD Shell" in
131 versions 6.1 and 7.0 and "Windows SDK 7.1 Command Prompt" in version 7.1. This
132 launches a Command Prompt which will usually select a `DEBUG` build environment
133 for the operating system that you are running. You should then run:
134
135 SetEnv /Release /x86
136
137 for 32-bit or:
138
139 SetEnv /Release /x64
140
141 for 64-bit. For Visual Studio 2005-2013, you need to use one of the shortcuts in
142 the "Visual Studio Tools" program group under the main program group for the
143 version of Visual Studio you installed. For Visual Studio 2015 and 2017, you
144 need to use the shortcuts in the "Windows Desktop Command Prompts" (2015) or
145 "VC" (2017) group under the "Visual Studio Tools" group.
146
147 Unlike `SetEnv` for the Windows SDK, the architecture is selected by using a
148 different shortcut, rather than by running a command.
149
150 For Visual Studio 2005-2010, excluding version-specific prefixes, these are
151 named "Command Prompt" for 32-bit and "x64 Cross Tools Command Prompt" or
152 "x64 Win64 Command Prompt" for 64-bit. It does not matter whether you use a
153 "Cross Tools" or "Win64" version for x64, this simply refers to whether the
154 compiler itself is a 32-bit or 64-bit program; both produce 64-bit output and
155 work with OCaml.
156
157 For Visual Studio 2012 and 2013, both x86 and x64 Command Prompt shortcuts
158 indicate if they are the "Native Tools" or "Cross Tools" versions. Visual Studio
159 2015 and 2017 make the shortcuts even clearer by including the full name of the
160 architecture.
161
162 The Build Tools for Visual Studio 2015 and 2017 provide shortcuts similar to
163 the ones of their respective Visual Studio version.
164
165 You cannot at present use a cross-compiler to compile 64-bit OCaml on 32-bit
166 Windows.
167
168 Once you have started a Command Prompt, you can verify that you have the
169 compiler you are expecting simply by running:
170
171 cl
172 Microsoft (R) C/C++ Optimizing Compiler Version 19.00.23506 for x86
173 ...
174
175 You then need to start Cygwin from this Command Prompt. Assuming you have
176 installed it to its default location of `C:\cygwin`, simply run:
177
178 C:\cygwin\bin\mintty -
179
180 (note the space and hyphen at the end of the command).
181
182 This should open a terminal window and start bash. You should be able to run
183 `cl` from this. You can now change to the top-level directory of the directory
184 of the OCaml distribution.
185
186 The Microsoft Linker is provided by a command called `link` which unfortunately
187 conflicts with a Cygwin command of the same name. It is therefore necessary to
188 ensure that the directory containing the Microsoft C/C++ Compiler appears at
189 the beginning of `PATH`, before Cygwin's `/usr/bin`. You can automate this from
190 the top-level of the OCaml distribution by running:
191
192 eval $(tools/msvs-promote-path)
193
194 If you forget to do this, `make` will fail relatively
195 quickly as it will be unable to link `ocamlrun`.
196
197 Now run:
198
199 ./configure --build=i686-pc-cygwin --host=i686-pc-windows
200
201 for 32-bit, or:
202
203 ./configure --build=x86_64-unknown-cygwin --host=x86_64-pc-windows
204
205 for 64-bit.
206
207 Finally, use `make` to build the system, e.g.
208
209 make
210 make install
211
212 After installing, it is not necessary to keep the Cygwin installation (although
213 you may require it to build additional third party libraries and tools). You
214 will need to use `ocamlopt` (or `ocamlc -custom`) from the same Visual Studio or
215 Windows SDK Command Prompt as you compiled OCaml from, or `ocamlopt` will not
216 be able to find `cl`.
217
218 If you wish to use `ocamlopt` from Cygwin's bash on a regular basis, you may
219 like to copy the `tools/msvs-promote-path` script and add the `eval` line to
220 your `~/.bashrc` file.
221
222 * The Microsoft Visual C/C++ compiler does not implement "computed gotos", and
223 therefore generates inefficient code for `runtime/interp.c`. Consequently,
224 the performance of bytecode programs is about 2/3 of that obtained under
225 Unix/GCC, Cygwin or Mingw-w64 on similar hardware.
226
227 * Libraries available in this port: `bigarray`, `dynlink`, `num`,
228 `str`, `threads`, and large parts of `unix`.
229
230 * The replay debugger is partially supported (no reverse execution).
231
232 === CREDITS
233
234 The initial port of Caml Special Light (the ancestor of OCaml) to Windows NT
235 was done by Kevin Gallo at Microsoft Research, who kindly contributed his
236 changes to the OCaml project.
237
238 == Mingw-w64 Ports
239
240 === REQUIREMENTS
241
242 The native-code compiler (`ocamlopt`) and static linking of OCaml bytecode with
243 C code (`ocamlc -custom`) require the appropriate Mingw-w64 gcc and the
244 `flexlink` tool (see <<bmflex,above>>). Mingw-w64 gcc is provided by the
245 `mingw64-i686-gcc-core` package for 32-bit and the `mingw64-x86_64-gcc-core`
246 package for 64-bit.
247
248 - Do not try to use the Cygwin version of flexdll for this port.
249
250 - The standalone mingw toolchain from the Mingw-w64 project
251 (http://mingw-w64.org/) is not supported. Please use the version packaged in
252 Cygwin instead.
253
254 === COMPILATION FROM THE SOURCES
255
256 The command-line tools must be compiled from the Unix source distribution
257 (`ocaml-X.YY.Z.tar.gz`), which also contains the files modified for Windows.
258 (Note: you should use cygwin's `tar` command to unpack this archive. If you
259 use WinZip, you will need to deselect "TAR file smart CR/LF conversion" in
260 the WinZip Options Window.)
261
262 Now run:
263
264 ./configure --build=i686-pc-cygwin --host=i686-w64-mingw32
265
266 for 32-bit, or:
267
268 ./configure --build=x86_64-unknown-cygwin --host=x86_64-w64-mingw32
269
270 for 64-bit.
271
272 Finally, use `make` to build the system, e.g.
273
274 make
275 make install
276
277 After installing, you will need to ensure that `ocamlopt` (or `ocamlc -custom`)
278 can access the C compiler. You can do this either by using OCaml from Cygwin's
279 bash or by adding Cygwin's bin directory (e.g. `C:\cygwin\bin`) to your `PATH`.
280
281 * Libraries available in this port: `bigarray`, `dynlink`, `num`,
282 `str`, `threads`, and large parts of `unix`.
283
284 * The replay debugger is partially supported (no reverse execution).
285
286 [[seflexdll]]
287 == FlexDLL
288 Although the core of FlexDLL is necessarily written in C, the `flexlink` program
289 is, naturally, written in OCaml. This creates a circular dependency if you wish
290 to build entirely from sources. Since OCaml 4.03 and FlexDLL 0.35, it is now
291 possible to bootstrap the two programs simultaneously. The process is identical
292 for both ports. If you choose to compile this way, it is not necessary to
293 install FlexDLL separately -- indeed, if you do install FlexDLL separately, you
294 may need to be careful to ensure that `ocamlopt` picks up the correct `flexlink`
295 in your `PATH`.
296
297 You must place the FlexDLL sources for Version 0.35 or later in the directory
298 `flexdll/` at the top-level directory of the OCaml distribution. This can be
299 done in one of three ways:
300
301 * Extracting the sources from a tarball from
302 https://github.com/alainfrisch/flexdll/releases
303 * Cloning the git repository by running:
304 +
305 git clone https://github.com/alainfrisch/flexdll.git
306
307 * If you are compiling from a git clone of the OCaml repository, instead of
308 using a sources tarball, you can run:
309 +
310 git submodule update --init
311
312 OCaml is then compiled as normal for the port you require, except that before
313 building the compiler itself, you must compile `flexdll`, i.e.:
314
315 make flexdll
316 make
317 make flexlink.opt
318 make install
319
320 * You should ignore the error messages that say ocamlopt was not found.
321 * `make install` will install FlexDLL by placing `flexlink.exe`
322 (and the default manifest file for the Microsoft port) in `bin/` and the
323 FlexDLL object files in `lib/`.
324 * If you don't include `make flexlink.opt`, `flexlink.exe` will be a
325 bytecode program. `make install` always installs the "best"
326 `flexlink.exe` (i.e. there is never a `flexlink.opt.exe` installed).
327 * If you have populated `flexdll/`, you *must* run
328 `make flexdll`. If you wish to revert to using an externally
329 installed FlexDLL, you must erase the contents of `flexdll/` before
330 compiling.
331
332 == Unicode support
333
334 Prior to version 4.06, all filenames on the OCaml side were assumed
335 to be encoded using the current 8-bit code page of the system. Some
336 Unicode filenames could thus not be represented. Since version 4.06,
337 OCaml adds to this legacy mode a new "Unicode" mode, where filenames
338 are UTF-8 encoded strings. In addition to filenames,
339 this applies to environment variables and command-line arguments.
340
341 The mode must be decided before building the system, by tweaking
342 the `WINDOWS_UNICODE` variable in `Makefile.config`. A value of 1
343 enables the the new "Unicode" mode, while a value of 0 maintains
344 the legacy mode.
345
346 Technically, both modes use the Windows "wide" API, where filenames
347 and other strings are made of 16-bit entities, usually interpreted as
348 UTF-16 encoded strings.
349
350 Some more details about the two modes:
351
352 * Unicode mode: OCaml strings are interpreted as being UTF-8 encoded
353 and translated to UTF-16 when calling Windows; strings returned by
354 Windows are interpreted as UTF-16 and translated to UTF-8 on their
355 way back to OCaml. Additionally, an OCaml string which is not
356 valid UTF-8 will be interpreted as being in the current 8-bit code
357 page. This fallback works well in practice, since the chances of
358 non-ASCII string encoded in the a 8-bit code page to be a valid
359 UTF-8 string are tiny. This means that filenames
360 obtained from e.g. a 8-bit UI or database layer would continue to
361 work fine. Application written for the legacy mode or older
362 versions of OCaml might still break if strings returned by
363 Windows (e.g. for `Sys.readdir`) are sent to components expecting
364 strings encoded in the current code page.
365
366 * Legacy mode: this mode emulates closely the behavior of OCaml <
367 4.06 and is thus the safest choice in terms of backward
368 compatibility. In this mode, OCaml programs can only work with
369 filenames that can be encoded in the current code page, and the
370 same applies to ocaml tools themselves (ocamlc, ocamlopt, etc).
371
372 The legacy mode will be deprecated and then removed in future versions
373 of OCaml. Users are thus strongly encouraged to use the Unicode mode
374 and adapt their existing code bases accordingly.
375
376 Note: in order for ocaml tools to support Unicode pathnames, it is
377 necessary to use a version of FlexDLL which has itself been compiled
378 with OCaml >= 4.06 in Unicode mode. This is the case for binary distributions
379 of FlexDLL starting from version 0.37 and above.
380
381 == Trademarks
382
383 Microsoft, Visual C++, Visual Studio and Windows are registered trademarks of
384 Microsoft Corporation in the United States and/or other countries.
385