# Working with OCaml Windows (tips)

## Glossary

- [mingw-w64][]: a compiler based on GCC that produces native code running on Windows;
- [Cygwin][]: a POSIX library for Windows and a package manager where packages are either linked to that library or build with mingw-w64;
- [Win32 API][]: the C API of Windows;
- [win32unix][]: the implementation of the [`Unix`][Unix] module on Windows in OCaml;
- [MSVC][]: the C/C++ compiler written by Microsoft.

## Compiler ports

There are three ports of OCaml on Windows:
- the [Cygwin] port (currently broken);
- the mingw-w64 port;
- the msvc port.

Build instructions are in [`README.win32.adoc`][README].

## OCaml distributions

### Upstream opam and ocaml/opam-repository

Upstream opam 2.2 and ocaml/opam-repository will support Windows natively.

### OCaml for Windows / opam-repository-mingw

[opam-repository-mingw][] is a fork of opam and opam/opam-repository with patches to improve support on mingw. Used within a Cygwin environment. It has basic support for MSVC. It is already deprecated, but still maintained, synced with upstream within ~10 days. Quite usable, don't forget to setup the depext and the environment.

### [Diskuv-OCaml][]

I haven't tested it yet, but quite promising.

### WSL

Basically a Linux distribution, not too much interesting if we want to target Windows natively.

## Gotchas

### Setup

- Setting the `$HOME` env var on the Windows side to your Windows user directory helps, because all of Cygwin and Unix tools will look for their config files there instead of in the Cygwin root.
- I use `export BROWSER='cmd.exe /S /C start'` for odoc to work around a [b0 bug][b0-bug].
- `function open() { cmd.exe /S /C start }` :wink:

### Opam

