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. -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. 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. 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 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 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 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. 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. 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 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. 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 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. 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 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. .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 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. 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. 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). 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 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. 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) 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. 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. 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 ALSO make(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