Re: [Caml-list] Installing library with hidden modules

[Ivan Gotovchits <ivg@ieee.org>]

[-- Attachment #1: Type: text/plain, Size: 3920 bytes --]

Hi Daniel,

You're absolutely right in all details. And yes the devil is in details. I
should be more precise and disclose all the ingredients of my recipe.
Indeed, we are not using module aliases, and yes hiding the cmi file, of
course, will not fix the flat namespace of compilation units. So, the
solution that we are using for our libraries in CMU is pretty simple, for a
library/project named LIB do the following:

1. prefix all internal modules with the `LIB_`
2. provide a public module `LIB.ml` that reexports some of the internals
3. describe the public interface in `LIB.mli`
4. do not install `cmi` and `mli` files for the internal modules.

The public interface, of course, should not mention any internals.

Given a concrete example, suppose we want to implement a Monad library and
name it `monad`. The project structure would be the following:

```
monad_types.ml
monad_common.ml
monad_state.ml
monad_state.mli
monad_reader.ml
monad_reader.mli
...
monad.ml
monad.mli
```

A possible contents of the `monad.ml`:

```
include Monad_types
module State = Monad_state
module Reader = Monad_reader
...
```

The contents of the `monad.mli`

```
(** Lot's of docs *)
module type S = sig
   type 'a t
   val map : 'a t -> ('a -> 'b) -> 'b t
   val bind : 'a t -> ('a -> 'b t) -> 'b t
   val return : 'a -> 'a t
   ...
end

...

module State : sig
    type ('a,'e) t
    include S2 with type ('a,'e) t := ('a,'e) t
    ...
    val run : ('a,'e) t -> 'e -> 'a * 'e
end

...
```



The most controversial part is the duplication of the `mli` files. Of
course, one can omit `mli` for the internals, but I myself is a strong
proponent of writing mli files, and will not go that way. Thus, we decided
to support the two sets of mli files. The internal set, describes our
internal developer's interface, that is sometimes richer and less
stable than the external. The external defines the public API, that is
stable and versioned, it also must be well-documented. The internal
interfaces usually do not contain documents, except technical notes and
implementation details.


For a real life example, look at the graphlib library:

library structure:
https://github.com/BinaryAnalysisPlatform/bap/tree/master/lib/graphlib
oasis file:
https://github.com/BinaryAnalysisPlatform/bap/blob/master/oasis/graphlib


P.S. This is not the only solution. Another, probably better, solution,
that I was using before, is to use packing. It is much nicer in the sense,
that it solves the flat namespace issue. However, OASIS messes with the
packed modules, so we were forced to use this, more ad-hoc approach.

P.P.S. Strictly speaking we do not need to install even the `cmx` of the
internal modules, however, their absence will prevent cross-module
optimization if my understanding of the latter is correct.

Best wishes,
Ivan


On Tue, May 9, 2017 at 5:01 PM, Daniel Bünzli <daniel.buenzli@erratique.ch>
wrote:

> On Monday, 8 May 2017 at 14:49, Ivan Gotovchits wrote:
> > An absence of the cmi file, will prevent users from accessing the module
> directly. The OASIS system provides an easy way to hide modules, with the
> `InternalModules` field. OASIS will install all the necessary parts of the
> module (i.e., cmxs, cma, o, a, etc), but will not install the interface
> part.
>
>
> If I'm not mistaken you can't do that with module aliases, you'll need the
> cmi files of the right hand side of the alias (`module M : sig end = M` is
> invalid syntax).
>
> Besides it's not because you hide the cmi files that the names won't show
> up at link time. If your "hidden" toplevel names are generic (let's say
> `Config`), they will still prevent linking with other libraries that define
> the same generic names.
>
> Again, you can't hide toplevel names using module aliases.
>
> Best,
>
> Daniel
>
>
>

[-- Attachment #2: Type: text/html, Size: 5600 bytes --]