[ocaml-platform] Unique file names

[Alain Frisch]

On 03/05/2013 03:06 PM, Yaron Minsky wrote:
> On Tue, Mar 5, 2013 at 5:10 AM, Alain Frisch <alain.frisch at lexifi.com> wrote:
>>   - You need to adapt all tools (ocamldep, ocamldoc and also third party
>> tools), and this might change their interface (e.g. for ocamldoc, you will
>> need to specify for each source file what's its implicit prefix).
>
> I agree that this would have to be solved, though I think this is
> worth doing.  You'd need some kind of lookup from the easy to find
> file (e.g., core_list.cmi) to the hard-to-find file (list.ml).

Do you agree that this requires not only a lookup algorithm, but also a 
way to specify to ocamldoc, file per file on its command-line, which 
"prefix" to use?  At least this is required if you want to allow using 
ocamldoc to generate a single documentation for module spanning several 
"namespaces" at once.

> This doesn't seem like much of an issue, since you can feel free to
> simply use unique file-names if you'd like to.  This is merely an
> option for developers who want to organize things in this way.  In the
> end, I think it won't matter most of the time, because I hope that as
> we develop better build tools, they will handle this stuff
> automatically.
 > But if people want, they can name things uniquely and use simple
 > Makefiles.

Again, I'm going to illustrate that we do crazy and non-standard stuffs 
here, but the way we integrate third-party libraries into our project is 
to take their source files and create an very simple OMakefile (usually 
2 or 3 lines) to integrate them in our global tree.  I understand this 
is a rather uncommon scenario, but it is a useful one, at least in our 
context because (i) we want everything to be under the control of our 
revision system so that we can very simply extract a full source tree 
corresponding to a distributed version of our application; (ii) we 
regularly rebuild the whole tree (e.g. as soon as we do a release, we 
recompile everything from sources) and being able to benefit from global 
parallel build is nice; (iii) released build specifications don't always 
work nicely under Windows and/or don't allow to inject custom 
compilation flags (e.g. to enable new warnings); (iv) having everything 
under the control of the same build system makes it easy to insert debug 
statement in the middle of a library and recompile (only) the necessary 
dependencies; (v) we don't use ocamlfind but recreated something similar 
within omake, but this assumes that everything is under the control of 
omake.

Anyway, I'm not trying to convince anyone else that this is a good 
strategy, only that it is currently in use in a least one non-trivial 
code base.  So the assumption that the choice of filenames for source 
code is purely on the developer side does not completely hold (I admit 
it will not be very difficult to rename files upon import if we need to).

>>   - You can deploy compiled files for several libraries in the same
>> directory, but not the corresponding .mli files (for documentation purpose).
>
> I think this is fairly poor practice.  Directory structures are useful
> anyway, and one might as well encourage their use.

I'm not claiming this is good practice in general (and I don't think we 
do that, specifically), but people should realize that some proposals 
will put pressure on many tools and will disallow some usage scenario 
currently in use and which they are not even aware of.  Just as an 
example, we have developed a simple IDE for OCaml code to be embedded in 
our application; it assumes that ocamldoc has been applied at once to 
all distributed libraries and that all the resulting HTML files are in a 
single directory.  I guess this is a rather non-standard use of 
ocamldoc, but it works quite well for us.  We will update our IDE and 
our use of ocamldoc if required, but when evaluating the respective pros 
and cons of various proposals, the cost of adapting all existing tools / 
usage scenarios should not be neglected (and people have little way to 
know about the amount of work required for those adaptations).


Alain