DMAKE.DOC

		       ALPHA RELEASE V1.00 5-Jan-1988

			   *ALPHA* *ALPHA* *ALPHA*

	NOTE!!	This is an alpha version.  I have yet to add all the features
	I will eventually want (like \ line continuation).  In fact, that's
	the whole point of saying 'alpha' above ... only people interesting
	in exploring and testing the radical features of DMake should be
	using this release.

	You MUST be familar with 'make' to understand these instructions.

	The default file is 'DMakefile'.  Options are:

	-a		    force a time comparisons to fail
	-f filename	    use this instead of DMakefile
	-n		    don't actually execute the lines
	-v	(debugging)

			       RADICAL FEATURES

	We are all familar with the UNIX make utility.	We all hate it.
	This program is the beginnings of my solution to the problem.

	(1) Multiple dependancies on the left:

	    ram:a.o ram:b.o ram:c.o : a.c b.c c.c
		cc %(right) -o %(left)

	(2) Wildcards with virtual reverse mapping (I just made that word
	    up).  In the example below, a directory search is used to
	    resolve the *.c wildcard in the line "ram:*.o : *.c".  The left
	    side is then replaced with the resolved list changing the order
	    according to the wildcard specification ( *.c -> ram:*.o ).
	    NOTE that the two wildcard specifications have to contain the
	    same wildcards in the same order.  NO directory search is made
	    for the objects ... the names are generated from the source.

	    Finally, note the line 'ram:*.o : *.asm'... note that this
	    combined with 'ram:*.o : *.c' specifies a joinin of the two
	    specs ... the 'ram:*.o' spec in the linker line will contain
	    ALL the objects.

	    $(EXE) : ram:symbols.m ram:*.o
		ln +Q %(ram:*.o) -o $(EXE)

	    ram:*.o :	*.c
		cc +Iram:symbols.m %(right) -o %(left)

	    ram:*.o :	*.asm
		as %(right) -o %(left)

	    ram:symbols.m : include:symbols.m
		copy %(right) %(left)

	(3) $ and % variables.  $(SYMBOL) is the standard way to specify
	    a symbol name.  %(symbol) is used to macro-insert wildcard
	    symbols that appear on the right.  Two special %
	    symbols exist:  %(left) contains the stuff on the left and
	    %(right) contains the stuff on the right.

	    Note the difference between these two lines:

	    all:    ram:*.o
		ln %(ram:*.o) -o c:blah

	    ram:*.o : *.c
		cc %(*.c) -o %(left)

	    The difference is that the symbol in the linker line contains
	    ALL the objects while the symbol in the compiler line contains
	    only the CURRENT .c file being compiled.  The reason is explained
	    below, but it ought to be obvious.

	    Note that only variables on the right of the ':' may be
	    specified via their name in a %() macro.  You can refer to
	    the left side with %(left), or the entire right side with
	    %(right).

	(4) Another form that might be useful is this:

	    ram:*.o : *.c *.h
		cc %(*.c) -o %(left)

	    Carefully now:  Each .O file is dependant on its .C file.
	    Each .O file depends on ALL OF THE .H FILES.


			    SPECIFICATION OF DEPENDANCIES

	The specification of dependancies might seem a bit confusing to
	you.  Lets take a general example:

	a b c d  : r s t u

	The rule is as follows:  UNTIL one side is exhausted, one item on
	the left is dependant on one item on the right.  That is, a : r,
	b : s, c : t  etc....

	If there are EXTRA arguments on the right, each argument is applied
	to ALL THE ARGUMENTS ON THE LEFT.  If I had a 'v' above it would be
	equivalent to  a : v, b : v, c : v, d : v.

	EXTRA arguments on the left are disalloweds except for two cases:

	blah :			- blah depends on nothing
	a b c d e : x		- a : x, b : x, c : x , d : x, etc....
	*.c : *.h		- WRONG THIS DOES NOT SPECIFY ALL THE
				  .C FILES DEPENDANT ON THE .H FILES!!!

	*.o : *.c *.h		- This does, as well as saying that each
				  object depends on its associated .C file

			EXECUTION ORDER & VARIABLES

	Whenever possible, a depth first execution order will be taken:

	all:	ram:symbols.m	$(OBJS)
	    ln "%(OBJS)" -o c:blah

	$(OBJS): *.c
	    cc +Iram:symbols.m %(right) -o %(left)

	ram:symbols.m : include:symbols.m
	    copy %(right) %(left)

	Here, the symbols are guarenteed to be copied before the objects
	are compiled.  Variables work somewhat like the normal make.  You
	can create variables with '=':

	SRCS =	a.c b.c c.c
	OBJS =	$(SRCS:"*.c":"ram:*.o")             (i.e. ram:a.o, ram:b.o ...)

	When used in the Makefile, use $(SYMBOL) to get an exact replacement,
	%(SYMBOL) to get an indirect replacement.  That is,

	OBJS = ram:*.o

	all: $(OBJS)
	    ln %(OBJS) ...

	Here, %(OBJS) finds "ram:*.o" then re-applies it to %, giving you
	the object list.

	The other little item you just saw is global name replacement on
	symbol inclusion:

	    $(SYMNAME:"oldwild":"newwild")      -if the symbol is a list of
						 files and not a wildcard

	    %(SYMNAME:"oldwild":"newwild")      -if the symbol is a wildcard
						 on the righthand side of
						 the dependancy.

	Causes the symbol to be parsed (space delimits) and each filename
	rung through the grinder.  Each filename is matched with the left
	wildcard and then modified according to the right wildcard.  Here
	are two common DMakefiles:

	SRCS =	a.c b.c c.c d.c e.c
	OBJS =	$(SRCS:"*.c":"ram:*.o")

	all: $(OBJS)
	    ln $(OBJS) -o c:blah

	$(OBJS) : $(SRCS)
	    cc %(right) -o %(left)

				---

	SRCS =	*.c
	OBJS =	ram:*.o

	# note, in the line below you must specify $(SRCS) on the right
	# hand side of you want %(SRCS) to expand properly

	all: $(OBJS) $(SRCS)
	    ln %(OBJS) -o c:blah
	    Echo "%(SRCS)"

	$(OBJS) : $(SRCS)
	    cc %(right) -o %(left)

	arc: $(SRCS) c:blah
	    -delete ram:x.arc
	    arc a ram:x %(right)


				ALPHA 'TO-DO'

	There are probably lots of bugs.  The bigest one now is the lack
	of error detection... it won't stop if it comes across an error.
	You *can* ^C dmake though ... no problem.

	DMake is currently extremely slow ... extremely extremely slow.
	I am not releasing source yet (cause it's a mess).  You just
	wouldn't BELIEVE what I had to go through!

	DMake currently uses Execute() to run commands.  Error codes are
	ignored.  However, you *can* 'cd' ... this is handled internally.
	The original directory can be returned to via 'cd' with no argument.

	Since Execute() is used, command lines that are too long get
	chopped.  Eventually there will be no limit (for non BCPL program).
	But, since 'cd' is internal, you can sometimes shorten the link
	line.  In the example below we use the wildcard modification
	feature to modify ram:*.o to just *.o in the link line after having
	CD'd to ram:.

	OBJS = ram:*.o
	SRCS = *.c

	$(EXE): $(OBJS)
	    cd ram:
	    ln %(right:"ram:*":"*") -lc32 -o $(EXE)
	    cd

	$(OBJS): $(SRCS)
	    cc %(right) -o %(left)