[ANN] Windows-friendly OCaml 4.12 distribution - Diskuv OCaml 0.1.0

The 0.2.x release is not yet available but I wanted to give an early heads-up on upcoming breaking changes.

0.2.x Upcoming Breaking Changes

1) (Major) Changed Opam root from $env:USERPROFILE/.opam to $env:LOCALAPPDATA/opam

Why? The new Opam root will be the standard in a future release of Opam. That Opam root should work even if you are on a managed Windows machine (especially corporate/enterprise installations). One of the aims of Diskuv OCaml is to be standards compliant as much as possible, which means less hassle for you if you use another Windows distribution in the future.

Consequences: During the upgrade (instructions will be given in the upcoming 0.2.x announcement) you will be prompted to accept the deletion of the old Opam root and your old Opam switches. If you have adopted the Local Project directory structure (ex. diskuv-ocaml-starter) then ./makeit prepare-dev will recreate the Opam root and your Opam switch correctly based on your .opam files. If you have been creating Opam switches manually (which is not currently recommended because the Diskuv OCaml pinned package versions will be missing) you will use opam install ./xxx.opam --deps-only --with-test to re-install the packages in your new Opam switches.

Thanks to @dra27 for extensively reviewing Opam changes for Windows MSVC+MSYS2!

2) (Minor) Changed make.cmd script to makeit.cmd

Why? If you are an OCaml package maintainer and are creating documentation for your users, it would be nice if you had the same copy-and-paste documentation for both Windows and *nix (Linux/macOS). With this rename your user instructions can be ./makeit build-dev to build your project regardless of whether your users are on Windows or *nix; that syntax works in Powershell where makeit.cmd will be invoked and it works in *nix where the shell script makeit will be invoked. There will be an example of that in diskuv-ocaml-starter in the upcoming announcement.
(An alternative could have been typing ./make but that may be confused with make)

Consequences: You’ll need to rename your make.cmd script.


What is the win over using esy here? Esy has solved a lot of these issues on Windows and works very well in my experience.

Not trying to downplay the huge effort here, I’m genuinely curious about the tradeoffs of choosing one tool over the other.


@ulrikstrid (Simplification alert) Esy gives access to the Javascript ecosystem. Diskuv OCaml (DKML) gives access to the C ecosystem. C and Javascript are complementary, so in my categories of thought DKML and Esy are complementary as well.

I think the support for Windows is incidental in both DKML and Esy, mostly because both currently depend on fdopen’s MinGW repository for Windows support.

Since DKML is so new, I’ll explain how DKML gives access to the C ecosystem:

  1. Generally it is a bad idea to link GCC-compiled libraries with MSVC-compiled libraries in the same executable. Most of the Windows effort in DKML is getting OCaml packages to compile with MSVC because MSVC is often the only “supported” choice for third-party C libraries on Windows.
  2. The next release of DKML will bundle vcpkg which is currently the most popular C package manager. Vcpkg has packaged 1348 well-maintained, officially supported C libraries that work equally (*) on Windows, Linux and OS/X. There is also community supported platforms like Android and some of the embedded space.
  3. I’ve been getting help from @fdopen / @nojb / @yallop to get a MSVC port of ocaml-ctypes: Library for binding to C libraries using pure OCaml integrated. The combination of vcpkg + ctypes gives an uncomplicated escape hatch for myself and other people who want to base their software on OCaml but also want to be de-risked from the current small size of the OCaml ecosystem.
  4. OCaml already has great support for the C language (ctypes is one example of this), so it is counterproductive for DKML to change standards like Dune and Opam. My last post was an example of the standards adherence you can expect in the future.

In conclusion I’d say that Esy and DKML both provide escape hatches to the bigger Javascript and C ecosystems, and both provide an on-ramp for new users familiar with Javascript and C to come into the OCaml fold. It really boils down to whether your needs revolve around Javascript+OCaml, C+OCaml or pure OCaml.

Hope that helps. Apologies for the verbosity.

