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 windows install instructions to opam #2658

Merged
merged 11 commits into from
Sep 6, 2024
Merged

Update windows install instructions to opam #2658

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
00b43b9
Update Windows install page to recommend opam 2.2
Sudha247 Aug 21, 2024
0a01f2a
Update the installation tutorial for Windows
Sudha247 Aug 21, 2024
572359c
Merge branch 'main' of https://github.com/ocaml/ocaml.org into window…
Sudha247 Aug 22, 2024
6ca0c8e
Merge the installation instructions
dra27 Aug 28, 2024
3b29012
Remove out-of-date user note
dra27 Aug 28, 2024
eed109f
Apply suggestions from code review
Sudha247 Aug 28, 2024
6f8c3bf
Merge branch 'windows-install' of https://github.com/Sudha247/ocaml.o…
Sudha247 Aug 28, 2024
8b732f3
remove repeated word
christinerose Aug 29, 2024
d80ebd5
link the opam blog for more info
Sudha247 Aug 29, 2024
63b18da
fix merge conflicts
Sudha247 Aug 29, 2024
b62b838
Update src/ocamlorg_frontend/pages/install.eml
Sudha247 Aug 30, 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
68 changes: 29 additions & 39 deletions data/tutorials/getting-started/1_00_install_OCaml.md
View file
Open in desktop
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 *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 *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.
Sudha247 marked this conversation as resolved.
Show resolved Hide resolved

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
77 changes: 50 additions & 27 deletions src/ocamlorg_frontend/pages/install.eml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,53 +120,76 @@ 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>

Sudha247 marked this conversation as resolved.
Show resolved Hide resolved
<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>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>
<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 it for you. For details of more advanced alternatives, see </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>
Sudha247 marked this conversation as resolved.
Show resolved Hide resolved
</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
Loading