Use Diskuv OCaml as the Windows option

data/tutorials/gs_00_up_and_running.md

@@ -11,26 +11,37 @@ date: 2021-05-27T21:07:30-00:00
 
 # Get Up and Running With OCaml
 
-This page will walk you through the installation of OCaml and the Dune build system, as well as offer support for
-your favourite text editor or IDE. These instructions work on Unix-based systems like Linux and macOS, and there are also instructions on how to install OCaml on Windows.
+This page will walk you through the installation of OCaml and the Dune build system, as well as offer support for your favourite text editor or IDE. These instructions work on Windows and Unix-based systems like Linux and macOS.
+
+**Guidelines for following instructions on this page**
+
+A **shell** is a program you can run that will let you enter commands in a text windows using only your keyboard. When this page asks you to enter commands in your shell:
+* On macOS you will run the `Terminal` app to start a shell
+* On Windows, you can start PowerShell by pressing the Windows key (`⊞`), typing "PowerShell" and then clicking Open `Windows PowerShell`. There is an older shell called "Command Prompt" you can use as well
+* On Linux you are already familiar with a shell (typically bash or zsh)
+
+The code blocks (in black) on this page show the required commands (the text after `#` gives more information on the following commands). Type each command after the prompt `$`, although it's often represented by a `%`, `>`, or another symbol as well. Ensure you use the exact case and spacing shown, then hit return/enter at the end of every line.
 
 ## Installing OCaml
 
