Documentation request: Finding the root of the current workspace

Hi there,

Thanks for the hard work on dune.

TL;DR: should %{project_root} and %{workspace_root} expand to absolute paths?

Context: I'm trying to generate part of a dune file; the documentation suggests this: (rule (with-stdout-to dune.inc.gen (run ./gen-dune.exe))).

Assume gen-dune.exe is compiled from gen_dune.ml, and is used to generate one rule per .xyz file in the project's root.

gen_dune.ml has to enumerate .xyz files in the project's root, but it's not trivial for it to know where that is, since its run from the build directory. Changing the rule to (rule (with-stdout-to dune.inc.gen (run ./gen-dune.exe %{project_root}))) runs gen-dune.exe with argument ., which is the path from gen_dune.ml, not from gen-dune.exe, nor an absolute path.

Is there a way to get an absolute path? Am I doing something wrong?

Thanks!

Start with the documentation for %{project_root}, %{workspace_root}, and the shown rule using gen-dune.exe. Check how these variables are expanded when the executable runs from the build directory, then clarify the supported way to locate the project root and what path form users should expect. Update the relevant documentation and example so the expected behavior is unambiguous.