Skip to content

Commit

Permalink
Update windows install instructions to opam (ocaml#2658)
Browse files Browse the repository at this point in the history 
* Update Windows install page to recommend opam 2.2

* Update the installation tutorial for Windows

* Merge the installation instructions

* Remove out-of-date user note

* Apply suggestions from code review

Co-authored-by: David Allsopp <[email protected]>

* remove repeated word

* link the opam blog for more info

* Update src/ocamlorg_frontend/pages/install.eml

Co-authored-by: Christine Rose <[email protected]>

---------

Co-authored-by: David Allsopp <[email protected]>
Co-authored-by: Christine Rose <[email protected]>
  • Loading branch information
@Sudha247 @dra27
@christinerose @sabine
3 people authored and sabine committed Dec 10, 2024
1 parent 2ab1a6e commit bdbb0e6
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 66 deletions.
68 changes: 29 additions & 39 deletions data/tutorials/getting-started/1_00_install_OCaml.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,16 @@ category: "First Steps"

This guide will walk you through a minimum installation of OCaml. That includes installing a package manager and [the compiler](#installation-on-unix-and-macos) itself. We'll also install some platform tools like a build system, support for your editor, and a few other important ones.

On this page, you'll find installation instructions for Linux, macOS, and &ast;BSD for recent OCaml versions. For Docker, Linux instructions apply, except when setting up opam. For Windows, we recommend using WSL2 but also provide instructions for installing OCaml 4.14.0 via the [DkML](https://gitlab.com/dkml/distributions/dkml#installing) distribution. If you are setting up OCaml on Windows and are unsure which installation method to use, you might be interested in reading [OCaml on Windows](/docs/ocaml-on-windows) first.
On this page, you'll find installation instructions for Linux, macOS, Windows, and &ast;BSD for recent OCaml versions. For Docker, Linux instructions apply, except when setting up opam.

**Note**: You'll be installing OCaml and its tools through a [command line interface (CLI), or shell](https://www.youtube.com/watch?v=0PxTAn4g20U)

## Installation on Unix and macOS
## Install opam

OCaml has an official package manager, [opam](https://opam.ocaml.org/), which allows users to download and install OCaml tools and libraries. Opam also makes it practical to deal with different projects which require different versions of OCaml.

Opam also installs the OCaml compiler. Alternatives exist, but opam is the best way to install OCaml. Although OCaml is available as a package in most Linux distributions, it is often outdated.

### 1. Install opam

To install opam, you can [use your system package manager](https://opam.ocaml.org/doc/Install.html#Using-your-distribution-39-s-package-system) or download the [binary distribution](https://opam.ocaml.org/doc/Install.html#Binary-distribution). The details are available in these links, but for convenience, we use package distributions:

**For macOS**
Expand Down Expand Up @@ -58,16 +56,32 @@ $ sudo pacman -S opam
sudo apt-get install --no-install-recommends opam
```

**For Windows**

It's easiest to install opam with [WinGet](https://github.com/microsoft/winget-cli):

```shell
PS C:\> winget install Git.Git OCaml.opam
```

**Binary Distribution**

If you want the latest release of opam, install it through the binary distribution. For that, you'll need to install the following system packages first: `gcc`, `build-essential`, `curl`, `bubblewrap`, and `unzip`. Note that they might have different names depending on your operating system or distribution. Also, note this script internally calls `sudo`.
If you want the latest release of opam, install it through the binary distribution. On Unix and macOS, you'll need to install the following system packages first: `gcc`, `build-essential`, `curl`, `bubblewrap`, and `unzip`. Note that they might have different names depending on your operating system or distribution. Also, note this script internally calls `sudo`.

The following command will install the latest version of opam that applies to your system:
```shell
$ bash -c "sh <(curl -fsSL https://raw.githubusercontent.com/ocaml/opam/master/shell/install.sh)"
```

### 2. Initialise opam on Unix
On Windows, the winget package is maintained by opam's developers and uses the binaries released [on GitHub](https://github.com/ocaml/opam/releases), however you can also install using an equivalent PowerShell script:

```powershell
Invoke-Expression "& { $(Invoke-RestMethod https://raw.githubusercontent.com/ocaml/opam/master/shell/install.ps1) }"
```

> **Advanced Windows 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.
## Initialise opam

After you install opam, you'll need to initialise it. To do so, run the following command, as a normal user. This might take a few minutes to complete.

Expand All @@ -82,48 +96,24 @@ Make sure you follow the instructions provided at the end of the output of `opam
$ eval $(opam env)
```

Opam is now installed and configured! You can now move to [installing the OCaml Platform development tools](#install-platform-tools) in the section below.

**Note**: opam can manage something called _switches_. This is key when switching between several OCaml projects. However, in this “getting started” series of tutorials, switches are not needed. If interested, you can read an introduction to [opam switches here](/docs/opam-switch-introduction).

## Installation on Windows

In this section, we'll describe using the [DkML](https://gitlab.com/dkml/distributions/dkml#installing) Windows distribution. Expect to see another officially-supported Windows installation provided directly by opam in the coming months; it will be compatible with your DkML installation.

Note that only OCaml version 4.14.0 is available via DkML.

> **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.
on Unix, and from the Windows Command Prompt:

#### 1. Install the DkML Distribution

Run the following in a terminal (either Windows PowerShell or Command Prompt):

```powershell
winget install Microsoft.VisualStudio.2019.BuildTools --override "--wait --passive --installPath C:\VS --addProductLang En-us --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
winget install Git.Git
winget install Diskuv.OCaml
```
for /f\"tokens=*\" %i in ('opam env') do @%i
```

And then in a new terminal:
or from PowerShell:

```powershell
dkml init --system
(& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ }
```

> Any problems installing? Be sure to read the [latest release notes](https://gitlab.com/dkml/distributions/dkml/-/releases).
> You can file an issue at https://gitlab.com/dkml/distributions/dkml/-/issues.
#### 2. Create an opam Switch

This step is necessary only if you want to create a new independent environment. `dkml init` already set up a default opam switch for you to work in.
Opam is now installed and configured!

You can create a new switch with the `dkml init` command. The only compiler version available is 4.14.0. Use PowerShell or a Command Prompt to create a directory anywhere and then create a switch:
**Note**: opam can manage something called _switches_. This is key when switching between several OCaml projects. However, in this “getting started” series of tutorials, switches are not needed. If interested, you can read an introduction to [opam switches here](/docs/opam-switch-introduction).

```powershell
C:\Users\frank> mkdir someproject
C:\Users\frank> cd someproject
C:\Users\frank\someproject> dkml init
```
> Any problems installing? Be sure to read the [latest release notes](https://opam.ocaml.org/blog/opam-2-2-0/).
> You can file an issue at https://github.com/ocaml/opam/issues or https://github.com/ocaml-windows/papercuts/issues.
## Install Platform Tools

Expand Down
81 changes: 54 additions & 27 deletions src/ocamlorg_frontend/pages/install.eml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -120,53 +120,80 @@ Layout.render
</h2>
<ol>
<li>
<h3>Install the DkML Windows distribution</h3>
<h3>Install the opam package manager</h3>
<p>
The installer sets up OCaml 4.14.0 and <a target="_blank" href="https://github.com/ocaml/opam">OCaml's package manager opam</a>,
with Git and the Visual Studio compiler.
OCaml's package manager, opam, supports Windows natively since version 2.2.0 and is the recommended way to install OCaml on Windows.

If you need a different OCaml version, check out the alternative installation instructions
If you are looking for a different installation method, check out the alternative installation instructions
provided in the <a href="<%s Url.tutorial "ocaml-on-windows" %>">"OCaml on Windows" guide</a>.
</p>

<p>
Before you run the installer: Make sure your Windows username does <b>not</b> contain a space character (e.g. for <code>C:\Users\Jane Smith</code>, OCaml will not install properly).
</p>

<p>
Run the following in a terminal (either Windows PowerShell or Command Prompt):
</p>

<%s! Copy_to_clipboard.small_code_snippet ~id:"install-winget-vs2019buildtools" "winget install Microsoft.VisualStudio.2019.BuildTools --override \"--wait --passive --installPath C:\\VS --addProductLang En-us --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended\"" %>
<%s! Copy_to_clipboard.small_code_snippet ~id:"install-winget-git" "winget install Git.Git" %>
<%s! Copy_to_clipboard.small_code_snippet ~id:"install-winget-dkml" "winget install Diskuv.OCaml" %>
<%s! Copy_to_clipboard.small_code_snippet ~id:"install-winget" "winget install Git.Git OCaml.opam" %>

<p>
And then in a <strong>NEW</strong> terminal:
</p>
</li>

<%s! Copy_to_clipboard.small_code_snippet ~id:"dkml-init-system" "dkml init --system" %>
<li>
<h3>Initialise opam</h3>

<p>
Now, we are ready to initialise opam, which will create a default
<a href="<%s Url.tutorial "opam-switch-introduction" %>">opam switch</a>.
An opam switch is an isolated environment for the OCaml compiler
and any packages you install.
</p>

<%s! Copy_to_clipboard.small_code_snippet ~id:"init-opam" "opam init" %>

<p> During <code>opam init</code>, you will be asked about Unix
support infrastructure. You can select option 1 to let opam manage
it for you. For details of more advanced alternatives, see <a

target="_blank"
href="https://opam.ocaml.org/blog/opam-2-2-0-windows/">the opam
blog</a>. </p>

<p>Any problems installing? Be sure to read the
<a href="https://gitlab.com/dkml/distributions/dkml/-/releases">latest DkML release notes</a>.
And if the release notes aren't relevant to your issue,
<a href="https://gitlab.com/dkml/distributions/dkml/-/issues">file a new issue</a>
</p>
</li>

<li>
<h3>Activate the opam switch</h3>
<p>
You need to activate the opam switch by running on cmd

<%s! Copy_to_clipboard.small_code_snippet ~id:"cmd-activate" "for /f\"tokens=*\" %i in ('opam env') do @%i" %>

or on PowerShell

<%s! Copy_to_clipboard.small_code_snippet ~id:"powershell-activate" "(& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ }" %>
</p>
</li>
</ol>

<p>
Congratulations, you have now installed OCaml as well as the <a href="<%s Url.learn_platform %>">OCaml Platform Tools</a>!
Congratulations, you have now installed OCaml!</a>!
</p>

<p>
The <a href="<%s Url.learn_platform %>">OCaml Platform Tools</a> include the <a target="_blank" href="https://dune.build/">build system Dune</a>
and provide you with a complete OCaml development environment.
</p>
</div>
<div>
<div class="prose dark:prose-invert">
<h2>Set Up an OCaml Development Environment</h2>

<p>Now you are ready to write some OCaml code!</p>
<p>
The <a href="<%s Url.learn_platform %>">OCaml Platform Tools</a>,
which includes the <a target="_blank" href="https://dune.build/">build system Dune</a>,
complete your OCaml development environment. To install them in your current opam switch, run this command:
</p>

<%s! Copy_to_clipboard.small_code_snippet ~id:"install-platform-tools" "opam install ocaml-lsp-server odoc ocamlformat utop" %>

<p>Now you are ready to write some OCaml code!</p>
</div>
<a class="btn mt-6 gap-2" href="<%s Url.tutorial "tour-of-ocaml" %>">Take A Tour of OCaml <%s! Icons.arrow_small_right "h-6 w-6" %></a>
</div>
<a class="btn mt-6 gap-2" href="<%s Url.tutorial "tour-of-ocaml" %>">Take a Tour of OCaml <%s! Icons.arrow_small_right "h-6 w-6" %></a>

</div>
</div>
</div>
Expand Down

0 comments on commit bdbb0e6

Please sign in to comment.