(*) Eventually I’d like to see vcpkg treated as an Opam depexts package manager for Windows. Since packages from Debian, homebrew, et cetera are almost always C-based packages, those same packages can usually be found on vcpkg. The benefits should flow to Esy users as well.


Quick question, as Diskuv OCaml is distributed under the Fair Source License, if a teacher were to tell a bunch of students to use it for coursework, would that fall under ‘personal use’ for each of them? Or would they be considered part of an ‘organization’?


Definitely personal use. I’m make sure that is explicit somewhere.


Nice, well done. I’ve wanted that for quite some time, but never managed to look into it. Can’t wait to try it


I made it explicit on the README.md of diskuv / diskuv-ocaml. But I just realized I missed perhaps half of your question; which section do teachers and professors fall under? Those teachers and professors, most of whom are employees of a school, are clearly members of an “organization” that uses DKML and they would not have the personal grant. But it would still be free unless more than 5 teachers were teaching OCaml at the same time in the same school. I think “5” is a reasonable line for now, but your question is clarifying that supporting a single teacher with 50 students is a very different proposition than supporting a single office employee. So thanks for raising the question. And if you know of or have a situation where that line looks unreasonable, just ping me.

1 Like

Thank you for doing this work – it’s the first time we’re seeing full, native integration of OCaml into Windows. I wanted to ask you: is there a path forward that reduces the setup time and requirements? I understand the need to install the VSC compiler. Building everything, however, seems wasteful. Can we just download the binaries?

This thread was about version 0.1.x, and there have been major changes in 0.2.x and 0.3.x that address that. (Each major release had its own discuss.ocaml thread. In hindsight that was a mistake. More on that later)

In particular 0.2.6 introduced a binary release: [ANN] Windows-friendly OCaml 4.12 distribution 2nd preview release (0.2.0) - #6 by jbeckford . But the simple summary is there are some really important binaries that will fail on the end-user’s machine since they are compiled with hardcoded absolute paths:

  1. ocamlc -config has hardcoded paths. If you were to move an OCaml compiler to a different directory, anyone calling ocamlc -config (Dune, etc.) would break.
  2. I think ocamlfind and ocamlbuild have hardcoded paths, and there are others I’ve stumbled across.

On Linux desktops it is OK to hardcode paths because almost all Linux desktop users have sudo to install to standardized /usr/bin and /usr/lib locations. Similar situation exists for macOS desktop users. But many Windows desktop users do not have Administrator rights, and software must be installed in an arbitrary path like D:\Users\Student1234.

Until hardcoded paths disappear, the safest and simplest way is to compile the correct hardcoded path into the binaries at install time. There is an alternative that Esy uses: binary patching. For many people binary patching would be okay, but software distributed under the “Diskuv” umbrella needs to be reproducible + auditable.

Status of the various binaries:

  • Opam is relocatable (it doesn’t seem to have hardcoded paths). And Opam in particular has a time-consuming compilation process. So today if you use the Diskuv OCaml installer the opam.exe is downloaded as a binary asset.
  • Dune is relocatable. It is not downloaded today as a binary asset because it compiles so quickly … downloading it is premature optimization.
  • Work is being done (not by me!) to make ocamlc relocatable. When that is complete, the compiling step for ocamlc will disappear from the installer.
  • No one, to my knowledge, is working on making other binaries relocatable.

Will keep using this thread going forward

For reference the other threads were:

0.2.x: [ANN] Windows-friendly OCaml 4.12 distribution 2nd preview release (0.2.0)

0.3.x: [ANN] New release of Windows DKML with system compiler and easy Opam switch creation

The upcoming 0.4.x (which introduces a single setup.exe installer) will be announced in this thread.


Thank you for the comprehensive answer, and great job on this project. This is one of the biggest hurdles towards making OCaml more mainstream IMO.
Also sorry for missing the other threads – you might want to take the version out of the title of the thread if you’ll keep using this one (which I think is a good idea).

So assuming ocamlc becomes relocatable, what are the other things that are compiled? Just ocamlfind and ocamlbuild? I imagine they don’t take much time either.

