Use [opam exec -- dune build] rather than rely on [eval $(opam env)]

[jonahbeckford]

TLDR: I'm about to recommend consistently to all DkML users to use opam exec -- dune build rather than ... opam env ... and then dune build. I would like to see if the UX team agrees.

This suggestion is feedback that I've collected from many users about the difficulty on remembering the eval $(opam env) magic. This applies to students I've witnessed using Ubuntu, and also comes through in tickets to DkML Windows users. Worse, on Windows, the syntax is (& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ } with PowerShell and for /f "tokens=*" %i in ('opam env') do @%i with Command Prompt.

Personally, I stopped using that magic invocation a year ago and doing so has improved my productivity.

Here is the latest example of that feedback from another user:

As far as feedback it is less burdensome to use this command vs the old way of doing it. Much easier to remember. But it can also be made easier than this. Following other package managers like npm you could use the npx command to exec stuff.

Let's say we start on https://ocaml.org/docs/your-first-program. The user does dune build and it fails (this was the issue above; the failure reason wasn't as important as the confusion about the correct "path" and "dir" and "env"). Why does the user have to do the eval $(opam env) magic (or its Windows cousins) at all, or even understand what opam switches are?

I know that page links to a section about working within global opam switches but only "When you work on several OCaml projects simultaneously ...". So it is easy to forget, but more important it is unnecessary for a person doing their first OCaml program.

---

PS. I have a major update to DkML coming. The Major changes are listed at https://gitlab.com/dkml/distributions/dkml/-/blob/next/contributors/changes/v2.1.0.md?ref_type=heads. So the installation instructions on ocaml.org will need a revamp.

[cuihtlauac]

Hi @jonahbeckford, thanks for starting this discussion.

PS. I have a major update to DkML coming.

We'd love to update all windows related texts in the install instruction

This suggestion is feedback that I've collected from many users about the difficulty on remembering the eval $(opam env) magic.

I share this feeling. I always disliked that idea. I'm using direnv, and I find it even easier.

Let's say we start on https://ocaml.org/docs/your-first-program. The user does dune build and it fails

I'm sorry, I'm not sure I understand. Are you saying the current instructions are failing in Windows?

P.S.

Do you have any opinion on WSL? We receive feedback from users working on this. Should we mention this too?

[jonahbeckford]

I'm using direnv, and I find it even easier.

Yep, I use direnv as well. Too bad it doesn't work on Windows, and too bad direnv conflicts when opam users also have opam init hooks (ocaml/opam#5486).

---

Let's say we start on https://ocaml.org/docs/your-first-program. The user does dune build and it fails

I'm sorry, I'm not sure I understand. Are you saying the current instructions are failing in Windows?

I am saying it is trivial for the dune build command to fail. When I was teaching OCaml to four students on Ubuntu (before we moved to Windows), one of the main issues was the students forgetting eval $(opam env) at the start of the day ... then dune build would fail. Worse was when they did do eval $(opam env) but from the wrong project directory ... then their project would partially compile but break on the dependencies.

---

Do you have any opinion on WSL? We receive feedback from users working on this. Should we mention this too?

WSL2 is one of those things that is "easy" to get started with, but then the users will curse us when they realize they can only build Linux executables but not Windows executables. And then they install Windows and find their favorite opam libraries do not work on Windows. I know this from personal experience ... async does not work on Windows, and I only found that out 3 months into a project and had to waste a couple weeks rewriting. Most other people would have left OCaml and written a nasty blog article. I try to warn people when I can (the last was 9 days ago: https://discuss.ocaml.org/t/ann-first-release-of-ocaml-bindings-to-the-polars-dataframe-library/13382/11?u=jbeckford).

The core problem is that OCaml does not cross-compile easily from Linux to Windows, unlike other standard compiled languages like C++ and Rust. At best there is https://github.com/ocaml-cross/opam-cross-windows which I've never used ... notice the lack of dune and the reliance on ocamlfind -toolchain arcania that newcomers will find very difficult to navigate.