Skip to content

Latest commit

 

History

History
396 lines (297 loc) · 17.2 KB

README.win32.adoc

File metadata and controls

396 lines (297 loc) · 17.2 KB
Raw

Release notes for the Microsoft Windows ports of OCaml

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 (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 ocamlc -custom

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

The Graphics library

yes

yes

no

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

(**)

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.

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.

Table of Contents

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.

In addition to Cygwin, FlexDLL must also be installed, which is available from https://github.com/alainfrisch/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 Visual Studio 2015 and later, you will need to compile the C objects from source, or build ocaml using the flexdll target.

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 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 (*)

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

Visual Studio 2017

19.10.x.x

32/64-bit
(*)

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. (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. 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 and 2017, you need to use the shortcuts in the "Windows Desktop Command Prompts" (2015) or "VC" (2017) 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 and 2017 make 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 world will fail relatively quickly as it will be unable to link ocamlrun.

Now run:

cp config/m-nt.h byterun/caml/m.h
cp config/s-nt.h byterun/caml/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 to build the system, e.g.

make 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 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. (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.)

Now run:

cp config/m-nt.h byterun/caml/m.h
cp config/s-nt.h byterun/caml/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 to build the system, e.g.

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

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 OCaml distribution. This can be done in one of three ways:

  • Extracting the sources from a tarball from https://github.com/alainfrisch/flexdll/releases

  • 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 flexdll world [bootstrap] opt opt.opt flexlink.opt install

  • You should ignore the error messages that say ocamlopt was not found.

  • 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 don’t include make flexlink.opt, flexlink.exe will be a bytecode program. make 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 flexdll. If you wish to revert to using an externally installed FlexDLL, you must erase the contents of flexdll/ before compiling.

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 variable in config/Makefile. A value of 1 enables the the new "Unicode" mode, while a value of 0 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.