OCaml real pain points

[threepwood]

@nojb

While I have heard people periodically complain about different aspects of how Dune works, often these complaints are made in unstructured form in the middle of random threads in various forums. This makes it rather difficult to convert them into concrete suggestions and/or proposals for improvements. A more constructive way to go about it would be to open an issue in GitHub - ocaml/dune: A composable build system for OCaml. (and/or, even better still, engage with the dev team and propose a fix).

I have to say since I started this discussion, I just said “I don’t like using dune” as an “ocaml pain point”, that doesn’t necessarily mean I think dune can be improved, because I think in many cases the thing I don’t like is a fundamental design choice. And of course I’m thankful the developers made something at all and maintain it and they’re entitled to design it the way they like, but it so happens it doesn’t suit my use well and it feels reasonable to say so in the “pain points” thread. Not having the time or expertise to write an alternative build system from scratch I’m at best vaguely hoping to encourage whoever might try their hand at some point. In the same way I might say I don’t like that if-without-else statements don’t have terminators or that Set.Make(Int).fold and List.fold_left have different argument orders, I’m not expecting it to change any time soon.

To talk about the concrete issues, at least these things I don’t like seem to me to be non-negotiable parts of the design:

• S-exps
• The use of dune files in every directory (I plead guilty to not having written down what usability issue I hit when I tried using subdir)
• The requirement for dune-project and opam files and having a notion of package and the public_name stuff (like this error), what I call the “bureaucratic” aspect of dune
• Related, all the rules, aliases, renaming patterns (dune exec ./file.exe where ./file.exe is not a real file) that are built-in instead of being easily configurable or extensible
• The fact you have to go through dune to call code which makes it hard to use for informal script-like things or multi-language projects

Here are things that I think ought to be improvable but in practice I’m not sure what one can do about it from the outside:

• Warn-error. This comes up on here all the time. According to the discussion here, the developers don’t want to change it because they think they need a system to save all warnings first. For my personal use this is completely unneeded but I’m not even a professional user, I’m not in a position to convince anyone here.

• The documentation. I don’t have any sort of expertise to write doc about dune, but also, my impression is that the developers are totally aware that the documentation is very lacking. See for instance this post (and the whole thread — btw the list of stanzas is still not sorted on the website, even though there is a PR that claims to have sorted it, I’m rather confused). In this post from 2023 it is mentioned that a rewrite effort is ongoing, as far as I can tell this has been very partial since the general aspect of the doc has not changed, especially the reference part.

  My issue with the documentation is the general lack of discoverability (due to the unstructured dump of esoterically-named options) and the lack of precise, complete description of what this or that does, which often forces you to experiment to find out (here is a recent example of a question I had to experiment to answer). Again I think the developers know, the first issue of discoverability especially is brought up in the thread I linked many times.

With all that said, as part of working on a bigger project right now I am compiling a list of usability issues I hit on the way (with dune or other things) that I will try to act on or at least post about when I am done.