[ocaml-platform] Idea: use (possibly extended) toplevel directives as source headers

[Gabriel Scherer]

Interleaved with the namespace discussion, there is a debate about the
amount of program semantics that should or not be encoded through
command-line options and more generally the build system.

There is currently a rather arbitrary separation between semantic
features that can be specified in one or another world. Which
compilation units are accessible can only be set on the command-line,
which ones are opened cannot (it is a mix of the Pervasives hardcoded
convention and in-program "open" statements). There are two reasons to
wish to place any aspect of a unit semantics in the source code or in
the environment, so I think language designers should support both use
cases and let users choose:
- the source code is of course the easiest place to inspect and share
to analyze or communicate a unit's semantics (plus it has a precise,
well-defined semantics)
- putting things in the environment (in the build system or in the
file system) allows factoring redundancies away;that's the very point
of using external modules (factoring common code as libraries); why
can't we "factorize" a common set of "open" present in the same order
in several source files? This could be done either by having an "open"
option on the command-line (semantics in the build system), or adding
some sort of (include open "foo.mlopen") in the source code, that
explicitly performs the open present in a file (semantics in the file
system)

We should worry whenever a semantic feature can be expressed only in a
source without being shareable through the environment (that's
currently the case of "open" and local module renaming choices, and
the namespace discussion may change that), or only through the
environment without being expressible in the source. I'm here focusing
on the latter case.

Besides some less-interesting compilation options (-inline, ...), this
is in particular the case of
- ocamlfind packages used by a given program (more generally, search
path settings)
- preprocessing settings needed to correctly parse a given program
(somehow lesser priority, not discussed in this mail)

I think we could consider extending OCaml code units with a "header"
zone that contains semantics information corresponding to this
information.

The good news is that there already exists a widely used syntax that
could be added to source code without introducing ambiguities:
toplevel directives.

   #require "foo";;
   #warnings "3,4,85";;
   #directory "/opt/unpackaged";;

  let x = ... in ...

The restriction would be that they can only be used at the very
beginning of a source file, not nested anywhere in a program (just
like build systeam features are unit-global today).

Note that "#require" is not specified in the OCaml manual, it is a
de-facto standard introduced by ocamlfind. I think have such explicit
"import" support could be fairly useful for tooling (see all the nice
things the "go" tool allows for users of the Go programming language),
but I'm not sure it should be standardized as explicitly referring to
the ocamlfind tool, or a more abstract notion of "package" that could
also please the serious industrial users that maybe don't use
ocamlfind internally (I have no idea).