Feature request: good interactions of `(include_subdirs qualified)` and `unqualified`

Desired Behavior

I would want (include_subdirs qualified) and unqualified to interact nicely, describing only what happens to sub-directories.

Example

Let's say we have a project of this shape:

$ tree
.
├── bar
│   ├── baz
│   │   ├── baaz.ml
│   │   └── baazo.ml
│   ├── bez
│   │   └── beez.ml
│   └── dune
├── dune
├── dune-project
├── foo.ml
└── qux
    └── quux.ml

This project contains two dune files, one at top-level and one in the directory bar. I find more readable to read the names of the OCaml files:

• bar/baz/baaz.ml
• bar/baz/baazo.ml
• bar/bez/beez.ml
• qux/quux.ml

Now let us consider two different ways in which (include_subdirs qualified) and unqualified can be written in the dune files. These two examples are included in the PR https://github.com/ocaml/dune/pull/7629.

Example 1: (include_subdirs unqualified) under (include_subdirs qualified)

In this example, the top-level dune file contains (include_subdirs qualified) while bar/dune contains (include_subdirs unqualified). The latter means that, within the bar/ directory, everything should be seen as if they were at the same level, so we'd see that sub-directory as if it were:

• bar/baaz.ml
• bar/baazo.ml
• bar/beez.ml

Then, at top-level, things should be built in a qualified way, giving therefore:

• Bar.Baaz
• Bar.Baazo
• Bar.Beez
• Qux.Quux

Example 2: (include_subdirs qualified) under (include_subdirs unqualified)

This example is the opposite: the top-level dune file contains (include_subdirs unqualified) while bar/dune contains (include_subdirs qualified). The latter means that, within the bar/ directory, things should be see in a qualified way, so we'd see that sub-directory as it is, with modules Baz.Baaz, Baz.Baazo and Bez.Beez. At top-level, things should be built in an unqualified way, giving therefore:

• Baz.Baaz
• Baz.Baazo
• Bez.Beez
• Quux

Discussions

I think I am basically seeing things as if we were building modules from the leaves of the file tree and deciding as we go up the file tree whether to include the sub-modules in a qualified or unqualified way (or I guess not at all if there is an (include_subdirs no)). I think the semantics of the include_subdirs stanza can be made pretty clear considering that it only applies to how we consider sub-directories. However, it might be a bit of a pain to implement, and I feel implementing the generic way (and the qualified under unqualified in particular) might be tricky.

I suppose it would also make sense to simply reject such a suggestion and to say that there may be only one (include_subdirs) stanza in a part of a file tree. However, the current situation very much allows several such stanzas to inhabit the same file tree, except somehow modules are then not findable. Those situations should probably be rejected with a clean error message instead.

Start by reading the desired behavior and the two examples in this issue, then inspect the referenced PR #7629 for existing experiments. Compare nested (include_subdirs qualified) and unqualified in both directions. Done means the documented module names are produced consistently, or unsupported combinations are rejected with a clean error message.