I’ve been struggling with some dune & odoc stuff and wanted to share my experiences in case there are better ways to do things that aren’t documented.
I’m not sharing the below because I just want to vent, but because I’m using Ocaml more thoroughly as a beginner, and want to help improve the developer experience for others as I enjoy working with the language, despite its frustrations (such as feedback on syntax errors or determining what scope the compiler thinks you’re in)
-
Structuring a dune project into directories is an absolute nightmare. Creating private packages as submodules with well defined boundaries only works if your target is an executable, not a public library. I don’t understand why this limitation exists. I ended up having to define a private package as a public one to keep the code separate, but this introduced other headaches.
-
It’s documented how to include test dependencies like ppx_expect in opam but no way to specify them in dune, so that when you try and set up a new switch without test dependencies, the build fails because you still reference uninstalled ppxes.
-
odoc spits out blank file for a library if you forget to specify a public_name - there should be warning or something (the docs aren’t 100% clear on this)
-
When you give opam a project directory to install the dependencies of, it just picks one of the opam files instead of all them, most importantly without a warning or indication of what it is doing.
-
The odoc syntax is a bit quirky but it’s nice to be able to integrate your API and reference documentation in a fluid way. I wish there was a clearer path for cross referencing documentation between libraries.
-
Code generation projects with dune could be better documented, eg. how to manage cases where you don’t know the names of your target artifacts until runtime. include_subdirs doesn’t seem to be the way to do it, and code promotion doesn’t make sense to me ( for both this use case, and at all, ie I don’t get how you would use it for anything)
-
When you’re generating your opam filled with dune-project, it would be nice to at least get a warning there are libraries you’ve forgotten to specify as opam dependencies that you’ve referenced in your dune files (I wonder if this is even possible)