document what is considered in "source files"

[Khady]

https://dune.readthedocs.io/en/stable/concepts/dependency-spec.html#dependency-specification

(source_tree <dir>) depends on all source files in the subtree with root <dir>.

The documentation of the dependency specification says that source_tree allows to depend on source files, but I couldn't find in the doc what dune considers to be a source file.

[Alizter]

There is an entry in the FAQ about this: https://dune.readthedocs.io/en/stable/faq.html#files-and-directories-whose-names-begin-with-period-are-ignored-by-source-tree

We could probably link it from the source_tree entry. Basically, anything that is a file not generated/built by dune is a source in your project. When building these all get "copied" into _build/default and built there.

cc @emillon

[Khady]

Thanks for the link. I'd say that the FAQ doesn't really answer the question. It specifies some things that are excluded, not that everything else is taken.

And unrelated to the original issue, but the FAQ entry only mentions how to accept hidden dirs, not how to accept hidden files.

[Alizter]

@Khady It might not be obvious, but it is talking about files and directories in the title. I agree the documentation is subpar and needs improvement however. Here is what needs to be done:

1. We define explicitly what we mean by a source dir/file.
2. Keep the FAQ entry but don't keep it as the primary source of documentation. The information should be in the manual in relevant places (dirs stanza, dep spec, etc.)
3. Add some examples and clear up the wording.

Thanks for reporting this, it definitely needs improvement.