\documentstyle[12pt,nopagenumbers]{article}
\setlength{\oddsidemargin}{0.0in}
\setlength{\evensidemargin}{0.0in}
\setlength{\textwidth}{6.5in}
\setlength{\topmargin}{-0.5in}
\setlength{\textheight}{9.5in}
\settowidth{\parindent}{paper}
\setlength{\parskip}{1ex}
\newcommand{\name}[0]{How to use {\em make}}
\title{}
\author{}
\date{}
\newcommand{\PSbox}[3]{\mbox{\rule{0in}{#3}\special{psfile=#1}\hspace{#2}}}
\begin{document}
%\maketitle
%\thispagestyle{empty}
%\newpage
%\thispagestyle{empty}
\pagestyle{myheadings}
\markright{\name}

\begin{center}
{\Large \bf Makefile Primer}\\
\vspace{1ex}
How to use {\em make}\\
Course 1.12\\
Spring 1997\\
Based on 1.124 Makefile Primer\\
\end{center}

\section*{Introduction}
{\em make} is a command generator which generates a sequence of
commands for execution by the UNIX shell.  These commands usually
relate to the maintenance of a set of files in a software development
project.  We will use {\em make} to help us organize our C++ and C
source code files during the compilation and linking process.  In
particular, {\em make} can be used to sort out the dependency
relations among the various source files, object files and executables
and to determine exactly how the object files and executables will be
produced.


\section*{Invoking {\em make} from the command line}
{\em make} may be invoked from the command line by typing
\begin{quote}
make -f makefilename program
\end{quote}
Here, {\em program} is the name of the {\bf target} i.e.~the program
to be made.  {\em makefilename} is a {\bf description file} which
tells the {\em make} utility how to build the target {\em program}
from its various {\bf components}.  Each of these components could be
a target in itself. {\em make} would therefore have to build these
targets, using information in the description file, before {\em
program} can be made.  {\em program} need not necessarily be the
highest level target in the hierarchy, although in practice it often
is.

It is not always necessary to specify the name of the description file
when invoking {\em make}.  For example,
\begin{quote}
make program
\end{quote}
would cause {\em make} to look in the current directory for a default
description file named {\em makefile} or {\em Makefile}, in that
order.

Furthermore, it is not even necessary to specify the name of the final
target.  Simply typing
\begin{quote}
make
\end{quote}
will build the first target found in the default description file,
together with all of its components.  On the other hand, it is also
possible to specify multiple targets when invoking {\em make}.

There are a few other command line options which we will not discuss
here.  To find out more about these options, type {\em man make} at
your {\em athena\%} prompt.


\section*{{\em make} description files (makefiles)}
Here is an example of a simple makefile:
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
program: main.o iodat.o\\
\> cc -o program main.o iodat.o\\
main.o: main.c\\
\> cc -c main.c\\
iodat.o: iodat.c\\
\> cc -c iodat.c
\end{tabbing}
\end{quote}

Each entry consists of a {\bf dependency line} containing a colon, and
one or more {\bf command lines} each starting with a tab.  Dependency
lines have one or more {\bf targets} to the left of the colon.  To the
right of the colon are the {\bf component files} on which the
target(s) depend.

A command line will be executed if any target listed on the dependency
line does not exist, or if any of the component files are more recent
than a target.

Here are some points to remember:
\begin{itemize}
\item Comments start with a pound sign (\#).
\item Continuation of a line is denoted by a backslash ($\backslash$).
\item Lines containing equals signs (=) are macro definitions (see
next section).
\item Each command line is typically executed in a separate Bourne
shell i.e.~{\em sh}\footnote{Type {\em man sh} to find out more about
the Bourne shell.}.
\end{itemize}

To execute more than one command line in the same shell, type them on
the same line, separated by semicolons.  Use a $\backslash$ to
continue the line if necessary. For example,
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
program: main.o iodat.o\\
\> cd newdir; $\backslash$\\
\> cc -o program main.o iodat.o
\end{tabbing}
\end{quote}
would change to the directory {\em newdir} before invoking {\em cc}.
(Note that executing the two commands in separate shells would not
produce the required effect, since the {\em cd} command is only
effective within the shell from which it was invoked.)
  
The Bourne shell's pattern matching characters maybe used in command
lines, as well as to the right of the colon in dependency lines e.g.
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
program: *.c\\
\> cc -o program *.c
\end{tabbing}
\end{quote}


\section*{Macros}
\subsection*{Macro definitions in the description file}
Macro definitions are of the form
\begin{quote}
name = string
\end{quote}
Subsequent references to \$({\em name}) or \$\{{\em name}\} are then
interpreted as {\em string}.  Macros are typically grouped together at
the beginning of the description file.  Macros which have no string to
the right of the equals sign are assigned the null string.  Macros may
be included within macro definitions, regardless of the order in which
they are defined.

Here is an example of a macro:
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
CC = /mit/cygnus/decmipsbin/g++\\
program: program.c\\
\> \$\{CC\} -o program program.c
\end{tabbing}
\end{quote}

\subsection*{Shell environment variables}
Shell variables that were part of the environment before {\em make}
was invoked are available as macros within {\em make}.  Within a {\em
make} description file, however, shell environment variables must be
surrounded by parentheses or braces, unless they consist of a single
character.  For example, \$\{PWD\} may be used in a description file
to refer to the current working directory.

\subsection*{Command line macro definitions}
Macros can be defined when invoking {\em make} e.g.
\begin{quote}
make program CC=/mit/cygnus/decmipsbin/g++
\end{quote}

\subsection*{Internal macros}
{\em make} has a few predefined macros:
\begin{enumerate}
\item \$? evaluates to the list of components that are {\em younger}
than the current target.  Can only be used in description file command
lines.

\item \$@ evaluates to the current target name.  Can only be used in
description file command lines.

\item \$\$@ also evaluates to the current target name.  However, it
can only be used on dependency lines.
\end{enumerate}

Example:
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
PROGS = prog1 prog2 prog3\\
\$\{PROGS\}: \$\$@.c\\
\> cc -o \$@ \$?
\end{tabbing}
\end{quote}

This will compile the three files {\em prog1.c}, {\em prog2.c} and
{\em prog3.c}, unless any of them have already been compiled.  During
the compilation process, each of the programs becomes the current
target in turn.  In this particular example, the same effect would
be obtained if we replaced the \$? by \$@.c.

\subsection*{Order of priority of macro assignments}
The following is the order of priority of macro assignments, from
least to greatest:
\begin{enumerate}
\item Internal (default) macro definitions.
\item Shell environment variables.
\item Description file macro definitions.
\item Command line macro definitions.
\end{enumerate}
Items 2.~and 3.~can be interchanged by specifying the {\em -e} option
to {\em make}.

\subsection*{Macro string substitution}
String substitutions may be performed on all macros used in
description file shell commands.  However, substitutions occur only at
the end of the macro, or immediately before white space.  The
following example illustrates this:

\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
LETTERS = abcxyz xyzabc xyz\\
print:\\
\> echo \$(LETTERS:xyz=def)
\end{tabbing}
\end{quote}
This description file will produce the output
\begin{quote}
abcdef xyzabc def
\end{quote}


\section*{Suffix rules}
The existence of naming and compiling conventions makes it possible to
considerably simplify description files.  For example, the C compiler
requires that C source files always have a {\em .c} suffix.  Such
naming conventions enable {\em make} to perform many tasks based on
{\bf suffix rules}.  {\em make} provides a set of default suffix
rules.  In addition, new suffix rules can be defined by the user.

For example, the description file on page 2 can be simplified to
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
program: main.o iodat.o\\
\> cc -o program main.o iodat.o
\end{tabbing}
\end{quote}
{\em make} will use the following default macros and suffix rules to
determine how to build the components {\em main.o} and {\em iodat.o}.
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
CC = cc\\
CFLAGS = -O\\
.SUFFIXES: .o .c\\
.c.o:\\
\> \$\{CC\} \$\{CFLAGS\} \$$<$
\end{tabbing}
\end{quote}
The entries on the {\em .SUFFIXES} line represent the suffixes which
{\em make} will consider {\bf significant}.  Thus, in building {\em
iodat.o} from the above description file, {\em make} looks for a
user-specified dependency line containing {\em iodat.o} as a target.
Finding no such dependency, {\em make} notes that the {\em .o} suffix
is significant and therefore it looks for another file in the current
directory which can be used to make {\em iodat.o}.  Such a file must
\begin{itemize}
\item have the same name (apart from the suffix) as {\em iodat.o}.
\item have a significant suffix.
\item be able to be used to make {\em iodat.o} according to an
existing suffix rule.
\end{itemize}
{\em make} then applies the above suffix rule which specifies how to
build a {\em .o} file from a {\em .c} file.  The \$$<$ macro evaluates
to the component that triggered the suffix rule i.e.~{\em iodat.c}.

After the components {\em main.o} and {\em iodat.o} have been updated
in this way (if necessary), the target {\em program} will be built
according to the directions in the description file.

\subsection*{Internal macros in suffix rules}
The following internal macros can only be used in suffix rules.
\begin{enumerate}
\item \$$<$ evaluates to the component that is being used to make the
target.

\item \$* evaluates to the filename part (without any suffix) of the
component that is being used to make the target.
\end{enumerate}

Note that the \$? macro cannot occur in suffix rules.  The \$@ macro,
however, can be used.

\subsection*{Null suffixes}
Files with null suffixes (no suffix at all) can be made using a suffix
rule which has only a single suffix e.g.
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
.c:\\
\> \$\{CC\} -o \$@ \$$<$
\end{tabbing}
\end{quote}

This suffix rule will be invoked to produce an executable called {\em
program} from a source file {\em program.c}, if the description file
contains a line of the form
\begin{quote}
program:
\end{quote}
Note that in this particular situation it would be incorrect to
specify that {\em program} depended on {\em program.c}, because {\em
make} would then consider the command line to contain a null command
and would therefore not invoke the suffix rule.  This problem does not
arise when building a {\em .o} file from a {\em .c} file using suffix
rules.  A {\em .o} file {\em can} be specified to depend on a {\em .c}
file (and possibly some additional header files) because of the
one-to-one relationship that exists betweeen {\em .o} and {\em .c}
files.

\subsection*{Writing your own suffix rules}
Suffix rules and the list of significant suffixes can be redefined.
A line containing {\em .SUFFIXES} by itself will delete the current
list of significant suffixes e.g.
\vspace{-3ex}
\begin{quote}
\begin{tabbing}
\hspace{3em}\=\\
.SUFFIXES:\\
.SUFFIXES: .o .c\\
.c.o:\\
\> \$\{CC\} -o \$@ \$$<$
\end{tabbing}
\end{quote}

\begin{thebibliography}{9}
\bibitem{}{S. Talbot, `Managing Projects with Make', O'Reilly \&
Associates, Inc.}
\end{thebibliography}
\end{document}