ocaml
Unclear documentation of project/workspace root
This is #1848 again. The documentation says %{project_root} is the root of your project when it's actually inside _build for hygiene reasons, and I got confused by the docs. I thought I could just read some files that I had in my project but it turned out I needed to tell dune to pull them in as explicit dependencies. I ended up learning about hygiene from #1848 and when I went to read more in the documentation I found it doesn't explain this anywhere. Some more "design overview" in the front matter of the docs could really help with this, but I won't pretend to understand dune well enough to know how to best explain it.
The confusing bit is in the Variables section which says this.
project_root is the root of the current project. It is typically the root of your project and as long as you have a dune-project file there, project_root is independent of the workspace configuration.
Another point I would like to add is that the value of %{project_root} is a path relative to the directory containing the dune file in which it appears; the latter may not be the same as the cwd for commands. Trying to run actions like (run cat %{project_root}/some-file) will not get you what you expect.
