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

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 3 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
45 changes: 28 additions & 17 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 @@ -88,42 +88,53 @@ Opam is now installed and configured! You can now move to [installing the OCaml

## 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.
<!-- 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.
Note that only OCaml version 4.14.0 is available via DkML. -->

OCaml's official package manager, opam, works on Windows from opam 2.2 onwards. You can use opam natively on Command Prompt or PowerShell.

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

#### 1. Install the DkML Distribution
#### 1. Install opam

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
winget install OCaml.opam
```

And then in a new terminal:
> 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.

#### 2. Initialise opam

<!-- This step is necessary only if you want to create a new independent environment. `opam init` already set up a default opam switch for you to work in.

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: -->

The following command will initialise opam on your system. This will take a while to complete. After it's done, you will have a default switch with the latest version of the compiler.

```powershell
dkml init --system
opam init
```

> 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
Make sure you follow the instructions provided at the end of the output of `opam init` to complete the initialisation. Typically, this is:

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.
```
for /f\"tokens=*\" %i in ('opam env') do @%i
```

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:
on Command Prompt, and on PowerShell:

```powershell
C:\Users\frank> mkdir someproject
C:\Users\frank> cd someproject
C:\Users\frank\someproject> dkml init
```
(& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ }
```

Opam is now installed and configured! You can now move to installing the OCaml Platform development tools in the next section.

**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).

## Install Platform Tools

Expand Down
72 changes: 50 additions & 22 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,12 +120,11 @@ 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's 2.2 version onwards supports Windows natively. It is the recmmended way to install OCaml on Windows machines.

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>

Expand All @@ -137,36 +136,65 @@ Layout.render
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-dkml" "winget install 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
its own instance of Cygwin installation. For more details, see </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
Loading