[MLton] MLton import headers

[Matthew Fluet]

On Sat, 4 Oct 2008, Wesley W. Terpstra wrote:
> My personal opinion is that removing the default and requiring the
> user to always specify the linkage would be surprising when compared
> to how one typically uses C libraries. There are only two cases where
> the default is 'wrong'. 1) PIC archives, which are a corner case very
> few projects need. In this case the header has no default and forces
> you to pay attention. 2) You are compiling a library including ML code
> and C code. In this case we require:
>  #define PART_OF_XYZ
>  #include "xyz.h"
> inside your C files instead of:
>  #include "xyz.h"
>  #include "xyz-private.h"
> This doesn't seem particularly onerous or strange to me. You're
> cooperating with MLton to build a library in this case, so it's fair
> for us to have a (not-so-uncommon) convention you need to be aware of.

That seems like a reasonable rationale.  If I understand things correctly, 
though, one advantage of the
   #include "xyz.h"
   #include "xyz-private.h"
approach is that is textually separates the public (in the sense of the 
documented portions of the library API available for use in other 
projects) functions from the private (in the sense of the undocumented 
portions of the library API) functions.  That is, clients of "xyz.h" can't 
even see the prototypes of the private functions.  On the other hand, if 
the platform supports the right visibility attributes, then although a 
client might be able to see the prototype of a private function in a 
(combined) "xyz.h" header, they would fail at link time, because the 
function wouldn't be visible in the binary library.  I guess you 
acheive this effect in the (combined) "xyz.h" by using
   #define MLLIB_PRIVATE(x)
when not PART_OF_XYZ to hide the private functions.

> What I do think we need is a new annotation, 'defaultImport
> public/external'. This way your 'prim.sml' that does all the
> _import/_address/_symbol'ing can be easily switched between
> static/dynamic import.

This shifts the point of change from the 'prim.sml' file to the 'xyz.mlb' 
file.  While one could use "-default-ann 'defaultImport public'", this 
could have undesirable effects if you import from two different libraries 
that demand different linking, since one global default doesn't apply.

Anyways, it doesn't appear that there are clear-cut solutions.  But, I 
tend to agree that an auto-generated SML import header is a sufficiently 
rare corner case that it doesn't really demand extra compiler support.

-Matthew