A single setup-*.exe executable is now all that is necessary to install the Diskuv OCaml distribution on 64-bit Windows!

Today you can use a prerelease of v0.4.0 which is available at https://github.com/diskuv/dkml-installer-ocaml/releases/download/v0.4.0-prerel11/setup-diskuv-ocaml-windows_x86_64-0.4.0.exe

The prerelease:

  • is for experienced Windows users only because the prerelease is not signed! You will have to fight with your browser, operating system and anti-virus software to run the setup executable
  • is not reproducible. Because many Diskuv packages have not yet made it into Opam, the builds need several opam pins of unstable branches.
  • has not been incorporated into the https://diskuv.gitlab.io/diskuv-ocaml documentation site. But the Beyond Basics documentation should still be accurate.

Once those items above are addressed, a real (non-prerelease) 0.4.0 will be announced.

Existing Diskuv OCaml users: Your existing Opam switches should be unaffected by the upgrade. But please make sure you can recreate your Opam switches (ie. use a .opam file) if something goes wrong.

Release notes, including details of the migration to the Apache 2.0 license, are at available at https://github.com/diskuv/dkml-installer-ocaml/releases/tag/v0.4.0-prerel11


suceeded by way of ‘Run by Administrator’;; :sweat_smile:

1 Like

The 0.4.0 release of Diskuv OCaml for Windows users is available! It is usable enough that I’ve let my school-age kids (elementary through high school) install it and go through some tutorials.

The links to the documentation are available from the above link as well.

Here are the one-time inconveniences if you install this release:

  1. The built-in antivirus Windows Defender treats newly signed binaries like spam. There needs to be enough people who “Report this file as safe” before the binaries are trusted. If you do nothing but mark it safe or install it on Windows, you are helping others!
  2. The installer will automatically install the Visual Studio compiler if needed. But Visual Studio sometimes requires a reboot. The instructions will tell you if you need the reboot.
  3. The Visual Studio Code OCaml plugin defaults to expecting a legacy ocamlenv program on Windows. You have to search for ocamlenv in Visual Studio Code Settings and disable it. This should have a fix, but not in time for this release.

Windows parity with Unix

  1. opam commands like opam install should work without any wrappers. But
    you should create new switches with opam dkml init (see --help for options).

  2. dune commands like dune build should work without any wrappers. The only
    hiccup is that aliases like dune build @runtest need to be escaped in
    PowerShell like:

    dune build `@runtest
  3. You have partial support if your home directory has spaces, since it is very common on Windows to have your username be FirstName LastName. So far I’ve configured/patched most things to work with spaces, but there could be common packages that were missed, and only NTFS drives work.

  4. OCaml 4.12.1. I’d like to upgrade to 4.13 or 4.14, but having support for Visual Studio Code debugging with 4.12-only ocamlearlybird is more important, especially for traditional Windows users.

  5. Dune 2.9.3. I’ve bundled in support in 2.9.3 for fswatch/inotify so that dune build --watch works on Windows. Nothing is blocking an upgrade to 3.x except time (ie. not now) and a reason.

  6. Opam 2.1.2 plus some PRs that are pending the not-yet-released version 2.2.

  7. Git performance on Windows just sucks. It is like someone designed it for a Linux kernel :face_with_raised_eyebrow:. Apparently Git FSMonitor in 2.37.0 can be enabled to speed things up, but I don’t have real-world experience with it because it was just released yesterday.

  8. MSYS2, which can be accessed with with-dkml bash, now uses the CLANG64 variant. There are thousands of up-to-date third-party libraries available and, unlike MinGW, they are ABI compatible with the dominant Windows compiler (MSVC). And if you are interested there is an ocamlverse Help Wanted to add the CLANG64 compiler as an alternative to the Administrator-requiring, reboot-needing MSVC compiler.

Thanks to OCaml Software Foundation for sponsoring this!

0.4.x will be the last minor versions of the “preview”. I’ll be shifting to closing out any show-stopping bugs, and updating the various Windows onboarding guides for OCaml to officially include Diskuv OCaml.


The full change log and upgrade instructions is available at Releases · diskuv/dkml-installer-ocaml · GitHub


I installed diskuv and did opam switch list-available. It responded with # No matches found. Does opam switch create not work? I am looking to try ocaml 5.0 on windows.

Use opam dkml init to create a 4.12.1 switch (use --help if needed). There is a walkthrough on Beyond Basics — Diskuv OCaml 0.4.0 documentation for how to use that.

opam switch create does work as long as you pick the right OCaml compiler, but a regular switch is not sufficient for packages with embedded Unix commands to work on Windows. opam dkml init handles the Unix bridging, the correct OCaml compilers and also the extra Windows Opam repositories for you.

OCaml 5.0? I haven’t even looked at 5.0 yet, and wasn’t planning on adding it until the 5.0 compiler and several widely used packages were ready on the MinGW flavor of Windows. That might be a while. Why wait? Because the regular Diskuv installer is prioritizing everything-should-work-out-of-the-box-on-Windows. If that timeline conflicts with something you are working on (ex. you maintain a widely used package or tool) please give feedback.

1 Like

I tried it today, it mostly works, thanks!
opam install ocaml-lsp-server also works, but when I format a file in vscode, I got an error:

ocamlformat: option `--profile': invalid value `'conventional'', expected one
             of `conventional', `default', `compact', `sparse', `ocamlformat'
             or `janestreet'
Usage: ocamlformat [OPTION]... [SRC]...
Try `ocamlformat --help' for more information.

