Skip to content

Commit

Permalink
Incorporate PR review and remove stdout
Browse files Browse the repository at this point in the history 
- Change wording of the introduction
- Recommend using winget install Git.Git OCaml.opam
- Shorten instructions when they can be made more concise
  • Loading branch information
@tmattio
tmattio committed Oct 10, 2024
1 parent e5ab191 commit 726c085
Showing 1 changed file with 53 additions and 179 deletions.
232 changes: 53 additions & 179 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,191 +6,89 @@ description: >
category: "Resources"
---

Opam now features a fully native Windows compatible installation process that we
recommend new users to follow below.
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.

In order to have access to OCaml on a Windows PC, users must use opam, so that's our
first step.
There are a couple scenarios when other OCaml installers may be useful:

Opam is now distributed via `winget` for Windows.
* 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)

```shell-session
$ winget show OCaml.opam
Found opam [OCaml.opam]
Version : 2.2.1
Publisher : OCaml, Inc.
[...]
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 │
│ ------ │ ------------------------------- │ ----------------------------- │
│ 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 is done by running the following command in your terminal:
## 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 OCaml.opam
Found opam [OCaml.opam] Version 2.2.1
This application is licensed to you by its owner.
Microsoft is not responsible for, nor does it grant any licenses to, third-party packages.
Downloading https://github.com/ocaml/opam/releases/download/2.2.1/opam-2.2.1-x86_64-windows.exe
██████████████████████████████ 9.89 MB / 9.89 MB
Successfully verified installer hash
Starting package install...
Path environment variable modified; restart your shell to use the new value.
Command line alias added: "opam"
Successfully installed
Notes: See https://opam.ocaml.org/blog for the latest news on how to use opam.
> winget install Git.Git OCaml.opam
```

Once the package is installed, you can launch a new shell to have access to
your fresh opam binary.
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
```

As for any other platform out there, you have to initialise your opam
installation with the `opam init` command.
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.

The first thing to know is that opam requires a Unix-like environment to
function. By default, opam relies on `cygwin` and is also compatible with
opam requires a Unix-like environment to function. By default, opam relies on `cygwin` and is also compatible with
`msys2`.

At *init-time*, opam scans your machine for available Unix environments and
prompts you to choose your favourite option. That being said, it is recommended
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 the possible interferences of other tools
that interact with such environments might introduce. Think of it as a
sandboxed 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.

```shell-session
> opam init
No configuration file found, using built-in defaults.
<><> Windows Developer Mode <><><><><><><><><><><><><><><><><><><><><><><><> 🐫
opam does not require Developer Mode to be enabled on Windows, but it is
recommended, in particular because it enables support for symlinks without
requiring opam to be run elevated (which we do not recommend doing).
More information on enabling Developer Mode may be obtained from
https://learn.microsoft.com/en-gb/windows/apps/get-started/enable-your-device-for-development
<><> Unix support infrastructure ><><><><><><><><><><><><><><><><><><><><><> 🐫
opam and the OCaml ecosystem in general require various Unix tools in order to operate correctly. At present, this requires the installation of Cygwin to provide these tools.
How should opam obtain Unix tools?
> 1. Automatically create an internal Cygwin installation that will be managed by opam (recommended)
2. Use Cygwin installation found in C:\cygwin64
3. Use MSYS2 installation found in C:\msys64
4. Use another existing Cygwin/MSYS2 installation
5. Abort initialisation
[1/2/3/4/5]
Checking for available remotes: rsync and local, git.
- you won't be able to use mercurial repositories unless you install the hg command on your system.
- you won't be able to use darcs repositories unless you install the darcs command on your system.
<><> Fetching repository information ><><><><><><><><><><><><><><><><><><><> 🐫
[default] Initialised
<><> Required setup - please read <><><><><><><><><><><><><><><><><><><><><> 🐫
In normal operation, opam only alters files within ~\AppData\Local\opam.
However, to best integrate with your system, some environment variables
should be set. When you want to access your opam installation, you will
need to run:
for /f "tokens=*" %i in ('opam env') do @%i
At *init-time*, opam scans your machine for available Unix environments and
prompts you to choose your favorite option. We recommend
letting it create its own internal Cygwin installation that will remain managed
by opam. This cuts down the possible interferences that other tools
interacting with such environments might introduce. Think of it as a
sandboxed environment.

You can always re-run this setup with 'opam init' later.
Opam's default behavior when initializing 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 an alternative to it
instead, like `msvc` with the following command:

