diff --git a/data/tutorials/getting-started/1_00_install_OCaml.md b/data/tutorials/getting-started/1_00_install_OCaml.md index fc4d5e11dc..50f8af8b7e 100644 --- a/data/tutorials/getting-started/1_00_install_OCaml.md +++ b/data/tutorials/getting-started/1_00_install_OCaml.md @@ -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** @@ -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. @@ -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 diff --git a/src/ocamlorg_frontend/pages/install.eml b/src/ocamlorg_frontend/pages/install.eml index ea09c25b88..216889fa37 100644 --- a/src/ocamlorg_frontend/pages/install.eml +++ b/src/ocamlorg_frontend/pages/install.eml @@ -120,53 +120,80 @@ Layout.render
  1. -

    Install the DkML Windows distribution

    +

    Install the opam package manager

    - The installer sets up OCaml 4.14.0 and OCaml's package manager opam, - 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 ">"OCaml on Windows" guide.

    -

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

    -

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

    - <%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" %> -

    - And then in a NEW terminal: -

    +
    2. - <%s! Copy_to_clipboard.small_code_snippet ~id:"dkml-init-system" "dkml init --system" %> +
  2. +

    Initialise opam

    + +

    + Now, we are ready to initialise opam, which will create a default + ">opam switch. + An opam switch is an isolated environment for the OCaml compiler + and any packages you install. +

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

    During opam init, 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 the opam + blog.

    -

    Any problems installing? Be sure to read the - latest DkML release notes. - And if the release notes aren't relevant to your issue, - file a new issue -

    +
    3. + +
  3. +

    Activate the opam switch

    +

    + 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 $_ }" %> +

- Congratulations, you have now installed OCaml as well as the OCaml Platform Tools! + Congratulations, you have now installed OCaml!!

-

- The OCaml Platform Tools include the build system Dune - and provide you with a complete OCaml development environment. -

+ +
+
+

Set Up an OCaml Development Environment

-

Now you are ready to write some OCaml code!

+

+ The OCaml Platform Tools, + which includes the build system Dune, + complete your OCaml development environment. To install them in your current opam switch, run this command: +

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

Now you are ready to write some OCaml code!

+
+ ">Take A Tour of OCaml <%s! Icons.arrow_small_right "h-6 w-6" %>
- ">Take a Tour of OCaml <%s! Icons.arrow_small_right "h-6 w-6" %> +