MLton MLTONWIKIVERSION

CompilationManager

Home Index

The Compilation Manager (CM) is SML/NJ's mechanism for supporting programming-in-the-very-large. To aid in porting code from SML/NJ and in developing code simultaneously with MLton and SML/NJ, MLton supports a very limited subset of CM files. From MLton's point of view, a CM file `foo.cm` defines a list of SML source files. The call

    mlton foo.cm

is equivalent to compiling an SML program consisting of the concatenation of these files. As always with MLton, the concatenation must be the whole program you wish to compile.

In its simplest form, a CM file contains the keywords `Group is` followed by an explicit list of sml files. For example, if `foo.cm` contains

    Group is
    bar.sig
    bar.fun
    main.sml

then a call `mlton foo.cm` is equivalent to concatenating the three files together and calling MLton on that SML file. The list of files defined by a CM file is the same as the order in which the filenames appear in the CM file. Thus, to MLton, order in a CM file matters. In the above example, if `main.sml` refers to a structure defined in `bar.fun`, then `main.sml` must appear after `bar.fun` in the file list.

CM files can also refer to other CM files. A reference to `bar.cm` from within `foo.cm` means to include all of the SML files defined by `bar.cm` before any of the subsequent files in `foo.cm`. For example if `foo.cm` contains

    Group is
    bar.cm
    main.sml

and `bar.cm` contains

    Group is
    bar.sig
    bar.fun

then a call to `mlton foo.cm` is equivalent to compiling the concatenation of `bar.sig`, `bar.fun`, and `main.sml`.

CM also has a preprocessor mechanism that allows files to be conditionally included. This can be useful when developing code with SML/NJ and MLton. In SML/NJ, the preprocessor defines the symbol `SMLNJ_VERSION`. In MLton, no symbols are defined. So, to conditionally include `foo.sml` when compiling under SML/NJ, one can use the following pattern.

    # if (defined(SMLNJ_VERSION))
    foo.sml
    # endif

To conditionally include `foo.sml` when compiling under MLton, one can negate the test.

    # if (! defined(SMLNJ_VERSION))
    foo.sml
    # endif

The filenames listed in a CM file can be either absolute paths or relative paths, in which case they are interpreted relative to the directory containing the CM file. If a CM file refers either directly or indirectly to an SML source file in more than one way, only the first occurrence of the file is included. Finally, the only valid file suffixes in a CM file are `.cm`, `.fun`, `.sig`, and `.sml`.

## Comparison with CM

If you are unfamiliar with CM under SML/NJ, then you can skip this section.

MLton supports the full syntax of CM as of SML/NJ version 110.9.1. Extensions since then are unsupported. Also, many of the syntactic constructs are ignored. The most important difference between the two is that order in CM files matters to MLton but not to SML/NJ, which performs automatic dependency analysis. Also, CM supports export filters, which restricts the visibility of modules. MLton ignores export filters. As a consequence, it is possible that a program that is accepted by SML/NJ's CM might not be accepted by MLton's CM. In this case, you will have to manually reorder the files and possibly rename modules so that the concatenation of the files is the program you intend.

CM performs cutoff recompilation to avoid recompiling the entire program, while MLton always compiles the entire program. CM makes a distinction between groups and libraries, which MLton does not. CM supports other tools like lex and yacc, while MLton does not. MLton relies on traditional makefiles to use other tools.

## Porting SML/NJ CM files to MLton

If you have already created large projects using SML/NJ and CM, there may be a large number of file dependencies implicit in your sources that are not reflected in your CM files. Because MLton relies on ordering in CM files, your CM files probably will not work with MLton. To help in porting CM files to MLton, the MLton distribution includes the sources for a utility, `cmcat`, that will print an ordered list of files corresponding to a CM file. See `util/cmcat/cmcat.sml` for details. Building `cmcat` requires that you have already installed a recent version of SML/NJ.

Alternatively, you can convert your CM files to `.mlb` files. The MLton distribution includes the sources for a utility, `cm2mlb`, that will print an ML Basis file with essentially the same semantics as the CM file -- handling the full syntax of CM supported by your installed SML/NJ version and correctly handling export filters. When `cm2mlb` encounters a `.cm` import, it attempts to convert it to a corresponding `.mlb` import. CM anchored paths are translated to paths according to a default configuration file (`cm2mlb-map`). For example, the default configuration includes

    $basis.cm/basis.cm  $(SML_LIB)/basis/basis.mlb

to ensure that a `$/basis.cm` import is translated to a `$(SML_LIB)/basis/basis.mlb` import. See `util/cm2mlb` for details. Building `cm2mlb` requires that you have already installed a recent version of SML/NJ.

Last edited on 2005-11-30 23:40:40 by StephenWeeks.