- Filesystem is especially slow; don't count on rebuilding your whole opam switch often and don't create local switches.
- If opam is stuck or crashed, there might be zombie processes still holding files open. Kill the parent shell and restore the install. Opam recovers gracefully.
- Don't try running two opam processes simultaneously.
- Cygwin/Unix tools expect Unix-style file paths with forward slashes. Some Windows tools will accept forward slashes, but not all. Use [`cygpath`][cygpath] to convert between path styles. If you link with `cygwin1.dll`, prefer using forward paths, but if you're targetting native Windows, it makes sense to support the whole set of Windows accepted styles.
- Run `git config --global core.autocrlf false`.
- Shell scripts must have LF (`\n`) line endings. Beware if you have [multiline quoted string literals](https://v2.ocaml.org/manual/lex.html#sss:stringliterals). Put in your `.gitattributes`:

  *.sh text eol=lf
  *.bash text eol=lf

- Dune 3.0 has [some problems][dune-3] on Windows (`dune exec --` incremental compilation is broken).

### OCaml, systems programming

- Contrary to Unix, on Windows opened files cannot be removed, moved, or renamed. The current working directory of a process cannot be removed, moved, or renamed. Any parent director of an opened file cannot be manipulated in the same manner. Beware of this behavior and races.
- It is currently impossible to kill and wait for arbitrary processes from the `Unix` module, only sub-processes. [#11021][].
- Use latest Lwt (>= 5.6.1) and OCaml (>= 4.14) :wink: fixes comming through!
- There are [Reserved DOS devices names](https://en.wikipedia.org/wiki/DOS#Reserved_device_names).
> There are reserved device names in DOS that cannot be used as filenames regardless of extension as they are occupied by built-in character devices.
> + `CON`, for console
> + `AUX`, for auxiliary
> + `PRN`, for printer
> + `NUL`, for null devices; added in 86-DOS 1.10 and PC DOS 1.0.
>
> It is still possible to create files or directories using these reserved device names, such as through direct editing of directory data structures in disk sectors.

…or you can by using Cygwin, but native Windows programs will miserably fail.
- Deleting a file named `NUL` is tricky: [SO][SO-NUL].
- Save yourself from trouble and use [`Fpath`][Fpath] to handle your file paths.
- Files opened in text mode will back and forth from CRLF (`\r\n`) to LF (`\n`) line endings on read and write. This can lead to annoying bugs, especially when calculating the size of a file. Prefer opening files in binary mode.
- Files created within a Cygwin env (shell, programs, …) often have the executable bit set. Think of removing it before commiting the file. Mostly harmless otherwise.
- No fork on Windows, only `CreateProcess`.

### Interfacing with C (writing C stubs)

- OCaml strings are UTF-8, most of Windows APIs in C expect wide-chars strings in UTF-16, don't forget to convert the strings. See [Interfacing with C][intfc].
- Checkout [`unixsupport.h`][unixsupport.h] to raise exceptions from C and handle file descriptors and sockets.
- Use the `_WIN32` macro for conditional compilation.
- mingw-w64 re-implements the Windows API for copyright reasons. Some seldom-used or recent (say, Windows 10) APIs are not available.

### Cross-compilation to Windows

Haven't tested myself, try [opam-cross-windows][] and/or [Dune 3's Cross Compilation][dune-x-compilation].

## Windows niceties

- [winget][], a package manager for Windows, can install all the tools below;
- [PowerToys][], a collection of config switches to make your life easier. I use it to rebind caps lock to ctrl because I use the [best editor][emacs].
- [Clink][], GNU readline shortcuts for Windows cmd;
- Windows Terminal (a better terminal emulator), or WezTerm (has tabs, faster), or alacritty (even faster, but no tabs which is annoying with a stacking WM). Install the Cygwin shell as a profile in your terminal emulator.
- If you use Emacs, try `(require 'cygwin-mount)(cygwin-mount-activate)` with `cygwin-mount.el` package.

## Docker for Windows

Prefer Hyper-V backend and Windows containers to run native Windows code. Set the Docker daemon to use that over WSL2 backend. Then, use `--isolation=hyperv` or `--isolation=process` to switch between Hyper-V (an hypervisor for Virtual Machines) or process-level isolation. Processes are faster to boot, but potentially less secure.

See the [naming scheme][opam-docker-windows] for our Opam Docker images.

docker run -it ocaml/opam:windows-mingw
docker run -it ocaml/opam:windows-msvc

- Beware, typing `ctrl-c` in a running Docker container will exit it right away!
- It's possible to set the number of cpus `--cpus` and the amount of memory `--memory` when running containers, but not when building Docker images.
- The default network is `nat`.
- It's not possible to squash images with `--squash`.
- BuildKit syntax isn't supported.
- There are multiple [Windows base images][microsoft-windows-base-os-images] available; use at least servercore.
- At the beginning of a Dockerfile for Windows, write `` #escape=` ``. The correct escape and line continuation for Windows is not the backslash `\` but the backtick `` ` ``.

[mingw-w64]: https://www.mingw-w64.org/
[Cygwin]: https://www.cygwin.com/
[Win32 API]: https://www.cygwin.com/
[win32unix]: https://github.com/ocaml/ocaml/tree/4.14.0/otherlibs/win32unix
[MSVC]: https://docs.microsoft.com/en-us/cpp/build/reference/compiling-a-c-cpp-program?view=msvc-170
[Unix]: https://docs.microsoft.com/en-us/cpp/build/reference/compiling-a-c-cpp-program?view=msvc-170
[README]: https://github.com/ocaml/ocaml/blob/4.14.0/README.win32.adoc
[opam-repository-mingw]: https://fdopen.github.io/opam-repository-mingw/
[intfc]: https://ocaml.org/manual/intfc.html#s%3Ainterfacing-windows-unicode-apis
[#11021]: https://github.com/ocaml/ocaml/issues/11021
[unixsupport.h]: https://github.com/ocaml/ocaml/blob/4.14.0/otherlibs/win32unix/unixsupport.h
[SO-NUL]: https://stackoverflow.com/questions/17883481/delete-a-file-named-nul-on-windows
[Fpath]: https://erratique.ch/software/fpath
[cygpath]: https://cygwin.com/cygwin-ug-net/cygpath.html
[dune-3]: https://github.com/ocaml/dune/issues?q=is%3Aopen+is%3Aissue+author%3AMisterDA+Dune+3+Windows+
[winget]: https://docs.microsoft.com/fr-fr/windows/package-manager/winget/
[PowerToys]: https://docs.microsoft.com/en-us/windows/powertoys/
[Clink]: https://chrisant996.github.io/clink/
[opam-docker-windows]: https://discuss.ocaml.org/t/ann-ocaml-opam-images-for-docker-for-windows/8179
[microsoft-windows-base-os-images]: https://hub.docker.com/_/microsoft-windows-base-os-images
[emacs]: https://www.gnu.org/software/emacs/
[b0-bug]: https://github.com/b0-system/b0/issues/4#issuecomment-972752060
[Diskuv-OCaml]: https://diskuv.gitlab.io/diskuv-ocaml/
[opam-cross-windows]: https://github.com/ocaml-cross/opam-cross-windows
[dune-x-compilation]: https://dune.readthedocs.io/en/stable/cross-compilation.html