Some struggles with dune and opam and odoc

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)

  1. 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.

  2. 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.

  3. 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)

  4. 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.

  5. 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.

  6. 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)

  7. 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)


Re: #7

I opened an issue about that: Automatically add opam dependencies to dune-project file · Issue #7449 · ocaml/dune · GitHub


FWIW, there is the package opam-dune-lint (GitHub - ocurrent/opam-dune-lint: Ensure dune and opam dependencies are consistent) in the ecosystem which provides part of this functionality I think.

I’ve used it a couple times myself and its been pretty useful.