opam doesn't have any configuration options for cmd; you will have to run for /f "tokens=*" %i in ('opam env') do @%i
whenever you change you current 'opam switch' or start a new terminal session. Alternatively, would you like to select a
different shell? [y/n] n
```

One detail to address about having a fully functional opam installation is
related to Git.

On Windows, there are many ways to have a functioning Git installation. Opam will
look for a compatible Git, and if none is found, it will prompt you with a set of
options to install one.

```shell-session
<><> Git ><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫
Cygwin Git is functional but can have credentials issues for private repositories, we recommend using:
- Install via 'winget install Git.Git'
- Git for Windows can be downloaded and installed from https://gitforwindows.org
Which Git should opam use?
> 1. Install Git with along with Cygwin internally
2. Enter the location of your Git installation
3. Abort initialisation to restart your shell.
[1/2/3]
opam install system-msvc
```

Opam's default behaviour when initialising is to install a fresh `switch` as
well as an ocaml compiler of version `> 4.05`.
After `opam init` completes, run the following command to update your environment:

```shell-session
<><> Creating initial switch 'default' (invariant ["ocaml" {>= "4.05.0"}] - initially with ocaml-base-compiler)
<><> Installing new switch packages <><><><><><><><><><><><><><><><><><><><> 🐫
Switch invariant: ["ocaml" {>= "4.05.0"}]
The following system packages will first need to be installed:
mingw64-x86_64-gcc-core
<><> Handling external dependencies <><><><><><><><><><><><><><><><><><><><> 🐫
[Installing external dependencies]
<><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫
∗ installed arch-x86_64.1
∗ installed base-bigarray.base
∗ installed base-threads.base
∗ installed base-unix.base
∗ installed host-arch-x86_64.1
∗ installed host-system-mingw.1
⬇ retrieved mingw-w64-shims.0.2.0 (https://opam.ocaml.org/cache)
⬇ retrieved flexdll.0.43 (https://opam.ocaml.org/cache)
∗ installed flexdll.0.43
∗ installed ocaml-options-vanilla.1
∗ installed conf-mingw-w64-gcc-x86_64.1
∗ installed ocaml-env-mingw64.1
∗ installed system-mingw.1
⬇ retrieved ocaml-config.3 (2 extra sources)
⬇ retrieved ocaml-config.3 (2 extra sources)
∗ installed mingw-w64-shims.0.2.0
⬇ retrieved ocaml-base-compiler.5.2.0 (https://opam.ocaml.org/cache)
∗ installed ocaml-base-compiler.5.2.0
∗ installed ocaml-config.3
∗ installed ocaml.5.2.0
∗ installed base-domains.base
∗ installed base-nnp.base
Done.
# Run for /f "tokens=*" %i in ('opam env --switch=default') do @%i to update the current shell environment
```

You can see that in this specific run of the command, opam chose `mingw` as
a C compiler, but know that you can very well choose an alternative to it
instead, like `msvc` with the following command:

```shell-session
$ opam install system-msvc
> for /f "tokens=*" %i in ('opam env --switch=default') do @%i
```

Once your environment has been updated with the given hint, you will have a
fully functional OCaml compiler available to you:

```shell-session
> for /f "tokens=*" %i in ('opam env --switch=default') do @%i
You can verify your installation with

```
> ocaml --version
The OCaml toplevel, version 5.2.0
Expand All @@ -204,33 +102,9 @@ Hello OCamleers!!
#
```

## DkML

We recommend installing opam 2.2 for new users; it comes with full Windows support.

There are a couple scenarios when other OCaml installers may be useful:

* when 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)
* when you want **only to run, not develop, applications**, you can use [Docker](#docker-images) or [WSL2](#wsl2)

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 │
│ ------ │ ------------------------------- │ ----------------------------- │
│ Tier 1 │ OCaml 5 with Opam 2.2 │ Full support. │
│ Tier 2 │ 4.14.0 with Diskuv OCaml │ Supported on select versions. │
│ Tier 3 │ 5 with WSL2 │ User supported. │
│ Tier 3 │ 5 with Docker | User supported. │
╰──────────────────────────────────────────────────────────────────────────╯
```
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).

## Installation Environments
## Other Installation Environments

### WSL2

Expand Down Expand Up @@ -300,7 +174,7 @@ Diskuv OCaml documentation](https://diskuv-ocaml.gitlab.io/distributions/dkml/#i

## Editor Support for OCaml on Windows

### Visual Studio Code on Windows
### Visual Studio Code

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

Expand All @@ -314,7 +188,7 @@ Diskuv OCaml documentation](https://diskuv-ocaml.gitlab.io/distributions/dkml/#i
Visual Studio Code. 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 726c085

Please sign in to comment.