-It's a straightfoward process to install OCaml. [Opam](https://opam.ocaml.org/) is OCaml's package manager, so we'll install it first. You will also use Opam when installing third-party OCaml libraries.
+The foundation for installing OCaml and third-party OCaml libraries is [Opam](https://opam.ocaml.org/), OCaml's package manager. On Unix-like systems you'll install and manage Opam through the Unix shell; on Windows you'll use a traditional `setup.exe` installer that will install and manage Opam on your behalf. Whether you are on Unix or Windows, you'll end up with OCaml ready for you to use.
 
-Find the all installation instructions for both Unix-like systems and Windows below. If you're new to the CLI, the code blocks (in black) show the required commands (the text after # gives more information on the following commands). Type each command after the prompt $, although it's often represented by a %, >, or another symbol as well. Ensure you use the exact case and spacing shown, then hit return/enter at the end of every line.
+Find all the installation instructions for both Unix-like systems and Windows in the sections below:
+
+* Linux or macOS: [Installation for Linux and macOS](#installation-for-linux-and-macos)
+* Windows: [Installation for Windows](#installation-for-windows)
 
 ### Installation for Linux and macOS
 
-In the cases below, `# Homebrew` indicates the command if you're using [Homebrew](https://brew.sh/) as the installer, and `# MacPorts` is if you're using [MacPorts](https://www.macports.org/) to install.
+In the code blocks below, `# Homebrew` indicates the command if you're using [Homebrew](https://brew.sh/) as the installer, and `# MacPorts` is if you're using [MacPorts](https://www.macports.org/) to install.
 
 **For macOS**
 
-```
+```console
 # Homebrew
 brew install opam
 
-# MacPort
+# MacPorts
 port install opam
 ```
 
@@ -41,7 +52,7 @@ methods.](https://opam.ocaml.org/doc/Install.html)
 **Install Compiler**
 It's essential to install the OCaml compiler because OCaml is a compiled language, so please don't skip this step. The first part sets up Opam, and the second part installs the OCaml base compiler:
 
-```
+```console
 # environment setup
 $ opam init
 $ eval `opam env`
@@ -64,7 +75,7 @@ The OCaml base compiler installation uses the `opam switch create` command; `swi
 
 Next, check that OCaml is installed properly with the following commands. The line beneath the $ command shows the desired output for both the OCaml version and the toplevel version (installed specifically with the above `switch` command):
 
-```
+```console
 $ which ocaml
 /Users/frank/.opam/4.14.0/bin/ocaml
 
@@ -75,24 +86,65 @@ The OCaml toplevel, version 4.14.0
 As an alternative **for either Linux or macOS**, a binary distribution of Opam is
 available:
 
-```
+```bash
 sh <(curl -sL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)
 ```
 
-### For Windows
+### Installation for Windows
+
+In this section we'll describe using the new [Diskuv OCaml](https://github.com/diskuv/dkml-installer-ocaml#readme) ("DKML") Windows installer. Expect to see another officially supported Windows installation provided directly by Opam in the coming months; it will be compatible with your DKML installation.
+
+> Advanced Users: If you are familiar with "Cygwin" or "WSL2", there are other installation methods described on the [OCaml on Windows](/docs/ocaml-on-windows) page.
 
-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 has comprehensive installation steps for [setting up WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
+Before using the DKML installer, briefly review the following:
+
+* You need to **stay at your computer** and press "Yes" for any Windows security popups;
+  after the DKML installer finishes installing two programs (`Visual Studio Installer`
+  and `Git for Windows`) you can leave your computer for the remaining one (1) hour.
+
+* First time installations may get a notification printed in red. If you see it, reboot your computer and then restart your installation so that Visual Studio Installer can complete. The notification looks like:
+
+  ```diff
+  - FATAL [118acf2a]. The machine needs rebooting.
+  - ...
+  - >>  The machine needs rebooting. <<<
+  -         ...
+  -         FATAL [5f927a8b].
+  -         A transient failure occurred.
+  -         ...
+  -         >>  A transient failure occurred. <<<
+  ```
+
+* You may be asked to accept a certificate from
+  `Open Source Developer, Gerardo Grignoli` for the `gsudo` executable
+  that was issued by
+  `Certum Code Signing CA SHA2`.
+
+Now go ahead and download and run:
+
+* OCaml 4.12.1 with Git and Visual Studio compiler: [setup-diskuv-ocaml-windows_x86_64-1.0.0.exe](https://github.com/diskuv/dkml-installer-ocaml/releases/download/v1.0.0/setup-diskuv-ocaml-windows_x86_64-1.0.0.exe)
+
+Check that OCaml is installed properly with the following commands in your shell (PowerShell or Command Prompt).
+The line beneath the $ command shows the desired output for both the OCaml version and the toplevel version:
+
+```console
+$ where.exe ocaml
+C:\Users\frank\AppData\Local\Programs\DiskuvOCaml\0\usr\bin\ocaml.exe
+
+$ ocaml -version
+The OCaml toplevel, version 4.12.1
+```
 
-On the other hand, if you need Windows binaries, 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's 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](/docs/ocaml-on-windows) page on the old version of the site.
+To learn more about Diskuv OCaml, see the [official
+Diskuv OCaml documentation](https://diskuv.gitlab.io/diskuv-ocaml/#introduction).
 
 ## The OCaml Toplevel
 
 _Toplevel_ is a read-eval-print loop (REPL). It's one of the things that makes OCaml so efficient because it compiles while you code, allowing for iteration.
 
 OCaml comes with two additional compilers: one compiles to **native code** (sometimes called machine code or executable binary), directly read by the CPU, and the other compiles to **bytecode**, creating an executable that can be interpreted by a variety of runtime environments, making more flexible.
 
-For now, let's first use the recommended toplevel, which we installed above:
+For now, let's open a shell and use the recommended toplevel, which we installed above:
 
 ```
 $ utop
@@ -140,7 +192,7 @@ OCaml compilation. We installed it with opam, above.
 Let's begin the simplest project with Dune and OCaml. We ask `dune` to
 initialize a new project, and then change into the created directory:
 
-```
+```console
 $ dune init proj helloworld
 Success: initialized project component named helloworld
 $ cd helloworld
@@ -155,24 +207,42 @@ $ dune build
 When we change our program, we can type `dune build` again to make a new
 executable. To run the program, we can use:
 
-```
+```console
 $ dune exec ./bin/main.exe
 Hello, World!
 ```
 
 Or, alternatively,
 
-```
+```console
 $ dune exec helloworld
 Hello, World!
 ```
 
-Let's look at the contents of our new directory:
+Let's look at the contents of our new directory.
 
-```
-$ ls
-bin  _build  dune-project  helloworld.opam  lib  test
-```
+* On macOS and Linux use the directory listing command (`ls`):
+
+  ```console
+  $ ls
+  bin  _build  dune-project  helloworld.opam  lib  test
+  ```
+* On Windows use the directory listing command (`dir`):
+
+  ```console
+  $ dir
+      Directory: C:\source\helloworld
+
+
+  Mode                 LastWriteTime         Length Name
+  ----                 -------------         ------ ----
+  d-----          8/8/2022  12:18 PM                bin
+  d-----          8/8/2022  12:18 PM                lib
+  d-----          8/8/2022  12:18 PM                test
+  d-----          8/8/2022  12:18 PM                _build
+  -a----          8/8/2022  12:18 PM             36 dune-project
+  -a----          8/8/2022  12:18 PM              0 helloworld.opam
+  ```
 
 All the build outputs generated by dune go in the `_build` directory. The
 `main.exe` executable is generated inside the `_build/default/bin/`
@@ -188,7 +258,7 @@ documentation](https://dune.readthedocs.io/en/stable/).
 ## Editor Support for OCaml
 
 For **Visual Studio Code**, and other editors support the Language Server
-Protocol, we use the OCaml language server, which was installed when we 
+Protocol, we use the OCaml language server, which was installed when we
 installed opam earlier.
 
 Now, we install the OCaml Platform Visual Studio Code extension from the Visual
@@ -200,34 +270,20 @@ from the list. Now, help is available by hovering over symbols in your program:
 
 ![Visual Studio Code](/media/tutorials/vscode.png)
 
-**On Windows using WSL2** you will remotely connect to your WSL2 instance from
-Visual Studio Code. Microsoft has 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):
-
-```
-$ /cygdrive/c/Users/Frank\ Smith/AppData/Local/Programs/Microsoft\ VS\ Code/Code.exe
-```
+**On Windows**
+1. If you used the recommended DKML installer you will need to:
+   1. Go to `File` > `Preferences` > `Settings` view (or press `Ctrl ,`)
+   2. Select `User` > `Extensions` > `OCaml Platform`
+   3. **Uncheck** `OCaml: Use OCaml Env`. That's it!
+2. Advanced users can follow
+[OCaml on Windows: Editor Support for OCaml on Windows](/docs/ocaml-on-windows#editor-support-for-ocaml-on-windows)
 
 **For Vim and Emacs** install the [Merlin](https://github.com/ocaml/merlin)
 system using opam:
 
-```
+```console
 $ opam install merlin
 ```
 
 The installation procedure will print instructions on how to link Merlin with
 your editor.
-
-**On Windows**, when using Vim, the default cygwin Vim will not work with
-Merlin. You will need install Vim separately. In addition to the usual
-instructions printed when installing Merlin, you may need to set the PATH in
-Vim:
-
-```
-let $PATH .= ";".substitute(system('opam config var bin'),'\n$','','''')
-```
-

data/tutorials/gs_03_ocaml_on_windows.md

@@ -9,12 +9,18 @@ date: 2021-05-27T21:07:30-00:00
 
 # 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](/docs/up-and-running).
+There is a new [Diskuv OCaml](https://github.com/diskuv/dkml-installer-ocaml#readme) ("DKML") Windows
+installer that we recommend for new users. Expect to see another officially supported Windows installation provided directly by Opam in the coming months; it will be compatible with a DKML installation.
 
-## opam-repository-mingw
+Our guidance is:
+
+* when you **want only to run, not develop, OCaml programs** you should use [Docker](#docker-images) or [WSL2](#wsl2)
+* when you **are familiar with Cygwin** you should use [Cygwin](#opam-repository-mingw)
+* when you **are everybody else, including students and first-time developers,** you should use [Diskuv OCaml](/docs/up-and-running)
+
+## Installation Environments
+
+### 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)
@@ -39,7 +45,7 @@ opam repo add upstream https://opam.ocaml.org --rank 2 --all-switches --set-defa
 This assumes you only have the `opam-repository-mingw` repository for this switch set with
 a priority of `1`.
 
-## opam.2.2.0
+### 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
@@ -48,9 +54,58 @@ 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
+### WSL2
+
+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 has comprehensive installation steps for [setting up WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
+
+After you have installed WSL2 and chosen one Linux distribution (we suggest [Ubuntu LTS](https://apps.microsoft.com/store/detail/ubuntu/9PDXGNCFSCZV?hl=en-us&gl=US)), you can follow the
+[Get Up and Running With OCaml: Installation for Linux and macOS](/docs/up-and-running) steps.
+
+### 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.
+
+## Editor Support for OCaml on Windows
+
+### Visual Studio Code on Windows
+
+**If you use the recommended DKML installer** you will need to:
+1. Go to `File` > `Preferences` > `Settings` view (or press `Ctrl ,`)
+2. Select `User` > `Extensions` > `OCaml Platform`
+3. **Uncheck** `OCaml: Use OCaml Env`
+
+**If you use WSL2** you will remotely connect to your WSL2 instance from
+Visual Studio Code. Microsoft has a [useful blog post](https://code.visualstudio.com/blogs/2019/09/03/wsl2)
+covering getting WSL2 and Visual Studio Code connected.
+
+**If you use Cygwin** 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):
+
+```
+$ /cygdrive/c/Users/Frank\ Smith/AppData/Local/Programs/Microsoft\ VS\ Code/Code.exe
+```
+
+### Vim and Emacs on Windows
+
+**For Vim and Emacs** install the [Merlin](https://github.com/ocaml/merlin)
+system using opam:
+
+```console
+$ opam install merlin
+```
+
+The installation procedure will print instructions on how to link Merlin with
+your editor.
+
+**If you use Vim**, the default cygwin Vim will not work with
+Merlin. You will need install Vim separately. In addition to the usual
+instructions printed when installing Merlin, you may need to set the PATH in
+Vim:
+
+```vim
+let $PATH .= ";".substitute(system('opam config var bin'),'\n$','','''')
+```