The target audience is developers learning OCaml. No functional programming knowledge is assumed. However, it comes after the “Get Started” and “Language” series.
Thanks to @ostera, @yawaramin, @jbe, and @lindig for their feedback. Share yours on GitHub, here, or use the “Open an Issue” and “Contribute” links at the bottom of the pages. We’ve recently received and merged many contributions; we’d be happy to add even more.
As for the rest of your work, thank you for these tutorials. Here are my 2 cents (somewhat opinionated).
I think modules and functors, as they are constructs of the language, should be presented independently of dune (and also of utop). I do think most of your examples would be fine with just using plain ocamlc/ocamlopt, if the goal is to explain the language constructs. For modules of course, an important part is their interaction with files and how .ml/.mli files map to modules and signatures.
And it would be fine (imho) if at the end of module tutorial you ended up with 4 ocamlc lines to build your example. The conclusion could be that yes, modules are a fine language construct, but compiling everything by hand is tedious. There are various ways to simplify this:
Makefiles (with some tutorials, probably in the advanced concepts section. They would have the virtue of explaining how to do things “from scratch” and what you can do if, for some reason, you cannot use dune for your project, or integrate with a project not yet using dune)
dune. Here, i think it is important to highlight (even more than you did) that dune helps you organise your code by allowing you to group together several module files under a common toplevel name and that’s what dune calls a library. dune can also build programs (executable). And libraries and executables can be grouped into a package, so that they can be distributed together.
I think this is important to make this distinction and explain these concepts (even to newcomers). Of course what you don’t want to explain is how dune achieves this (module aliases, Foo__A.ml …). And explain that they are a convention (used by dune) to organise OCaml programs, beyond what the plain compiler defines. Because (unfortunately) these concepts are overloaded in our ecosystem (the compiler also has a notion of library, cma/cmxa files, that is very much not the same thing) and newcomers could be confused when they read other materials referring to these other concepts.
This would have the advantage that the module and functor tutorial would be (as much as possible) dune independent the same way the List and Array tutorials are.
Very wrong. The OCaml language does not include any “library” concept.
Then partway through we get
" ```
$ opam exec – dune exec nube"
Wtf? OPAM, really?
Here’s another doozie: “In OCaml, each source file is compiled into a module”. What does that even mean? "Compiled into a module "? This kind of language is guaranteed to flummox anybody since , well, it makes no sense. An *.mli file is a source file. Does it get “compiled into a module”?
Very wrong. The OCaml language does not include any “library” concept.
This is an overloaded word. How do you call ocamlc/ocamlout output when using the -a option? I read library in the manual.
$ opam exec – dune exec nube"
Wtf? OPAM, really?
This is ugly, I agree. But it works in Windows, macOS and Linux without tweaking environment variables (not very nice either, in my opinion). That’s why it’s used.
Here’s another doozie: “In OCaml, each source file is compiled into a module”. What does that even mean? "Compiled into a module "? This kind of language is guaranteed to flummox anybody since , well, it makes no sense. An *.mli file is a source file. Does it get “compiled into a module”?
Wrt to dune libraries: I think it would be helpful to explain private_module. The dune docs say such modules are “marked” as private. But that’s a dunism, the language does not distinguish “private modules” in any way. So what exactly does that mean, and how are such modules related to the archive/lib generated by dune library stanzas?
Similar for modules_without_implementation (which is an oxymoron btw).
I don’t see that this is the case? With (wrapped false), I still get a .cma file. It is just structured differently, without an extra module being added to wrap and “namespace” the individual compilation units.
In any case, I don’t see what is so scandalous about calling a “library” what is called exactly that by ocamlc’s documentation.
That’s good feedback for the dune docs, and obviously feel free to follow up on them, but in this thread can we keep the feedback to the OCaml website introductory docs mentioned in the OP please?
My bad, what was I thinking? (wrapped false) cancels the namespacing, not the archiving. No scandal about library/archive, just a point of info that may be useful with respect to other build systems.
One missing point is First-class module… yes, it is an advanced point about modules, but one can be exposed when using caqti for example. Should I propose something ?
Of course, you’re more than welcome to propose anything. Do you see this as a section in an existing tutorial or the basis for an advanced modules & functors tutorial. There’s plenty to discuss there.