\documentstyle[manpage,epsf,twoside]{report}

\begin{document}

\begin{titlepage}
	\vspace*{1.0in}
	\begin{flushright}
		{\huge\bf Amiga Programmer's Make} \\[.25cm]
		{\rule[.1in]{4.5in}{.02in}}\\[.25cm]
		{\large\bf Version 1.4} \\[2.0cm]
		{\large\bf Reference Manual} \\[4.0cm]
		{\bf by Ben Eng}\\
    \end{flushright}
	\newpage
	\thispagestyle{empty}
	\center{
	\leavevmode
	\epsffile{logo.ps}
	}
	\vspace*{\fill}
	\begin{flushleft}
		{Copyright \copyright 1991 Ben Eng}\\[2.0cm]
		{\bf Ben Eng}\\[.25cm]
		{150 Beverley St.\ Apt.\#{}1L}\\
		{Toronto, Ontario}\\
		{M5T 1Y6}\\
		{CANADA}\\[2.0cm]
		{telephone: (416)--979--8761}\\
		{e-mail:  becker!jetpen!ben}\\
		{BIX: jetpen}\\[2.0cm]
{Permission is granted to make and distribute copies of this
manual and the software that is herein described, provided the copyright
notices are preserved on all copies.}\\
    \end{flushleft}
\end{titlepage}

\addtocontents{toc}{\protect\thispagestyle{empty}}
\setcounter{page}{1}
\tableofcontents
\renewcommand{\thepage}{\arabic{page}}

\begin{abstract}
Make is a programming utility used to automate the process of recompiling
multiple interdependent source files into an output file (the goal).  The
Make program uses rules of inference to make the goal.  The rules for
making the goal are explicitly stated in an input file called the Makefile,
and implicitly determined from builtin rules.  Normally, the Makefile for a
goal is written so that the only thing that needs to be done to recompile
newly modified source files is to run the Make program.
\end{abstract}

%\pagenumbering{arabic}
\chapter{Distribution}

This is version 1.4 of the Make utility (BMake) for the Amiga.  For
information regarding an updated version, if it exists, please contact the
author by electronic mail, telephone or through the postal service in that
order of priority.  Details of how to contact me can be found in the {\tt
README} file associated with the distribution.

If you choose to make use of this software or distribute this software to
other users, please read the GNU General Public License which is enclosed
with the distribution as the file called {\tt COPYING}.

If you did not receive this software from the author by magnetic media or
direct transmission, then please take the time to register your version
so that updates will continue to be offered in the future.  A lack of
response will indicate that the product does not deserve further attention
and the software will be orphaned; a strong response will demand rapid
improvements in future upgrades of the product.

To register simply send a letter or postcard with your name (and company,
if they are using the product), address, and telephone number, along with
the name and version number of the product you are registering.

If you are already registered or if you are presently registering, you may
receive an upgrade direct from the author by sending a money order in the
amount of CDN\$20.00 ({\bf twenty Canadian dollars}) payable to the author,
Ben Eng, to the address given on the inside cover of this manual or in the
{\tt README} file, along with a letter requesting an upgrade (please,
mention the name of the product).  The latest release of the requested
product will be promptly sent out to you, or at your request a later
release will be mailed to you when it is available (ie.  if you are waiting
for a feature to be added).  The price covers the cost of the media and
shipping.


\chapter{The Make Program}

\section{Introduction}

The Make program was written to reduce the tedium involved in developing
software.  A program under development usually needs to be recompiled
many times per day.  Typing out the full command line for each step of the
compilation becomes exceedingly tedious, and a shell script is too crude to
figure out the most efficient way to recompile a large set of source files.
The Make program suits this purpose well.

With a properly written Makefile in the current directory, all that needs
to be typed to build the project under development is {\tt make}.  To build
only a subset of the project defined in the Makefile, simply type {\tt
make~\it goalname}, where {\it goalname} is the name of the goal, that
requires rebuilding.  The actual dependencies that must be checked and the
commands which must be executed are all taken care of in the Makefile and
the builtin rules.

\section{Command Line Arguments}

Sometimes it is necessary to alter the behaviour of the Make program due to
special circumstances.  Command line arguments are provided to control how
the Make program operates.

\begin{tabular}{ll}
{-a}	& make all dependents regardless of modification time \\
{-b}	& do not use builtin rules \\
{-d}	& debug mode (enable printf) \\
{+m\#}	& sets the maximum line length to \# (minimum=1024) \\
{-n}	& prints commands to be executed, but do not execute them \\
{-p}	& prints the database, but do not run \\
{-t}	& make targets up-to-date by touching (commands not executed) \\
{-v\#}	& set verbose level to \#; 0=silent \\
{-f{\em makefile}}	& specify the makefile to run \\
{{\bf var}={\em value}}	& assigns the value to a variable \\
{{\em wildcards}}	& specify targets to make
\end{tabular}

The Make program requires Amiga OS 2.0 to run with maximum capability.
Under Amiga OS 1.3, there is no wildcard support.  Run the program with the
argument {\tt ?} to see its usage, or {\tt -h} to get more descriptive help
on acceptable command line arguments.

The environment variable {\tt ENV:system} can be set to {\tt yes} if you
wish the command execution to use the Amiga OS 2.0 System() call.  If
{\tt ENV:system} is set to {\tt no}, the Amiga OS Execute() call is used.
The latter is desirable if you are still running with a shell that does not
support the 2.0 conventions (WShell 1.2 falls under this category).


\chapter{The Makefile}

\section{Introduction}

The Makefile is a text file written to maintain the construction of an
output file from a set of source files.  Normally, a Makefile is used to
define the rules for building an executable binary file from a set of
object files, which are created by compiling source files.

The Make program will read in the Makefile and use the rules to determine
which source files require recompilation, and whether or not the executable
file needs to be relinked.  For large projects with dozens of source files,
and complex interdependencies between the source and include files, the use
of a Make program with a properly written Makefile is essential for
ensuring that the executable is up-to-date.  During the development cycle,
the tedium of manually recompiling newly modified source files is removed
from the programmer's responsiblity.  The procedure is automated by the
Make program, so that the programmer does not need to worry about which
files need to be updated and how to perform the updating.

For most applications a Makefile is easy to write.  A few minutes spent
writing a Makefile can save the programmer a great deal of time that may
have been wasted tediously typing in command lines to recompile a project.
The Make program was designed to make the rebuilding procedure trivial and
reliable.

\section{Description}

A typical Makefile is composed of three basic constructs:  comments,
variable definitions and rules.  Any line beginning with a {\tt \#}
character is considered to be a comment line.  Comment lines are ignored by
the Make program.  Variables (also known as macros) and rules are
complicated topics and they will be discussed in separate sections.

The Makefile is written to define the rules for making a goal up-to-date.
A goal file is up-to-date if it has a modification datestamp that is more
recent than all of its dependents, after all dependents are updated with
respect to their dependents.  This criterion is applied recursively, such
that the most deeply nested dependent will be made before any target file
that depends on it.

\section{Rules in a Makefile}

Several types of rules are recognized by the Make program; they can be
grouped into two categories:  explicit rules and implicit rules.  The
explicit rules are known as target rules.  The implicit rules exist as
suffix rules and pattern rules (internally these two types of rules are
represented in the same way).

\subsection{Explicit Rules}

Target rules are defined by a line that begins with one or more target
names, followed by a colon, an optional list of dependent filenames, an
optional semicolon and an optional command.  Subsequent lines that begin
with a tab character are command lines associated with the rule.  The next
line that does not begin with a tab character indicates the end of the
current rule and the beginning of a new rule.

\begin{verbatim}
goal: target.o ; command three

target.o: source.c header.h
    command one
    command two
\end{verbatim}

In the above example, the Make program will read the Makefile and find the
first target filename to be {\tt goal}.  It will then attempt to make {\tt
goal} up-to-date by first making its dependents (namely, {\tt target.o})
up-to-date.  In order to make {\tt target.o} up-to-date, Make requires a
rule that contains {\tt target.o} as a target filename.  Such a rule exists
in the example Makefile with dependents {\tt source.c} and {\tt header.h},
which must in turn be made before {\tt target.o} can be made up-to-date.
Since {\tt source.c} and {\tt header.h} are not defined as targets in the
Makefile, the Make program must use builtin rules of inference to make
those files up-to-date, or it must give up and report that is doesn't know
how to make the target.  As it turns out, the source and header files are
known by builtin rules of inference to require no further action to be made
up-to-date, so the Make program can continue to make {\tt target.o} now
that its dependencies have fulfilled their requirements.  In order to make
{\tt target.o} up-to-date, {\tt command one} must be executed successfully,
and then {\tt command two} must be executed successfully after that.
Finally, the goal can be made by executing the command line, {\tt command
three}, and the Make program will terminate.

If there are no dependencies for a target, and a target needs to be remade
by the Make program, then the target is always remade.  A target with no
dependencies will always have its commands executed when that target needs
to be remade.

\subsubsection{Dependencies}

The dependencies of a target are the objects which a particular target
depends upon.  If a target depends upon an object, then the dependent
object must be updated before the target may be updated.  A target is not
up-to-date if its dependencies are not all up-to-date.

Additional dependencies can be added to a target defined in another rule by
writing a new rule which declares the additional dependencies.  Only one of
the rules may contain command lines, otherwise it is an error.  An example
where this might be done is given below:

\begin{verbatim}
target1.o target2.o : global.h
target1.o : one.h
target2.o : two.h
\end{verbatim}

\subsubsection{.ALWAYS}

If a target has {\tt .ALWAYS} as a dependency then that target will always
have its dependencies remade and its commands executed.

\subsubsection{.NEVER}

If a target has {\tt .NEVER} as a dependency then that target will never
have its dependencies remade or its commands executed.

\subsubsection{.ONCE}

If a target has {\tt .ONCE} as a dependency then that target will be
made only once.  When the target is encountered again, it will be skipped.

\subsubsection{.INVISIBLE}

If a target has {\tt .INVISIBLE} as a dependency then that target will be
invisible to all other targets.  That is, the invisible target may be made,
but the target that depended upon the invisible target will not be aware of
the fact.

\subsection{Implicit Rules}

\subsubsection{Pattern Rules}

When no explicit rule is defined for a target, the Make program must use
other means to determine how to make the target up-to-date.  Rules of
inference are defined by pattern rules.  An example of a double pattern
rule is:

\begin{verbatim}
%.o: %.c
    $(CC) -c $(CFLAGS) -o $@ $<
\end{verbatim}

The above suffix rule defines how to make any target with a filename ending
in {\tt .o} if there is a corresponding dependent filename that ends in
{\tt .c}.  The commands associated with a pattern rule are executed if the
dependent file is newer than the target file, which matches the pattern.
The {\tt \%} character matches any number of characters in the target name.
Only one such wildcard character may exist per name.

There may be only one dependent in a pattern rule (extra dependents given
on the line are ignored).  The {\tt \%} character in the dependency pattern
is replaced with the stem (the sequence of characters which were matched by
the {\tt \%}) from the target name.

A single pattern rule of the form:

\begin{verbatim}
%.Z:
    compress $*
\end{verbatim}

is the same as a double pattern rule, except that there is no dependency
pattern.  As a result, the automatic variable {\tt \$<} is not defined in the
scope of a single suffix rule.  Since there are no dependencies, any target
matching a single suffix rule will always be remade; the commands will
always be executed.

There may be more than one pattern rule applicable per target name.  The
first matching pattern rule will have priority.  If several pattern rules
are defined with the same target pattern, then the pattern rule that was
defined earlier will have priority over all later definitions.  Thus,
pattern rules with the same target but different dependencies can be
defined in natural prioritized order; the first one defined will be the
first one applied to inference rules.

However, if a new definition is given that exactly duplicates both the
target pattern and the dependency pattern then the new definition will
replace the old pattern rule.

\subsubsection{Suffix Rules}

To maintain compatibility with older versions of Make, suffix rules can be
defined.  They are a poor man's style of pattern rules.  An example of a
double suffix rule is:

\begin{verbatim}
.c.o:
    $(CC) -c $(CFLAGS) -o $@ $<
.SUFFIXES: .c .o
\end{verbatim}

The above suffix rule defines how to make any target with a filename ending
in {\tt .o} if there is a corresponding dependent filename that ends in
{\tt .c}.  The commands associated with a suffix rule are executed if the
dependent file is newer than the target file.

A suffix rule has no dependencies listed to the right of the colon.  If
such dependencies exist, then the rule definition is considered to be an
ordinary target rule.

The {\tt .SUFFIXES} directive is used to cause the Make program to find all
ordinary rules that can be interpreted as suffix rules matching the suffix
arguments.  Each suffix rule is transformed into its equivalent pattern
rule at this time.

\subsubsection{Pattern Rules versus Suffix Rules}

Pattern rules should be used because they are far more flexible than suffix
rules.  Suffix rules are internally represented by pattern rules anyway,
but an extra {\tt .SUFFIXES} directive must be given before a suffix rule
is recognized.

\subsection{Command Lines}

Command lines are executed in order of appearance if any dependency is
newer than the target.  The commands executed for a rule should do
something that causes the target's modification date to be updated.

The Make program knows nothing about what the command lines mean or do.
The command lines are simply passed to the shell for execution.  If
executing the command line results in an error, then the Make program will
terminate.

Sometimes it is desirable to ignore the error returned by a command,
because failure to execute the command does not affect the successful
completion of the Makefile.  If this is true then the error returned by a
command can be ignored by preceding the command with a {\tt -} character.
For example:

\begin{verbatim}
clean:
    -delete #?.o
\end{verbatim}

Normally, each command is printed (echoed) before execution.  Echoing for
each command can be disabled by preceding it with a {\tt @} character.  This
does not affect its execution.  The {\tt @} character does not redirect the
standard output of the program being executed.  Redirection must be stated
explicitly.

\subsubsection{Special Commands}

The {\tt cd} command can be used to change the current directory of the
Make program.  This command is special; it is handled by the Make program
itself, instead of being executed by the shell.  After the current
directory is changed, all subsequent commands which are executed from
within Make will inherit the new current directory, until another {\tt cd}
command is issued.  If no argument is given to {\tt cd} then the original
current directory is restored.  The original current directory, where the
Make program was executed, will be restored before the Make program exits.

Conditional commands are also handled internally by the Make program.
Refer to section \ref{condcmds} on the behaviour of conditional
commands.

\subsubsection{Variable Assignment Commands}

A command line containing the {\tt =} character will be interpreted as a
variable assignment (see section \ref{varass}).  Thus, variables can be
given values which depend upon which rule was resolved.  Variable
assignment commands are executed in the context of the rule which is being
resolved at run time.


\subsection{Default Target Rule}

Sometimes it might be desirable to define a rule that is only executed when
all other rules have failed to make a target up-to-date.  As a last resort,
one might wish to simply {\tt touch} the target file, or perform no action
at all, and allow Make to continue.

\begin{verbatim}
.DEFAULT:
    command lines
\end{verbatim}

If the {\tt .DEFAULT} target is given no commands (as is the default
behaviour) then the Make program will terminate with an error whenever it
encounters a target name that cannot be made.


\subsection{Builtin Rules}

By default, the Make program knows several builtin pattern rules.  Here is
a list of their definitions:

\begin{verbatim}
%,v:

%.a: RCS/%.a,v
    $(CO) -u $@
%.a:

%.c: RCS/%.c,v
    $(CO) -u $@
%.c:

%.h: RCS/%.h,v
    $(CO) -u $@
%.h:

%.i: RCS/%.i,v
    $(CO) -u $@
%.i:

%.o: %.c
    $(CC) -c $(CFLAGS) -o $@ $<

%.o: %.a
    $(AS) -c $(AFLAGS) -o $@ $<
\end{verbatim}

Notice that assembly and C language headers and source files have no
dependencies and require no commands to be executed in order to make them
up-to-date.  User defined rules should be added to the Makefile if that is
not the case.

\subsection{User Defined Builtin Rules}

If the user needs to supplement the internal builtin rules with addition
suffix rules and variable definitions, they can be declared in one of two
files:  {\tt S:builtins.make} or {\tt builtins.make}.  If they exist, these
two files are read (in the order listed above) before the Makefile by the
Make program.  All rules and variables in these files may be referenced (or
overridden) in the Makefile.


\section{Variables and Macros}

\label{varass}

Variables can contain macro definitions of multiple filenames or other
text.  They are useful for replacing multiple occurrences of the same body
of text with references to a variable (macro expansion).  A variable is
defined in the Makefile with an assignment statement.  Only the last
assignment of a variable is recognized, because the rules are processed
after the entire Makefile has been interpreted into internal rules by the
Make program.

In a makefile, the line:

\begin{verbatim}
myvariable = source.c header.h
\end{verbatim}

is used to assign the string {\tt source.c header.h} to the variable named
{\tt myvariable}.  In the following rule definition:

\begin{verbatim}
target.o: $(myvariable)
\end{verbatim}

the \$(myvariable) reference is expanded into the string assigned to
{\tt myvariable}.  If the macro expansion contains further references to other
variables, then they are also recursively expanded until the resulting
string is fully expanded.  Undefined macros are expanded to nothing (empty
strings).  \$\{myvariable\} is equivalent to \$(myvariable).
For single character variable names, the parentheses or braces are not
necessary to expand the macro; the single character may immediately follow
the {\tt\$ }.

Additional text can be concatenated to the end of the value of an existing
variable by using the {\tt +=} operator, like this:

\begin{verbatim}
alpha = abc
alpha += def
\end{verbatim}

The result of {\tt\$(alpha)} is now {\tt abc def}.  Notice the space
inserted at the point of concatenation.  This ensures that filenames are
not split between different lines.

It is possible to define a variable which results in an infinitely
recursive macro expansion.  This is illegal, and it will result in an error
when that variable is referenced.

A variable can be defined, such that its value is expanded immediately at
the time of assignment.  These are called simple variables, and they are
assigned with the {\tt :=} operator.  Note that when a simple variable is
assigned, any other references to variables will expand to their value as
assigned above the line of the simple variable being assigned.  Here is an
example:

\begin{verbatim}
simplevar := $(myvariable)
\end{verbatim}

The only difference between an ordinary variable and a simple variable is
that the value of the simple variable is expanded only once during its
assignment, whereas the value of an ordinary variable needs to be expanded
every time it is referenced.  Referencing a simple variable requires only a
simple substitution, whereas referencing an ordinary variable requires a
recursive macro expansion, which requires more work (memory, stack, and CPU
instructions).

Variables referenced in the target and dependencies of a rule are expanded
during the rule definition.  Variables referenced in each command line
associated with a rule are expanded when the command line is executed.

Both $\backslash$\$ and \$\$ expand to the character \$, but the latter is
recommended.


\subsection{Automatic Variables}

There is a set of variables that are automatically defined at runtime by
the Make program.


\begin{tabular}{ll}
\$@		& expands to: target filename \\
\$*		& expands to: target filename without its suffix \\
\$<		& expands to: the first dependent filename \\
\$\^	& expands to: all dependents of target newer than target
	(not implemented) \\
\$\%	& expands to: dependent member of the target archive (not implemented) \\
\$?		& expands to: all dependents of the target archive (not implemented)
\end{tabular}


The value of an automatic variable depends on where it is referenced.  An
automatic variable has a different value according to the objects of the
rule to which it applies.  \$@ does not expand in the target position.
Automatic variables making reference to dependencies do not make sense when
used in the place of a target name or dependency, so they will not be
defined when referenced in those situations; those variables will expand to
their proper values in command lines.

If a {\tt D} extension appears in the automatic variable name then only the
directory part of the value is returned.  A {\tt F} extension returns only
the file part of the value.  Thus, \verb|$(@D)| is equivalent to
\verb|$(dir $@)|; in fact, all of these extensions are implemented as
builtin macros.


\subsection{Complex Variable names and Macro Expansions}

Rarely is it necessary to apply what is discussed in this topic, but the
information will be given for completeness.  Because of the recursive
nature of the macro expansion algorithm, it is possible to construct
variables that act like arrays (or other complex data types) through the
use of variable names that themselves contain a nested macro expansion.
Here is an example of an obscure sort of Makefile that uses this technique:

\begin{verbatim}
A1	= one.c
A2	= two.c

target.o: ${A$(B)}
    $(CC) -c $(CFLAGS) -o $@ $<
\end{verbatim}

Depending on whether the value of the variable {\tt B} is set to {\tt 1} or
{\tt 2}, the target file will depend on {\tt one.c} or {\tt two.c}.

Although there is no internal limit restricting the level to which macros
can be nested (in the variable name and its value), it is recommended that
nesting be kept to a minimum to conserve on memory consumption and stack
usage.  Each level of nesting requires at least an additional 2K of memory.

Please note that the maximum length of a variable name is limited to 256
characters.

\section{Function Calls}
\newpage

\begin{manpage}{Make}{Function Calls}{}

\subtitle{Function Calls}

Function calls of the form {\tt\$(function~arguments)} or
{\tt\$\{function~arguments\}} will be processed differently than a normal
macro expansion.  A function call acts like a macro expansion in that it
returns a string.  All spaces, except for the sequence of spaces before the
first argument (after expansion), are significant.

\subtitle{String Functions}

(see section 9.2 of the GNU Make manual)

String functions generally accept a set of input strings and perform a
transformation to return a result string.

\separator
\function*{\$(filter pattern,text)}

A pattern is a word that optionally contains a single wildcard character
{\tt\%}.  All words in {\tt text} that do not match the {\tt pattern} are
removed, so that this function call returns only matching words.

\separator
\function*{\$(filter-out pattern,text)}

All words in {\tt text} that match the {\tt pattern} are removed, so that
this function call returns only non-matching words.  The result is the
complement of the result of \$(filter pattern,text).

\separator
\function*{ \$(findstring find,in)}

If the {\tt in} string contains the {\tt find} string then the {\tt find}
string is returned, otherwise the result is an empty string

\separator
\function*{\$(patsubst pattern,replacement,text)}

The result is a list of words derived from {\tt text}.  {\tt text} is a
whitespace separated list of words.  Each word is compared with {\tt
pattern}.  A {\tt\%} character in the pattern matches any number of
characters; only one {\tt\%} may appear in the pattern.  If the pattern
does not match the word then the word is appended unchanged to the result,
otherwise a substitution is performed on the word, the result of which is
appended to the result.

If a substitution is necessary, then the resulting word is formed by any
characters preceding the {\tt\%} of {\tt replacement}, plus every character
of the current word of {\tt text} that was matched by the {\tt\%} of {\tt
pattern}, plus any characters following the {\tt\%} of {\tt replacement}.
In other words, if the {\tt\%} character occurs in both {\tt pattern} and
{\tt replacement} then the substring matched by the {\tt\%} will be
substituted for the {\tt\%} in the {\tt replacement} string, which will
then be used as the next word of the result.  For example,
\$(patsubst~pre\%post,a\%b,dogfood~preAApost) will result in the string
{\tt dogfood~aAAb}.

\separator
\function*{\$(sort list)}

sorts the list of names into ascending lexical order.

\separator
\function*{\$(strip string)}

strips leading and trailing whitespace from string, and replaces embedded
sequences of spaces with a single space.

\separator
\function*{\$(subst from,to,text)}

replaces all occurrences in {\tt text} that match the string {\tt from}
with the string {\tt to}.


\subtitle{Filename Functions}

Filename functions perform transformations on parts of pathnames.  The disk
objects do not have to actually exist in the filesystem, but the pathnames
generally should follow the usual naming conventions.  Three parts of a
pathname may be operated upon:  the directory part, the filename part and
the suffix part of the filename.

\separator
\function*{\$(dir names)}

Extracts the directory part of each pathname in {\tt names}, including the
trailing slash or colon.  No checking is done to determine whether the
result is actually a directory or not; this command acts only as a string
function, and knows nothing about the organization of the filesystem.

\separator
\function*{\$(notdir names)}

Extracts the file part of each pathname in {\tt names}.  The result is the
complement of \$(dir names).

\separator
\function*{\$(suffix names)}

Extracts only the suffix of each pathname in {\tt names}.  The suffix is
the rightmost part of the name starting at the last {\tt .} character.

\separator
\function*{\$(basename names)}

Extracts all but the suffix of each pathname in {\tt names}.  The result
is the complement of \$(suffix names).
	
\separator
\function*{\$(addsuffix suffix,names)}

The result is the list of names with {\tt suffix} appended to each word of
the list.

\separator
\function*{\$(addprefix prefix,names)}

The result is the list of names with {\tt suffix} prepended to each word of
the list.

\separator
\function*{\$(join list1,list2)}

The result is the wordwise concatenation of {\tt list1} with {\tt list2}.

\separator
\function*{\$(word n,text)}

Returns the nth word of {\tt text}.  The first word of text is numbered
1, and the last word of text is numbered \$(words text).

\separator
\function*{\$(words text)}

Returns the number of words in {\tt text}.

\separator
\function*{\$(firstword names)}

Returns the first word of {\tt names}.  The result is the same as
\$(word~1,names)

\separator
\function*{\$(wildcard pattern)}

The {\tt pattern} argument is an Amiga OS wildcard pattern.  The result is
a list of files matching that pattern.

NOTE:  Wildcards are only supported under Amiga OS 2.0

An example of a generic makefile that can be used to compile a program,
that depends only upon all of the .c files in the current directory, is
given below:


\begin{verbatim}
SRCS := $(wildcard #?.c)
OBJS := $(subst .c,.o,$(SRCS))

a.out:	$(OBJS)
    $(CC) -o $@ $(CFLAGS) $(OBJS)
\end{verbatim}


\subtitle{Special Functions}

\separator
\function*{\$(foreach var,list,text)}

(see section 9.4 of the GNU Make manual)

This function call is not implemented.  A workaround might be to unroll the
loop manually.

\separator
\function*{\$(getenv name)}

The result is the contents of the environment variable {\tt ENV:name}.
This function call is offered to allow the Makefile to explicitly reference
an environment variable, instead of the internal Make variable.

Note:  referencing an undefined variable for the first time automatically
assigns the result of \$(getenv~macro) to the variable.

\separator
\function*{\$(origin variable)}

(see section 9.5 of the GNU Make manual)

Not implemented.

\separator
\function*{\$(shell command line)}

(see section 9.6 of the GNU Make manual)

This function call is not implemented.  A workaround might be to redirect
the {\tt command~line} standard output into an environment variable and
then capture the environment variable's value into a macro for Make to use.

\end{manpage}

\section{Conditionals}

\subsection{Conditional Directives}

A conditional directive can be used to control which parts of a Makefile
are executed, based upon the value assigned to certain variables.  The
familiar

\begin{verbatim}
if condition
    ...true...
else
    ...false...
endif
\end{verbatim}

syntax is used for this purpose, where {\tt \ldots true\ldots} represents
any number of lines which are executed if the condition is true, and {\tt
\ldots false\ldots} represents any number of lines which are executed if
the condition is false.  Each of the three conditional directives must
appear as the first word on a line.  The {\tt else} directive is optional.
The condition may be one of the following:

\begin{tabular}{ll}
eq(arg1,arg2)	& true if arg1 is exactly equal to arg2 \\
neq(arg1,arg2)	& true if arg1 is not equal to arg2 \\
def(variable)	& true if variable is defined \\
ndef(variable)	& true if variable is undefined \\
exists(pathname)	& true if pathname exists in the filesystem \\
nexists(pathname)	& true if pathname does not exist in the filesystem
\end{tabular}

Nested conditionals are acceptable.  There is no way to perform logical
{\bf AND} and logical {\bf OR} operations within the condition expression,
so nested conditionals will have to be used instead to do the same job.
Each {\tt if} and {\tt else} must have a matching {\tt endif} directive
associated with its conditional construct.

The {\tt else} and {\tt endif} directives must reside in the same Makefile
as their corresponding {\tt if} directive.  A conditional construct cannot
be split across Makefiles.

The use of conditional directives in a Makefile is vaguely analogous to the
use of {\tt \#{}if}, {\tt \#{}else}, and {\tt \#{}endif} preprocessor
directives in C source code to control conditional compilation.


\subsection{Conditional Commands}

\label{condcmds}

The conditional commands can be used to control the behaviour of the
command lines of rules.  The syntax is exactly the same as the syntax for
conditional directives, except that conditional commands are indented with
a tab; they appear in the body of a rule along with other commands.
Nesting is supported.

Here is an example of where a conditional command might be useful for
checking out RCS files, when the RCS directory is not accessible by the
Make program (when knowledge of RCS file organization is private to RCS
itself):

\begin{verbatim}
%.c:
    if nexists($@)
        $(CO) -u $@
    endif
\end{verbatim}


\section{Pragma Directive}

Command line arguments for the Make program may be added to a line
beginning in {\tt pragma}.  For example,

\begin{verbatim}
pragma +m2048
\end{verbatim}

will set the maximum line length to at least 2048 bytes, if that parameter
has not already been set to a higher value.


\section{Include Directive}

Other Makefiles can be included from a Makefile with the {\tt .INCLUDE}
directive (it must appear at the beginning of a line, like any other
directive).  For example,

\begin{verbatim}
.INCLUDE submakefile
\end{verbatim}

will read in all the rules and macros from a file called {\tt submakefile}
and then continue reading the current Makefile.  This can be done from the
builtin Makefiles as well as any user Makefile.  Nesting of includes is
allowed; the maximum nesting level is indefinite.

\section{Phony Directive}

The {\tt .PHONY} directive can be used to mark a target as having no
correspondence to a real file.  This is useful for propagating the proper
up-to-date condition past a phony target rule.  For example,

\begin{verbatim}
all:  target1 target2

.PHONY: all
\end{verbatim}


\chapter{Building Make}

\section{Compiling}

The source code for this program was written for the DICE C compiler,
version 2.06.30, by Matthew Dillon.  The tab size is set to 4.  You will
require the 2.0 Amiga include files from CATS of Commodore-Amiga to compile
this program.  The source code should compile under any ANSI C compiler for
the Amiga.

If the executable needs to be recompiled then the following procedure
should be used.

Rename the Make program to {\tt make} and move it to a directory in your
shell's execution path.  The Makefile supplied with the program is probably
incompatible with more primitive versions of Make.

The {\tt include/scdir.h} header file should be copied to a directory in
the include path for your compiler.  The compiler should be set up to
compile using the Amiga OS 2.0 (or later) include files.

The link library {\tt ben.lib} needs to be made first.  Change your
directory to the {\tt ben} directory and type {\tt make}.  If all goes
well, then the {\tt ben.lib} library will be created; it should be moved to
the library search path for your compiler, so that the linker will be able
to find it.

Change your directory to the main source directory for the make utility and
type {\tt make} to create the binary executable file {bmake}.  This file
can be renamed to the standard {\tt make}, and placed in the command search
path for convenience.


\section{Parameters}

\subsubsection{{\tt DEBUG} = (1 default) non-zero if debug calls are
activated}

Defining {\tt DEBUG} to 0 will disable code generation for the debugging
option.  The -d command line option will be disabled if {\tt DEBUG} is 0.
{\tt DEBUG} enabled by default (in {\tt make.h}).  Enabling {\tt DEBUG}
adds about 2400 bytes to the size of the final executable.

\subsubsection{{\tt FNCALLS} = (1 default) non-zero if function calls are
activated}

If function calls are to be recognized, this parameter should be defined to
be non-zero.  Disabling function calls will make the executable somewhat
smaller, and memory requirements will be lower.  Enabling {\tt FNCALLS}
adds about 4600 bytes to the size of the final executable.

\subsubsection{{\tt MAXSUFFIX} = (16 default) the maximum number of
characters in a suffix}

This parameter limits the maximum size of filename extensions
recognized by the Make program.  This affects suffix rules and other
operations that operating on suffixes.  Suffixes are allocated on
the stack and dynamically in this fixed size.

\subsubsection{{\tt MAX_MACRONAME} = (256 default) the maximum number of
characters in a name}

This parameter limits the size of a macro name.

\subsubsection{{\tt MAXPATHNAME} = (108 default) the maximum number of
characters in a pathname}

This parameter limits the size of a pathname that can be used to
resolve suffix rules.  Dynamically allocated.


\section{Options}

In the Makefile, the {\tt -gs} option can be added to {\tt CFLAGS} to
enable DICE's dynamic stack code.  It makes the program grow in size by a
couple of kilobytes, and it slows down execution by a few milliseconds, but
it does make it safe to run the Make program on a huge Makefile that makes
extensive use of recursive macros and rules, without having to worry about
overflowing the stack.


\section{Debugging}

If debugging is enabled ({\tt DEBUG}=1), then the command line arguments
{\tt -d -v9 +l} will generate a verbose log file called {\tt make.log},
which will give some insight into what the Make program was attempting to
do.  The {\tt +l} parameter directs Make's output to {\tt make.log}.
Higher verbosity levels will cause more details to be logged.


\chapter{Compatibility}

What follows is a list of features, which are not yet supported in this
implementation of Make:

\begin{itemize}
\item the {\tt override} directive
\item the {\tt foreach} function
\item the {\tt origin} function
\item the {\tt shell} function
\item static pattern rules
\item double colon rules
\item {\tt VPATH} search path for dependencies
\item the {\tt vpath} directive
\item communicating options to a submake
\item the automatic variables \$\^{}, \$? and \$\%
\item the directives {\tt .IGNORE}, {\tt .PRECIOUS} and {\tt .SILENT}
\item archives are not supported.
\item the automatic variable {\tt MAKELEVEL} is not implemented.
\item the {\tt MAKEFILES} variable is not supported
\item parallel execution is not supported.
\item the special significance of {\tt +} in a command line
\end{itemize}

What follows is a list of incompatibilities:

\begin{itemize}
\item the command line arguments are different
\item GNU Make allows conditional expressions in five forms: \\
		ifeq (arg1,arg2) \\
		ifeq 'arg1' 'arg2'\\
		ifeq "arg1" "arg2" \\
		ifeq 'arg1' "arg2" \\
		ifeq "arg1" 'arg2' \\
		this implementation only allows the first form.
\item the AmigaDOS wildcard syntax is different than that used in Unix.
\item the behaviour of certain pattern rules may not be what is
		expected because GNU Make only matches patterns in the file part
		of the pathname, whereas the entire pathname is matched in this
		implementation.
\item executing the Make program from within a Makefile is untested,
		and the author doesn't know what to expect.
\item None of the builtin rules are the same.  Only a very basic set
		of C language rules have been included to save memory.
		Embellishing the builtin rules can be done in one of the Makefiles
		which are read in before the user Makefile.
\item When using the {\tt dir} function, pathnames without a directory
		part are not translated into {\tt ./} for the current directory,
		because in AmigaDOS, the current directory is the null string.
		Thus {\tt dir} and {\tt nodir} may not be undone with the
		{\tt join} function.
\item GNU Make does not allow conditional commands, but they are
		supported in this program.
\item GNU Make does not support the {\tt exists} or {\tt nexists}
		conditions, but they are supported in this program.
\item The use of quotation marks and backslash characters to delimit
		strings and escape characters respectively is ignored on the most
		part in this program.
\item GNU Make may consider the dependent of an implicit rule (a
		pattern rule) to be terminal; ie. there is no need for the
		dependent of an implicit rule to be made first.  This program
		does not consider such a dependent as terminal.  A single
		suffix (pattern) rule with no dependents and no commands may
		be used to terminate the search.
\end{itemize}

\end{document}