Comment author: spyder

I've just found #5752 which indicates the original fix hasn't been released yet. I did a build of trunk and my particular issue still exists.

Comment author: @gasche

On my machine, adding the -r option to ocamlbuild, or adding an empty _tags or myocamlbuild.ml (which is another way to enable recursive traversal by default) makes your code compile fine.

Comment author: spyder

That does fix it, but I was avoiding recursive traversal because I thought that would add the entire triangle subfolder to the namespace. However when I attempt to use module Green within main.ml, it gives me an error even with -r.

What are the rules around recursive traversal?

Comment author: @gasche

There is a different between "include" and "traverse" that is more or less explained in the manual ( http://caml.inria.fr/pub/docs/manual-ocaml/ocamlbuild.html#sec388 ):

• "traverse" controls which directories ocamlbuild considers to be "part of the world" (eg. hygiene), a directory that has not been traversed will not be used for anything, nor its _tags file inspected.
• "include" affects the naming of compilation units, by letting you use unqualified instead of directory-qualified module names to indicate units to ocamlbuild. For example, a file foo/lib.mllib will contain "bar/Toto" to refer to foo/bar/toto.{ml,mli}, unless foo/_tags has ": include" (or they're both included in the same parent directory from which compilation is run)

"traverse" is set to true whenever there is either a _tags or myocamlbuild.ml file at the directory from which you launch the ocamlbuild command, and false otherwise -- to avoid the "ocamlbuild takes hour to do nothing if I mistakenly run it from my /home" effect.

Comment author: spyder

ok. That's a little bit confusing, I didn't understand include vs traverse at all from my reading of the docs until you pointed it out. But I can see the difference now.

Now that I know what's happening, I added "true: traverse" to my src/_tags file (not present in the example) which also solves the problem without asking ocamlbuild to traverse my entire project.

Comment author: @gasche

Thanks for the feedback. If you have concrete suggestions for a clearer rewording of the documentation, I'm all ears.

Comment author: spyder

That's a tough one. I don't think I've seen any other build system that can traverse for dependencies to build with but not include them in the namespace; the concepts are usually linked and that's what I expected when I was reading the docs. They didn't really explain how traversal was different to include, so I assumed they were basically the same.

You could copy/paste what you wrote here to the start of the subdirectories documentation and it would be a massive help :)

Comment author: @gasche

The distinction is important in OCaml if/when several subdirectories have compilation units of the same (base)name: the compiler itself, but also the tool around it, will react very badly if a single "compilation run" see them at the same time. With the current design, you may have a prog.x86.mlpack that refers to x86/Backend, and prog.x86-64.mlpack that refer to x86-64/Backend, with both subdirectories traversed but not included at each run.

Comment author: spyder

I'm getting it now :)

These are all concepts that are probably familiar to experienced OCaml developers but I'm still very new, having spent most of my career developing in Java. For someone like me that traversal vs include explanation you gave above would be invaluable to include in the docs.