The other feedback is that it took too long, almost 3 hours to have it installed. It is hard to convince people to give it a try unless he/she is already sold on ocaml.


I also tried opam install ppx_jane, which gave me such an error:

PS C:\Users\IDEA\git\hello> opam install ppx_jane      
[NOTE] External dependency handling not supported for
       OS family 'windows'.
       You can disable this check using 'opam option   
       --global depext=false'
[ERROR] Package conflict!
  * Missing dependency:
    - variantslib >= v0.14
    not available because the package is pinned to     
      version 109.15.02

No solution found, exiting
1 Like

I agree. It needs to transition to precompiled executables, at least for the compiler and such.

Do I understand it right, this mean that you can statically link OCaml binaries into native Windows application if you build using CLANG64? If so, this is really cool.

This is the first time I hear about using clang on Windows with OCaml. As I understand, since clang has similar interface to GCC it is mostly straightforward to swap it for MinGW GCC in the MinGW port? Does anyone have experience with such setup? Compilation speed and performance? I remember my colleague Niels G. W. Serup looked at MinGW GCC vs. MSVC on Windows and OCaml bootstrap was slightly slower with GCC, which is not a huge deal. I wonder, how is it with clang… Also, I think I heard from @nojb that MinGW GCC port is a bit slower for floating point math functions, since MSVC is apparently better at implementing them as intrinsics. Wonder how is it with clang is here, again…

One thing I found as I was digging deeper is that there are two different variants of CLANG64 on Windows: 1) the version available from MSYS2 that uses the MinGW headers and 2) the version available from Visual Studio that uses the Windows SDK. So I don’t think CLANG64 in MSYS2 will be ABI compatible as I was initially led to believe.

Yes, if anyone has more information that would be useful.

The goal of CLANG64 on Windows is to provide a cl.exe front-end to the clang compiler. So yes it would help in an incremental swapping process to add Windows compatibility to a Unix-only OCaml package. That is:

  1. Starting from GCC + Linux
  2. Port your C headers to MinGW. Now you have GCC + MinGW using either Cygwin or MSYS2.
  3. Port the build logic (how to specify include directories, compiler warnings, etc.) to cl.exe. Now you have cl.exe + MinGW using CLANG64 + MSYS2.
  4. Port your C headers to Windows SDK. Now you have cl.exe + Windows SDK using either CLANG64 + WinSDK, or MSVC. And you have to install the Windows SDK, but you get real ABI compatibility.

(Of course you can skip some of those steps, or even stop early.)
I’d like to know if anyone would benefit from step 3.