Using Dream as demonstrated in the tutorial is failing on Windows

[heathhenley]

Trying to follow along with https://ocaml.org/docs/your-first-program#installing-and-using-modules-from-a-package - when I got to the install / run dream part, I ran into some problems on windows.

Here's the versions:

C:\dev\ocaml\hello2>opam --version
2.2.0~alpha0~20221228

and OCaml 4.14.1 on Windows 11 with dune 3.6.2.

I'm getting an issue with pkg-config if I try to install dream with opam:

#=== ERROR while compiling conf-pkg-config.3 ==================================#
"pkg-config": command not found.


<><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
┌─ The following actions failed
│ ▼ fetch camlp-streams                5.0.1
│ ▼ fetch caqti.1.9.0, caqti-lwt.1.9.0
│ ▼ fetch cppo                         1.6.9
│ λ build conf-pkg-config              3
└─

I believe the same issue is reported on the Dream repo here: aantron/dream#313 and also on opam:
ocaml/opam-repository#24851

I'm just going to switch to using WSL to work through the tutorials if this doesn't turn out to be an issue between the keyboard and chair. If it is really just a Windows support thing, maybe a note should be added where the tutorials use Dream so that others newbies don't hit this snag? It's a bummer to run into this while trying to learn OCaml, and I would be happy to PR it if it's something you think is useful.

Confirmed the hello world dream tutorials example is working using WSL on Windows instead.

[cuihtlauac]

Hi @heathhenley, sorry to hear about the bad experience in Windows. Honestly, this was not tested under Windows; you're the first to try running this in Windows. Thanks for letting us know about this issue.

Yes, a disclaimer may help. If the second part of this tutorial works in Windows, the others will too. "Your first OCaml program" is the only tutorial that requires installing Opam packages; the other only needs vanilla OCaml.

[sabine]

We have to change to a different code example anyways, since the "Getting Started" and "Language" sections are not meant to use packages from the OCaml ecosyste. That should reduce the dependencies and risk for such breakage a lot.

[heathhenley]

We have to change to a different code example anyways, since the "Getting Started" and "Language" sections are not meant to use packages from the OCaml ecosyste. That should reduce the dependencies and risk for such breakage a lot.

