2.10 Multiple directories

If your project gets big, it becomes increasingly difficult to navigate a directory filled with `.sml', `.sig', `.uo', `.ui' files for all of your units, in addition to executables and build infrastructure. Mosmake supports distributing the source code for the units that make up your program into several subdirectories according to logical principles. (This is not as simple as it sounds, either -- but I've promised not to preach, so I won't go into specifics).

Mosmake's cross-directory support is based on three design principles:

• 1. The entire compilation shall be controlled by a single `Makefile' in the top-level directory. If you wonder why not instead a `Makefile' in each subdirectory, you should go and read Peter Miller's excellent article Recursive Make Considered Harmful and then come back afterwards.

• 2. The location of a unit is part of its identity. Thus you can have two source files both called `frob.sml' but in different directories, although the current Moscow ML bytecode linker is going to be confused if you try to link both of them into the same binary. This means that you can, to a certain extent, use the directory hierarchy for namespace management for unit names. On the other hand you need to give the location with each dependency declaration.

  Later versions of Mosmake may include some support for inferring locations from last names, if enough people pester me about it.

• 3. Finished binaries always end up in the project's main directory, no matter where their `.sml' source is found. This is just because I think it is the most practical general principle.

The most primitive way to use the cross-directory support is to simply add directory parts to the unit names in the `Dependencies' file:

foo/data:
foo/read: foo/data
bar/write: foo/data
bar/stuff: foo/read bar/write %PROGRAM

Then Mosmake will generate rules that switch to the `foo' and `bar' directories as appropriate for compiling each of the four units. The references to units in `foo' will get rewritten to `../foo' when compiling in `bar', and directory-change messages will get emitted to make the output of the entire make process parseable by Emacs's compile-mode.

However, adding a lot of directory prefixes to the unit names will do nothing to keep the `Dependencies' file itself readable, even if brace expansion can keep the explosion somewhat under control. Therefore Mosmake supports having one `Dependencies' file in each directory, even if they are combined to form one top-level `mosmake.dep'. With per-directory `Dependencies' we could instead have:

# This is foo/Dependencies
data:
read: data

# This is bar/Dependencies
write: ../foo/data
stuff: /foo/read write %PROGRAM

Then, in order to tell Mosmake where to look for Dependencies files, put

MOSMAKEDIRS = foo bar

in the `Makefile' in the superdirectory. $(MOSMAKEDIRS) is a whitespace-separated list of directories where Mosmake will expect to find a `Dependencies' file. Note that if `.' is not part of the list, Mosmake will not try to read a `Dependencies' file in the main directory itself.

Here are the properties of subdirectory `Dependencies' files, some of which are shown in the preceding example:

• Unit names in a subdirectory `Dependencies' file are interpreted relative to the subdirectory where it is found. This goes for units to the right of the colons as well as the defining instance to the left of the colon. In principle one could have removed the `data:' line from `foo/Dependencies' and instead put `../foo/data:' in `bar/Dependencies'. Although there would not be much point in that, save for obfuscating the build system.

• A unit name that starts with a slash is interpreted relative to the project's main directory (i.e., where the `mosmake.dep' file is built) -- not what the OS may think of as the "root directory".

• However, a unit name that starts with `$(' will not be relativized to the `Dependencies' file where it is found. See section 2.9 Linking with external libararies.

• There's still no difference between a macro name and a unit name. That is: A macro name has a directory part, too, and to use a macro the right directory must be either implicit or explicit in the reference. A macro reference that includes `..' indirections will work as expected.

One disadvantage of only having one master makefile is that just typing make `target' won't work unless your current directory is the project root. Mosmake comes with a stub file `Makefile.chain' that you can use to make make commands work even when started from a subdirectory. Copy `Makefile.chain' to the main directory and then place in each subdirectory a `Makefile' containing

DOWN = foo/bar   # where are we, relative to the root?
UP   = ../..     # where is the root, relative to us?
include $(UP)/Makefile.chain

Then `Makefile.chain' will take care of starting a suitable make command from the top level directory. When you type make FILENAME, `Makefile.chain' will even try to guess intelligently whether FILENAME is a local object file, such that the top-level command should be make foo/bar/FILENAME, or binary or meta-target, such that the top-level command should be make FILENAME.