Skip to content

Commit

Permalink
Update ocaml on Windows: add opam 2.2 (#2727)
Browse files Browse the repository at this point in the history 
Co-authored-by: Raja Boujbel <[email protected]>
Co-authored-by: Christine Rose <[email protected]>
Co-authored-by: R. Boujbel <[email protected]>
Co-authored-by: Thibaut Mattio <[email protected]>
Co-authored-by: Jonah Beckford <[email protected]>
  • Loading branch information
@RadioPotin @rjbou
@christinerose @tmattio @jonahbeckford
6 people authored Nov 8, 2024
1 parent b3124ac commit 8764d54
Showing 1 changed file with 138 additions and 52 deletions.
190 changes: 138 additions & 52 deletions data/tutorials/getting-started/3_01_ocaml_on_windows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,73 +6,105 @@ description: >
category: "Resources"
---

There is a [DkML] Windows
installer that we recommend for new users. However, while [DkML] has a modern OCaml 4.14.0 compiler,
it does not track the latest OCaml compilers. We will officially support Windows as a Tier 1
platform with a [major release of opam](#opam-22) in the coming months, and it will be compatible with
DkML installations.
We recommend installing [opam](https://opam.ocaml.org/) for new users. Opam, the OCaml package manager, has full Windows support since version 2.2 and provides the most up-to-date OCaml environment.

[DkML]: https://gitlab.com/dkml/distributions/dkml#installing
There are a couple scenarios when other OCaml installers may be useful:

Our guidance is when you want:
* If you want **to develop applications and either are unfamiliar with Unix or care more about stability and ease-of-use than the latest compiler**, you can use [Diskuv OCaml](#diskuv-ocaml)
* If you want **only to run, not develop, applications**, you can use [Docker](#docker-images) or [WSL2](#wsl2)

* **To only run, and not develop, applications**, use [Docker](#docker-images) or [WSL2](#wsl2)
* **To develop applications and have some familiarity with Unix**, use [opam-repository-mingw](#opam-repository-mingw)
* **To develop applications and care more about stability and ease-of-use than the latest compiler**, use [DkML](https://gitlab.com/dkml/distributions/dkml#installing)

The guidance is based on the availability table below:
The recommendations are based on the availability table below:

* Tier 1 is fully supported with the latest compilers.
* Tier 2 is supported but maintained when possible.
* Tier 3 is user supported.

```
╭──────────────────────────────────────────────────────────────────────────────────────────╮
│ Tier │ OCaml Version and Environment │ Support and Availability │
│ ------ │ --------------------------------- │ ------------------------------------------- │
│ Tier 1 │ OCaml 5 with Opam 2.2 │ Full support. Coming in the next few months │
│ Tier 2 │ 4.14.0 with DkML │ Supported on select versions. Available now │
│ Tier 3 │ 4.14.0 with opam-repository-mingw │ Deprecated. Available now and mostly works │
│ Tier 3 │ 4.14.2 with WSL2 │ User supported. Available now │
│ Tier 3 │ 4.14.1 with Docker | User supported. Available now │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────────────────────────────────────────────────╮
│ Tier │ OCaml Version and Environment │ Support │
│ ------ │ ------------------------------- │ ----------------------------- │
│ Tier 1 │ OCaml 5.x with Opam 2.2+ │ Full support. │
│ Tier 2 │ 4.14.x with Diskuv OCaml │ Supported on select versions. │
│ Tier 3 │ 5.x with WSL2 │ User supported. │
│ Tier 3 │ 5.x with Docker │ User supported. │
╰──────────────────────────────────────────────────────────────────────────╯
```

## Installing Opam on Windows

Opam is distributed via winget for Windows. To install it, run the following command in your terminal:

```shell-session
> winget install Git.Git OCaml.opam
```

We recommend installing Git from `winget`; however, you can omit this step and install Git using your preferred method if needed.
Opam will look for a compatible Git, and if none is found, it will prompt you with a set of options to install one.

After installation, launch a new shell to access the opam binary.

```shell-session
$ opam --version
2.2.1
```

## opam 2.2
Once opam is installed, run the `opam init` command to set up your opam environment.

You will notice that the repository information fetching stage takes a while to
complete. This is normal (for the moment), so we advise our users to get
themselves their favourite hot beverage while it runs.

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 support Windows. This includes
supporting an external dependency installation for Windows and integrating it with the
Windows shell. From an `opam-repository` perspective, the `ocaml-base-compiler`
packages will support the MinGW-w64 and MSVC variants.
opam requires a Unix-like environment to function. By default,
opam relies on Cygwin and is also compatible with MSYS2.

## Installation Environments
At *init-time*, opam scans your machine for available Unix environments and
prompts you to choose your favourite option. We recommend
to let it create its own internal Cygwin installation that will remain managed
by opam. This cuts down possible interferences from other tools
that interact with such environments. Think of it as a
sandboxed environment.

### `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)
that contains 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.
Opam's default behavior when initialising is to install a fresh `switch` as
well as an OCaml compiler of version `> 4.05`. By default, opam chooses `mingw` as
a C compiler when creating switches, but know that you can choose to install an
alternative instead, like `msvc`, with the following command:

```
opam install system-msvc
```

After `opam init` completes, run the following command to update your environment:

On CMD:
```
> for /f "tokens=*" %i in ('opam env --switch=default') do @%i
```
On PowerShell:
```
> (& opam env --switch=default) -split '\\r?\\n' | ForEach-Object { Invoke-Expression $_ }
```
Opam will display the shell update command each time it is needed.

As of August 2021, [the repository will no longer be updated](https://fdopen.github.io/opam-repository-mingw/2021/02/26/repo-discontinued/). However, 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:
You can verify your installation with

```
opam repo add upstream https://opam.ocaml.org --rank 2 --all-switches --set-default
> ocaml --version
The OCaml toplevel, version 5.2.0
> ocaml
OCaml version 5.2.0
Enter #help;; for help.
# print_endline "Hello OCamleers!!";;
Hello OCamleers!!
- : unit = ()
#
```

This assumes you only have the `opam-repository-mingw` repository for this switch set with
a priority of `1`.
You should now have a functioning OCaml environment ready for development. If you encounter any issues or need further assistance, don't hesitate to consult the [OCaml community](https://ocaml.org/community).

## Other Installation Environments

### WSL2

Expand All @@ -88,21 +120,75 @@ 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.

### Diskuv OCaml

Diskuv OCaml ("DKML") is an OCaml distribution that supports software development in pure OCaml.
The distribution is unique because of its:
* full compatibility with OCaml standards like opam, Dune, and OCamlFind.
* focus on "native" development (desktop software, mobile apps, and embedded software) through support for the standard native compilers,
like Visual Studio and Xcode.
* ease-of-use through simplified installers and simple productivity commands. High school, college, and university students should be
able to use it
* security through reproducibility, versioning, and from-source builds.

To install DKML, 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 ninety (90) minutes.

* 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`.

Then download and run:

* OCaml 4.14.0 with Git and Visual Studio compiler: [setup-diskuv-ocaml-windows_x86_64-1.1.0.exe](https://github.com/diskuv/dkml-installer-ocaml/releases/download/v1.1.0_r2/setup-diskuv-ocaml-windows_x86_64-1.1.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\usr\bin\ocaml.exe

$ ocaml -version
The OCaml toplevel, version 4.14.0
```

To learn more about Diskuv OCaml, see the [official
Diskuv OCaml documentation](https://diskuv-ocaml.gitlab.io/distributions/dkml/#introduction).

## Editor Support for OCaml on Windows

### Visual Studio Code on Windows
### Visual Studio Code (VSCode)

**If you use opam installation**, you will need to add opam switch prefix on your path that runs VSCode.

**If you use the recommended DkML installer**, you will need to:
**If you use the 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.
VSCode. Microsoft has a [useful blog post](https://code.visualstudio.com/blogs/2019/09/03/wsl2)
that covers getting WSL2 and Visual Studio Code connected.

### Vim and Emacs on Windows
### Vim and Emacs

**For Vim and Emacs** install the [Merlin](https://github.com/ocaml/merlin)
system using opam:
Expand Down

0 comments on commit 8764d54

Please sign in to comment.