.TH USGMAKE 1
.SH NAME
usgmake \- maintain, update, and regenerate groups of programs
.SH SYNOPSIS
.B usgmake
.RB [ \-f " makefile]"
.RB [ \-p ]
.RB [ \-i ]
.RB [ \-k ]
.RB [ \-s ]
.RB [ \-r ]
.RB [ \-n ]
.RB [ \-b ]
.RB [ \-e ]
.RB [ \-m ]
.RB [ \-t ]
.RB [ \-d ]
.RB [ \-q ]
[\|names\|]
.SH DESCRIPTION
The following is a brief description of all options and some special
names:
.TP "\w'\f3\-f\fP makefile\ \ 'u"
.BI \-f " makefile\^"
Description file name.
.I makefile\^
is assumed to
be the name of a description file.
A file name of
.B \-
denotes the standard input.
The contents of
.I makefile\^
override the built-in rules if they
are present.
.TP
.B \-p
Print out the complete set of macro definitions and target descriptions.
.TP
.B \-i
Ignore error codes returned by invoked commands.
This
mode is entered if the fake target name
.B \&.\s-1IGNORE\s+1
appears in the description file.
.TP
.B \-k
Abandon work on the current
entry, but continue on other branches
that do not depend on that entry.
.TP
.B \-s
Silent mode.
Do not print command lines before executing.
This mode is also entered if the fake target name
.B \&.\s-1SILENT\s+1
appears in the description file.
.TP
.B \-r
Do not use the built-in rules.
.TP
.B \-n
No execute mode.
Print commands, but do not execute
them.
Even lines beginning with an
.B @
are printed.
.TP
.B \-b
Compatibility mode for old makefiles.
.TP
.B \-e
Environment variables override assignments within makefiles.
.TP
.B \-m
Print a memory map showing text, data, and stack.
This option
is a no-operation on systems without the \f2getu\^\fP system call.
.TP
.B \-t
Touch the target files (causing them to be up-to-date)
rather than issue the usual commands.
.TP
.B \-d
Debug mode.
Print out detailed information on files
and times examined.
.TP
.B \-q
Question.
The \f2make\^\fP command returns a zero or non-zero
status code depending on whether the target file is or
is not up-to-date.
.TP
.B \&.\s-1DEFAULT\s+1
If a file must be made but there are no explicit commands
or relevant built-in rules, the commands associated
with the name
.B \&.\s-1DEFAULT\s+1
are used if it exists.
.TP
.B \&.\s-1PRECIOUS\s+1
Dependents of this target will not be removed when
quit or interrupt are hit.
.TP
.B \&.\s-1SILENT\s+1
Same effect as the \f3\-s\fP option.
.TP
.B \&.\s-1IGNORE\s+1
Same effect as the \f3\-i\fP option.
.PP
.I make\^
executes commands in
.I makefile\^
to update
one or more target
.IR names .
.I name\^
is typically a program.
If no
.B \-f
option is present, \f3makefile\fP, \f3Makefile\fP, \f3s.makefile\fP,
and \f3s.Makefile\fP are
tried in order.
If
.I makefile\^
is
.BR \- ,
the standard input is taken.
More than one
.BI \- " makefile"
argument pair may appear.
.PP
.I make\^
updates a target only if it depends on files that are
newer than the target.
All prerequisite files of a target are added recursively to
the list of targets.
Missing files are deemed to be out of date.
.PP
.I makefile\^
contains a sequence of entries that specify dependencies.
The first line of an entry is a
blank-separated, non-null list of targets, then a
.BR : ,
then a (possibly null) list of prerequisite files or dependencies.
Text following a
.B ;
and all following lines
that begin with a tab are shell commands
to be executed to update the target.
The first line that does not begin with a tab or
.B #
begins
a new dependency or macro definition.
Shell commands may
be continued across lines with the <backslash><new-line> sequence.
Everything printed by make (except the initial tab) is passed
directly to the shell as is.
Thus,
.PP
.ss 18
.RS
.PD 0
echo a\\
.br
b
.RE
.ss 12
.PD
.PP
will produce
.PP
.ss 18
.RS
.PD 0
ab
.RE
.ss 12
.PD
.PP
exactly the same as the shell would.
.PP
Sharp
.RB ( # )
and new-line surround comments.
.PP
The following
.I makefile\^
says that
.B pgm
depends on two
files
.B a.o
and
.BR b.o ,
and that they in turn depend on
their corresponding source files
.RB ( a.c
and
.BR b.c )
and a common file
.BR incl.h :
.PP
.ss 18
.RS
.PD 0
.TP
pgm: a.o b.o
cc a.o b.o \-o pgm
.TP
a.o: incl.h a.c
cc \-c a.c
.TP
b.o: incl.h b.c
cc \-c b.c
.PD
.RE
.ss 12
.PP
Command lines are executed one at a time, each by its
own shell.
The first one or two characters in a command can be
the following: \f3-\fP, \f3@\fP, \f3-@\fP, or \f3@-\fP.
If \f3@\fP is present, printing of the command is suppressed.
If \f3-\fP is present, \f2make\^\fP ignores an error.
A line is printed when it is executed unless the
.B \-s
option is present, or the entry
.B \&.\s-1SILENT\s+1:
is in
.IR makefile ,
or unless the initial character sequence contains a \f3@\fP.
The
.B \-n
option specifies printing without execution; however, if the
command line has the string
.B $(\s-1MAKE\s+1)
in it,
the line is
always executed (see discussion of the
.SM
.B MAKEFLAGS
macro under
.IR Environment ).
The
.B \-t
(touch) option updates the modified date of a
file without executing any commands.
.PP
Commands returning non-zero status normally terminate
.IR make .
If the
.B \-i
option is present, or the entry \f3.\s-1IGNORE\s+1:\fP appears in
.IR makefile ,
or the initial character sequence of the command contains
\f3-\fP.
the error is ignored.
If the
.B \-k
option is present,
work is abandoned on the current
entry, but continues on other branches
that do not depend on that entry.
.PP
The
.B \-b
option allows old makefiles (those written for the old version
of \f2make\^\fP) to run without errors.
The difference between the old version
of \f2make\^\fP and this version is that this version requires all dependency
lines to have a (possibly null or implicit) command associated with them.
The previous version of
.I make\^
assumed if no command was specified explicitly
that the command was null.
.PP
Interrupt and quit cause the target to be deleted
unless the target is a dependency of the special name \f3.\s-1PRECIOUS\s+1\fP.
.SS Environment
The environment is read by \f2make\^\fP.
All variables are assumed to be macro
definitions and processed as such.
The environment variables are processed
before any makefile and after the internal rules;
thus, macro assignments
in a makefile override environment variables.
The
.B \-e
option causes
the environment to override the macro assignments in a makefile.
.PP
The \f3\s-1MAKEFLAGS\s+1\fP environment variable
is processed by \f2make\^\fP as containing
any legal input option (except \f3\-f\fP, \f3\-p\fP, and \f3\-d\fP) defined
for the command line.
Further,
upon invocation, \f2make\^\fP ``invents'' the variable if it is not in the
environment, puts the current options into it, and passes it on to
invocations of commands.
Thus, \f3\s-1MAKEFLAGS\s+1\fP always contains the
current input options.
This proves very useful for ``super-makes''.
In fact, as noted above,
when the \f3\-n\fP option is used, the command
.B $(\s-1MAKE\s+1)
is executed
anyway; hence, one can perform a \f3make \-n\fP recursively on a whole software
system to see what would have been executed.
This is because the \f3\-n\fP
is put in \f3\s-1MAKEFLAGS\s+1\fP and passed to further invocations of
.BR $(\s-1MAKE\s+1) .
This is one way of debugging
all of the makefiles for a software project without actually doing anything.
.PP
.SS Macros
Entries of the form
.IB string1 " = " string2\^
are macro definitions.
.I string2
is defined as all characters up to a comment character or
an unescaped newline.
Subsequent appearances of
.RI $( string1 [: subst1 =[ subst2\^\fP]])
are replaced by
.IR string2 .
The parentheses are optional if a single character macro name is used and
there is no substitute sequence.
The optional
.RI : subst1 = subst2\^
is a substitute sequence.
If it is specified, all non-overlapping occurrences of \f2subst1\^\fP in the
named macro are replaced by \f2subst2\^\fP.
Strings (for the purposes of this
type of substitution) are delimited by
blanks, tabs, new-line characters, and beginnings of lines.
An example of the use of the substitute sequence is shown under
.IR Libraries .
.SS Internal Macros
There are five internally maintained macros which are useful
for writing rules for building targets.
.TP 5
\f3$\(**\fP
The macro \f3$\(**\fP stands for
the file name part of the current dependent with the suffix deleted.
It is
evaluated only for inference rules.
.TP
\f3$@\fP
The \f3$@\fP macro stands for
the full target name of the current target.
It is evaluated
only for explicitly named dependencies.
.TP
\f3$<\fP
The \f3$<\fP macro is only evaluated for inference rules or
the \f3.\s-1DEFAULT\s+1\fP rule.
It is
the module which is out of date with respect to the target (i.e.,
the ``manufactured'' dependent file name).
Thus, in the \f3.c.o\fP rule, the \f3$<\fP macro would evaluate to
the \f3.c\fP file.
An example for making
optimized \f3.o\fP files from \f3.c\fP files is:
.PP
.PD 0
.ss 18
.RS
.RS
.TP
\&.c.o:
.br
cc \-c \-O $\(**.c
.RE
.RE
.PD
.TP 5
\&
or:
.PP
.PD 0
.RS
.RS
.TP
\&.c.o:
.br
cc \-c \-O $<
.RE
.RE
.ss 12
.PD
.TP 5
\f3$?\fP
The \f3$?\fP macro is evaluated when explicit rules from the makefile
are evaluated.
It is
the list of prerequisites that are out of date with respect to
the target;
essentially, those modules which must be rebuilt.
.TP
\f3$%\fP
The \f3$%\fP macro is only evaluated when the target is an
archive library member of the form \f3lib(file.o)\fP.
In this case,
\f3$@\fP evaluates to \f3lib\fP and \f3$%\fP evaluates to the
library member, \f3file.o\fP.
.PP
Four of the five macros can have alternative forms.
When an upper case \f3D\fP or \f3F\fP is appended to any of the four
macros the meaning is changed to ``directory part'' for \f3D\fP
and ``file part'' for \f3F\fP.
Thus, \f3$(@D)\fP refers to the directory
part of the string \f3$@\fP.
If there is no directory part,
\f3./\fP is generated.
The only macro excluded from this
alternative form is \f3$?\fP.
The reasons for this are debatable.
.SS Suffixes
Certain names (for instance, those ending with \f3.o\fP)
have inferable prerequisites such as \f3.c\fP, \f3.s\fP, etc.
If no update commands for such a file appear in
.IR makefile ,
and if an inferable prerequisite
exists, that prerequisite is compiled to make the target.
In this case,
.I make\^
has
inference rules
which allow building files from other files
by examining the suffixes and determining an
appropriate
inference rule
to use.
The current default inference rules
are:
.PP
.RS
\&.c \|.c~ \|.sh \|.sh~ \|.c.o \|.c~.o \|.c~.c \|.s.o \|.s~.o \|.y.o \|.y~.o \|.l.o \|.l~.o
.br
\&.y.c \|.y~.c \|.l.c \|.c.a \|.c~.a \|.s~.a \|.h~.h
.RE
.PP
The internal rules for \f2make\^\fP are contained in the source
file \f3rules.c\fP for the \f2make\^\fP program.
These rules can be
locally modified.
To print out the rules compiled into
the \f2make\^\fP on any machine in a form suitable for recompilation,
the following command is used:
.PP
.RS
make \|\-fp \|\- \|2>/dev/null \|</dev/null
.RE
.PP
The only peculiarity in this output is the
.B (null)
string which
.IR printf (3S)
prints when handed a null string.
.PP
A tilde in the above rules refers to an \s-1SCCS\s+1 file
(see
.IR sccsfile (5)).
Thus, the
rule \f3.c~.o\fP would transform an \s-1SCCS\s+1 C source file into an
object file (\f3.o\fP).
Because the \f3s.\fP of the \s-1SCCS\s+1 files is a prefix
it is incompatible with \f2make\^\fP's suffix point-of-view.
Hence,
the tilde is a way of changing any file reference into an \s-1SCCS\s+1
file reference.
.PP
A rule with only one suffix (i.e. \f3.c:\fP) is the definition
of how to build \f2x\^\fP from \f2x\^\fP\f3.c\fP.
In effect, the other suffix is null.
This is useful for building targets
from only one source file (e.g., shell procedures, simple C programs).
.PP
Additional suffixes are given as the
dependency list for \f3.\s-1SUFFIXES\s+1\fP.
Order is significant; the first possible name for which both
a file and a rule exist is inferred as a prerequisite.
The default list is:
.PP
.RS
\&\f3.\s-1SUFFIXES\s+1\fP: \|.o \|.c \|.y \|.l \|.s
.RE
.PP
Here again, the above command for printing the internal rules will
display the list of suffixes implemented on the current machine.
Multiple suffix lists accumulate; \f3.\s-1SUFFIXES\s+1:\fP with no dependencies
clears the list of suffixes.
.SS Inference Rules
The first example can be done more briefly:
.PP
.ss 18
.RS
.PD 0
.TP
pgm: a.o b.o
.br
cc a.o b.o \-o pgm
.TP
a.o b.o: incl.h
.RE
.ss 12
.PD
.PP
This is because \f2make\^\fP has a set of internal rules for building
files.
The user may add rules to this list by simply putting
them in the \f2makefile\^\fP.
.PP
Certain macros are used by the default inference rules
to permit the inclusion of optional matter in
any resulting commands.
For example,
.SM
.BR CFLAGS\*S ,
.SM
.BR LFLAGS\*S ,
and
.SM
.B YFLAGS
are used for compiler options to
.IR cc (1),
.IR lex (1),
and
.IR yacc (1)
respectively.
Again, the previous method for examining
the current rules is recommended.
.PP
The inference of prerequisites can be controlled.
The rule to create a file with suffix
.B \&.o
from a file with suffix
.B \&.c
is specified as an entry with \f3.c.o:\fP as the target and no dependents.
Shell commands associated with the target define the
rule for making a \f3.o\fP file from a \f3.c\fP file.
Any target that has no slashes in it and starts with a dot
is identified as a rule and not a true target.
.SS Libraries
If a target or dependency name contains parenthesis, it is
assumed to be an archive library, the string within parenthesis
referring to a member within the library.
Thus \f3lib(file.o)\fP and \f3$(\s-1LIB\s+1)(file.o)\fP both refer to
an archive library which contains \f3file.o\fP. (This assumes
the
.SM
.B LIB
macro has been previously defined.)\ 
The expression \f3$(\s-1LIB\s+1)(file1.o file2.o)\fP is not legal.
Rules pertaining to archive libraries have the form
.BI \&. \s-1XX\s+1 .a
where the
.SM
.I XX\^
is the suffix from which the archive member
is to be made.
An unfortunate byproduct of the current implementation
requires the
.SM
.I XX\^
to be different from the suffix of the archive
member.
Thus, one cannot have \f3lib(file.o)\fP depend upon \f3file.o\fP explicitly.
The most common use of the archive interface follows.
Here, we assume the source files are all C type source:
.PP
.ss 18
.RS
.PD 0
.TP
lib:
lib(file1.o) lib(file2.o) lib(file3.o)
.br
@echo lib is now up to date
.TP
\&.c.a:
.br
$(\s-1CC\s+1) \-c $(\s-1CFLAGS\s+1) $<
.br
ar rv $@ $*.o
.br
rm \-f $*.o
.RE
.ss 12
.PD
.PP
In fact, the \f3.c.a\fP rule listed above is built into \f2make\^\fP and
is unnecessary in this example.
A more interesting, but more limited example of an archive library
maintenance construction follows:
.PP
.ss 18
.RS
.PD 0
.TP
lib:
lib(file1.o) lib(file2.o) lib(file3.o)
.br
$(\s-1CC\s+1) \-c $(\s-1CFLAGS\s+1) $(?:.o=.c)
.br
ar rv lib $?
.br
rm $?
@echo lib is now up to date
.TP
\&.c.a:;
.RE
.ss 12
.PD
.PP
Here the substitution mode of the macro expansions is used.
The \f3$?\fP
list is defined to be the set of object file names (inside \f3lib\fP) whose C
source files are out of date.
The substitution mode
translates the \f3.o\fP to \f3.c\fP.
(Unfortunately, one cannot as yet transform
to \f3.c~\fP; however, this may become possible in the future.)\ 
Note also, the disabling of the
\&\f3.c.a:\fP rule, which would have created each object file, one by one.
This particular construct speeds up archive library maintenance considerably.
This type of construct becomes very cumbersome if the archive library
contains a mix of assembly programs and C programs.
.SH FILES
[Mm]akefile and s\f3.\fP[Mm]akefile
.SH SEE ALSO
sh(1),
mk(8).
.br
.I "Make\-A Program for Maintaining Computer Programs\^"
by
S. I. Feldman.
.br
.I "An Augmented Version of Make\^"
by
E. G. Bradford.
.SH BUGS
Some commands return non-zero status inappropriately;
use
.B \-i
to overcome the difficulty.
Commands that are directly executed by the shell,
notably
.IR cd (1),
are ineffectual across new-lines in
.IR make .
The syntax \f3(lib(file1.o file2.o file3.o)\fP is illegal.
You cannot build \f3lib(file.o)\fP from \f3file.o\fP.
The macro \f3$(a:.o=.c~)\fP doesn't work.
.br