Namespacing Last updated May 4, 2022

OCaml supports namespaces within the language. But unlike many other languages that support articulated names like A.B.C, it does not map such "module paths" to filesystem paths.

OCaml uses a flat namespace for module source file names. If you use the same module file name in different file system locations within a project you will get a name clash. Every module source file must be uniquely named.

There is only one way to address the problem: give your source files names that are likely to be unique. The easy way to do this is to decide on a prefix string likely to be unique. That might start with your project name, or it might replicate the filesystem path locating your source file, by replacing filesystem separator (usually '/') with '_' or some other character.

The downside of this solution is that it creates another problem. Now instead of having e.g. a/b.ml, we need a/a__b.ml or the like.

A better solution is to adopt a hybrid strategy that uses both filename prefixing and OCaml aliasing to implement a form of namespacing. That is the strategy pursued by both Dune and OBazl.

The "top-level module aliases" facility provides a mechanism that tools can use to emulate hierarchical filesystem-based namespacing.

Special considerations: -no-alias-deps, -opaque, and -linkall.

OCaml has a sophisticated module system that is partially tied to the file system.

Each OCaml "compilation unit" determines a module, whose name is the file name, capitalized and truncated to remove the extension. Thus foo.ml determines module Foo.

The OBazl Demos repo contains some basic examples, using simple makefiles, demonstrating the interplay of module aliasing equations, namespaces, and the file system.

File names including double underscores, such as foo__bar.ml, receive special treatment. The compiler will treat the double underscore as a dot, in this case yielding Foo.bar.

Translated into English, this seems to mean that, for example. if lib.ml contains module FooBar = Lib__fooBar, then Lib.FooBar corresponds to Lib__fooBar.

Both the top-down and the bottom-up models depend essentially on a module containing the module aliasing equations that determine submodules; OBazl calls such modules ns resolver modules or resolvers for short. They are express using rule ocaml-ns-resolver.

Top-down namespaces are defined at the aggregate level. This is the strategy pursued by Dune: membership in a namespace is expressed by the list of modules in a library stanza. Dune automatically renames the modules, adding the namespace prefix (e.g. Foo__) to the module names, and generates a resolver ("wrapper") module containing the required module aliasing equations ; then everything is packaged up in an archive file.

To support top-down namespaces, OBazl provides rules ocaml_ns_archive and ocaml_ns_library; members of the namespace are listed in the submodules attribute. OBazl does the same thing Dune does: generates the resolver and renames the submodules. Both Dune and OBazl support user-defined resolver modules for top-down namespaces. Dune always packages namespaces in archives, but in OBazl they may also be organized as OBazl libraries, or they may not be aggregated at all. (See Aggregators for more on the distinction OBazl draws between libraries and archives.)

Top-down namespaces are easy to define, but they are limited. Targets that use a namespaced module must depend on the namespace aggregate (ocaml_ns_library or ocaml_ns_archive) containing the module; they cannot depend directly on submodules. If changes are made to a submodule, all targets that depend on its namespace aggregate will be rebuilt, whether or not they depend on the module that was changed.

Top-down namespaces have one major shortcoming, as noted above: clients can only depend on the aggregates; they may not depend directly on submodules. Bottom-up namespaces eliminate this shortcoming. Targets may depend directly on namespaced modules; furthermore, bottom-up namespaces need not be organized as library or archive aggregates at all. They are determined by explicitly defining an ocaml_ns_resolver specifying the namespace prefix and listing its submodules. The submodules (which may include interfaces) indicate their membership in a namespace directly, by passing an ocaml_ns_resolver target label via the ns attribute of ocaml_module and ocaml_signature.

A less serious shortcoming of top-down namespaces is the use of transition functions with hidden label-typed attributes, which adds overhead (and considerable complexity, if you ever need to debug them). Bottom-up namespaces use neither hidden attributes nor transition functions.

Top-down namespaces select their submodules; the submodules in a bottom-up namespace elect membership.

Bottom-up namespaces are much more powerful and flexible than top-down namespaces. Targets can depend directly on namespaced submodules; this can be used to optimize builds. When a bottom-up submodule is changed only targets that depend on it are rebuilt. And since aggregation and namespacing are orthogonal, namespaced submodules can be aggregated ad libitum. For example, if a set of targets depends on a subset of three submodules in a namespace that contains ten submodules, this subset can be aggregated as a library or archive. Multiple aggregates can contain submodules from the same namespace. Aggregates can even contain submodules from multiple namespaces. The OBazl rules will ensure that the resolver module is always included in the dependency graphs of submodules, and OBazl’s dependency manager will always normalize the graphs to remove duplicates while retaining dependency order.

Another way to look at it: in most languages that explicitly support some form of namespacing, namespaces are closed, in the sense that the only way to access an element in the namespace is by going through the namespace, so to speak. OBazl’s bottom-up namespaces are open: we can access the submodules in a bottom-up namespace without reference to the namespace name.

Which is to say that such "namespaces", being based on OCaml’s module aliasing mechanism, are only pseudo-namespaces. The OCaml language does not know anything about such namespaces; it only knows how to resolve module aliases. For example, a reference A.B might be aliased to A__B (i.e. a__b.ml, automatically renamed from b.ml), but module names are opaque; OCaml will not interpret A__B as "submodule B in namespace A ". So we can access that (sub)module directly, without "going through" module A. In fact we can include it in any namespace we like; for example, we can put it in namespace Foo by putting the following aliasing equation in the resolver module foo.ml: module B = A__B. We can also expose it under a different name: module Bar = A__B would expose it as Foo.Bar.

As an example: just about everything in the OCaml compiler sources depends on the standard library, which is packaged as an archive stdlib.cma built by target //stdlib. If those dependencies are expressed as dependencies on //stdlib, then a change in any stdlib submodule will trigger a rebuild of almost everything. But if they are expressed as direct submodule dependencies, e.g. //stdlib:Stdlib.List, then the rebuild triggered by a change to one submodule will include only those targets that genuinely depend on it, directly or indirectly. (Example: parsing/BUILD.bazel)