Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update ocaml on Windows: add opam 2.2 #2727

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
+138 −52
Open

Update ocaml on Windows: add opam 2.2 #2727

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
88b16d8
Add opam for Windows installation tutorial
RadioPotin Sep 17, 2024
79744ca
Minor line editing / formatting on 3_01_ocaml_on_windows.md
christinerose Oct 2, 2024
90a1ac4
edit section mentioning winget
RadioPotin Oct 3, 2024
3146086
remove windows file management comment
RadioPotin Oct 3, 2024
a85ca05
Change OCaml compiler version to 4.14.2
RadioPotin Oct 3, 2024
be5ec64
Removed unnecessary work and fixed spelling error
christinerose Oct 4, 2024
e5ab191
Incorporate changes from #554
tmattio Oct 10, 2024
726c085
Incorporate PR review and remove stdout
tmattio Oct 10, 2024
823dec1
Apply suggestions from code review
tmattio Oct 11, 2024
1a71cd7
Update data/tutorials/getting-started/3_01_ocaml_on_windows.md
tmattio Oct 11, 2024
779c41d
line edits 3_01_ocaml_on_windows.md
christinerose Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 138 additions & 52 deletions data/tutorials/getting-started/3_01_ocaml_on_windows.md
View file
Open in desktop
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
```
tmattio marked this conversation as resolved.
Show resolved Hide resolved
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.

tmattio marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps there could be a link here on how to add switch prefix to the path?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is that needed at all? If it is needed, we should file a bug somewhere since that is quite unpleasant for a user.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll ping @dra27 on this one


**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
Loading