Including Sub-Modules from Separate Files

This document describes draft support for including a submodule from a separate file. This support is new in 1.21 and is considered unstable - it might change in future releases.

Example

The basic idea is that a module M in a file M.chpl can break its submodules across multiple files by placing them in a directory called M/.

The following example shows both the directory layout and file contents:

M.chpl
M/
    L.chpl

program.chpl # Uses M

M.chpl contains the following:

module M {
  include module L; // finds module L in L.chpl
  // equivalent to including L.chpl here, e.g.
  // module L {  ... }
}

M/L.chpl contains the following:

module L {
  writeln("In module L");
}

program.chpl contains the following:

import M;
// Could refer to public symbols in M.L

The program is compiled with this command:

chpl program.chpl

Visibility Details

Module visibility can be specified at the include module statement, as with include private module L; or include public module L. As with regular module { } statements, the default is public. In other words - include module L; is equivalent to include public module L.

Module visibility can additionally be specified inside the file declaring the submodule. For example, L.chpl could contain public module L { } or private module L { }. If the module declaration indicates private visibility but the include module line does not, the compiler will issue an error. Otherwise, the visibility at the include module line will be used.

Errors

It is currently an error if include module is used within a module that is inside an inline submodule in the file containing that code. Such cases can be handled by using include module for all of the levels of submodule in the file.

It is currently an error to if include module is used within a module in a file that has a name other than the module name (plus .chpl)