Merge pull request #1600 from patricoferris/update-windows

initial ocaml on windows explanation

.gitignore

@@ -29,4 +29,5 @@ script/generate_opam_update_list
 opam_update_list
 *.bz2
 *.ai
-*.json
+*.json
+_opam

site/learn/tutorials/up_and_running.md

@@ -62,10 +62,20 @@ sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.
 
 ### For Windows
 
-We use the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/)
-installer which comes in 32bit and 64bit versions. This installer gives you
-opam and OCaml installations all in one go. It is used from within a Cygwin
-environment, but the executables produced have no dependency on Cygwin at all.
+OCaml on Windows is still a work in progress. In the meantime, if you only
+need to *run* OCaml programs on a Windows machine, then the simplest solution
+is to use the Windows Subsystem for Linux 2 (WSL2). WSL2 is a feature that
+allows Linux programs to run directly on Windows. WSL2 is substantially easier
+and faster to use than WSL1. Microsoft have comprehensive installation steps
+for [setting up WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
+
+On the other hand, if you need Windows binaries then you will have to use the
+[OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/) installer
+which comes in 32bit and 64bit versions. This installer gives you opam and
+OCaml installations all in one go. It is used from within a Cygwin environment,
+but the executables produced have no dependency on Cygwin at all. For a more
+comprehensive update on the state of OCaml on Windows, see the 
+[OCaml on Windows](/platform/ocaml_on_windows.html) page.
 
 ## The OCaml top level
 
@@ -200,6 +210,10 @@ from the list. Now, help is available by hovering over symbols in your program:
 
 ![Visual Studio Code](/img/vscode.png "")
 
+**On Windows using WSL2** you will remotely connect to your WSL2 instance from
+Visual Studio Code. Microsoft have a [useful blog post](https://code.visualstudio.com/blogs/2019/09/03/wsl2)
+covering getting WSL2 and Visual Studio Code connected.
+
 **On Windows**, we must launch Visual Studio Code from within the Cygwin window,
 rather than by clicking on its icon (otherwise, the language server will not be
 found):

site/platform/ocaml_on_windows.md

@@ -0,0 +1,51 @@
+<!-- ((! set title OCaml on Windows !)) ((! set platform !)) -->
+
+*Table of contents*
+
+# OCaml on Windows
+
+Full support for OCaml on Windows is actively being worked on and a workable
+environment can already be achieved today. A gentle reminder that if you do not
+need Windows binaries, then a more stable option is to use WSL2. This is
+described on the [up and running page](/learn/tutorials/up_and_running.html).
+
+## opam-repository-mingw
+
+[opam-repository-mingw](https://github.com/fdopen/opam-repository-mingw) is an
+[opam repository](https://opam.ocaml.org/doc/Manual.html#Repositories)
+containing patches for packages to build and install on Windows as well as
+mingw-w64 and MSVC compiler variants (in both 32 and 64-bit). For a long time this has been
+maintained by [@fdopen](https://fdopen.github.io/opam-repository-mingw/) along
+with [installers](https://fdopen.github.io/opam-repository-mingw/installation/)
+to create a custom Cygwin environment with opam and OCaml installed.
+
+As of August 2021, [the repository will no longer be updated](https://fdopen.github.io/opam-repository-mingw/2021/02/26/repo-discontinued/). It is still useful as an overlay to
+the [default opam repository](https://github.com/ocaml/opam-repository). This
+means if a package exists in `opam-repository-mingw` the opam client will use
+that information, otherwise it will fall through to `opam-repository`. To add
+`opam-repository` as an underlay to your opam setup (assuming you followed the
+manual installation from the [OCaml for Windows](https://fdopen.github.io/opam-repository-mingw/installation/)
+site), you can use:
+
+```
+opam repo add upstream https://opam.ocaml.org --rank 2 --all-switches --set-default
+```
+
+This assumes you only have the `opam-repository-mingw` repository for this switch set with
+a priority of `1`.
+
+## opam.2.2.0
+
+After the [successful release](https://github.com/ocaml/opam/releases/tag/2.1.0) 
+of opam 2.1.0 the [next version](https://github.com/ocaml/opam/projects/2) of
+`opam` will focus on closing the gap to fully supporting Windows. This includes
+supporting external dependency installation for Windows and integrating with the
+Windows shell. From an `opam-repository` perspective, the `ocaml-base-compiler`
+packages will need to support the mingw-w64 and MSVC variants.
+
+## Docker Images
+
+The [`ocaml/opam`](https://hub.docker.com/r/ocaml/opam) Docker Hub repository
+now contains regularly updated Windows images. This includes images using
+`msvc` and `mingw`. If you are comfortable with Docker, this might be an
+easier way to get a working Windows environment on your machine.