MS - MAKE WITH SHELL
--------------------

ms is a shell script that generates rules for make and builds C source
organized into build modules. A build module puts a boundary around a set of
source files and can contain rules for generating sources or headers. Build
modules can be used to separate platform specific implementations, create
multiple binaries, and more generally for organizing code.

USAGE
-----

Make the "ms" file available in your PATH or copy it and distribute it with
your code base. It can be used like make(1), i.e. most command line arguments
like macro definitions and targets are passed straight on to make.  The
expected directory structure has a build configuration file named "build.sh" at
the root and one or more sub-directories for build modules. 

BUILD MODULES
-------------

Build modules are directories which contain source files and a module
configuration file named "module.sh". The module configuration file is a shell
script that is invoked when ms is executed and should list source files that
belong to the build in the SOURCES variable. The working directory is that of
the module, so e.g. globbing *.c lists all immediate source files in the
module directory. Makefile rules are generated for each listed source but any
standard output is also passed on to make(1) and variables, rules, and commands
can be dynamically generated here.

The sources are compiled into a static library which is used when linking any
binary that depends on the module, such as the primary binary output or tests.
For this reason it is a good idea to place main functions in separate source
files so that functions in other object files in the library can be linked in
with other definitions of main. Each build module can be linked into a binary
if specified in the module configuration.

If a module generates header files then it is necessary to list them in the
HEADERS variable.

The module configuration can communicate with ms by defining the following
shell variables:

 - BINARY: name of binary 
 - SOURCES: list of source files 
 - OBJECTS: list of object files to include in the module library for which
   non-default Makefile rules have been generated
 - HEADERS: list of generated header files
 - REQUIRE: list of modules dependencies
 - TESTS: list of test binaries

where a list is a white-space delimited sequence. Additionally, if the common
make variables CFLAGS, CPPFLAGS, LDFLAGS, and LDLIBS are defined in the module
configuration file, they are applied only for the module's members.

When "module.sh" is invoked the following variables are defined:

 - SOURCE: the path of "build.sh" 
 - TARGET: the base path where are build outputs should be located
 - MODULE: the name (directory filename) of the module
 - MODULE_DIR: the path from $SOURCE to the module

An example project which have two modules, "data" and "cmd", might contain the
following files:

    ./ms
    ./build.sh

    ./include/data.h

    ./src/data/module.sh
    ./src/data/load.c
    ./src/data/store.c

    ./src/cmd/module.sh
    ./src/cmd/main.c

The base directory contains "ms" and "build.sh". When "ms" is executed it reads
"build.sh", which may contain arbitrary shell functions and code. Its main
purpose, however, is to specify which modules are part of the build
and this is done by defining the MODULES variable. In this case it could
contain the line

    MODULES="src/data src/cmd"

TESTING MS
----------

Run the ./check command in the root directory which outputs minimal TAP to
standard output. Test-run outputs are stored in the ./logs/ directory.