[RFC] Update the state of OCaml on Windows

[patricoferris]

After a healthy discussion of all the different ways OCaml can work on Windows on discuss.ocaml.org there seemed to be at least some consensus that the current information needs updated (disclaimer: I'm not a windows user, I just want to see this issue resolved). To that end, I've tried to summarise the different points made with some pros and cons and hopefully someone with a little more Windows experience can take this issue and make a PR (or perhaps we can reach a consensus here on the issue), there's a vague proposal at the end.

Current Situation

The site currently uses the up_and_running post to detail how to get OCaml on a variety of OSes. On windows it recommends OCaml for windows. The problem highlighted on discuss is that the underlying opam-repository (opam-repository-mingw) is to be discontinued next month: https://fdopen.github.io/opam-repository-mingw/2021/02/26/repo-discontinued/

Possible updates

WSL2

Pros: seems to be easy to setup and should work with most OCaml because it is Linux, this is in fact what we recommend in the CONTRIBUTING.md for this site. This is important to note, if a new user simply wishes to "run OCaml on their windows machine" perhaps this is the simplest and most robust approach?

Cons: as pointed out on discuss you need a complicated cross-compiling environment in order to get windows binaries.

OCaml for Windows + Explanation of overlays

Pros: sticking almost with the current content but providing more information about how to use the various existing opam-repositories @dra27 describes in this comment. This is truly OCaml on windows though.

Cons: requires a greater understanding of OCaml tools like opam and so the explanation will be longer and likely more confusing for complete beginners.

Docker

Pros: Thanks to some awesome work there are now OCaml windows docker images, this would remove a lot of head-scratching setup for beginners. The images are also being used in CI so should be updated regularly and in a working state.

Cons: dependency on docker

Aside: it may be worth mentioning the docker images (https://hub.docker.com/r/ocaml/opam) anyway, I think a lot of beginners will have docker installed these days especially coming from any other programming languages and in the initial "trying out OCaml" phase this might be a very painless way to get started?

---

Proposal

Again, disclaimer, I am not a windows user but it feels like perhaps mentioning all of these approaches could be useful in a staged way of saying:

1. Run OCaml on Windows => WSL2
2. Run OCaml and produce Windows binaries => OCaml on Windows, plus explanation of opam-repository, deprecation of opam-repository-mingw and something about opam.2.2.0 plans. Perhaps if this starts getting too long we can split it into its own page, someone has to explain OCaml on windows somewhere, why not ocaml.org :)) ?

And perhaps a section on the docker images which would be useful for Linux, macOS and Windows users to get "up and running" with OCaml.

[dra27]

This is a thoroughly good idea, @patricoferris! It's definitely worth splitting the problem into "New user who wants to try OCaml and happens to be on Windows" vs "User who needs Windows binaries".

I don't know the technical details for the editor (it's not my workflow!), but it would be worth the complete beginner having something like:

• You need WSL2 (that's worth underscoring - WSL1 is harder and slower to use with opam), linking the standard instructions from Microsoft and recommending Ubuntu 20.04 as the distro to use
• This is the plumbing required to use VS Code + WSL2 installation of OCaml
• Note that you'll be producing Linux binaries, not native Windows programs (with a link to a separate page on native Windows)

I don't think it's wrong at this stage to state that running OCaml on native Windows is just not a beginner operation (but that we're working on it!)

[patricoferris]

Thanks @dra27 -- that sounds like a good compromise, especially catering towards the beginner use case on the up_and_running page. Do you think it is worth mentioning the docker images at all on this page ? It might add some confusion but I'm also aware that the images are not really promoted anywhere obvious at the moment (it might also help clear up the "should I be using ocaml/opam, ocaml/opam2, ocaml/ocaml or ocurrent/opam repository" problem 😁)

[dra27]

I'm not sure about Docker, to be honest - it seems to be something that users are either very familiar with or utterly terrified by (from limited experience based on triaging opam issues for repro cases!). I would think it's definitely worth a mention, again with a link to a separate page - I think what's probably wanted is the keyword "Docker" somewhere for those that know, but with no risk that a beginner (both for OCaml and Docker) ends up in a container thoroughly confused!