[ocaml-platform] Unique file names

[Yaron Minsky]

On Tue, Mar 5, 2013 at 11:07 AM, Alain Frisch <alain.frisch at lexifi.com> wrote:
> 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.

I would think you'd need to get the information to ocamldoc, I'm not
really sure how.  I'm actually quite fond of your proposal for
ocamldoc, which is to have ocamldoc information come not from the
source but from annotations of the files that are generated by the
compilation tools.  That would presumably make this question largely
go away, since you would have named those files (cmo,cmx,cmi) uniquely
anyway.

>> 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.

Us too!

> 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.

Indeed, all the same reasons apply here for us.

> 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).

Right, and that's exactly what I would propose you would do if that's
how you want to deploy.  From my perspective, I'd like to keep the
ability to have short filenames (and therefore filename clashes), but
entirely within the kind of solution you describe.

>>>   - 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.

But, if people who demand this use-case simply rename files to
explicitly include the namespace as a prefix, then aren't we
guaranteeing they can continue as they were?  The only real issue is
that they may have a little more work to import external libraries,
which seems a smallish price to pay.

> 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).

Again, I think my proposal allows what you want without forcing the
entire world to use painfully long filenames.

y