PMAKE(1)PMAKE(1)NAME
pmake, smake - create programs in parallel
SYNOPSIS
pmake [-d what] [-e] [-f makefile] [-h] [-i] [-k] [-l] [-n] [-p #] [-q]
[-r] [-s] [-t] [-v] [-B] [-C] [-D variable] [-I directory]
[-J #] [-M] [-P] [-V] [-W] [VAR1=value1] [VAR2=value2...] [targ1]
[targ2 ...]
ARGUMENTS-d what Specify what modules should print debugging
information. what is a string of letters from the
following set: a, c, d, j, m, s, t, v. Use A or * to
print all information.
-e Give environment variables precedence over those in the
makefile(s).
-f makefile Specify a different makefile to read than the standard
``Makefile'' or ``makefile''. If makefile is "-",
standard input is read.
-h Prints out help information and default values.
-i ``Ignore errors'' - ignore non-zero exit statuses of
commands.
-k ``Keep-going'' - if an error is encountered, keep
working on those parts of the input graph that are not
affected by the error.
-l Create a lock file (called ``LOCK.make'') to prevent
other people from executing pmake in the same
directory. Useful when simultaneous makes in the same
place can be disastrous for the final product (too many
cooks and all that). Note that this locking will not
prevent you from invoking pmake twice in the same place
- if you own the lock file, pmake will warn you about
it but continue to execute.
-n ``No execute'' - do not execute commands. Just print
the ones that would be executed.
-p # Tell pmake if and when to print the input graph. The
number is the bitwise OR of the numbers 1 and 2. 1
means print the graph before making anything and 2
means print the graph after making everything. 3 means
do both.
-q ``Query'' - do not execute any commands. Just exit 0
if the given target(s) is (are) up to date and exit
non-zero otherwise.
Page 1
PMAKE(1)PMAKE(1)-r ``Remove built-in rules'' - do not parse the built-in
rules given in the system makefile.
-s ``Silence'' - do not echo commands as they are
executed.
-t ``Touch targets'' - rather than executing the commands
to create a target, just change its modification time
so it appears up-to-date. This is dangerous.
-v ``System V'' - invokes compatibility functions suitable
for acting like the System V (IRIX) version of make(1).
This implies -B, and -V. Automatically set when pmake
is invoked as smake.
-B ``Backwards-compatible'' - performs as much like
make(1) as possible (including executing a single shell
per command and expanding variables as make did) while
still performing in parallel.
-C ``Non-compatible'' - turns off all compatibility
specified up to the point at which -C is encountered.
-D variable Defines the given variable to be 1 in the global
context.
-I directory Specify another directory in which to look for
#include'd makefiles. This flag may be repeated as
many times as necessary.
-J # Specify the maximum number of jobs to run at once.
-M Be as much like make(1) as possible. No parallel
execution. Old-style variable expansion. One shell per
command, etc.
-P ``Don't use Pipes'' - see the section on OUTPUT.
-V ``Do old-style variable expansion'' - expands an
unknown variable to the empty string.
-W Don't print warning messages.
VAR=value Set the value of the variable VAR to the given value.
This supersedes any value assigned to the variable in
the makefile. See VARIABLES.
smake is equivalent to pmake -v.
The flags -x, -X and -L are recognized but ignored by this implementation
of pmake.
Page 2
PMAKE(1)PMAKE(1)DESCRIPTION
pmake is a program designed to make the maintenance of other programs
much easier. Its input is a ``makefile'' that specifies which files
depend on which other files and what to do about files that are ``out-
of-date.'' pmake's most important feature is its ability to run several
different jobs at once, making the creation of systems considerably
faster. It also has a great deal more functionality than make(1).
pmake is generally compatible with make(1). The main differences are:
1) The pmake variable substitution, as described below, is very different
and will cause problems unless the makefile is converted or the -V
flag is given or when pmake is invoked as smake.
2) Because pmake creates targets in parallel, certain sequences which
depend on the sources of a target being created sequentially will
fail. For example:
prod : $(PROGRAM) clean
This is liable to cause some of the object files to be removed after
having been created during the current invocation (or, at the very
least, the object files will not be removed when the program has been
made), leading to errors in the final linking stage. This problem
cannot even be avoided by limiting the maximum concurrency to one,
since the traversal of the dependency graph is done in a breadth-
first, rather than a depth-first way. For make(1) behavior, rewrite
the makefile, or give pmake the -M flag.
3) pmake forks only one shell to execute the commands to recreate a
target. This means that changes of directory, environment, etc.,
remain in effect throughout the creation process. It also allows for a
more natural entry of shell loop constructs without the need for
backslashes and semicolons required by the one-shell-per-command
paradigm used by make(1). It is possible to have pmake execute each
command in a single shell by giving it the -B flag.
4) pmake strips the leading directory from the files in a target's local
variables, unlike make(1). For example, pmake looks in the current
directory for file.c when making gen/file.o:
default: gen/file.o
.c.o:
cc -c-o $@ $<
To have pmake look in the gen directory for file.c, add a ``.PATH:
gen'' target to the makefile. The .PATH target, which is described
below, is ignored by make(1). Note that pmake in system V (IRIX)
compatibility mode will not strip leading directories.
5) pmake can interpret a comment line that begins with ``# if'' as a
conditional statement. Duplicate the comment character before the line
to avoid a warning message.
Page 3
PMAKE(1)PMAKE(1)
6) pmake doesn't have make(1)'s tilde rules for SCCS files.
7) pmake only understands the i,k,n,q,r,s,t, and u options in make's
MAKEFLAGS environment variable. The other make options are ignored due
to differences in semantics.
8) pmake converts an escaped newline into a space.
MAKEFILES
If you don't specify a makefile to read, pmake looks for Makefile in the
current directory. If that file does not exist, it looks for makefile.
(This search order is reversed for smake or when using the -M flag.)
There are four basic types of lines in a makefile:
1) File dependency specifications
2) Creation commands
3) Variable assignments
4) Comments, include statements and conditional directives
Any line may be continued over multiple lines by ending it with a
backslash. The backslash, following newline and any initial white-space
on the following line are compressed into a single space.
DEPENDENCY LINES
On a dependency line, there are targets, sources and an operator. The
targets ``depend'' on the sources and are usually created from them. Any
number of targets and sources may be specified on a dependency line. All
the targets in the line are made to depend on all the sources. If you
run out of room, use a backslash at the end of the line to continue onto
the next one.
Any file may be a target and any file may be a source, but the
relationship between them is determined by the ``operator'' that
separates them. Three operators are defined:
: A target on the line is considered ``out-of-date'' if any of
its sources has been modified more recently than the target.
Sources for a target accumulate over lines when this operator
is used.
! Targets will always be recreated, but this will not happen
until all of its sources have been examined and recreated, if
necessary. Sources accumulate over lines as for the colon.
:: Much like the colon, but acts like the ! operator if no sources
are specified. In addition sources do not accumulate over
lines. Rather, the commands associated with the line (see
below) are executed only if the target is out-of-date with
Page 4
PMAKE(1)PMAKE(1)
respect to the sources on that line only. In addition, the
target will not be removed if pmake is interrupted, unlike for
the other two operators.
For example:
a : a.o b.o c.o
b ! d.o e.o
c :: f.o
command1
a : g.o
b ! h.o
c ::
command2
specifies that a depends on a.o, b.o, c.o and g.o and will be remade only
if out-of-date with respect to these four files. b depends on d.o, e.o
and h.o and will always be remade, but only after these three files have
been remade. c will be remade with command1 if it is out-of-date with
respect to f.o, as for the colon operator, while command2 will always be
executed.
Targets and sources may also contain standard shell wildcard characters
(?, *, [ and {}), but the ?, *, [ and ] characters may only be used in
the final component of the target or source. If a target or source
contains only curly braces and no other wildcard characters, it need not
describe an existing file. Otherwise, only existing files will be used.
For example, the pattern
{a,b,c}.o
will expand to
a.o b.o c.o
regardless of whether these three files exist, while
[abc].o
will only expand to this if all three files exist. The resulting
expansion is in directory order, not alphabetically sorted as in the
shell.
COMMANDS
Associated with each target is a series of shell commands, collectively
called a script. The creation script for a target should immediately
follow the dependency line for that target. Each of the commands in this
script must be preceded by a tab character.
While any given target may appear on more than one dependency line, only
one of these dependency lines may be followed by a creation script,
unless the "::" operator is used.
One helpful feature of pmake is the ability to delay execution of a
target's commands until everything else has been done. To do this, make
one of the commands for the target be just ``...'' (an ellipsis) on a
Page 5
PMAKE(1)PMAKE(1)
line by itself. The ellipsis itself won't be executed, of course, but any
commands in the target's script that follow the ellipsis will be saved
until pmake is done processing everything it needs to process. If you
were to say,
a.o : a.c
cc -c a.c
...
@echo "All done"
Then the command ``echo "All done"'' would execute once everything else
had finished. Note that this will only happen if ``a.o'' is found to be
out-of-date. Macros and variables in these delayed commands are
evaluated once at the time they would have executed and again when (at
the end) they are actually executed. This means that shell variables,
which usually must be escaped with a `$' (as in `$$i') must now be
escaped twice (as in `$$$$i').
There is another way in which makefile shell commands differ from regular
shell commands, as illustrated in the previous example. The first two
characters after the initial tab (and any other white-space) are treated
specially. If they are any combination of `@' and `-', (``@'', ``@-'',
``-@'' or ``-''), they cause pmake to do different things.
In most cases, shell commands are printed to the screen before they're
actually executed. This is to keep you informed of what's going on. If an
`@' appears, however, this echoing is suppressed. In the case of the echo
command, above, this makes sense. It would look silly to see
echo "All done"
All done
so pmake allows you to avoid that (this sort of echo control is only
available if you use the Bourne or C shells to execute your commands,
since the commands are echoed by the shell, not by pmake).
The other special character is the `-'. Shell commands exit with a
certain ``exit status.'' Normally this status will be 0 if everything
went ok and non-zero if something went wrong. For this reason, pmake will
consider an error to have occurred if one of the commands it invokes
returns a non-zero status. When it detects an error, its usual action is
to stop working, wait for everything in process to finish, and exit with
a non-zero status itself. This behavior can be altered, however, by
means of -i or -k arguments, or by placing a `-' at the front of the
command. (Another quick note: the decision of whether to abort a target
when one of its shell commands returns non-zero is left to the shell that
is executing the commands. Some shells allow this ``error-checking'' to
be switched on and off at will while others do not.)
VARIABLES
pmake has the ability to save text in variables to be recalled later at
your convenience. Variables in pmake are used much like variables in
sh(1) and, by tradition, consist of all upper-case letters. (They can
also contain lower-case letters, numbers, and punctuation characters
Page 6
PMAKE(1)PMAKE(1)
except =, :, ) and }. # must be preceded with a backslash). They are
assigned- and appended-to using lines of the form
VARIABLE = value
VARIABLE += value
respectively, while being conditionally assigned-to (if not already
defined) and assigned-to with expansion by lines of the form
VARIABLE ?= value
VARIABLE := value
With :=, any variable on the right-hand side will be replaced with its
current definition. Put at least one blank between the end of the
variable name and the assignment operator. Finally,
VARIABLE != command
will execute command using the Bourne shell and place the result in the
given variable. Newlines are converted to spaces before the assignment
is made. This is not intended to be used with commands that produce a
large amount of output. If you use it this way, pmake will probably
deadlock. A particularly useful example of this is:
OSVERS!=uname -r | sed 'y/\./\_/' | cut -c1-3
which will set the variable OSVERS to the major and minor release of the
current system, separated by an underscore.
Variables are expanded by enclosing the variable name in either
parentheses or curly braces and preceding the whole thing with a dollar
sign. For example, to set the variable CFLAGS to the string
``-I../hdrs -O'' place the line
CFLAGS = -I../hdrs -O
in the makefile and use the word $(CFLAGS) wherever you would like the
string ``-I../hdrs -O'' to appear. To pass a string of the form
``$(name)'' or ``${name}'' through to the shell (e.g., to tell it to
substitute one of its variables), you can use ``$$(name)'' and
``$${name}'', respectively, or, as long as the name is not a pmake
variable, you can just place the string in directly, as pmake will not
expand a variable it doesn't know, unless it is given one of the three
compatibility flags -V, -B, or -M, or invoked as smake.
There are two distinct times at which variable substitution occurs: When
parsing a dependency line, such substitution occurs immediately upon
reading the line. Thus all variables used in dependency lines must be
defined before they appear on any dependency line. For variables that
appear in shell commands, variable substitution occurs when the command
is processed, that is, when it is prepared to be passed to the shell or
before being saved for later execution (see COMMANDS above).
There are four different types of variables at which pmake will look when
trying to expand any given variable. They are (in order of decreasing
precedence): (1) variables that are defined specific to a certain target.
Page 7
PMAKE(1)PMAKE(1)
These are the so-called ``local'' variables and will only be used when
performing variable substitution on the target's shell script and in
dynamic sources (see below for more details), (2) variables that were
defined on the command line, (3) variables defined in the makefile and
(4) those defined in pmake's environment, as passed by your login shell.
An important side effect of this searching order is that once you define
a variable on the command line, nothing in the makefile can change it.
The SHELL macro is treated specially. It is automatically set by pmake at
the start to be /bin/sh. The value of the environment variable SHELL
does not affect the value of the SHELL macro. If the SHELL macro is
defined in the makefile or on the command line it replaces the original
value (and changes the shell used for all commands), but does NOT affect
the SHELL environment variable.
As mentioned above, each target has associated with it as many as seven
``local'' variables. Four of these variables are always set for every
target that must be recreated. Each local variable has a long, meaningful
name and a short, one-character name that exists for backwards-
compatibility. They are:
.TARGET (@) The name of the target.
.OODATE (?) The list of sources for this target that were
deemed out-of-date.
.ALLSRC (>) The list of all sources for this target.
.PREFIX (*) The file prefix of the file. This contains only
the file portion - no suffix or leading
directory components.
Three other ``local'' variables are set only for certain targets under
special circumstances. These are the ``.IMPSRC'', ``.ARCHIVE'' and
``.MEMBER'' variables. When they are set, how they are used, and what
their short forms are detailed in later sections.
In addition, for System V Make compatibility, the variables ``@F'',
``<F'', and ``*F'' are defined as the file parts of the ``@'', ``>'' and
``*'' variables. Likewise, ``@D'', ``<D'', and ``*D'' are directory
parts.
Four of these local variables may be used in sources on dependency lines.
The variables expand to the proper value for each target on the line. The
variables are ``.TARGET'', ``.PREFIX'', ``.ARCHIVE'', and ``.MEMBER''.
In addition, certain variables are set by or have special meaning to
pmake. The .PMAKE (and MAKE) variable is set to the name by which pmake
was invoked, to allow recursive makes to use the same version, whatever
it may be. All command-line flags given to pmake are stored in the
.MAKEFLAGS (and MFLAGS) variable just as they were given. This variable
is also exported to subshells as the PMAKE environment variable.
Page 8
PMAKE(1)PMAKE(1)
Variable expansion may be modified as for the C shell. A general
expansion specification looks like:
$(variable[:modifier[:...]])
Each modifier begins with a single character, thus:
Mpattern
This is used to select only those words (a word is a series of
characters that are neither spaces nor tabs) that match the
given pattern . The pattern is a wildcard pattern like that
used by the shell, where "*" means 0 or more characters of any
sort; "?" is any single character; "[abcd]" matches any single
character that is either `a', `b', `c' or `d' (there may be any
number of characters between the brackets); [0-9] matches any
single character that is between `0' and `9' (i.e., any digit.
This form may be freely mixed with the other bracket form), and
\ is used to escape any of the characters "*", "?", "[" or ":",
leaving them as regular characters to match themselves in a
word. For example, the system makefile <makelint.mk> uses
$(CFLAGS:M-[ID]*) to extract all the -I and -D C compiler flags
for lint.
Npattern
This is identical to ":M" except it substitutes all words that
don't match the given pattern.
S/search-string/replacement-string/[g]
Causes the first occurrence of search-string in the variable to
be replaced by replacement-string, unless the "g" flag is given
at the end, in which case all occurrences of the string are
replaced. The substitution is performed on each word in the
variable in turn. If search-string begins with a "^", the
string must match starting at the beginning of the word. If
search-string ends with a "$", the string must match to the end
of the word (these two may be combined to force an exact
match). If a backslash precedes these two characters, however,
they lose their special meaning. Variable expansion also occurs
in the normal fashion inside both the search-string and the
replacement-string, except that a backslash is used to prevent
the expansion of a "$", not another dollar sign, as is usual.
Note that search-string is just a string, not a pattern, so
none of the usual regular-expression/wildcard characters has
any special meaning save "^" and "$". In the replacement
string, the "&" character is replaced by the search-string
unless it is preceded by a backslash. You are allowed to use
any character except colon or exclamation point to separate the
two strings. This so-called delimiter character may be placed
in either string by preceding it with a backslash.
T Replaces each word in the variable expansion by its last
component (its ``tail''). For example, given
OBJS = ../lib/a.o b /usr/lib/libm.a
Page 9
PMAKE(1)PMAKE(1)
TAILS = $(OBJS:T)
the variable TAILS would expand to ``a.o b libm.a''.
H This is similar to ":T", except that every word is replaced by
everything but the tail (the ``head''). Using the same
definition of OBJS from above, the string ``$(OBJS:H)'' would
expand to ``../lib /usr/lib''. Note that the final slash on
the heads is removed and anything without a head is replaced by
the empty string.
E ":E" replaces each word by its suffix (``extension''). For
example, ``$(OBJS:E)'' would give you ``.o .a''.
R This replaces each word by everything but the suffix (the
``root'' of the word). For example, ``$(OBJS:R)'' would give
you ``../lib/a b /usr/lib/libm''.
In addition, pmake supports the System V form of substitution
$(variable:string1=string2)
where all occurrences of string1 at the end of each word in the variable
expansion are replaced by string2.
COMMENTS, INCLUSION AND CONDITIONALS
Makefile inclusion and conditional structures reminiscent of the C
compiler have also been included in pmake.
Comments begin with a `#' anywhere but in a shell command and continue to
the end of the line. The comment character can included in macros if
preceded with a backslash (\). If the `#' comes at the beginning of the
line, however, the following keywords are recognized and acted on:
#include "makefile"
#include <system makefile>
This is very similar to the C compiler's file-inclusion facility, right
down to the syntax. What follows the #include must be a filename
enclosed either in double-quotes or angle brackets. Variables will be
expanded between the double-quotes or angle-brackets. If angle-brackets
are used, the system makefile directory is searched. If the name is
enclosed in double-quotes, the including makefile's directory, followed
by all directories given via -I arguments, followed by the system
directory, is searched for a file of the given name.
If the file is found, pmake starts taking input from that file as if it
were part of the original makefile.
When the end of the file is reached, pmake goes back to the previous file
and continues from where it left off. This facility is recursive up to a
depth limited only by the number of open files allowed to any process at
one time.
Page 10
PMAKE(1)PMAKE(1)
include makefile
sinclude makefile
This (non-standard) include syntax is recognized for compatibility with
the IRIX make(1) command. No search paths are used. The file name may
contain variables. For ``include'', it is a fatal error if the file is
not readable; for ``sinclude'', a non-readable file is silently ignored.
#if [!] expr [ op expr ... ]
#ifdef [!] variable [op variable...]
#ifndef [!] variable [op variable...]
#ifmake [!] target [op target...]
#ifnmake [!] target [op target...]
These are all the beginnings of conditional constructs in the spirit of
the C compiler. Conditionals may be nested to a depth of thirty.
In the expressions given above, op may be either || (logical OR) or &&
(logical AND). && has a higher precedence than ||. As in C, pmake will
evaluate an expression only as far as necessary to determine its value.
If the left side of an && is false, the expression is false and vice
versa for ||. Parentheses may be used as usual to change the order of
evaluation.
One other boolean operator is provided: ! (logical negation). It is of a
higher precedence than either the AND or OR operators, and may be applied
in any of the ``if'' constructs, negating the given function for ``#if''
or the implicit function for the other four.
Expr can be one of several things. Four functions are provided, each of
which takes a different sort of argument.
The function defined is used to test for the existence of a variable.
Its argument is, therefore, a variable name. Certain variable names
(e.g., ``IRIX'', ``SYSV'', and ``unix'') are defined in the system
makefile (see FILES) to specify the sort of system on which pmake is
being run. These are intended to make makefiles more portable. Any
variable may be used as the argument of the defined function.
The make function is given the name of a target in the makefile and
evaluates to true if the target was given on pmake's command-line or as a
source for the .MAIN target before the line containing the conditional.
The exists function takes a file name, which file is searched for on the
system search path (as defined by .PATH targets (see below)). It
evaluates true if the file is found.
The function empty takes a variable expansion specification (minus the
dollar sign) as its argument. If the resulting expansion is empty, this
evaluates true.
Expr can also be an arithmetic or string comparison, with the left-hand
side being a variable. The standard C relational operators are allowed,
and the usual number/base conversion is performed, with the exception
Page 11
PMAKE(1)PMAKE(1)
that octal numbers are not supported. If the right-hand side of a "==" or
"!=" operator begins with a quotation mark, a string comparison is done
between the expanded variable and the text between the quotation marks.
If no relational operator is given, the expression must be a single
variable, which is interpreted as a boolean. If the variable evaluates to
a 0 value, the expression is false and if it evaluates to a non-zero
value, the expression is true.
When, in the course of evaluating one of these conditional expressions,
pmake encounters some word it does not recognize, it applies one of
either make or defined to it, depending on the form of ``if'' used. For
example, ``#ifdef'' will apply the defined function, while ``#ifnmake''
will apply the negation of the make function.
If the expression following one of these forms evaluates true, the
reading of the makefile continues as before. If it evaluates false, the
following lines are skipped. In both cases, this continues until either
an #else or an #endif line is encountered.
#else
The #else, as in the C compiler, causes the sense of the last conditional
to be inverted and the reading of the makefile to be based on this new
value, i.e., if the previous expression evaluated true, the parsing of
the makefile is suspended until an #endif line is read. If the previous
expression evaluated false, the parsing of the makefile is resumed.
#elif [!] expr [ op expr ... ]
#elifdef [!] variable [op variable...]
#elifndef [!] variable [op variable...]
#elifmake [!] target [op target...]
#elifnmake [!] target [op target...]
The ``elif'' constructs are a combination of ``else'' and ``if,'' as the
name implies. If the preceding ``if'' evaluated false, the expression
following the ``elif'' is evaluated and the lines following it are read
or ignored the same as for a regular ``if.'' If the preceding ``if''
evaluated true, however, the ``elif'' is ignored and all following lines
until the ``endif'' (see below) are ignored.
#endif
#endif is used to end a conditional section. If lines were being skipped,
the reading of the makefile resumes. Otherwise, it has no effect (the
makefile continues to be parsed as it was just before the #endif was
encountered).
#undef
Takes the next word on the line as a global variable to be undefined
(only undefines global variables, not command-line variables). If the
variable is already undefined, no message is generated.
Page 12
PMAKE(1)PMAKE(1)TARGET ATTRIBUTES
In pmake, files can have certain ``attributes.'' These attributes cause
pmake to treat the targets in special ways. An attribute is a special
word given as a source to a target on a dependency line. The words and
their functions are given below:
.DONTCARE If a target is marked with this attribute and pmake can't
figure out how to create it, it will ignore this fact and
assume the file isn't really needed or actually exists and
pmake just can't find it. (.OPTIONAL is a synonym for
.DONTCARE.)
.EXEC This causes the marked target's shell script to always be
executed (unless the -n or -t flag is given), but appear
invisible to any targets that depend on it.
.IGNORE Giving a target the .IGNORE attribute causes pmake to ignore
errors from any of the target's commands, as if they all had
`-' before them.
.INVISIBLE This allows you to specify one target as a source for
another without the one affecting the other's local
variables.
.JOIN This forces the target's shell script to be executed only if
one or more of the sources was out-of-date. In addition, the
target's name, in both its .TARGET variable and all the
local variables of any target that depends on it, is
replaced by the value of its .ALLSRC variable. Another
aspect of the .JOIN attribute is it keeps the target from
being created if the -t flag was given.
.MAKE The .MAKE attribute marks its target as being a recursive
invocation of pmake . This forces pmake to execute the
script associated with the target (if it is out-of-date)
even if you gave the -n or -t flag.
.NOTMAIN Normally, if you do not specify a target to make in any
other way, pmake will take the first target on the first
dependency line of a makefile as the target to create.
Giving a target this attribute keeps it from this fate.
.PRECIOUS When pmake is interrupted, it will attempt to clean up after
itself by removing any half-made targets. If a target has
this attribute, however, pmake will leave it alone
.SILENT Marking a target with this attribute keeps its commands from
being printed when they're executed.
.USE By giving a target this attribute, you turn the target into
pmake's equivalent of a macro. When the target is used as a
source for another target, the other target acquires the
Page 13
PMAKE(1)PMAKE(1)
commands, sources and attributes (except .USE) of the
source. If the target already has commands, the .USE
target's commands are added to the end. If more than one
.USE-marked source is given to a target, the rules are
applied sequentially.
The following target attributes are recognized but not implemented on
IRIX: .EXPORT, .EXPORTSAME, and .NOEXPORT.
SPECIAL TARGETS
As there were in make(1), so there are certain targets that have special
meaning to pmake . When you use one on a dependency line, it is the only
target that may appear on the left-hand-side of the operator. The
targets are as follows:
.BEGIN Any commands attached to this target are executed before
anything else is done. You can use it for any initialization
that needs doing.
.DEFAULT This is sort of a .USE rule for any target (that was used
only as a source) that pmake can't figure out any other way
to create. Only the shell script is used. The .IMPSRC
variable of a target that inherits .DEFAULT's commands is set
to the target's own name.
.END This serves a function similar to .BEGIN: commands attached
to it are executed once everything has been recreated (so
long as no errors occurred). It also serves the extra
function of being a place on which pmake can hang commands
you put off to the end. Thus the script for this target will
be executed before any of the commands you save with the
``...''.
.IGNORE This target marks each of its sources with the .IGNORE
attribute. If you don't give it any sources, then it is like
giving the -i flag.
.INCLUDES The sources for this target are taken to be suffixes that
indicate a file that can be included in a program source
file. The suffix must have already been declared with
.SUFFIXES (see below). Any suffix so marked will have the
directories on its search path (see .PATH, below) placed in
the .INCLUDES variable, each preceded by a -I flag. The .h
suffix is already marked in this way in the system makefile.
.INTERRUPT When pmake is interrupted, it will execute the commands in
the script for this target, if it exists.
.LIBS This does for libraries what .INCLUDES does for include
files, except the flag used is -L, as required by those
linkers that allow you to tell them where to find libraries.
The variable used is .LIBS.
Page 14
PMAKE(1)PMAKE(1)
.MAIN If you didn't give a target (or targets) to create when you
invoked pmake , it will take the sources of this target as
the targets to create.
.MAKEFLAGS This target provides a way for you to always specify flags
for pmake when the makefile is used. The flags are just as
they would be typed to the shell, though the -f and -r flags
have no effect.
.NOTPARALLEL
This is used to make only one target at a time. It is
equivalent to giving the -J 1 flag.
.NULL This allows you to specify what suffix pmake should pretend a
file has if, in fact, it has no known suffix. Only one suffix
may be so designated. The last source on the dependency line
is the suffix that is used (you should, however, only give
one suffix).
.ORDER Sources for this target, which are targets themselves, are
made in the specified order. This feature only works in the
simplest of cases, and is never applied if the listed target
is a 'main' target (i.e. listed on the command line). This
feature does not interact well with '::' rules.
.PATH If you give sources for this target, pmake will take them as
directories to search for files it cannot find in the current
directory. If you give no sources, it will clear out any
directories added to the search path before.
.PATHsuffix This does a similar thing to .PATH, but it does it only for
files with the given suffix. The suffix must have been
defined already.
.PRECIOUS Gives the .PRECIOUS attribute to each source on the
dependency line, unless there are no sources, in which case
the .PRECIOUS attribute is given to every target in the file.
.RECURSIVE Applies the .MAKE attribute to all its sources. It does
nothing if you don't give it any sources.
.SHELL Tells pmake to use some other shell than the Bourne Shell.
The sources for the target are organized as keyword=value
strings. If a value contains white-space, it may be
surrounded by double-quotes to make it a single word. Be
sure to have at least one space between the ':' and the start
of the first keyword/value string. The possible sources are:
path=path
Tells where the shell actually resides. If you specify
this and nothing else, pmake will use the last component
of the path to find the specification. Use this if you
Page 15
PMAKE(1)PMAKE(1)
just want to use a different version of the Bourne or C
Shell (pmake knows how to use the C Shell too).
name=name
This is the name by which the shell is to be known. It
is a single word and, if no other keywords are specified
(other than path), it is the name by which pmake
attempts to find a specification for the it. You can use
this if you would just rather use the C Shell than the
Bourne Shell (``.SHELL: name=csh'' will do it).
Similarly, use the name ``ksh'' for the Korn Shell and
``tcsh'' for the 'totally-cool' version of C Shell.
quiet=echo-off command
The command pmake should send to stop the shell from
printing its commands. Once echoing is off, it is
expected to remain off until explicitly turned on.
echo=echo-on command
The command pmake should give to turn echoing back on
again.
filter=printed echo-off command
Many shells will echo the echo-off command when it is
given. This keyword tells pmake in what format the shell
actually prints the echo-off command. Wherever pmake
sees this string in the shell's output, it will delete
it and any following white-space, up to and including
the next newline.
echoFlag=flag to turn echoing on
The flag to pass to the shell to turn echoing on at the
start. If either this or the next flag begins with a
`-', the flags will be passed to the shell as separate
arguments. Otherwise, the two will be concatenated.
errFlag=flag to turn error checking on
Flag to give the shell to turn error checking on at the
start.
check=command to turn error checking on
The command to make the shell check for errors or to
print the command that's about to be executed (%s
indicates where the command to print should go), if
hasErrCtl is "no".
ignore=command to turn error checking off
The command to turn error checking off or the command to
execute a command ignoring any errors. "%s" takes the
place of the command.
Page 16
PMAKE(1)PMAKE(1)
hasErrCtl=yes or no
This takes a value that is either yes or no, telling how
the "check" and "ignore" commands should be used. NOTE:
If this is "no", both the check and ignore commands
should contain a \n at their end if the shell requires a
newline before executing a command.
noninterFlag=flag to turn interactivity checking off
Flag to give the shell to turn force the shell into
non-interactive mode.
The strings that follow these keywords may be enclosed in
single or double quotes (the quotes will be stripped off) and
may contain the usual C backslash characters.
The built-in rule for using csh will convince csh to read the
.cshrc file in 'interactive' mode - i.e. the standard test if
($?prompt) will return true. This may not be acceptable.
The only way around this is to specify a complete csh shell
specification and specify the -f flag. This will simply tell
csh to not read the .cshrc at all. The appropriate SHELL
specification is:
.SHELL: path=/bin/csh \
name=csh \
noninterFlag=-f \
quiet="unset verbose" \
echo="set verbose" \
filter="unset verbose" \
echoFlag=v \
errFlag=e \
hasErrCtl=F \
check="echo \"%s\"\n" \
ignore="csh -c \"%s || exit 0\""
.SILENT Applies the .SILENT attribute to each of its sources. If
there are no sources on the dependency line, then it is as if
you gave pmake the -s flag.
.SINGLESHELL
This is used to create a shell for each command. It is
equivalent to giving the -B flag.
.SUFFIXES This is used to give new file suffixes for pmake to handle.
Each source is a suffix pmake should recognize. If you give a
.SUFFIXES dependency line with no sources, pmake will forget
about all the suffixes it knew (this also clobbers the null
suffix). For those targets that need to have suffixes
defined, this is how you do it.
Page 17
PMAKE(1)PMAKE(1)
In addition to these targets, a line of the form
attribute : sources
applies the attribute to all the targets listed as sources except as
noted above.
The .EXPORT target is recognized but not implemented on IRIX.
THE POWER OF SUFFIXES
One of the best aspects of both make(1) and pmake comes from their
understanding of how the suffix of a file pertains to its contents and
their ability to do things with a file based solely on its suffix. pmake
also has the ability to find a file based on its suffix, supporting
different types of files being in different directories. The former
ability derives from the existence of so-called transformation rules
while the latter comes from the specification of search paths using the
.PATH target.
TRANSFORMATION RULES
A special type of dependency, called a transformation rule, consists of a
target made of two known suffixes stuck together followed by a shell
script to transform a file of one suffix into a file of the other. The
first suffix is the suffix of the source file and the second is that of
the target file. For example, the target ``.c.o,'' followed by commands,
would define a transformation from files with the ``.c'' suffix to those
with the ``.o'' suffix. A transformation rule has no source files
associated with it, though attributes may be given to one in the usual
way. These attributes are then applied to any target that is on the
``target end'' of a transformation rule. The suffixes that are
concatenated must be already known to pmake in order for their
concatenation to be recognized as a transformation, i.e., the suffixes
must have been the source for a .SUFFIXES target at some time before the
transformation is defined. Many transformations are defined in the
system makefile (see FILES), which you should examine for more examples
as well as to find what is already available. (You should especially note
the various variables used to contain flags for the compilers,
assemblers, etc., used to transform the files. These variables allow you
to customize the transformations to your own needs without having to
redefine them.) A transformation rule may be defined more than once, but
only the last such definition is remembered by pmake. This allows you to
redefine the transformations in the system makefile if you wish.
Transformation rules are used only when a target has no commands
associated with it, both to find any additional files on which it depends
and to attempt to figure out just how to make the target should it end up
being out-of-date. When a transformation is found for a target, another
of the seven ``local'' variables mentioned earlier is defined:
.IMPSRC (<) The name/path of the source from which the
target is to be transformed (the ``implied''
source).
Page 18
PMAKE(1)PMAKE(1)
For example, given the following makefile:
a.out : a.o b.o
$(CC) $(.ALLSRC)
and a directory containing the files a.o, a.c and b.c, pmake will look at
the list of suffixes and transformations given in the built-in rules and
find that the suffixes ``.c'' and ``.o'' are both known and there is a
transformation rule defined from one to the other with the command
``$(CC) $(CFLAGS) -c $(.IMPSRC).'' Having found this, it can then check
the modification times of both a.c and b.c and execute the command from
the transformation rule as necessary in order to update the files a.o and
b.o.
pmake, unlike make(1) before it, has the ability to apply several
transformations to a file even if the intermediate files do not exist.
Given a directory containing a .o file and a .v file, and transformations
from .v to .w, .w to .c and .c to .o, pmake will define a transformation
from .v -> .o using the three transformation rules you defined. In the
event of two paths between the same suffixes, the shortest path will be
chosen between the target and the first existing file on the path. So if
there were also a transformation from .w files to .o files, pmake would
use the path .v -> .w -> .o instead of .v -> .w -> .c -> .o.
Once an existing file is found, pmake will continue to look at and record
transformations until it comes to a file to which nothing it knows of can
be transformed, at which point it will stop looking and use the path it
has already found.
What happens if you have a .o file, a .v file and a .r file, all with the
same prefix, and transformations from .v -> .o and .r -> .o? Which
transformation will be used? pmake uses the order in which the suffixes
were given on the .SUFFIXES line to decide between transformations:
whichever suffix came first, wins. So if the three suffixes were
declared
.SUFFIXES : .o .v .r
the .v -> .o transformation would be applied. Similarly, if they were
declared as
.SUFFIXES : .o .r .v
the .r -> .o transformation would be used. You should keep this in mind
when writing such rules. Note also that because the placing of a suffix
on a .SUFFIXES line doesn't alter the precedence of previously-defined
transformations, it is sometimes necessary to clear the whole lot of them
out and start from scratch. This is what the .SUFFIXES-only line,
mentioned earlier, will do.
SEARCH PATHS
pmake also supports the notion of multiple directories in a more
flexible, easily-used manner than has been available in the past. You
can define a list of directories in which to search for any and all files
that aren't in the current directory by giving the directories as sources
Page 19
PMAKE(1)PMAKE(1)
to the .PATH target. The search will only be conducted for those files
used only as sources, on the assumption that files used as targets will
be created in the current directory.
The line
.PATH : RCS
would tell pmake to look for any files it is seeking (including ones made
up by means of transformation rules) in the RCS directory as well as the
current one. Note, however, that this searching is only done if the file
is used only as a source in the makefile; the file cannot be created by
commands in the makefile.
A search path specific to files with a given suffix can also be specified
in much the same way.
.PATH.h : h /usr/include
causes the search for header files to be conducted in the ``h'' and
``/usr/include'' directories as well as the current one.
When expanding wildcards, these paths are also used. If the pattern has a
recognizable suffix, the search path for that suffix is used. Otherwise,
the path defined with the regular .PATH target is used.
When a file is found somewhere other than the current directory, its name
is replaced by its full pathname in any ``local'' variables.
Two types of suffixes are given special attention when a search path is
defined for them. On IRIX, the C compiler lets you specify where to find
header files (.h files) by means of -I flags similar to those used by
pmake. If a search path is given for any suffix used as a source for the
.INCLUDES target, the variable $(.INCLUDES) will be set to contain all
the directories on the path, in the order given, in a format which can be
passed directly to the C compiler. Similarly, one may give directories
to search for libraries to the compiler by means of -L flags.
Directories on the search path for a suffix which was the source of the
.LIBS target will be placed in the $(.LIBS) variable ready to be passed
to the compiler.
LIBRARIES AND ARCHIVES
Two other special forms of sources are recognized by pmake. Any source
that begins with the characters ``-l'' (lower-case L) or ends in a suffix
that is a source for the .LIBS target is assumed to be a library, and any
source that contains a left parenthesis in it is considered to be a
member (or members) of an archive.
Libraries are treated specially mostly in how they appear in the local
variables of those targets that depend on them. Since IRIX supports the
-L flag when linking, the name of the library (i.e., its ``-l'' form) is
used in all local variables. pmake assumes that you will use the
$(.LIBS) variable in the appropriate place.
Page 20
PMAKE(1)PMAKE(1)
The process of creating a library or archive can be a painful one, what
with all the members having to be kept outside the archive as well as
inside it in order to keep them from being recreated. pmake has been set
up, however, to allow you to reference files that are in an archive in a
relatively painless manner. The specification of an archive member is
written as:
archive(member [member...])
Both the open and close parentheses are required and there may be any
number of members between them (except 0, that is). Members may also
include wildcards characters. When such a source is examined, it is the
modification time of the member, as recorded in the archive, that is used
to determine its datedness.
If an archive member has no commands associated with it, pmake goes
through a special process to find commands for it. First, implicit
sources are sought using the ``member'' portion of the specification. So
if you have something like ``libmalloc.a(malloc.o)'' for a target, pmake
attempts to find sources for the file ``malloc.o,'' even if it doesn't
exist. If such sources exist, pmake then looks for a transformation rule
from the member's suffix to the archive's (in this case from .o -> .a)
and tacks those commands on as well.
To make these transformations easier to write, three local variables are
defined for the target:
.ARCHIVE (%) The path to the archive file.
.MEMBER (!) The actual member name (literally the part in
parentheses).
.TARGET (@) The path to the file which will be archived, if
it is only a source, or the same as the .MEMBER
variable if it is also a target.
Using the transformations already in the system makefile, a makefile for
a library might look something like this:
OBJS = setup.o doit.o transfer.o shutdown.o
.o.a :
...
rm -f $(.MEMBER)
lib.a : lib.a($(OBJS))
ar cru $(.TARGET) $(.OODATE)
Note that the following .o -> .a transformation is bad:
.o.a :
ar r $(.ARCHIVE) $(.TARGET)
...
rm -f $(.TARGET)
Page 21
PMAKE(1)PMAKE(1)
The reason is simple: you should not execute ``ar'' on the same archive
several times at once. Also, it is much slower than archiving all the .o
files at the end.
OUTPUT
When creating targets in parallel, several shells are executing at once,
each wanting to write its output to the screen. This output must be
captured by pmake in some way in order to prevent the screen from being
filled with garbage even more indecipherable than one can already get
from these programs. pmake has two ways of doing this, one of which
provides for much cleaner output and a clear delineation between the
output of different jobs, the other of which provides a more immediate
response so one can tell what is really happening. The former is done by
notifying the user when the creation of a given target starts, capturing
the output, and transferring it to the screen when the job finishes,
preceded by an indication as to which job produced the output. The
latter is done by catching the output of the shell (and its children) and
buffering it until an entire line is received, then printing that line
preceded by the name of the job from which the line came. The name of
the job is just the target which is being created by it. Since this
second method is preferred, it is the one used by default. The first
method will be used if the -P flag is given to pmake.
PARALLELISM
pmake and smake attempt to create several targets at once. The degree of
useful concurrency depends on the targets, as well as the number of
processors on the machine. On IRIX, the default concurrency value for
single-processor systems is 2. On multi-processor systems that have more
than 1 unrestricted processor, the value is 4 (see mpadmin(1) to change
the number of unrestricted processors). To change the default
concurrency, use the -J flag. This flag can be set on the command line,
inside a makefile with the .MAKEFLAGS target or with the PMAKE
environment variable.
DEBUGGING
To debug makefiles, use the -d what option to print various information
about pmake's internal processing. The what argument is a string of
single characters that tell pmake what aspects you are interested in. The
characters and the information they produce are as follows:
a Archive searching and caching.
c Conditional evaluation.
d The searching and caching of directories.
j Various snippets of information related to the running of the
multiple shells.
m The making of each target: what target is being examined; when
it was last modified; whether it is out-of-date; etc.
Page 22
PMAKE(1)PMAKE(1)
s The application of suffix-transformation rules.
t The maintenance of the list of targets.
v Variable assignment.
A or *
Print all information.
Of these all, the m and s letters will be most useful to you. If the -d
is the final argument or the argument from which it would get these key
letters begins with a -, all of these debugging flags will be set,
resulting in massive amounts of output.
COMPATIBILITY
Invoking pmake as smake or using the -v option turns on numerous
compatibility options. However there are still a few areas where pmake's
behavior differs from classic System V make.
The -d option in make doesn't take any sub-options, whereas in pmake it
does.
In pmake the standard output and standard error streams for all executed
rules are merged together. Unlike make it is impossible to redirect the
standard error of a rule to a location other than the standard output of
pmake.
The set of default suffixes defined is not completely the same between
pmake and make. In particular the suffixes .a and .b are defined in
system.mk for pmake while in make they are not. This means that single
(or NULL) suffix rules will not be applied to .a files in pmake whereas
they will (potentially) be applied in make. To make pmake the same as
make one would have to undefine all the pre-defined suffixes, and add
back just those that were in common with make.
The -n option functions quite differently between pmake and make. make
will scan each shell command looking for potential re-invocations of
itself, and if it finds one, will assume that it is a recursive make and
execute the line. pmake does no such scanning of the shell commands and
will only execute a command in -n mode if the target is specified as a
recursive target using the .RECURSIVE attribute.
The treatment of the SHELL environment variable differs - pmake is in
conformance with POSIX 1003.2.
The compatibility modes of pmake attempt to emulate a 'least common
denominator' version of make as might be found in early BSD releases or
System V Release 3. It makes no attempt to emulate the more modern
features found in later System V and BSD releases.
Page 23
PMAKE(1)PMAKE(1)FILES
Makefile or makefile default input file
$(TOOLROOT)/usr/include/make/system.mk System makefile (the built-in
rules)
/usr/include/make/system.mk Alternate system makefile (the built-in
rules)
/usr/include/make/makelib.mk .USE target for making archives
/usr/include/make/makelint.mk .USE target for making lint libraries
ENVIRONMENT
PMAKE Flags pmake and smake should always use when invoked.
SHELL Not used to set shell interpretor for commands.
SEE ALSOmake(1) for a more complete explanation of the lower-case flags to pmake.
There are numerous books on make usage. These explain many of the
features described here though most versions of make are not as feature
rich as pmake. One such book is:Managing Projects with Make, 2nd ed.;
authored by Andrew Oram and Steve Talbott, from O'Reilly & Associates.
Page 24
