_Overview of make_
------------------

This library provides a Scheme version of the standard unix
`make' utility. Its syntax is intended to simulate regular
unix make in Scheme.

If you are already familiar with make, skip down the precise
details of the make collection. This section contains a
brief overview of make. The idea is to explain how to
generate some project you have from a collection of source
files that go through several stages of processing.

For example, lets say that you are writing soem project that
has three input files (that you create and maintain) called
a.input, b.input, and c.input. Further, there are two stages
of processing -- first you run a particular tool
"make-output" that takes an input file and produces and
output file, and second you combine the input files into a
single file using "output". Using make, you might write
this:

a.output: a.input
	make-output a.input a.output
b.output: b.input
	make-output b.input b.output
c.output: c.input
	make-output c.input c.output 
total: a.output b.output c.output
	combine a.output b.output c.output 

Once you've put those above lines in a file called
"Makefile", you can issue the command:

  make total 

that builds your entire project. The Makefile consists of
several lines that tell `make' how to create each piece. The
first two lines say that a.output depends on a.input and the
command for making a.output from a.input is 

  make-output a.input a.ouput

The point of this exercise is that the `make' utility looks
at the file creation dates of the various files and only
re-builds what is necessary.  Make is based on building
things with shell programs. If, on the other hand, you want
to build similar things with various Scheme programs, you
can use the make collection.

Here's the equivalent Scheme program: 

(require (lib "make.ss" "make"))

(define (make-output in out)
   ...)

(define (combine-total . args)
  ...)

(make
  (("a.ouput" ("a.input") (make-output "a.output" "a.input"))
   ("b.ouput" ("b.input") (make-output "b.output" "b.input"))
   ("c.ouput" ("c.input") (make-output "c.output" "c.input"))
   ("total" ("a.output" "b.output" "c.output")
            (combine-total "a.output" "b.output" "c.output")))

If you were to fill in the ellipses above with calls to
`system', you'd have the exact same thing as the original
Makefile. In addition, if you use `make/proc', you can
abstract over the various make lines (for example, the
a.output, b.output, and c.output lines are very similar and
it would be good to write a program to generate those
lines).
			      
_make.ss_
---------

The make.ss library in the `make' collection provides a
`make' macro and a `make/proc' procedure.

> (make ((target (depend ...) command ...) ...) argv)

expands to

  (make/proc
    (list (list target (list depend ...) (lambda () command ...)) ...)
    argv)

> (make/proc spec argv) performs a make according to `spec'
and using `argv' as command-line arguments selecting one
or more targets.  `argv' can either be a string or a
vector of strings.

`spec' is a MAKE-SPEC:

  MAKE-SPEC = (list-of MAKE-LINE)
  MAKE-LINE = (list TARGET (list-of DEPEND-STRING) COMMAND-THUNK)
  TARGET = (union string (list-of string)) ; either a string or a list of strings
  DEPEND-STRING = string
  COMMAND-THUNK = (-> void)

To make a target, make/proc is first called on each of the
target's dependencies. If a target is not in the spec and it
exists, then the target is considered made. If a target is
older than any of its dependencies, the corresponding
COMMAND-THUNK is invoked. The COMMAND-THUNK is optional; a
MAKE-LINE without a COMMAND-THUNK is useful as a target for
making a number of other targets (the dependencies).

`make/proc' catches any exceptions raised by a COMMAND-THUNK
and wraps them in an exn:make structure, and raises the
wrapped exn. exn:make structures are defined with:

  (define-struct (exn:make struct:exn) (target orig-exn))

The `target' field is a string or a list of strings naming
the target(s), and the `orig-exn' field is the original
exception.

The maker.ss library is a signed unit that requires no
imports and provdes `make/proc'.

make.ss also provides the following parameters:

> (make-print-checking [on?]) - If #f, make only prints when
it is making a target. Otherwise, it prints when it is
checking the dependancies of a target. Defaultly #t.

> (make-print-dep-no-line [on?]) - If #f, make only prints
"checking..."  lines for dependancies that have a
corresponding make line.  Defaultly #f.

> (make-print-reasons [on?]) If #t, make prints the reason
for each dependancy that fires. Defaultly #t.

_collection.ss_
---------------

 [index entry: _collections, compiling_]

The collection.ss library in the make collection provides a
`make-collection' procedure.

> (make-collection collection-name collection-files argv) constructs
and performs a make to compile a collection of Scheme files into a
multi-file extension. `collection-name' is used as a name that is
embedded into publicly visible names in the extension (choosing a
unique `collection-name' for each extension helps avoid conflicts
among different extensions for certain operating
systems). `collection-files' is a list of Scheme source files to be
compiled. `argv' is passed on to `make'.

The resulting extension "_loader" is compiled to the current
directory's "compiled/native/PLATFORM" subdirectory, where `PLATFORM'
is replaced by the system name of the current platform. Intermediate
.c amd .kp files are placed into "compiled/native", and intermediate
object files are also placed into "compiled/native/PLATFORM".  The .c
and .kp files are preserved so that thay can be generated once for
compiling across multiple platforms with the same filesystem.

Make rules are also generated for compiling .zo files, placed in the
"compiled" directory. The make target "zo" makes all of the .zo
files. (In other words, pass #("zo") as `argv' to compile .zo files.)

The "compiled", "compiled/native", etc. directories are automatically
created if they do not already exist. Currently, `make-collection'
does not try to infer sophisticated file dependencies. Each .c/.kp/.zo
is dependent just on the .ss source file, each object file is depend
only on its .c file, and the extension is dependent only on the
object files.
