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

(docs) Use DkML 2.1.0 #2249

Merged
merged 3 commits into from
Mar 28, 2024
Merged

(docs) Use DkML 2.1.0 #2249

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ed7a1c9
Use DkML 2.1.0
jonahbeckford Mar 18, 2024
68a96d3
Update data/tutorials/getting-started/1_00_install_OCaml.md
jonahbeckford Mar 26, 2024
fdb96cb
Update 1_02_your_first_ocaml_program.md
jonahbeckford Mar 28, 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
2 changes: 1 addition & 1 deletion data/news/platform/platform-2023-09.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ For reference, here is a table of Dune's platform support (with `?` indicating t
|------------------|---------|-------|-----|-------|------------|
| Linux | Full | Yes | Yes | Yes | Yes |
| MacOS | Full | Yes | Yes | Yes | Yes |
| Windows (DKML) | Full | Yes | No* | Yes | Copy only |
| Windows (DkML) | Full | Yes | No* | Yes | Copy only |
| Windows (MinGW) | Limited | Yes | Yes | Yes | Yes |
| Windows (Cygwin) | Limited | Yes | Yes | Yes | Yes |
| Linux (Android) | Limited | Yes | Yes | ? | ? |
Expand Down
48 changes: 16 additions & 32 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,7 +9,7 @@ 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 WSL but also provide instructions for installing OCaml 4.14.0 via the [Diskuv OCaml](https://github.com/diskuv/dkml-installer-ocaml#readme) Installer. 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, 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.

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

Expand Down Expand Up @@ -83,38 +83,30 @@ 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 [Diskuv OCaml](https://github.com/diskuv/dkml-installer-ocaml#readme) (DKML) Windows installer. 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 Diskuv OCaml.
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.

#### 1. Use the DKML Installer
#### 1. Install the DkML Distribution

Before using the DKML installer, briefly review the following:
Run the following in a terminal (either Windows PowerShell or Command Prompt):

* Do not use the installer if you have a space in your username (ex. `C:\Users\Jane Smith`).

* You need to **stay at your computer** and press "Yes" for any Windows security popups. After the DKML installer finishes installing two programs (`Visual Studio Installer` and `Git for Windows`), you can leave your computer for the remaining one and a half (1.5) hours.

* First time installations may get a notification printed in red. If you see it, reboot your computer and then restart your installation so that Visual Studio Installer can complete. The notification looks like:

```diff
- FATAL [118acf2a]. The machine needs rebooting.
- ...
- >> The machine needs rebooting. <<<
- ...
- FATAL [5f927a8b].
- A transient failure occurred.
- ...
- >> A transient failure occurred. <<<
```
```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
```

* You may be asked to accept a certificate from `Open Source Developer, Gerardo Grignoli` for the `gsudo` executable that was issued by `Certum Code Signing CA SHA2`.
And then in a **NEW** terminal:
jonahbeckford marked this conversation as resolved.
Show resolved Hide resolved

Now, download and run:
```powershell
dkml init --system
```

* OCaml 4.14.0 with Git and Visual Studio compiler: [setup-diskuv-ocaml-windows_x86_64-1.2.0.exe](https://github.com/diskuv/dkml-installer-ocaml/releases/download/v1.2.0/setup-diskuv-ocaml-windows_x86_64-1.2.0.exe)
> 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

Expand All @@ -126,16 +118,8 @@ You can create a new switch with the `dkml init` command. The only compiler vers
C:\Users\frank> mkdir someproject
C:\Users\frank> cd someproject
C:\Users\frank\someproject> dkml init

# PowerShell only
C:\Users\frank\someproject> (& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ }

# Command Prompt only
C:\Users\frank\someproject> for /f "tokens=*" %i in ('opam env') do @%i
```

To learn more about Diskuv OCaml, see the [official Diskuv OCaml documentation](https://gitlab.com/dkml/distributions/dkml).

## Install Platform Tools

Now that we've successfully installed the OCaml compiler and the opam package manager, let's install some of the [OCaml Platform tools](https://ocaml.org/docs/platform), which you'll need to get the full developer experience in OCaml:
Expand Down
2 changes: 0 additions & 2 deletions data/tutorials/getting-started/1_02_your_first_ocaml_program.md
View file
Open in desktop
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not clear to me.

  • Are the examples working with DkML 2.1.0?
  • Are the examples working with WSL?
  • Are the examples working with Cygwin?

We should be explicit about what is working or not.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested it with DkML 2.1.0 and it works. So, I removed the "OCaml DKML installer due to a dependency issue" DkML-specific comment.

This is a PR for DkML 2.1.0. I don't think I should be on the hook to test WSL2 and Cygwin. Hopefully ocaml.org uses MDX so the examples can be tested in CI. If you do have CI, it is straightforward to add DkML to CI.

Side-note: I did nothing to fix the issue because I was completely unaware of that comment. It is weird that is works, and that makes me highly suspicious of the DkML-specific comment. I suspect that the comment was really for Dream (next side-note). Hopefully we can file issues in the future if there really was a problem with a simple PPX.

Side-note 2: The earlier Dream example does not work with DkML. But we've already discussed in #1962 that Dream has a huge dependency cone and to come up with alternatives.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, that's clear, thanks a lot. Maybe we could say something like this:

Note: This example was successfully tested on Windows using DkML 2.1.0

Copy link
Contributor Author

@jonahbeckford jonahbeckford Mar 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds confusing to the user ... in particular, it begs the following questions:

  1. How do I tell what version I am on?
  2. Why doesn't every example tell me which versions, operating systems and distributions it was tested on?

It seems like a good addition as an HTML comment for ocaml.org maintainers. Is that what you meant?

EDIT: In the interests of time, I added it in with some language on how to check the version. Since I know of at least one user today who was messed up by not having this PR, if you have more minor suggestions can you just add them and submit? Thx.

Original file line number Diff line number Diff line change
Expand Up @@ -302,8 +302,6 @@ Let's assume we'd like `hello` to display its output as if it was a list of stri
$ opam install ppx_show
```

**Note**: This example does not work yet on Windows with the OCaml DKML installer due to a dependency issue. To run it, advanced users could switch to Cygwin or WSL2. However, even if you do not run it, it's still a good idea to read the rest of the section to see how it works.

Dune needs to be told how to use it, which is done in the `lib/dune` file. Note that this is different from the `bin/dune` file that you edited earlier! Open up the `lib/dune` file, and edit it to look like this:
```lisp
(library
Expand Down
2 changes: 1 addition & 1 deletion data/tutorials/getting-started/2_00_editor_setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Pressing the key combination <kbd>Ctrl + Shift + P</kbd> opens a modal dialog at

### Windows Users

If you used the Diskuv OCaml (DKML) installer, you will need to:
If you used the DkML distribution, you will need to:
1. Go to `File` > `Preferences` > `Settings` view (or press `Ctrl ,`)
2. Select `User` > `Extensions` > `OCaml Platform`
3. Uncheck `OCaml: Use OCaml Env`. That's it!
Expand Down
16 changes: 8 additions & 8 deletions data/tutorials/getting-started/3_01_ocaml_on_windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,19 @@ description: >
category: "Resources"
---

There is a new [Diskuv OCaml][DKML] ("DKML") Windows
installer that we recommend for new users. However, while [Diskuv OCaml][DKML] has a modern OCaml 4.14.0 compiler,
There is a [DkML] Windows
installer that we recommend for new users. However, while [DkML] has a modern OCaml 4.14.0 compiler,
it does not track the latest OCaml compilers. We will officially support Windows as a Tier 1
platform with a [major release of opam](#opam-22) in the coming months, and it will be compatible with
DKML installations.
DkML installations.

[DKML]: https://github.com/diskuv/dkml-installer-ocaml#readme
[DkML]: https://gitlab.com/dkml/distributions/dkml#installing

Our guidance is when you want:

* **To only run, and not develop, applications**, use [Docker](#docker-images) or [WSL2](#wsl2)
* **To develop applications and have some familiarity with Unix**, use [opam-repository-mingw](#opam-repository-mingw)
* **To develop applications and care more about stability and ease-of-use than the latest compiler**, use [Diskuv OCaml](https://diskuv-ocaml.gitlab.io/distributions/dkml/)
* **To develop applications and care more about stability and ease-of-use than the latest compiler**, use [DkML](https://gitlab.com/dkml/distributions/dkml#installing)

The guidance is based on the availability table below:

Expand All @@ -31,9 +31,9 @@ The guidance is based on the availability table below:
│ Tier │ OCaml Version and Environment │ Support and Availability │
│ ------ │ --------------------------------- │ ------------------------------------------- │
│ Tier 1 │ OCaml 5 with Opam 2.2 │ Full support. Coming in the next few months │
│ Tier 2 │ 4.14.0 with Diskuv OCaml │ Supported on select versions. Available now │
│ Tier 2 │ 4.14.0 with DkML │ Supported on select versions. Available now │
│ Tier 3 │ 4.14.0 with opam-repository-mingw │ Deprecated. Available now and mostly works │
│ Tier 3 │ 4.14.1 with WSL2 │ User supported. Available now │
│ Tier 3 │ 4.14.2 with WSL2 │ User supported. Available now │
│ Tier 3 │ 4.14.1 with Docker | User supported. Available now │
╰──────────────────────────────────────────────────────────────────────────────────────────╯
```
Expand Down Expand Up @@ -92,7 +92,7 @@ easier way to get a working Windows environment on your machine.

### Visual Studio Code on Windows

**If you use the recommended DKML installer**, you will need to:
**If you use the recommended DkML installer**, you will need to:

1. Go to `File` > `Preferences` > `Settings` view (or press `Ctrl ,`).
2. Select `User` > `Extensions` > `OCaml Platform`.
Expand Down
2 changes: 1 addition & 1 deletion data/tutorials/platform/bp_06_configuring_your_editor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Pressing the key combination <kbd>Ctrl + Shift + P</kbd> opens a modal dialog at

### Windows Users

If you used the Diskuv OCaml (DKML) installer, you will need to:
If you used the DkML distribution, you will need to:
1. Go to `File` > `Preferences` > `Settings` view (or press `Ctrl ,`)
2. Select `User` > `Extensions` > `OCaml Platform`
3. Uncheck `OCaml: Use OCaml Env`. That's it!
Expand Down
27 changes: 20 additions & 7 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,7 +120,7 @@ Layout.render
</h2>
<ol>
<li>
<h3>Use the Diskuv OCaml ("DKML") Windows installer</h3>
<h3>Install the DkML Windows distribution</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.
Expand All @@ -129,16 +129,29 @@ Layout.render
provided in the <a href="<%s Url.ocaml_on_windows %>">"OCaml on Windows" guide</a>.
</p>

<div class="not-prose">
<a class="btn gap-2" href="https://github.com/diskuv/dkml-installer-ocaml/releases/download/v1.2.0/setup-diskuv-ocaml-windows_x86_64-1.2.0.exe">
<%s! Icons.download "h-6 w-6" %> Download DKML Installer
</a>
</div>

<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_snippet.render ~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_snippet.render ~id:"install-winget-git" "winget install Git.Git" %>
<%s! Copy_to_clipboard_snippet.render ~id:"install-winget-dkml" "winget install Diskuv.OCaml" %>

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

<%s! Copy_to_clipboard_snippet.render ~id:"dkml-init-system" "dkml init --system" %>

<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>
</ol>

Expand Down
Loading