NAME

	am		Anthony's Make 


SYNOPSIS

	am <makefile> [target]


DESCRIPTION

AM is a programmer's tool to maintain, update, and regenerate groups
of files and/or programs.  It is similar to MAKE as described by the
POSIX.2 draft standard 11.2, and this document parallels the draft
in order to point out the subtle differences between AM and MAKE.

The AM utility can be used as part of software development to update
files that are derived from other files.  A typical case is one where
object files are derived from the corresponding source files.  The AM
utility examines time relationships and updates those derived files
(targets) that have modified times earlier than the modified times of
the files (prerequisites) from which they are derived.  A description 
file ("makefile") contains a description of the relationships between 
files, and the commands that must be executed to update the targets to
reflect changes in their prerequisites.  Each specification, or rule, 
shall consist of a target, optional prerequisites, and optional 
commands to be executed when a prerequisite is newer than the target.


OPTIONS

None.


OPERANDS

makefile	This required argument, is a pathname of a description
		file, which is also referred to as the "makfile".  A
		pathname of "-", shall *NOT* denote the standard input.

target		This optional argument, is the first target to be 
		processed.  If no target is specified, when AM is
		processing the makefile, the first target that AM
		encounters shall be used.


EXTERNAL INFLUENCES

STANDARD INPUT

Not used.


INPUT FILES

The input file, otherwise known as the makefile, is a text file
containing rules, macro definitions, and comments.


ASYNCHRONOUS EVENTS

All traps are left to their default actions.  If AM receives a SIGHUP,
SIGTERM, SIGINT, or SIGQUIT then AM will terminate as per request
*WITHOUT* removing the current target.


EXTERNAL EFFECTS

STANDARD OUTPUT

The AM utility shall write all commands to be executed to standard
output unless the command is prefixed with an at-sign (@).  If AM is
invoked without any work needing to be done, it shall *NOT* write a
message to standard output indicating that no action was taken. 


STANDARD ERROR

Standard error is used for diagnostic messages only.


OUTPUT FILES

None.  However, the utilities invoked by AM may create additional files.


EXTENDED DESCRIPTION

The AM utility attempts to perform the actions required to ensure
that the specified target(s) are up-to-date.  A target is considered
out-of-date if it is older than any of its prerequisites or it does
not exist.  The AM utility shall treat all prerequisites as targets
themselves and recursively ensure that they are up-to-date, processing
them in the order which they appear in the rule.  The AM utility shall
use the modification times of files to determine if the corresponding
targets are out-of-date.

After AM has ensured that all of the prerequisites of a target are
up-to-date, and if the target is out-of-date, the commands associated
with the target entry shall be executed.  If there are no commands
listed for the target, the target shall be treated as up-to-date.


MAKEFILE SYNTAX

A makefile can contain rules, macro definitions, and comments.  If a
macro is defined more than once, the value of the macro shall be the
last one specified.  Comments start with a number-sign (#) and
continue until an unescaped <newline> is reached.

A backslash before a <newline> serves as a line continuation mark, and 
is used to create long-lines.   A line will continue to be extended until 
an unescaped <newline> is reached.

When an escaped <newline> (one preceded by a backslash) is found anywhere
in the makefile, it shall be replaced, along with any leading white 
space on the following line, with a single <space>.  


MAKEFILE EXECUTION

Command lines shall be processed one at a time by writing the command
line to standard output, unless prefixed with an at-sign (@), and
executing the command(s) in the line.  Commands shall be executed by
passing the command line to the command interpreter via the system()
function.

The environment for the command being executed shall contain all of the
variables in the environment of AM.  All macros are considered to be part 
of the environment too.

By default, when AM receives a non-zero status from the execution of a
command, it terminates with an error message to standard error.  If
the command is prefixed by a hyphen (-) then any error found while
executing the command shall be ignored.

Command lines can have one or more of the following prefixes: a hyphen
(-) to ignore errors, an at-sign (@) to be silent, or a plus-sign (+)
if the command is always executed (this prefix is for compatibility with
MAKE and is ignored).


TARGET RULES

Target rules are formatted as follows:

	target [target ...] : [prerequisite ...]
	[<tab>command
	 <tab>command
	 ...]

	(line that does not begin with <tab>)

Target entries are specified by a <blank>-separated, non-null list of
targets, then a colon, then a <blank>-separated, possibly empty list
of prerequisite.  All following lines, if any, that begin with a <tab>,
are command lines to be executed to update the target(s).  The first
line that does not begin with a <tab> shall begin a new entry.

Target names can be any character supported by the host system,
excluding <blank>s, <tab>s, <newline>s, and colons (:), which are used 
for delimiters.

For any given target there can be only one target rule.  The first
occurrence of a target in a makefile shall be used.  All subsequent
rules for the same target are ignored.  There is *no* support for 
adding prerequisites to a target's prerequisite list once a target
rule is defined.

There are no special targets or inference rule support.  


MACROS

Macro definitions are in the form:

	string1 = [string2]

The macro named string1 is defined as having the value of string2,
where string2 is defined as all characters, if any, after the equal
sign up to an unescaped <newline>.  Any <blank>s immediately before or
after the equal sign shall be ignored.

Subsequent appearances of $(string1) shall be replaced by string2.
The parentheses are *NOT* optional if string1 is a single character.
The macro $$ shall be replaced by the single character $.  

Macro names can be any character that the host system would allow in 
the definition of environment variables, excluding parentheses, ( and ), 
which are used for delimiters.

Macros can appear anywhere in the makefile, except within other macro 
references (ie. no nesting).  Macros in target and command lines shall 
be evaluated when the line is read.  Macros in macro definition lines 
shall be evaluated *IMMEDIATELY*.  A macro that has not been defined 
shall evaluate to a null string without causing any error condition.  

If a macro is defined more than once, the value of the macro shall be the 
last one specified prior to it being referenced.

Macro assignments shall be accepted from the sources listed below, in 
the order shown.  If a macro name already exists at the time it is being
processed, the newer definition shall replace the existing definition.

   1)	The contents of the environment, including the variables with
	null values in the order defined in the environment.

   2)	Macros defined in the makefile, processed in the order specified.

There are no internal macros supported.  The SHELL macro shall *NOT* be
treated specially.


EXIT STATUS

  0	Successful completion.
  1	General error.
  2	Usage error.
  3	Failed to open makefile.
  4	Failed to allocate memory.


INSTALLATION

AM can be built on any system providing at least K&R C.  It has been 
tested on 

	o  SunOS with GCC
	o  ATARI Mega ST with Sozobon C
	o  PC clone with Turbo C
	o  Interactive UNIX System V/386 release 3.2

For all machines, the compile command line should be

	cc -O -o am am.c

The value RULES represents the number of slots available to record
target rules, dependencies, and commands.  The default value chosen
should handle most project makefiles.  RULES can be overridden on the
command line with -DRULES=nn, where 0 < nn < INT_MAX.

On a DOS machine using Turbo C, it may be necessary to add the include
directive

	#include <time.h>

with the rest of the includes if sys/stat.h does not properly define or
use time_t.  Also, on some older K&R C compilers, stdlib.h may not be 
defined and so it might be necessary to remove the include directive for 
it. 


REFERENCES

[Mil87]	Webb Miller, "A Software Tools Sampler", Prentice Hall, 87
	ISBN 0-13-822305-X, chaper 2

[POSIX]	POSIX.2 draft 11.2 MAKE


FILES

ant.c		Obfuscated source
ant.README	Manual for AM
ant.test.mk	Test makefile


BUGS

Unknown as of 20 March 92.