It looks like the goal of this section was to demonstrate how to install packages using opam, and there is also ppx_show used in the next section (haven't tried on windows yet). Is there some other package you think is better to use here? Or are you suggesting removing these sections / introducing opam install elsewhere? If you have some idea of what you would like to see I would be happy to take a crack at it.

[sabine]

I think this requirement is in conflict with what people need. People need to know how to install a package from opam and how to use a ppx. When we introduce a new "cookbooks" section that explicitly encourages content relating to packages from the ecosystem, this could be moved into a cookbook entry ("using an opam package" / "using a PPX" / "printing an arbitrary value").

I think a possible improvement right now would be to have a package with less dependencies, ideally one that is very established, or belongs to the OCaml Platform tools, or to the compiler.

[heathhenley]

Ok so something like removing the "Installing and using modules from a package " and "Using the preprocessor to generate code" sections from "Your first program" tutorial, and instead, opam installing and demonstrating using a module from a different package that is well supported. If that is correct, I'll take a crack at it. Are there any packages that you think are particularly useful for a beginner learn about here?

[sabine]

I wouldn't remove anything right now, since we can't move this content elsewhere yet. Just find a better package. (Sorry, don't know one off the top of my head.)

[cuihtlauac]

Are there any packages that you think are particularly useful for a beginner learn about here?

Actually, it's all about finding the right package. Ideally, we need something that is easy to use, has an intuitive purpose, does something useful, in a cool way, without too many dependencies and is portable. La perle rare

The goal is not to teach a package; the goal is to show that installing packages for ocaml is not different from NodeJS or others.

Let's say Dream was not the dream solution, just something that allowed writing fairly easy to understand oneliner.

[heathhenley]

Just commenting to note it - I got to testing the part with ppx_show and also had trouble getting it to run on windows, I didn't really look into this time, just switched over to WSL2:

<><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><>┌─ The following actions failed
│ ▼ fetch stdcompat 19
└─
╶─ No changes have been performed

[cuihtlauac]

Damm, it's serie noire

[heathhenley]

Do you think using odoc instead of Dream as a simple example might make sense? It's not as cool of an example as a webserver but I assume it's more portable because it's part of the platform tools. I confirmed it definitely opam installs on windows but haven't tried anything with it yet.

[cuihtlauac]

Do you think using odoc instead of Dream as a simple example might make sense? It's not as cool of an example as a webserver but I assume it's more portable because it's part of the platform tools. I confirmed it definitely opam installs on windows but haven't tried anything with it yet.

We need to address documentation generation. This is missing in the introduction docs. This will require installing and using odoc.

The complete guide: https://ocaml.org/docs/generating-documentation also needs to be checked and refreshed.

In “1st Program”, it would be nice to install a package involving some code writing.

[cuihtlauac]

@jonahbeckford do you have an idea of a package that could replace Dream in "Your 1st OCaml Program" tutorial?

We're looking for something

• Working in Linux, macOS and Windows
• Without too many dependencies
• Easy to understand what it does
• Easy to use
• Which allows writing a short example of code using the API
• Possibly fun

[jonahbeckford]

My students liked Bogue, although that won't work on the web. Lambdasoup, qrc and vg would be good as well for hands-on feedback. (Haven't tested vg but I think it works) Get Outlook for Android<https://aka.ms/AAb9ysg>

…

________________________________ From: Cuihtlauac Alvarado ***@***.***> Sent: Monday, January 22, 2024 11:54:56 PM To: ocaml/ocaml.org ***@***.***> Cc: Jonah Beckford ***@***.***>; Mention ***@***.***> Subject: Re: [ocaml/ocaml.org] Using Dream as demonstrated in the tutorial is failing on Windows (Issue #1962) @jonahbeckford<https://github.com/jonahbeckford> do you have an idea of a package that could replace Dream in "Your 1st OCaml Program" tutorial? We're looking for something * Working in Linux, macOS and Windows * Without too many dependencies * Easy to understand what it does * Easy to use * Which allows writing a short example of code using the API * Possibly fun — Reply to this email directly, view it on GitHub<#1962 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AREG4PKWZVOZECHMELGXFATYP5UFBAVCNFSM6AAAAABB5V64VCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMBVGQ3TKOBYGQ>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[cuihtlauac]

Vg sounds like an excellent idea. @heathhenley, do you want to try it in Windows?

[heathhenley]

Vg sounds like an excellent idea. @heathhenley, do you want to try it in Windows?

Yes I'll take a crack at it!

Maybe something like:

• switch dream for Vg example (provided it runs on Windows)
• add note to preprocessor example about Windows so noobs like me aren't discouraged

[heathhenley]

Didn't forget about this, but I had some problems with opam on windows, more or less, it's installing vg and prereqs properly, says they're installed if I check the version, but cannot find the packages when I try to use them. So I think I messed up my windows environment, going to reinstall and just start over this weekend. Everything just works on WSL Ubuntu though, so at least that's cool.

Another thing - even the minimal Vg examples are pretty verbose (in this context) - is it still a reasonable option? Maybe I'm missing something.. https://erratique.ch/software/vg/doc/image_howto.html

[jonahbeckford]

The tutorial is twelve (12) lines long versus sixteen (16) lines long. And three (3) of those twelve (12) lines long are unnecessary ... there is no need to wrap things in a function.

The more problematic things are:

1. Need a web browser or something similar to see the .svg files
2. Uses polymorphic variants.

Polymorphic variants is not good for an intro in hindsight.

[heathhenley]

What am I missing - the original tutorial requires installing and importing Dream, same steps for whatever package is chosen and then dropping in a single line:

let () = Dream.(run (router [ get "/" (fun (_ : request) -> html Hello.En.v) ]))

which compared to the Vg examples is easier to grok for a beginner, in my opinion.

Good point about the browser and polymorphic variants (yeah I need to look that up 😁).

[cuihtlauac]

Maybe vg wasn't such a great idea :-( There is a famous quote on how hard it is to make simple things, isn't it? :-)

@jonahbeckford: what's the simplification you have in mind?

[F-Loyer]

We have plenty of simple packages with not much dependencies.

See https://github.com/ocaml-community/awesome-ocaml

Some hints (quite simple libraries, not much dependencies):

• sexplib
• yojson

I could also think of "re" (regular expression with different available syntaxes, and also, IMHO, a better API than Str which works with a mutable global variable used by matched_group function to access the whole result of the pettern matching), but it had less added value on Str.

But I have to admit they are not as fun than a dream server.

ocamlnet is not that simple, but I guess that a simple example should be done (HTTP client).

Note: On Windows, it is not really the number of dependencies which matters, but the dependency on conf-... package(s) which opam don't know how to deal with. (On Linux, they are mapped to an apt get or something like this). Here dream has a conf-libssl. I guess there is a way to deal with such dependencies (with the help of vcpkg), but it would be a subject of a very focused article. Packages built with ctypes are also tricky because of the way the linker export symbols.

[heathhenley]

Thanks for the suggestions! I PR'd one possible option with Yojson - lmk if you think it's useful or not, or if it would be better to use a different package.

[sabine]

Resolved by #2093