Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/sirwumpus/ioccc-am

Best Utility (make) - IOCCC 1992 Winner
https://github.com/sirwumpus/ioccc-am

build-tool c ioccc make posix

Last synced: 11 months ago
JSON representation

Best Utility (make) - IOCCC 1992 Winner

Awesome Lists containing this project

README 

          
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 `` is reached.



A backslash before a `` serves as a line continuation mark, and

is used to create long-lines.   A line will continue to be extended

until an unescaped `` is reached.



When an escaped `` (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 .



## 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 ...]

	[command

	 command

	 ...]



	(line that does not begin with )



Target entries are specified by a -separated, non-null list of

targets, then a colon, then a ``-separated, possibly empty list

of prerequisites.  All following lines, if any, that begin with a

``, are command lines to be executed to update the target(s).  The

first line that does not begin with a `` shall begin a new entry.



Target names can be any character supported by the host system,

excluding `s`, `s`, ``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 ``.  Any `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 



*  SunOS with GCC

*  ATARI Mega ST with Sozobon C

*  PC clone with Turbo C

*  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 



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



* Webb Miller, "A Software Tools Sampler", Prentice Hall, 87

  ISBN 0-13-822305-X, chapter 2



* POSIX.2 draft 11.2 **make**



## BUGS



Unknown as of 20 March 1992.