It’s one thing to recommend dune as a build system. No prob.
It’s another thing entirely to teach newcomers that dune is OCaml. It is not. Emphatically not. It is in fact radically different. The build model dune presents is a grotesque distortion. Even worse the distortion is intentional.
If you really want to help newcomers, provide simple makefiles or shell files for basic examples. After all learning a programming language always involves more than just the language, it also involves how to distribute code across files and build stuff. Imho you do a terrible disservice to new users by pretending that the build discipline of OCaml should just be ignored.
Nice. But it doesn’t explain why or when you’d want to use lower building blocks.
Also, missing is an explanation of how to integrate a ppx, an example where it all "fits together” and how to bring back LSP support if at all possible
It’s another thing entirely to teach newcomers that dune is OCaml. It is not. Emphatically not.
This is not our intent. If what we’ve written sounds this way, it’s a bug that needs to be fixed. In this, we genuinely and candidly need your help to amend the text in a way that doesn’t create that impression. We have a hard time guessing how what we write is perceived.
If you really want to help newcomers, provide simple makefiles or shell files for basic examples. After all learning a programming language always involves more than just the language, it also involves how to distribute code across files and build stuff. Imho you do a terrible disservice to new users by pretending that the build discipline of OCaml should just be ignored.
I have a preference towards understanding how things work underneath before starting to use anything which does the job for me, no matter how helpful it is. I believe in learning bottom-up, for instance ocamlc first, dune second. However, going the other way around appeals to those willing to “start with the real thing”. There seem to be many, and admittedly, it works fine too.
That’s why we’ve decided to use Dune as the default build tool throughout the tutorials and have everything related to ocamlc and ocamlopt in a dedicated document. That implies learning how to build libraries only using Dune first. But if it feels like black magic, that’s not good. I’m convinced we can keep this structure and remove that impression.
You seem to have a very strong anti-dune bias. This makes taking your comment seriously very difficult.
Every competing language out there has easy to use tooling. Rust has cargo, python has pip, haskell has cabal and stack, etc. If you present OCaml as needing makefiles or shell files, you’ve automatically lost the inquisitive reader. Programmers want to get started with making working programs as fast as possible on every major platform, and not have to worry about the tooling.
That’s valid for a very specific type of newcomers, the ones already familiar with a unix like toolchain who will will mentally parse a Makefil without even thinking about it.
Showing someone who is not familiar with make a Makefile that calls to 5 different command line tools is not helpful.
Teaching them a make base workflow when the first few projects they’ll look up on Github will be using dune is not helpful.
To take an example in a different language, without thinking to hard, I can probably come up with 5-6 build tools for Java. Most of them will try very hard to hide from you that you are in fact calling javac to compile your program. But a newcomer document must use maven, not matter how different it is from the actual compilation pipeline.
“Dune is a very opinionated way of compiling OCaml programs, and there are alternatives” should be at least part 2, if not later, of the newcomers introduction.
Why do this? To complement a language tutorial with a tutorial covering the tools of the std distrib (compilers, ocamlobjinfo, ocamldep, etc.) without the noise of a build system.
Ideally only the those tools would be used. But in some of the examples noted above use ounit2 from OPAM, which requires the introduction of ocamlfind (findlib). That (findlib etc) probably merits a separate tutorial, as does OPAM itself.
This would presumably be helpful even to those who decide they want to use Dune, since it would explain why funny filenames like Foo__a.ml get generated.
The idea is to just show how the compiler command line works. Shell scripts would work for that. Makefiles would not need to call 5 different cmd line tools.
Dune is the build tool officially supported by the OCaml Platform. Forcing newcomers to learn something else in the OCaml website docs would be doing them a disservice imho. Look at the Go and Rust documentation. They don’t teach newcomers how to compile individual files with make. They teach the go and cargo tools.
I think the disconnect may be in who we are thinking about as this famous newcomer. For me, they’ve seen an interesting post on twitter/blog about OCaml. They peeked around, played with something like the dream examples and intrigued they decided to read a bit more.
I honestly don’t understand why we would talk to them about ocamlc, they are not interested. They want to know how they can use the language to achieve some higher goals, not learn the idiosyncrasy of the toolchain.
To do whatever they actual want to do with OCaml they will be using a build system, and that build system most probably will be dune. Let’s help them achieve that goal.
Is there value in understanding how these tools actual work? Absolutely! But have a page for that and let the people interested self select.
This discussion has diverged to another topic (“Should dune be taught in beginner tutorials”) and is not providing the useful feedback requested by the OP.
That’s a reasonable way to get started. Personally I find that the dune stuff is ok, but it clutters the tutorial. But clearly you need to address the use of Dune in some manner. One option would be the common method of providing a set of source and build files for the tutorial, liberally commented, and then just link to it. The explanation of the dune stuff could go in the dune file itself, as comments.
I don’t have anything against using dune. But I don’t like how dune related concepts that have nothing to do with the language appear out of the blue. And, since you cite rust, I think the OCaml tutorials could have roughly the same approach.
installing
simple hello world with ocamlc (and present ocamlopt also, as well as ocaml repl)
simple hellow world with dune and what it is and what it can do for you
All these are already written and mostly fine. What changes between the OCaml tutorials and the ones in the rust book is that although cargo is used for all following tutorials on basic language features, it is inconspicuous. It’s just cargo new my_new_concept, then edit src/main.rs then cargo run. No cargo concept is introduced until much much later (unit tests, advanced examples with crates etc…) and at no point are you asked to edit .toml files for simple tutorial programs.
I think the same can be done for OCaml’s tutorials. dune project init modules_tutorial, edit bin/main.ml, add other files in bin (a.ml, b.ml) and just dune exec bin/main.exe. No mention of package, public_name, libraries, executable and what not and no mention of editing dune files. That would actually be a no fuss, 0 conf, get started on a new OCaml concept.
I like this suggestion. No need to mess with config files in the beginning, just get dune to init the files for you with any needed dependencies. Thumbs up
