2.1 A Simple Example

Let's begin with a simple example to show how Mosmake works. Imagine that you have a program consisting of four SML source files. `data.sml' defines your basic data structures; `read.sml' and `write.sml' contains the actual code and both reference stuff exported by `data.sml', and `stuff.sml' is the main program that calls some functions from `read.sml' and `write.sml' but does not directly reference `data.sml'.

So you want to use Mosmake to compile this project. Put your `.sml' files in some directory, and create a file called `Dependencies' which reads

data:
read: data   # This is a comment. Comments span
write: data  # from the # sign to the end of line
stuff: read write %PROGRAM

This file defines the four units and contains information about which units use symbols from which other units. With Mosmake you have to enter this information by hand; in practise we've found that this is not as big a chore as it sounds. The line for `stuff' contains, in addition to the dependencies on `read' and `write', the special flag %PROGRAM which tells Mosmake that `stuff' is a stand-alone program and not just a module.

Also, create a `Makefile' that contains something like

MOSMLC  = mosmlc
PERL    = perl
MOSMLFLAGS =
MOSMAKE = mosmake
include $(MOSMAKE)/Makefile.inc

where the definition of the $(MOSMAKE) variable should be the path to the directory where you've installed the files in the Mosmake distribution. It can be either an absolute path or relative to your project directory; in this example we've put Mosmake in a subdirectory called `mosmake'.

Now type `make' -- or if you need to use some other command, like gmake, to launch GNU make instead of another make implementation, do that. Mosmake works only with GNU make.

A bunch of stuff happens, culminating in the production of a binary called stuff:

$ make
perl mosmake/cooker.pl . > mosmake.dep
mosmake/wrap ./ 'data.ui data.uo' mosmlc  -toplevel -c data.sml 
mosmake/wrap ./ 'read.ui read.uo' mosmlc  -toplevel -c data.ui read.sml 
mosmake/wrap ./ 'write.ui write.uo' mosmlc  -toplevel -c data.ui write.sml 
mosmake/wrap ./ 'stuff.ui stuff.uo' mosmlc  -toplevel -c read.ui
        write.ui stuff.sml 
mosmake/wrap ./ stuff mosmlc  data.uo read.uo write.uo stuff.uo \
   -o stuff 
make[1]: `stuff' is up to date.
$ 

Depending on the version of make you use, the output may look slightly different, but the overall pattern should be similar to the example shown. So what happened here?

First, the Perl script `cooker.pl' was executed. It read your `Dependencies' file and produced a makefile fragment called `mosmake.dep'. That contains the black magic that tells make how to orchestrate the (re)compilation of stuff. Even for a small project like this, the contents of `mosmake.dep' is slightly scary; you may want to take a peek at it just to enjoy not having to understand it.

Once `mosmake.dep' has been generated, make automatically reads its contents and uses it to build `stuff'. This is because Mosmake's `Makefile.inc', which was included from your `Makefile', itself includes `mosmake.dep' -- and that is also what caused make to run `cooker.pl' in the first place, because `mosmake.dep' was found to be missing or out-of-date with respect to `Dependencies'. (Got that?)

Next the mosmlc command-line compiler is run to compile each of the SML modules in turn and then to link the final executable. You may notice that the actual command used each time is not mosmlc itself but mosmake/wrap. This is a small wrapper script (hence its name) that helps out with implementing the smartmake feature (see section 2.2.6 The "smartmake" feature) and with compiling in subdirectories (see section 2.10 Multiple directories). The actual mosmlc command line begins witht the third argument to mosmake/wrap.

In the final mosmlc command, note that Mosmake has computed that `data.uo' must be linked into `stuff' even though `data' is not mentioned in `stuff''s line in `Dependencies'. As long as everything is in one directory, mosmlc does not really need to be told this, but make does need to be told that `stuff' must be relinked if `data.uo' changes. Keeping track of such dependencies without a tool like Mosmake would be messy ... ok, end of commercial break. I'll try to cut down on the preaching in the rest of the manual.

Finally, an informational message that `stuff' is up to date appears. This message is basically just fallout from the smartmake logic and can be ignored. It has no real information value, except that you can use it to see that the smartmake logic is enabled. (See section 2.2.6 The "smartmake" feature, for more info).