1 .\" $NetBSD: tutorial.ms,v 1.13 2017/03/01 13:05:11 kre Exp $
2 .\" Copyright (c) 1988, 1989, 1993
3 .\" The Regents of the University of California. All rights reserved.
5 .\" This code is derived from software contributed to Berkeley by
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" Copyright (c) 1988, 1989 by Adam de Boor
33 .\" Copyright (c) 1989 by Berkeley Softworks
35 .\" This code is derived from software contributed to Berkeley by
38 .\" Redistribution and use in source and binary forms, with or without
39 .\" modification, are permitted provided that the following conditions
41 .\" 1. Redistributions of source code must retain the above copyright
42 .\" notice, this list of conditions and the following disclaimer.
43 .\" 2. Redistributions in binary form must reproduce the above copyright
44 .\" notice, this list of conditions and the following disclaimer in the
45 .\" documentation and/or other materials provided with the distribution.
46 .\" 3. All advertising materials mentioning features or use of this software
47 .\" must display the following acknowledgement:
48 .\" This product includes software developed by the University of
49 .\" California, Berkeley and its contributors.
50 .\" 4. Neither the name of the University nor the names of its contributors
51 .\" may be used to endorse or promote products derived from this software
52 .\" without specific prior written permission.
54 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
55 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
56 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
57 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
58 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
59 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
60 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
61 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
62 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
63 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
66 .\" @(#)tutorial.ms 8.1 (Berkeley) 8/18/93
68 .EH 'PSD:12-%''PMake \*- A Tutorial'
69 .OH 'PMake \*- A Tutorial''PSD:12-%'
70 .\" Ix is an indexing macro similar to .IX but I've disabled it for now
71 .\" Since that would require 2 passes and I am not in the mood for that.
74 .\" Rd is section (region) define and Rm is region mention? Again disable for
80 .\" xH is a macro to provide numbered headers that are automatically stuffed
81 .\" into a table-of-contents, properly indented, etc. If the first argument
82 .\" is numeric, it is taken as the depth for numbering (as for .NH), else
83 .\" the default (1) is assumed.
85 .\" @P The initial paragraph distance.
86 .\" @Q The piece of section number to increment (or 0 if none given)
87 .\" @R Section header.
88 .\" @S Indent for toc entry
89 .\" @T Argument to NH (can't use @Q b/c giving 0 to NH resets the counter)
92 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
96 \\*(SN \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
100 .\" CW is used to place a string in fixed-width or switch to a
101 .\" fixed-width font.
102 .\" C is a typewriter font for a laserwriter. Use something else if
103 .\" you don't have one...
106 .el \&\\$3\fC\\$1\fP\\$2
108 .\" Anything I put in a display I want to be in fixed-width
112 .\" The stuff in .No produces a little stop sign in the left margin
113 .\" that says NOTE in it. Unfortunately, it does cause a break, but
114 .\" hey. Can't have everything. In case you're wondering how I came
115 .\" up with such weird commands, they came from running grn on a
144 \d\D'p -0.19i 0.0i 0.0i -0.13i 0.30i 0.0i 0.0i 0.13i'
151 \h'85u'\v'0.85n'\h
\a-\w
\a\\*(g9
\au/2u
\a\&\\*(g9
163 .ie !\\n(.$ .IP \(bu 2
166 .ie n .po +\w'NOTE 'u
174 2150 Shattuck Ave, Penthouse
179 Permission to use, copy, modify, and distribute this software and its
180 documentation for any purpose and without fee is hereby granted,
181 provided that the above copyright notice appears in all copies.
182 The University of California, Berkeley Softworks, and Adam de Boor make no
183 representations about the suitability of this software for any
184 purpose. It is provided "as is" without express or implied warranty.
189 PMake is a program for creating other programs, or anything else you
190 can think of for it to do. The basic idea behind PMake is that, for
191 any given system, be it a program or a document or whatever, there
192 will be some files that depend on the state of other files (on when
193 they were last modified). PMake takes these dependencies, which you
194 must specify, and uses them to build whatever it is you want it to
197 PMake is almost fully-compatible with Make, with which you may already
198 be familiar. PMake's most important feature is its ability to run
199 several different jobs at once, making the creation of systems
200 considerably faster. It also has a great deal more functionality than
201 Make. Throughout the text, whenever something is mentioned that is an
202 important difference between PMake and Make (i.e. something that will
203 cause a makefile to fail if you don't do something about it), or is
204 simply important, it will be flagged with a little sign in the left
208 This tutorial is divided into three main sections corresponding to basic,
209 intermediate and advanced PMake usage. If you already know Make well,
210 you will only need to skim chapter 2 (there are some aspects of
211 PMake that I consider basic to its use that didn't exist in Make).
212 Things in chapter 3 make life much easier, while those in chapter 4
213 are strictly for those who know what they are doing. Chapter 5 has
214 definitions for the jargon I use and chapter 6 contains possible
215 solutions to the problems presented throughout the tutorial.
216 .xH 1 The Basics of PMake
218 PMake takes as input a file that tells a) which files depend on which
219 other files to be complete and b) what to do about files that are
220 ``out-of-date.'' This file is known as a ``makefile'' and is usually
222 kept in the top-most directory of the system to be built. While you
223 can call the makefile anything you want, PMake will look for
227 (in that order) in the current directory if you don't tell it
229 .Ix 0 def makefile default
230 To specify a different makefile, use the
233 .CW "pmake -f program.mk" ''). ``
235 .Ix 0 ref makefile other
237 A makefile has four different types of lines in it:
240 File dependency specifications
246 Comments, include statements and conditional directives
249 Any line may be continued over multiple lines by ending it with a
251 .Ix 0 def "continuation line"
252 The backslash, following newline and any initial whitespace
253 on the following line are compressed into a single space before the
254 input line is examined by PMake.
255 .xH 2 Dependency Lines
257 As mentioned in the introduction, in any system, there are
258 dependencies between the files that make up the system. For instance,
259 in a program made up of several C source files and one header file,
260 the C files will need to be re-compiled should the header file be
261 changed. For a document of several chapters and one macro file, the
262 chapters will need to be reprocessed if any of the macros changes.
263 .Ix 0 def "dependency"
264 These are dependencies and are specified by means of dependency lines in
267 .Ix 0 def "dependency line"
268 On a dependency line, there are targets and sources, separated by a
269 one- or two-character operator.
270 The targets ``depend'' on the sources and are usually created from
275 Any number of targets and sources may be specified on a dependency line.
276 All the targets in the line are made to depend on all the sources.
277 Targets and sources need not be actual files, but every source must be
278 either an actual file or another target in the makefile.
279 If you run out of room, use a backslash at the end of the line to continue onto
282 Any file may be a target and any file may be a source, but the
283 relationship between the two (or however many) is determined by the
284 ``operator'' that separates them.
286 Three types of operators exist: one specifies that the datedness of a
287 target is determined by the state of its sources, while another
288 specifies other files (the sources) that need to be dealt with before
289 the target can be re-created. The third operator is very similar to
290 the first, with the additional condition that the target is
291 out-of-date if it has no sources. These operations are represented by
292 the colon, the exclamation point and the double-colon, respectively, and are
293 mutually exclusive. Their exact semantics are as follows:
295 .Ix 0 def operator colon
297 If a colon is used, a target on the line is considered to be
298 ``out-of-date'' (and in need of creation) if
301 any of the sources has been modified more recently than the target, or
303 the target doesn't exist.
305 .Ix 0 def out-of-date
307 Under this operation, steps will be taken to re-create the target only
308 if it is found to be out-of-date by using these two rules.
310 .Ix 0 def operator force
312 If an exclamation point is used, the target will always be re-created,
313 but this will not happen until all of its sources have been examined
314 and re-created, if necessary.
316 .Ix 0 def operator double-colon
318 If a double-colon is used, a target is out-of-date if:
321 any of the sources has been modified more recently than the target, or
323 the target doesn't exist, or
325 the target has no sources.
328 If the target is out-of-date according to these rules, it will be re-created.
329 This operator also does something else to the targets, but I'll go
330 into that in the next section (``Shell Commands'').
332 Enough words, now for an example. Take that C program I mentioned
333 earlier. Say there are three C files
341 The dependencies between the files could then be expressed as follows:
343 program : a.o b.o c.o
350 You may be wondering at this point, where
359 and the C files don't. The reason is quite simple:
361 cannot be made by linking together .c files \*- it must be
362 made from .o files. Likewise, if you change
364 it isn't the .c files that need to be re-created, it's the .o files.
365 If you think of dependencies in these terms \*- which files (targets)
366 need to be created from which files (sources) \*- you should have no problems.
368 An important thing to notice about the above example, is that all the
369 \&.o files appear as targets on more than one line. This is perfectly
370 all right: the target is made to depend on all the sources mentioned
371 on all the dependency lines. E.g.
380 The order of the dependency lines in the makefile is
381 important: the first target on the first dependency line in the
382 makefile will be the one that gets made if you don't say otherwise.
385 comes first in the example makefile, above.
387 Both targets and sources may contain the standard C-Shell wildcard
396 but the non-curly-brace ones may only appear in the final component
397 (the file portion) of the target or source. The characters mean the
400 These enclose a comma-separated list of options and cause the pattern
401 to be expanded once for each element of the list. Each expansion
402 contains a different element. For example,
403 .CW src/{whiffle,beep,fish}.c
404 expands to the three words
409 These braces may be nested and, unlike the other wildcard characters,
410 the resulting words need not be actual files. All other wildcard
411 characters are expanded using the files that exist when PMake is
414 This matches zero or more characters of any sort.
416 will expand to the same three words as above as long as
418 contains those three files (and no other files that end in
421 Matches any single character.
423 This is known as a character class and contains either a list of
424 single characters, or a series of character ranges
426 for example means all characters between a and z), or both. It matches
427 any single character contained in the list. E.g.
429 will match all letters, while
431 will match all numbers.
434 ``Isn't that nice,'' you say to yourself, ``but how are files
435 actually `re-created,' as he likes to spell it?''
436 The re-creation is accomplished by commands you place in the makefile.
437 These commands are passed to the Bourne shell (better known as
438 ``/bin/sh'') to be executed and are
440 .Ix 0 ref re-creation
442 expected to do what's necessary to update the target file (PMake
443 doesn't actually check to see if the target was created. It just
447 Shell commands in a makefile look a lot like shell commands you would
448 type at a terminal, with one important exception: each command in a
451 be preceded by at least one tab.
453 Each target has associated with it a shell script made up of
454 one or more of these shell commands. The creation script for a target
455 should immediately follow the dependency line for that target. While
456 any given target may appear on more than one dependency line, only one
457 of these dependency lines may be followed by a creation script, unless
458 the `::' operator was used on the dependency line.
459 .Ix 0 ref operator double-colon
463 If the double-colon was used, each dependency line for the target
464 may be followed by a shell script. That script will only be executed
465 if the target on the associated dependency line is out-of-date with
466 respect to the sources on that line, according to the rules I gave
468 I'll give you a good example of this later on.
470 To expand on the earlier makefile, you might add commands as follows:
472 program : a.o b.o c.o
473 cc a.o b.o c.o \-o program
483 Something you should remember when writing a makefile is, the
484 commands will be executed if the
486 on the dependency line is out-of-date, not the sources.
489 .Ix 0 ref out-of-date
490 In this example, the command
491 .CW "cc \-c a.c" '' ``
494 is out-of-date. Because of the `:' operator,
496 .Ix 0 ref operator colon
497 this means that should
501 have been modified more recently than
503 the command will be executed
505 will be considered out-of-date).
506 .Ix 0 ref out-of-date
508 Remember how I said the only difference between a makefile shell
509 command and a regular shell command was the leading tab? I lied. There
510 is another way in which makefile commands differ from regular ones.
511 The first two characters after the initial whitespace are treated
513 If they are any combination of `@' and `\-', they cause PMake to do
516 In most cases, shell commands are printed before they're
517 actually executed. This is to keep you informed of what's going on. If
518 an `@' appears, however, this echoing is suppressed. In the case of an
521 .CW "echo Linking index" ,'' ``
529 so PMake allows you to place an `@' before the command
530 .CW "@echo Linking index" '') (``
531 to prevent the command from being printed.
533 The other special character is the `\-'. In case you didn't know,
534 shell commands finish with a certain ``exit status.'' This status is
535 made available by the operating system to whatever program invoked the
536 command. Normally this status will be 0 if everything went ok and
537 non-zero if something went wrong. For this reason, PMake will consider
538 an error to have occurred if one of the shells it invokes returns a non-zero
539 status. When it detects an error, PMake's usual action is to abort
540 whatever it's doing and exit with a non-zero status itself (any other
541 targets that were being created will continue being made, but nothing
542 new will be started. PMake will exit after the last job finishes).
543 This behavior can be altered, however, by placing a `\-' at the front
545 .CW "\-mv index index.old" ''), (``
546 certain command-line arguments,
547 or doing other things, to be detailed later. In such
548 a case, the non-zero status is simply ignored and PMake keeps chugging
552 Because all the commands are given to a single shell to execute, such
553 things as setting shell variables, changing directories, etc., last
554 beyond the command in which they are found. This also allows shell
555 compound commands (like
557 loops) to be entered in a natural manner.
558 Since this could cause problems for some makefiles that depend on
559 each command being executed by a single shell, PMake has a
561 .Ix 0 ref compatibility
563 flag (it stands for backwards-compatible) that forces each command to
564 be given to a separate shell. It also does several other things, all
565 of which I discourage since they are now old-fashioned.\|.\|.\|.
568 A target's shell script is fed to the shell on its (the shell's) input stream.
569 This means that any commands, such as
571 that need to get input from the terminal won't work right \*- they'll
572 get the shell's input, something they probably won't find to their
573 liking. A simple way around this is to give a command like this:
575 ci $(SRCS) < /dev/tty
577 This would force the program's input to come from the terminal. If you
578 can't do this for some reason, your only other alternative is to use
579 PMake in its fullest compatibility mode. See
582 .Ix 0 ref compatibility
586 PMake, like Make before it, has the ability to save text in variables
587 to be recalled later at your convenience. Variables in PMake are used
588 much like variables in the shell and, by tradition, consist of
589 all upper-case letters (you don't
591 to use all upper-case letters.
592 In fact there's nothing to stop you from calling a variable
594 Just tradition). Variables are assigned-to using lines of the form
595 .Ix 0 def variable assignment
599 .Ix 0 def variable assignment
604 .Ix 0 def variable appending
605 .Ix 0 def variable assignment appended
607 conditionally assigned-to (if the variable isn't already defined) by
611 .Ix 0 def variable assignment conditional
613 and assigned-to with expansion (i.e. the value is expanded (see below)
614 before being assigned to the variable\*-useful for placing a value at
615 the beginning of a variable, or other things) by
619 .Ix 0 def variable assignment expanded
622 Any whitespace before
624 is stripped off. When appending, a space is placed between the old
625 value and the stuff being appended.
627 The final way a variable may be assigned to is using
629 VARIABLE != shell-command
631 .Ix 0 def variable assignment shell-output
635 has all its variables expanded (see below) and is passed off to a
636 shell to execute. The output of the shell is then placed in the
637 variable. Any newlines (other than the final one) are replaced by
638 spaces before the assignment is made. This is typically used to find
639 the current directory via a line like:
645 this is intended to be used to execute commands that produce small amounts
646 of output (e.g. ``pwd''). The implementation is less than intelligent and will
647 likely freeze if you execute something that produces thousands of
648 bytes of output (8 Kb is the limit on many UNIX systems).
650 The value of a variable may be retrieved by enclosing the variable
651 name in parentheses or curly braces and preceding the whole thing
654 For example, to set the variable CFLAGS to the string
655 .CW "\-I/sprite/src/lib/libc \-O" ,'' ``
656 you would place a line
658 CFLAGS = \-I/sprite/src/lib/libc \-O
660 in the makefile and use the word
662 wherever you would like the string
663 .CW "\-I/sprite/src/lib/libc \-O"
664 to appear. This is called variable expansion.
665 .Ix 0 def variable expansion
668 Unlike Make, PMake will not expand a variable unless it knows
669 the variable exists. E.g. if you have a
671 in a shell command and you have not assigned a value to the variable
673 (the empty string is considered a value, by the way), where Make would have
674 substituted the empty string, PMake will leave the
677 To keep PMake from substituting for a variable it knows, precede the
678 dollar sign with another dollar sign.
683 This causes PMake, in effect, to expand the
685 macro, which expands to a single
687 For compatibility, Make's style of variable expansion will be used
688 if you invoke PMake with any of the compatibility flags (\c
695 flag alters just the variable expansion).
699 .Ix 0 ref compatibility
701 .Ix 0 ref variable expansion
702 There are two different times at which variable expansion occurs:
703 When parsing a dependency line, the expansion occurs immediately
704 upon reading the line. If any variable used on a dependency line is
705 undefined, PMake will print a message and exit.
706 Variables in shell commands are expanded when the command is
708 Variables used inside another variable are expanded whenever the outer
709 variable is expanded (the expansion of an inner variable has no effect
710 on the outer variable. I.e. if the outer variable is used on a dependency
711 line and in a shell command, and the inner variable changes value
712 between when the dependency line is read and the shell command is
713 executed, two different values will be substituted for the outer
715 .Ix 0 def variable types
717 Variables come in four flavors, though they are all expanded the same
718 and all look about the same. They are (in order of expanding scope):
722 .Ix 0 ref variable local
724 Command-line variables.
725 .Ix 0 ref variable command-line
728 .Ix 0 ref variable global
730 Environment variables.
731 .Ix 0 ref variable environment
734 The classification of variables doesn't matter much, except that the
735 classes are searched from the top (local) to the bottom (environment)
736 when looking up a variable. The first one found wins.
737 .xH 3 Local Variables
739 .Ix 0 def variable local
740 Each target can have as many as seven local variables. These are
741 variables that are only ``visible'' within that target's shell script
742 and contain such things as the target's name, all of its sources (from
743 all its dependency lines), those sources that were out-of-date, etc.
744 Four local variables are defined for all targets. They are:
747 .Ix 0 def variable local .TARGET
749 The name of the target.
751 .Ix 0 def variable local .OODATE
753 The list of the sources for the target that were considered out-of-date.
754 The order in the list is not guaranteed to be the same as the order in
755 which the dependencies were given.
757 .Ix 0 def variable local .ALLSRC
759 The list of all sources for this target in the order in which they
762 .Ix 0 def variable local .PREFIX
764 The target without its suffix and without any leading path. E.g. for
766 .CW ../../lib/compat/fsRead.c ,
767 this variable would contain
771 Three other local variables are set only for certain targets under
772 special circumstances. These are the ``.IMPSRC,''
773 .Ix 0 ref variable local .IMPSRC
776 .Ix 0 ref variable local .ARCHIVE
779 .Ix 0 ref variable local .MEMBER
781 variables. When they are set and how they are used is described later.
783 Four of these variables may be used in sources as well as in shell
785 .Ix 0 def "dynamic source"
786 .Ix 0 def source dynamic
787 These are ``.TARGET'', ``.PREFIX'', ``.ARCHIVE'' and ``.MEMBER''. The
788 variables in the sources are expanded once for each target on the
789 dependency line, providing what is known as a ``dynamic source,''
791 allowing you to specify several dependency lines at once. For example,
793 $(OBJS) : $(.PREFIX).c
795 will create a dependency between each object file and its
796 corresponding C source file.
797 .xH 3 Command-line Variables
799 .Ix 0 def variable command-line
800 Command-line variables are set when PMake is first invoked by giving a
801 variable assignment as one of the arguments. For example,
803 pmake "CFLAGS = -I/sprite/src/lib/libc -O"
807 be a command-line variable with the given value. Any assignments to
809 in the makefile will have no effect, because once it
810 is set, there is (almost) nothing you can do to change a command-line
811 variable (the search order, you see). Command-line variables may be
812 set using any of the four assignment operators, though only
816 behave as you would expect them to, mostly because assignments to
817 command-line variables are performed before the makefile is read, thus
818 the values set in the makefile are unavailable at the time.
821 .Ix 0 ref variable assignment appended
824 because the old value of the variable is sought only in the scope in
825 which the assignment is taking place (for reasons of efficiency that I
826 won't get into here).
832 .Ix 0 ref variable assignment expanded
833 .Ix 0 ref variable assignment conditional
834 will work if the only variables used are in the environment.
836 is sort of pointless to use from the command line, since the same
837 effect can no doubt be accomplished using the shell's own command
838 substitution mechanisms (backquotes and all that).
839 .xH 3 Global Variables
841 .Ix 0 def variable global
842 Global variables are those set or appended-to in the makefile.
843 There are two classes of global variables: those you set and those PMake sets.
844 As I said before, the ones you set can have any name you want them to have,
845 except they may not contain a colon or an exclamation point.
846 The variables PMake sets (almost) always begin with a
847 period and always contain upper-case letters, only. The variables are
851 .Ix 0 def variable global .PMAKE
853 .Ix 0 def variable global MAKE
855 The name by which PMake was invoked is stored in this variable. For
856 compatibility, the name is also stored in the MAKE variable.
858 .Ix 0 def variable global .MAKEFLAGS
859 .Ix 0 def .MAKEFLAGS variable
860 .Ix 0 def variable global MFLAGS
862 All the relevant flags with which PMake was invoked. This does not
863 include such things as
865 or variable assignments. Again for compatibility, this value is stored
866 in the MFLAGS variable as well.
869 Two other variables, ``.INCLUDES'' and ``.LIBS,'' are covered in the
870 section on special targets in chapter 3.
871 .Ix 0 ref variable global .INCLUDES
872 .Ix 0 ref variable global .LIBS
874 Global variables may be deleted using lines of the form:
876 .Ix 0 def variable deletion
878 #undef \fIvariable\fP
882 must be the first character on the line. Note that this may only be
883 done on global variables.
884 .xH 3 Environment Variables
886 .Ix 0 def variable environment
887 Environment variables are passed by the shell that invoked PMake and
888 are given by PMake to each shell it invokes. They are expanded like
889 any other variable, but they cannot be altered in any way.
891 One special environment variable,
893 .Ix 0 def variable environment PMAKE
894 is examined by PMake for command-line flags, variable assignments,
895 etc., it should always use. This variable is examined before the
896 actual arguments to PMake are. In addition, all flags given to PMake,
899 variable or on the command line, are placed in this environment
900 variable and exported to each shell PMake executes. Thus recursive
901 invocations of PMake automatically receive the same flags as the
904 Using all these variables, you can compress the sample makefile even more:
908 cc $(.ALLSRC) \-o $(.TARGET)
917 .Ix 0 ref variable local .ALLSRC
919 .Ix 0 ref variable local .TARGET
925 Comments in a makefile start with a `#' character and extend to the
926 end of the line. They may appear
927 anywhere you want them, except in a shell command (though the shell
928 will treat it as a comment, too). If, for some reason, you need to use the `#'
929 in a variable or on a dependency line, put a backslash in front of it.
930 PMake will compress the two into a single `#' (Note: this isn't true
931 if PMake is operating in full-compatibility mode).
933 .Ix 0 ref compatibility
937 PMake was specifically designed to re-create several targets at once,
938 when possible. You do not have to do anything special to cause this to
939 happen (unless PMake was configured to not act in parallel, in which
940 case you will have to make use of the
947 but you do have to be careful at times.
949 There are several problems you are likely to encounter. One is
950 that some makefiles (and programs) are written in such a way that it is
951 impossible for two targets to be made at once. The program
954 always modifies the files
958 There is no way to change it. Thus you cannot run two of them at once
959 without something being trashed. Similarly, if you have commands
960 in the makefile that always send output to the same file, you will not
961 be able to make more than one target at once unless you change the
962 file you use. You can, for instance, add a
964 to the end of the file name to tack on the process ID of the shell
965 executing the command (each
969 thus giving you the shell variable
971 Since only one shell is used for all the
972 commands, you'll get the same file name for each command in the
975 The other problem comes from improperly-specified dependencies that
976 worked in Make because of its sequential, depth-first way of examining
977 them. While I don't want to go into depth on how PMake
978 works (look in chapter 4 if you're interested), I will warn you that
979 files in two different ``levels'' of the dependency tree may be
980 examined in a different order in PMake than they were in Make. For
981 example, given the makefile
986 PMake will examine the targets in the order
991 If the makefile's author expected PMake to abort before making
993 if an error occurred while making
997 needed to exist before
1000 s/he will be sorely disappointed. The dependencies are
1001 incomplete, since in both these cases,
1007 Another problem you may face is that, while PMake is set up to handle the
1008 output from multiple jobs in a graceful fashion, the same is not so for input.
1009 It has no way to regulate input to different jobs,
1010 so if you use the redirection from
1012 I mentioned earlier, you must be careful not to run two of the jobs at once.
1013 .xH 2 Writing and Debugging a Makefile
1015 Now you know most of what's in a makefile, what do you do next? There
1016 are two choices: (1) use one of the uncommonly-available makefile
1017 generators or (2) write your own makefile (I leave out the third choice of
1018 ignoring PMake and doing everything by hand as being beyond the bounds
1021 When faced with the writing of a makefile, it is usually best to start
1022 from first principles: just what
1024 you trying to do? What do you want the makefile finally to produce?
1026 To begin with a somewhat traditional example, let's say you need to
1027 write a makefile to create a program,
1029 that takes standard infix expressions and converts them to prefix form (for
1030 no readily apparent reason). You've got three source files, in C, that
1031 make up the program:
1036 Harking back to my pithy advice about dependency lines, you write the
1037 first line of the file:
1039 expr : main.o parse.o output.o
1041 because you remember
1047 files. Similarly for the
1049 files you produce the lines:
1054 main.o parse.o output.o : defs.h
1057 Great. You've now got the dependencies specified. What you need now is
1058 commands. These commands, remember, must produce the target on the
1059 dependency line, usually by using the sources you've listed.
1060 You remember about local variables? Good, so it should come
1061 to you as no surprise when you write
1063 expr : main.o parse.o output.o
1064 cc -o $(.TARGET) $(.ALLSRC)
1066 Why use the variables? If your program grows to produce postfix
1067 expressions too (which, of course, requires a name change or two), it
1068 is one fewer place you have to change the file. You cannot do this for
1069 the object files, however, because they depend on their corresponding
1082 which is wrong. So you round out the makefile with these lines:
1092 The makefile is now complete and will, in fact, create the program you
1093 want it to without unnecessary compilations or excessive typing on
1094 your part. There are two things wrong with it, however (aside from it
1095 being altogether too long, something I'll address in chapter 3):
1098 .CW "main.o parse.o output.o" '' ``
1099 is repeated twice, necessitating two changes when you add postfix
1100 (you were planning on that, weren't you?). This is in direct violation
1101 of de Boor's First Rule of writing makefiles:
1104 Anything that needs to be written more than once
1105 should be placed in a variable.
1107 I cannot emphasize this enough as being very important to the
1108 maintenance of a makefile and its program.
1110 There is no way to alter the way compilations are performed short of
1111 editing the makefile and making the change in all places. This is evil
1112 and violates de Boor's Second Rule, which follows directly from the
1116 Any flags or programs used inside a makefile should be placed in a variable so
1117 they may be changed, temporarily or permanently, with the greatest ease.
1119 The makefile should more properly read:
1121 OBJS = main.o parse.o output.o
1123 $(CC) $(CFLAGS) -o $(.TARGET) $(.ALLSRC)
1125 $(CC) $(CFLAGS) -c main.c
1127 $(CC) $(CFLAGS) -c parse.c
1129 $(CC) $(CFLAGS) -c output.c
1132 Alternatively, if you like the idea of dynamic sources mentioned in
1136 .Ix 0 ref "dynamic source"
1137 .Ix 0 ref source dynamic
1138 you could write it like this:
1140 OBJS = main.o parse.o output.o
1142 $(CC) $(CFLAGS) -o $(.TARGET) $(.ALLSRC)
1143 $(OBJS) : $(.PREFIX).c defs.h
1144 $(CC) $(CFLAGS) -c $(.PREFIX).c
1146 These two rules and examples lead to de Boor's First Corollary:
1149 Variables are your friends.
1151 Once you've written the makefile comes the sometimes-difficult task of
1153 making sure the darn thing works. Your most helpful tool to make sure
1154 the makefile is at least syntactically correct is the
1157 flag, which allows you to see if PMake will choke on the makefile. The
1160 flag lets you do is see what PMake would do without it actually doing
1161 it, thus you can make sure the right commands would be executed were
1162 you to give PMake its head.
1164 When you find your makefile isn't behaving as you hoped, the first
1165 question that comes to mind (after ``What time is it, anyway?'') is
1166 ``Why not?'' In answering this, two flags will serve you well:
1172 The first causes PMake to tell you as it examines each target in the
1173 makefile and indicate why it is deciding whatever it is deciding. You
1174 can then use the information printed for other targets to see where
1177 flag makes PMake print out its internal state when it is done,
1178 allowing you to see that you forgot to make that one chapter depend on
1179 that file of macros you just got a new version of. The output from
1181 is intended to resemble closely a real makefile, but with additional
1182 information provided and with variables expanded in those commands
1183 PMake actually printed or executed.
1185 Something to be especially careful about is circular dependencies.
1186 .Ix 0 def dependency circular
1193 In this case, because of how PMake works,
1195 is the only thing PMake will examine, because
1199 will effectively fall off the edge of the universe, making it
1200 impossible to examine
1202 (or them, for that matter).
1203 PMake will tell you (if run in its normal mode) all the targets
1204 involved in any cycle it looked at (i.e. if you have two cycles in the
1205 graph (naughty, naughty), but only try to make a target in one of
1206 them, PMake will only tell you about that one. You'll have to try to
1207 make the other to find the second cycle). When run as Make, it will
1208 only print the first target in the cycle.
1209 .xH 2 Invoking PMake
1214 PMake comes with a wide variety of flags to choose from.
1215 They may appear in any order, interspersed with command-line variable
1216 assignments and targets to create.
1217 The flags are as follows:
1218 .IP "\fB\-d\fP \fIwhat\fP"
1221 This causes PMake to spew out debugging information that
1222 may prove useful to you. If you can't
1223 figure out why PMake is doing what it's doing, you might try using
1226 parameter is a string of single characters that tell PMake what
1227 aspects you are interested in. Most of what I describe will make
1228 little sense to you, unless you've dealt with Make before. Just
1229 remember where this table is and come back to it as you read on.
1230 The characters and the information they produce are as follows:
1233 Archive searching and caching.
1235 Conditional evaluation.
1237 The searching and caching of directories.
1239 Various snippets of information related to the running of the multiple
1240 shells. Not particularly interesting.
1242 The making of each target: what target is being examined; when it was
1243 last modified; whether it is out-of-date; etc.
1249 The application of suffix-transformation rules. (See chapter 3)
1251 The maintenance of the list of targets.
1253 Variable assignment.
1260 letters will be most useful to you.
1263 is the final argument or the argument from which it would get these
1264 key letters (see below for a note about which argument would be used)
1267 all of these debugging flags will be set, resulting in massive amounts
1269 .IP "\fB\-f\fP \fImakefile\fP"
1271 Specify a makefile to read different from the standard makefiles
1275 .Ix 0 ref makefile default
1276 .Ix 0 ref makefile other
1279 is ``\-'', PMake uses the standard input. This is useful for making
1280 quick and dirty makefiles.\|.\|.
1281 .Ix 0 ref makefile "quick and dirty"
1284 Prints out a summary of the various flags PMake accepts. It can also
1285 be used to find out what level of concurrency was compiled into the
1286 version of PMake you are using (look at
1290 and various other information on how PMake was configured.
1291 .Ix 0 ref configuration
1292 .Ix 0 ref makefile system
1295 If you give this flag, PMake will ignore non-zero status returned
1296 by any of its shells. It's like placing a `\-' before all the commands
1302 in that it allows PMake to continue when it sees an error, but unlike
1304 where PMake continues blithely as if nothing went wrong,
1306 causes it to recognize the error and only continue work on those
1307 things that don't depend on the target, either directly or indirectly (through
1308 depending on something that depends on it), whose creation returned the error.
1309 The `k' is for ``keep going''.\|.\|.
1313 PMake has the ability to lock a directory against other
1314 people executing it in the same directory (by means of a file called
1315 ``LOCK.make'' that it creates and checks for in the directory). This
1316 is a Good Thing because two people doing the same thing in the same place
1317 can be disastrous for the final product (too many cooks and all that).
1318 Whether this locking is the default is up to your system
1319 administrator. If locking is on,
1321 will turn it off, and vice versa. Note that this locking will not
1322 prevent \fIyou\fP from invoking PMake twice in the same place \*- if
1323 you own the lock file, PMake will warn you about it but continue to execute.
1324 .IP "\fB\-m\fP \fIdirectory\fP"
1326 Tells PMake another place to search for included makefiles via the <...>
1329 options can be given to form a search path. If this construct is used the
1330 default system makefile search path is completely overridden.
1331 To be explained in chapter 3, section 3.2.
1335 This flag tells PMake not to execute the commands needed to update the
1336 out-of-date targets in the makefile. Rather, PMake will simply print
1337 the commands it would have executed and exit. This is particularly
1338 useful for checking the correctness of a makefile. If PMake doesn't do
1339 what you expect it to, it's a good chance the makefile is wrong.
1340 .IP "\fB\-p\fP \fInumber\fP"
1343 This causes PMake to print its input in a reasonable form, though
1344 not necessarily one that would make immediate sense to anyone but me. The
1346 is a bitwise-or of 1 and 2 where 1 means it should print the input
1347 before doing any processing and 2 says it should print it after
1348 everything has been re-created. Thus
1350 would print it twice\*-once before processing and once after (you
1351 might find the difference between the two interesting). This is mostly
1352 useful to me, but you may find it informative in some bizarre circumstances.
1355 If you give PMake this flag, it will not try to re-create anything. It
1356 will just see if anything is out-of-date and exit non-zero if so.
1359 When PMake starts up, it reads a default makefile that tells it what
1360 sort of system it's on and gives it some idea of what to do if you
1361 don't tell it anything. I'll tell you about it in chapter 3. If you
1362 give this flag, PMake won't read the default makefile.
1365 This causes PMake to not print commands before they're executed. It
1366 is the equivalent of putting an `@' before every command in the
1370 Rather than try to re-create a target, PMake will simply ``touch'' it
1371 so as to make it appear up-to-date. If the target didn't exist before,
1372 it will when PMake finishes, but if the target did exist, it will
1373 appear to have been updated.
1376 This is a mixed-compatibility flag intended to mimic the System V
1377 version of Make. It is the same as giving
1381 as well as turning off directory locking. Targets can still be created
1382 in parallel, however. This is the mode PMake will enter if it is
1389 This tells PMake it's ok to export jobs to other machines, if they're
1390 available. It is used when running in Make mode, as exporting in this
1391 mode tends to make things run slower than if the commands were just
1394 .Ix 0 ref compatibility
1396 Forces PMake to be as backwards-compatible with Make as possible while
1401 Executing one shell per shell command
1403 Expanding anything that looks even vaguely like a variable, with the
1404 empty string replacing any variable PMake doesn't know.
1406 Refusing to allow you to escape a `#' with a backslash.
1408 Permitting undefined variables on dependency lines and conditionals
1409 (see below). Normally this causes PMake to abort.
1413 This nullifies any and all compatibility mode flags you may have given
1414 or implied up to the time the
1416 is encountered. It is useful mostly in a makefile that you wrote for PMake
1417 to avoid bad things happening when someone runs PMake as
1419 or has things set in the environment that tell it to be compatible.
1425 environment variable or the
1430 .Ix 0 ref variable environment PMAKE
1431 .Ix 0 ref variable global .MAKEFLAGS
1432 .Ix 0 ref variable global MFLAGS
1433 .Ix 0 ref .MAKEFLAGS variable
1435 .IP "\fB\-D\fP \fIvariable\fP"
1437 Allows you to define a variable to have
1439 as its value. The variable is a global variable, not a command-line
1440 variable. This is useful mostly for people who are used to the C
1441 compiler arguments and those using conditionals, which I'll get into
1444 .IP "\fB\-I\fP \fIdirectory\fP"
1446 Tells PMake another place to search for included makefiles. Yet
1447 another thing to be explained in chapter 3 (section 3.2, to be
1450 .IP "\fB\-J\fP \fInumber\fP"
1452 Gives the absolute maximum number of targets to create at once on both
1453 local and remote machines.
1454 .IP "\fB\-L\fP \fInumber\fP"
1456 This specifies the maximum number of targets to create on the local
1457 machine at once. This may be 0, though you should be wary of doing
1458 this, as PMake may hang until a remote machine becomes available, if
1459 one is not available when it is started.
1461 .Ix 0 ref compatibility
1463 This is the flag that provides absolute, complete, full compatibility
1464 with Make. It still allows you to use all but a few of the features of
1465 PMake, but it is non-parallel. This is the mode PMake enters if you
1470 .Ix 0 ref "output control"
1471 When creating targets in parallel, several shells are executing at
1472 once, each wanting to write its own two cent's-worth to the screen.
1473 This output must be captured by PMake in some way in order to prevent
1474 the screen from being filled with garbage even more indecipherable
1475 than you usually see. PMake has two ways of doing this, one of which
1476 provides for much cleaner output and a clear separation between the
1477 output of different jobs, the other of which provides a more immediate
1478 response so one can tell what is really happening. The former is done
1479 by notifying you when the creation of a target starts, capturing the
1480 output and transferring it to the screen all at once when the job
1481 finishes. The latter is done by catching the output of the shell (and
1482 its children) and buffering it until an entire line is received, then
1483 printing that line preceded by an indication of which job produced
1484 the output. Since I prefer this second method, it is the one used by
1485 default. The first method will be used if you give the
1490 As mentioned before, the
1492 flag tells PMake to use Make's style of expanding variables,
1493 substituting the empty string for any variable it doesn't know.
1496 There are several times when PMake will print a message at you that is
1497 only a warning, i.e. it can continue to work in spite of your having
1498 done something silly (such as forgotten a leading tab for a shell
1499 command). Sometimes you are well aware of silly things you have done
1500 and would like PMake to stop bothering you. This flag tells it to shut
1501 up about anything non-fatal.
1504 This flag causes PMake to not attempt to export any jobs to another
1507 Several flags may follow a single `\-'. Those flags that require
1508 arguments take them from successive parameters. E.g.
1510 pmake -fDnI server.mk DEBUG /chip2/X/server/include
1512 will cause PMake to read
1514 as the input makefile, define the variable
1516 as a global variable and look for included makefiles in the directory
1517 .CW /chip2/X/server/include .
1520 A makefile is made of four types of lines:
1527 Variable assignments
1529 Comments, include statements and conditional directives
1532 A dependency line is a list of one or more targets, an operator
1537 and a list of zero or more sources. Sources may contain wildcards and
1538 certain local variables.
1540 A creation command is a regular shell command preceded by a tab. In
1541 addition, if the first two characters after the tab (and other
1542 whitespace) are a combination of
1546 PMake will cause the command to not be printed (if the character is
1548 or errors from it to be ignored (if
1550 A blank line, dependency line or variable assignment terminates a
1551 creation script. There may be only one creation script for each target
1558 Variables are places to store text. They may be unconditionally
1559 assigned-to using the
1562 .Ix 0 ref variable assignment
1563 operator, appended-to using the
1566 .Ix 0 ref variable assignment appended
1567 operator, conditionally (if the variable is undefined) assigned-to
1571 .Ix 0 ref variable assignment conditional
1572 operator, and assigned-to with variable expansion with the
1575 .Ix 0 ref variable assignment expanded
1576 operator. The output of a shell command may be assigned to a variable
1580 .Ix 0 ref variable assignment shell-output
1581 operator. Variables may be expanded (their value inserted) by enclosing
1582 their name in parentheses or curly braces, preceded by a dollar sign.
1583 A dollar sign may be escaped with another dollar sign. Variables are
1584 not expanded if PMake doesn't know about them. There are seven local
1600 may be used to specify ``dynamic sources.''
1601 .Ix 0 ref "dynamic source"
1602 .Ix 0 ref source dynamic
1603 Variables are good. Know them. Love them. Live them.
1605 Debugging of makefiles is best accomplished using the
1614 .xH 1 Short-cuts and Other Nice Things
1616 Based on what I've told you so far, you may have gotten the impression
1617 that PMake is just a way of storing away commands and making sure you
1618 don't forget to compile something. Good. That's just what it is.
1619 However, the ways I've described have been inelegant, at best, and
1621 This chapter contains things that make the
1622 writing of makefiles easier and the makefiles themselves shorter and
1623 easier to modify (and, occasionally, simpler). In this chapter, I
1624 assume you are somewhat more
1625 familiar with Sprite (or UNIX, if that's what you're using) than I did
1626 in chapter 2, just so you're on your toes.
1627 So without further ado...
1628 .xH 2 Transformation Rules
1630 As you know, a file's name consists of two parts: a base name, which
1631 gives some hint as to the contents of the file, and a suffix, which
1632 usually indicates the format of the file.
1636 naming conventions, with regard to suffixes, have also developed that have
1637 become almost as incontrovertible as Law. E.g. a file ending in
1639 is assumed to contain C source code; one with a
1641 suffix is assumed to be a compiled, relocatable object file that may
1642 be linked into any program; a file with a
1644 suffix is usually a text file to be processed by Troff with the \-ms
1645 macro package, and so on.
1646 One of the best aspects of both Make and PMake comes from their
1647 understanding of how the suffix of a file pertains to its contents and
1648 their ability to do things with a file based solely on its suffix. This
1649 ability comes from something known as a transformation rule. A
1650 transformation rule specifies how to change a file with one suffix
1651 into a file with another suffix.
1653 A transformation rule looks much like a dependency line, except the
1654 target is made of two known suffixes stuck together. Suffixes are made
1655 known to PMake by placing them as sources on a dependency line whose
1656 target is the special target
1662 $(CC) $(CFLAGS) -c $(.IMPSRC)
1664 The creation script attached to the target is used to transform a file with
1665 the first suffix (in this case,
1667 into a file with the second suffix (here,
1669 In addition, the target inherits whatever attributes have been applied
1670 to the transformation rule.
1671 The simple rule given above says that to transform a C source file
1672 into an object file, you compile it using
1677 This rule is taken straight from the system makefile. Many
1678 transformation rules (and suffixes) are defined there, and I refer you
1679 to it for more examples (type
1680 .CW "pmake -h" '' ``
1681 to find out where it is).
1683 There are several things to note about the transformation rule given
1690 .Ix 0 def variable local .IMPSRC
1692 This variable is set to the ``implied source'' (the file from which
1693 the target is being created; the one with the first suffix), which, in this
1694 case, is the .c file.
1698 variable. Almost all of the transformation rules in the system
1699 makefile are set up using variables that you can alter in your
1700 makefile to tailor the rule to your needs. In this case, if you want
1701 all your C files to be compiled with the
1703 flag, to provide information for
1709 .CW "CFLAGS = -g" '') (``
1710 and PMake would take care of the rest.
1713 To give you a quick example, the makefile in 2.3.4
1715 could be changed to this:
1719 $(CC) -o $(.TARGET) $(.ALLSRC)
1722 The transformation rule I gave above takes the place of the 6 lines\**
1724 This is also somewhat cleaner, I think, than the dynamic source
1725 solution presented in 2.6
1737 Now you may be wondering about the dependency between the
1741 files \*- it's not mentioned anywhere in the new makefile. This is
1742 because it isn't needed: one of the effects of applying a
1743 transformation rule is the target comes to depend on the implied
1744 source. That's why it's called the implied
1747 For a more detailed example. Say you have a makefile like this:
1752 and a directory set up like this:
1755 -rw-rw-r-- 1 deboor 34 Sep 7 00:43 Makefile
1756 -rw-rw-r-- 1 deboor 119 Oct 3 19:39 a.c
1757 -rw-rw-r-- 1 deboor 201 Sep 7 00:43 a.o
1758 -rw-rw-r-- 1 deboor 69 Sep 7 00:43 b.c
1762 will do the right thing, it's much more informative to type
1763 .CW "pmake -d s" ''. ``
1764 This will show you what PMake is up to as it processes the files. In
1765 this case, PMake prints the following:
1767 Suff_FindDeps (a.out)
1768 using existing source a.o
1769 applying .o -> .out to "a.o"
1772 applying .c -> .o to "a.c"
1775 applying .c -> .o to "b.c"
1777 trying a.y...not there
1778 trying a.l...not there
1779 trying a.c,v...not there
1780 trying a.y,v...not there
1781 trying a.l,v...not there
1783 trying b.y...not there
1784 trying b.l...not there
1785 trying b.c,v...not there
1786 trying b.y,v...not there
1787 trying b.l,v...not there
1797 is the name of a function in PMake that is called to check for implied
1798 sources for a target using transformation rules.
1799 The transformations it tries are, naturally
1800 enough, limited to the ones that have been defined (a transformation
1801 may be defined multiple times, by the way, but only the most recent
1802 one will be used). You will notice, however, that there is a definite
1803 order to the suffixes that are tried. This order is set by the
1804 relative positions of the suffixes on the
1806 line \*- the earlier a suffix appears, the earlier it is checked as
1807 the source of a transformation. Once a suffix has been defined, the
1808 only way to change its position in the pecking order is to remove all
1809 the suffixes (by having a
1811 dependency line with no sources) and redefine them in the order you
1812 want. (Previously-defined transformation rules will be automatically
1813 redefined as the suffixes they involve are re-entered.)
1815 Another way to affect the search order is to make the dependency
1816 explicit. In the above example,
1822 Since a transformation exists from
1826 PMake uses that, as indicated by the
1827 .CW "using existing source a.o" '' ``
1830 The search for a transformation starts from the suffix of the target
1831 and continues through all the defined transformations, in the order
1832 dictated by the suffix ranking, until an existing file with the same
1833 base (the target name minus the suffix and any leading directories) is
1834 found. At that point, one or more transformation rules will have been
1835 found to change the one existing file into the target.
1837 For example, ignoring what's in the system makefile for now, say you
1838 have a makefile like this:
1840 \&.SUFFIXES : .out .o .c .y .l
1843 mv lex.yy.c $(.TARGET)
1846 mv y.tab.c $(.TARGET)
1850 cc -o $(.TARGET) $(.IMPSRC)
1855 .CW "pmake -rd ms jive.out" ,'' ``
1856 you would get the following output for
1859 Suff_FindDeps (jive.out)
1860 trying jive.o...not there
1861 trying jive.c...not there
1862 trying jive.y...not there
1863 trying jive.l...got it
1864 applying .l -> .c to "jive.l"
1865 applying .c -> .o to "jive.c"
1866 applying .o -> .out to "jive.o"
1868 and this is why: PMake starts with the target
1870 figures out its suffix
1872 and looks for things it can transform to a
1874 file. In this case, it only finds
1876 so it looks for the file
1878 It fails to find it, so it looks for transformations into a
1880 file. Again it has only one choice:
1884 and, as you know, fails to find it. At this point it has two choices:
1897 first, but can't find it, so it looks for
1899 and, lo and behold, there it is.
1900 At this point, it has defined a transformation path as follows:
1908 and applies the transformation rules accordingly. For completeness,
1909 and to give you a better idea of what PMake actually did with this
1910 three-step transformation, this is what PMake printed for the rest of
1913 Suff_FindDeps (jive.o)
1914 using existing source jive.c
1915 applying .c -> .o to "jive.c"
1916 Suff_FindDeps (jive.c)
1917 using existing source jive.l
1918 applying .l -> .c to "jive.l"
1919 Suff_FindDeps (jive.l)
1920 Examining jive.l...modified 17:16:01 Oct 4, 1987...up-to-date
1921 Examining jive.c...non-existent...out-of-date
1924 \&.\|.\|. meaningless lex output deleted .\|.\|.
1926 Examining jive.o...non-existent...out-of-date
1929 Examining jive.out...non-existent...out-of-date
1931 cc -o jive.out jive.o
1934 One final question remains: what does PMake do with targets that have
1935 no known suffix? PMake simply pretends it actually has a known suffix
1936 and searches for transformations accordingly.
1937 The suffix it chooses is the source for the
1940 target mentioned later. In the system makefile,
1942 is chosen as the ``null suffix''
1943 .Ix 0 def suffix null
1944 .Ix 0 def "null suffix"
1945 because most people use PMake to create programs. You are, however,
1946 free and welcome to change it to a suffix of your own choosing.
1947 The null suffix is ignored, however, when PMake is in compatibility
1948 mode (see chapter 4).
1949 .xH 2 Including Other Makefiles
1950 .Ix 0 def makefile inclusion
1953 Just as for programs, it is often useful to extract certain parts of a
1954 makefile into another file and just include it in other makefiles
1955 somehow. Many compilers allow you say something like
1959 to include the contents of
1961 in the source file. PMake allows you to do the same thing for
1962 makefiles, with the added ability to use variables in the filenames.
1963 An include directive in a makefile looks either like this:
1971 The difference between the two is where PMake searches for the file:
1972 the first way, PMake will look for
1973 the file only in the system makefile directory (or directories)
1974 (to find out what that directory is, give PMake the
1978 The system makefile directory search path can be overridden via the
1982 For files in double-quotes, the search is more complex:
1985 The directory of the makefile that's including the file.
1987 The current directory (the one in which you invoked PMake).
1989 The directories given by you using
1991 flags, in the order in which you gave them.
1993 Directories given by
1995 dependency lines (see chapter 4).
1997 The system makefile directory.
2002 You are free to use PMake variables in the filename\*-PMake will
2003 expand them before searching for the file. You must specify the
2004 searching method with either angle brackets or double-quotes
2006 of a variable expansion. I.e. the following
2008 SYSTEM = <command.mk>
2013 .xH 2 Saving Commands
2016 There may come a time when you will want to save certain commands to
2017 be executed when everything else is done. For instance: you're
2018 making several different libraries at one time and you want to create the
2019 members in parallel. Problem is,
2021 is another one of those programs that can't be run more than once in
2022 the same directory at the same time (each one creates a file called
2024 into which it stuffs information for the linker to use. Two of them
2025 running at once will overwrite each other's file and the result will
2026 be garbage for both parties). You might want a way to save the ranlib
2027 commands til the end so they can be run one after the other, thus
2028 keeping them from trashing each other's file. PMake allows you to do
2029 this by inserting an ellipsis (``.\|.\|.'') as a command between
2030 commands to be run at once and those to be run later.
2034 case above, you might do this:
2037 lib1.a : $(LIB1OBJS)
2039 ar cr $(.TARGET) $(.ALLSRC)
2043 lib2.a : $(LIB2OBJS)
2045 ar cr $(.TARGET) $(.ALLSRC)
2049 .Ix 0 ref variable local .TARGET
2050 .Ix 0 ref variable local .ALLSRC
2051 This would save both
2055 commands until the end, when they would run one after the other
2056 (using the correct value for the
2058 variable, of course).
2060 Commands saved in this manner are only executed if PMake manages to
2061 re-create everything without an error.
2062 .xH 2 Target Attributes
2064 PMake allows you to give attributes to targets by means of special
2065 sources. Like everything else PMake uses, these sources begin with a
2066 period and are made up of all upper-case letters. There are various
2067 reasons for using them, and I will try to give examples for most of
2068 them. Others you'll have to find uses for yourself. Think of it as ``an
2069 exercise for the reader.'' By placing one (or more) of these as a source on a
2070 dependency line, you are ``marking the target(s) with that
2071 attribute.'' That's just the way I phrase it, so you know.
2073 Any attributes given as sources for a transformation rule are applied
2074 to the target of the transformation rule when the rule is applied.
2075 .Ix 0 def attributes
2080 .Ix 0 def attributes .DONTCARE
2082 If a target is marked with this attribute and PMake can't figure out
2083 how to create it, it will ignore this fact and assume the file isn't
2084 really needed or actually exists and PMake just can't find it. This may prove
2085 wrong, but the error will be noted later on, not when PMake tries to create
2086 the target so marked. This attribute also prevents PMake from
2087 attempting to touch the target if it is given the
2092 .Ix 0 def attributes .EXEC
2094 This attribute causes its shell script to be executed while having no
2095 effect on targets that depend on it. This makes the target into a sort
2096 of subroutine. An example. Say you have some LISP files that need to
2097 be compiled and loaded into a LISP process. To do this, you echo LISP
2098 commands into a file and execute a LISP with this file as its input
2099 when everything's done. Say also that you have to load other files
2100 from another system before you can compile your files and further,
2101 that you don't want to go through the loading and dumping unless one
2104 files has changed. Your makefile might look a little bit
2105 like this (remember, this is an educational example, and don't worry
2108 rule, all will soon become clear, grasshopper):
2110 system : init a.fasl b.fasl c.fasl
2111 for i in $(.ALLSRC);
2113 echo -n '(load "' >> input
2114 echo -n ${i} >> input
2117 echo '(dump "$(.TARGET)")' >> input
2120 a.fasl : a.l init COMPILE
2121 b.fasl : b.l init COMPILE
2122 c.fasl : c.l init COMPILE
2124 echo '(compile "$(.ALLSRC)")' >> input
2126 echo '(load-system)' > input
2129 .Ix 0 ref attributes .USE
2130 .Ix 0 ref variable local .ALLSRC
2133 sources, don't appear in the local variables of targets that depend on
2134 them (nor are they touched if PMake is given the
2138 Note that all the rules, not just that for
2142 as a source. This is because none of the other targets can be made
2145 has been made, thus they depend on it.
2147 .Ix 0 def attributes .EXPORT
2149 This is used to mark those targets whose creation should be sent to
2150 another machine if at all possible. This may be used by some
2151 exportation schemes if the exportation is expensive. You should ask
2152 your system administrator if it is necessary.
2153 .IP .EXPORTSAME \n(pw
2154 .Ix 0 def attributes .EXPORTSAME
2155 .Ix 0 def .EXPORTSAME
2156 Tells the export system that the job should be exported to a machine
2157 of the same architecture as the current one. Certain operations (e.g.
2158 running text through
2160 can be performed the same on any architecture (CPU and
2161 operating system type), while others (e.g. compiling a program with
2163 must be performed on a machine with the same architecture. Not all
2164 export systems will support this attribute.
2166 .Ix 0 def attributes .IGNORE
2167 .Ix 0 def .IGNORE attribute
2170 attribute causes PMake to ignore errors from any of the target's commands, as
2171 if they all had `\-' before them.
2172 .IP .INVISIBLE \n(pw
2173 .Ix 0 def attributes .INVISIBLE
2174 .Ix 0 def .INVISIBLE
2175 This allows you to specify one target as a source for another without
2176 the one affecting the other's local variables. Useful if, say, you
2177 have a makefile that creates two programs, one of which is used to
2178 create the other, so it must exist before the other is created. You
2181 prog1 : $(PROG1OBJS) prog2 MAKEINSTALL
2182 prog2 : $(PROG2OBJS) .INVISIBLE MAKEINSTALL
2186 is some complex .USE rule (see below) that depends on the
2189 variable containing the right things. Without the
2195 rule couldn't be applied. This is not as useful as it should be, and
2196 the semantics may change (or the whole thing go away) in the
2197 not-too-distant future.
2199 .Ix 0 def attributes .JOIN
2201 This is another way to avoid performing some operations in parallel
2202 while permitting everything else to be done so. Specifically it
2203 forces the target's shell script to be executed only if one or more of the
2204 sources was out-of-date. In addition, the target's name,
2207 variable and all the local variables of any target that depends on it,
2208 is replaced by the value of its
2211 As an example, suppose you have a program that has four libraries that
2212 compile in the same directory along with, and at the same time as, the
2213 program. You again have the problem with
2215 that I mentioned earlier, only this time it's more severe: you
2216 can't just put the ranlib off to the end since the program
2217 will need those libraries before it can be re-created. You can do
2218 something like this:
2220 program : $(OBJS) libraries
2221 cc -o $(.TARGET) $(.ALLSRC)
2223 libraries : lib1.a lib2.a lib3.a lib4.a .JOIN
2226 .Ix 0 ref variable local .TARGET
2227 .Ix 0 ref variable local .ALLSRC
2228 .Ix 0 ref variable local .OODATE
2232 In this case, PMake will re-create the
2234 as necessary, along with
2240 It will then execute
2242 on any library that was changed and set
2245 variable to contain what's in
2248 .CW "lib1.a lib2.a lib3.a lib4.a" .'' ``
2249 In case you're wondering, it's called
2251 because it joins together different threads of the ``input graph'' at
2252 the target marked with the attribute.
2253 Another aspect of the .JOIN attribute is it keeps the target from
2254 being created if the
2259 .Ix 0 def attributes .MAKE
2263 attribute marks its target as being a recursive invocation of PMake.
2264 This forces PMake to execute the script associated with the target (if
2265 it's out-of-date) even if you gave the
2269 flag. By doing this, you can start at the top of a system and type
2273 and have it descend the directory tree (if your makefiles are set up
2274 correctly), printing what it would have executed if you hadn't
2279 .Ix 0 def attributes .NOEXPORT
2280 .Ix 0 def .NOEXPORT attribute
2281 If possible, PMake will attempt to export the creation of all targets to
2282 another machine (this depends on how PMake was configured). Sometimes,
2283 the creation is so simple, it is pointless to send it to another
2284 machine. If you give the target the
2286 attribute, it will be run locally, even if you've given PMake the
2290 .Ix 0 def attributes .NOTMAIN
2292 Normally, if you do not specify a target to make in any other way,
2293 PMake will take the first target on the first dependency line of a
2294 makefile as the target to create. That target is known as the ``Main
2295 Target'' and is labeled as such if you print the dependencies out
2300 Giving a target this attribute tells PMake that the target is
2304 This allows you to place targets in an included makefile and
2305 have PMake create something else by default.
2307 .Ix 0 def attributes .PRECIOUS
2308 .Ix 0 def .PRECIOUS attribute
2309 When PMake is interrupted (you type control-C at the keyboard), it
2310 will attempt to clean up after itself by removing any half-made
2311 targets. If a target has the
2313 attribute, however, PMake will leave it alone. An additional side
2314 effect of the `::' operator is to mark the targets as
2316 .Ix 0 ref operator double-colon
2319 .Ix 0 def attributes .SILENT
2320 .Ix 0 def .SILENT attribute
2321 Marking a target with this attribute keeps its commands from being
2322 printed when they're executed, just as if they had an `@' in front of them.
2324 .Ix 0 def attributes .USE
2326 By giving a target this attribute, you turn it into PMake's equivalent
2327 of a macro. When the target is used as a source for another target,
2328 the other target acquires the commands, sources and attributes (except
2331 If the target already has commands, the
2333 target's commands are added to the end. If more than one .USE-marked
2334 source is given to a target, the rules are applied sequentially.
2336 The typical .USE rule (as I call them) will use the sources of the
2337 target to which it is applied (as stored in the
2339 variable for the target) as its ``arguments,'' if you will.
2340 For example, you probably noticed that the commands for creating
2344 in the example in section 3.3
2346 were exactly the same. You can use the
2348 attribute to eliminate the repetition, like so:
2350 lib1.a : $(LIB1OBJS) MAKELIB
2351 lib2.a : $(LIB2OBJS) MAKELIB
2355 ar cr $(.TARGET) $(.ALLSRC)
2359 .Ix 0 ref variable local .TARGET
2360 .Ix 0 ref variable local .ALLSRC
2362 Several system makefiles (not to be confused with The System Makefile)
2363 make use of these .USE rules to make your
2364 life easier (they're in the default, system makefile directory...take a look).
2365 Note that the .USE rule source itself
2367 does not appear in any of the targets's local variables.
2368 There is no limit to the number of times I could use the
2370 rule. If there were more libraries, I could continue with
2371 .CW "lib3.a : $(LIB3OBJS) MAKELIB" '' ``
2372 and so on and so forth.
2373 .xH 2 Special Targets
2375 As there were in Make, so there are certain targets that have special
2376 meaning to PMake. When you use one on a dependency line, it is the
2377 only target that may appear on the left-hand-side of the operator.
2380 As for the attributes and variables, all the special targets
2381 begin with a period and consist of upper-case letters only.
2382 I won't describe them all in detail because some of them are rather
2383 complex and I'll describe them in more detail than you'll want in
2385 The targets are as follows:
2389 Any commands attached to this target are executed before anything else
2390 is done. You can use it for any initialization that needs doing.
2393 This is sort of a .USE rule for any target (that was used only as a
2394 source) that PMake can't figure out any other way to create. It's only
2395 ``sort of'' a .USE rule because only the shell script attached to the
2399 variable of a target that inherits
2401 commands is set to the target's own name.
2403 .Ix 0 ref variable local .IMPSRC
2406 This serves a function similar to
2408 in that commands attached to it are executed once everything has been
2409 re-created (so long as no errors occurred). It also serves the extra
2410 function of being a place on which PMake can hang commands you put off
2411 to the end. Thus the script for this target will be executed before
2412 any of the commands you save with the ``.\|.\|.''.
2415 The sources for this target are passed to the exportation system compiled
2416 into PMake. Some systems will use these sources to configure
2417 themselves. You should ask your system administrator about this.
2419 .Ix 0 def .IGNORE target
2420 .Ix 0 ref .IGNORE attribute
2421 .Ix 0 ref attributes .IGNORE
2422 This target marks each of its sources with the
2424 attribute. If you don't give it any sources, then it is like
2427 flag when you invoke PMake \*- errors are ignored for all commands.
2430 .Ix 0 def .INCLUDES target
2431 .Ix 0 def variable global .INCLUDES
2432 .Ix 0 def .INCLUDES variable
2433 The sources for this target are taken to be suffixes that indicate a
2434 file that can be included in a program source file.
2435 The suffix must have already been declared with
2438 Any suffix so marked will have the directories on its search path
2441 below) placed in the
2443 variable, each preceded by a
2445 flag. This variable can then be used as an argument for the compiler
2446 in the normal fashion. The
2448 suffix is already marked in this way in the system makefile.
2449 .Ix 0 ref makefile system
2452 \&.SUFFIXES : .bitmap
2453 \&.PATH.bitmap : /usr/local/X/lib/bitmaps
2454 \&.INCLUDES : .bitmap
2457 .CW "-I/usr/local/X/lib/bitmaps" '' ``
2460 variable and you can then say
2462 cc $(.INCLUDES) -c xprogram.c
2466 variable is not actually filled in until the entire makefile has been read.)
2467 .IP .INTERRUPT \n(pw
2468 .Ix 0 def .INTERRUPT
2469 When PMake is interrupted,
2470 it will execute the commands in the script for this target, if it
2473 .Ix 0 def .LIBS target
2474 .Ix 0 def .LIBS variable
2475 .Ix 0 def variable global .LIBS
2476 This does for libraries what
2478 does for include files, except the flag used is
2480 as required by those linkers that allow you to tell them where to find
2481 libraries. The variable used is
2483 Be forewarned that PMake may not have been compiled to do this if the
2484 linker on your system doesn't accept the
2488 variable will always be defined once the makefile has been read.
2491 If you didn't give a target (or targets) to create when you invoked
2492 PMake, it will take the sources of this target as the targets to
2494 .IP .MAKEFLAGS \n(pw
2495 .Ix 0 def .MAKEFLAGS target
2496 This target provides a way for you to always specify flags for PMake
2497 when the makefile is used. The flags are just as they would be typed
2498 to the shell (except you can't use shell variables unless they're in
2504 flags have no effect.
2507 .Ix 0 ref suffix null
2508 .Ix 0 ref "null suffix"
2509 This allows you to specify what suffix PMake should pretend a file has
2510 if, in fact, it has no known suffix. Only one suffix may be so
2511 designated. The last source on the dependency line is the suffix that
2512 is used (you should, however, only give one suffix.\|.\|.).
2515 If you give sources for this target, PMake will take them as
2516 directories in which to search for files it cannot find in the current
2517 directory. If you give no sources, it will clear out any directories
2518 added to the search path before. Since the effects of this all get
2519 very complex, I'll leave it til chapter four to give you a complete
2521 .IP .PATH\fIsuffix\fP \n(pw
2523 This does a similar thing to
2525 but it does it only for files with the given suffix. The suffix must
2526 have been defined already. Look at
2530 for more information.
2532 .Ix 0 def .PRECIOUS target
2533 .Ix 0 ref .PRECIOUS attribute
2534 .Ix 0 ref attributes .PRECIOUS
2539 attribute to each source on the dependency line, unless there are no
2540 sources, in which case the
2542 attribute is given to every target in the file.
2543 .IP .RECURSIVE \n(pw
2544 .Ix 0 def .RECURSIVE
2545 .Ix 0 ref attributes .MAKE
2547 This target applies the
2549 attribute to all its sources. It does nothing if you don't give it any sources.
2552 PMake is not constrained to only using the Bourne shell to execute
2553 the commands you put in the makefile. You can tell it some other shell
2554 to use with this target. Check out
2555 .B "A Shell is a Shell is a Shell"
2558 for more information.
2560 .Ix 0 def .SILENT target
2561 .Ix 0 ref .SILENT attribute
2562 .Ix 0 ref attributes .SILENT
2565 as a target, it applies the
2567 attribute to each of its sources. If there are no sources on the
2568 dependency line, then it is as if you gave PMake the
2570 flag and no commands will be echoed.
2573 This is used to give new file suffixes for PMake to handle. Each
2574 source is a suffix PMake should recognize. If you give a
2576 dependency line with no sources, PMake will forget about all the
2577 suffixes it knew (this also nukes the null suffix).
2578 For those targets that need to have suffixes defined, this is how you do it.
2580 In addition to these targets, a line of the form
2582 \fIattribute\fP : \fIsources\fP
2586 to all the targets listed as
2588 .xH 2 Modifying Variable Expansion
2590 .Ix 0 def variable expansion modified
2591 .Ix 0 ref variable expansion
2592 .Ix 0 def variable modifiers
2593 Variables need not always be expanded verbatim. PMake defines several
2594 modifiers that may be applied to a variable's value before it is
2595 expanded. You apply a modifier by placing it after the variable name
2596 with a colon between the two, like so:
2598 ${\fIVARIABLE\fP:\fImodifier\fP}
2600 Each modifier is a single character followed by something specific to
2601 the modifier itself.
2602 You may apply as many modifiers as you want \*- each one is applied to
2603 the result of the previous and is separated from the previous by
2606 There are seven ways to modify a variable's expansion, most of which
2607 come from the C shell variable modification characters:
2609 .IP "M\fIpattern\fP"
2611 .Ix 0 def modifier match
2612 This is used to select only those words (a word is a series of
2613 characters that are neither spaces nor tabs) that match the given
2615 The pattern is a wildcard pattern like that used by the shell, where
2617 means 0 or more characters of any sort;
2619 is any single character;
2621 matches any single character that is either `a', `b', `c' or `d'
2622 (there may be any number of characters between the brackets);
2624 matches any single character that is between `0' and `9' (i.e. any
2625 digit. This form may be freely mixed with the other bracket form), and
2626 `\\' is used to escape any of the characters `*', `?', `[' or `:',
2627 leaving them as regular characters to match themselves in a word.
2628 For example, the system makefile
2631 .CW "$(CFLAGS:M-[ID]*)" '' ``
2636 flags that would be passed to the C compiler. This allows it to
2637 properly locate include files and generate the correct dependencies.
2638 .IP "N\fIpattern\fP"
2640 .Ix 0 def modifier nomatch
2641 This is identical to
2643 except it substitutes all words that don't match the given pattern.
2644 .IP "S/\fIsearch-string\fP/\fIreplacement-string\fP/[g]"
2646 .Ix 0 def modifier substitute
2647 Causes the first occurrence of
2649 in the variable to be replaced by
2650 .I replacement-string ,
2653 flag is given at the end, in which case all occurrences of the string
2654 are replaced. The substitution is performed on each word in the
2655 variable in turn. If
2659 the string must match starting at the beginning of the word. If
2663 the string must match to the end of the word (these two may be
2664 combined to force an exact match). If a backslash precedes these two
2665 characters, however, they lose their special meaning. Variable
2666 expansion also occurs in the normal fashion inside both the
2669 .I replacement-string ,
2671 that a backslash is used to prevent the expansion of a
2673 not another dollar sign, as is usual.
2676 is just a string, not a pattern, so none of the usual
2677 regular-expression/wildcard characters have any special meaning save
2681 In the replacement string,
2684 character is replaced by the
2686 unless it is preceded by a backslash.
2687 You are allowed to use any character except
2688 colon or exclamation point to separate the two strings. This so-called
2689 delimiter character may be placed in either string by preceding it
2693 .Ix 0 def modifier tail
2694 Replaces each word in the variable expansion by its last
2695 component (its ``tail''). For example, given
2697 OBJS = ../lib/a.o b /usr/lib/libm.a
2703 .CW "a.o b libm.a" .'' ``
2706 .Ix 0 def modifier head
2709 except that every word is replaced by everything but the tail (the
2710 ``head''). Using the same definition of
2713 .CW "$(OBJS:H)" '' ``
2715 .CW "../lib /usr/lib" .'' ``
2716 Note that the final slash on the heads is removed and
2717 anything without a head is replaced by the empty string.
2720 .Ix 0 def modifier extension
2721 .Ix 0 def modifier suffix
2722 .Ix 0 ref suffix "variable modifier"
2724 replaces each word by its suffix (``extension''). So
2725 .CW "$(OBJS:E)" '' ``
2730 .Ix 0 def modifier root
2731 .Ix 0 def modifier base
2732 This replaces each word by everything but the suffix (the ``root'' of
2734 .CW "$(OBJS:R)" '' ``
2736 .CW "../lib/a b /usr/lib/libm" .''
2739 In addition, the System V style of substitution is also supported.
2742 $(\fIVARIABLE\fP:\fIsearch-string\fP=\fIreplacement\fP)
2744 It must be the last modifier in the chain. The search is anchored at
2745 the end of each word, so only suffixes or whole words may be replaced.
2746 .xH 2 More on Debugging
2747 .xH 2 More Exercises
2749 You've got a set programs, each of which is created from its own
2750 assembly-language source file (suffix
2752 Each program can be assembled into two versions, one with error-checking
2753 code assembled in and one without. You could assemble them into files
2754 with different suffixes
2758 for instance), but your linker only understands files that end in
2760 To top it all off, the final executables
2764 How can you still use transformation rules to make your life easier
2765 (Hint: assume the error-checking versions have
2767 tacked onto their prefix)?
2769 Assume, for a moment or two, you want to perform a sort of
2770 ``indirection'' by placing the name of a variable into another one,
2771 then you want to get the value of the first by expanding the second
2772 somehow. Unfortunately, PMake doesn't allow constructs like
2776 What do you do? Hint: no further variable expansion is performed after
2777 modifiers are applied, thus if you cause a $ to occur in the
2778 expansion, that's what will be in the result.
2779 .xH 1 PMake for Gods
2781 This chapter is devoted to those facilities in PMake that allow you to
2782 do a great deal in a makefile with very little work, as well as do
2783 some things you couldn't do in Make without a great deal of work (and
2784 perhaps the use of other programs). The problem with these features,
2785 is they must be handled with care, or you will end up with a mess.
2787 Once more, I assume a greater familiarity with
2789 or Sprite than I did in the previous two chapters.
2793 PMake supports the dispersal of files into multiple directories by
2794 allowing you to specify places to look for sources with
2796 targets in the makefile. The directories you give as sources for these
2797 targets make up a ``search path.'' Only those files used exclusively
2798 as sources are actually sought on a search path, the assumption being
2799 that anything listed as a target in the makefile can be created by the
2800 makefile and thus should be in the current directory.
2802 There are two types of search paths
2803 in PMake: one is used for all types of files (including included
2804 makefiles) and is specified with a plain
2807 .CW ".PATH : RCS" ''), ``
2808 while the other is specific to a certain type of file, as indicated by
2809 the file's suffix. A specific search path is indicated by immediately following
2812 with the suffix of the file. For instance
2814 \&.PATH.h : /sprite/lib/include /sprite/att/lib/include
2816 would tell PMake to look in the directories
2817 .CW /sprite/lib/include
2819 .CW /sprite/att/lib/include
2820 for any files whose suffix is
2823 The current directory is always consulted first to see if a file
2824 exists. Only if it cannot be found there are the directories in the
2825 specific search path, followed by those in the general search path,
2828 A search path is also used when expanding wildcard characters. If the
2829 pattern has a recognizable suffix on it, the path for that suffix will
2830 be used for the expansion. Otherwise the default search path is employed.
2832 When a file is found in some directory other than the current one, all
2833 local variables that would have contained the target's name
2837 will instead contain the path to the file, as found by PMake.
2838 Thus if you have a file
2844 $(CC) -o $(.TARGET) $(.ALLSRC)
2846 the command executed to create
2849 .CW "cc -o mumble ../lib/mumble.c" .'' ``
2850 (As an aside, the command in this case isn't strictly necessary, since
2851 it will be found using transformation rules if it isn't given. This is because
2853 is the null suffix by default and a transformation exists from
2857 Just thought I'd throw that in.)
2859 If a file exists in two directories on the same search path, the file
2860 in the first directory on the path will be the one PMake uses. So if
2861 you have a large system spread over many directories, it would behoove
2862 you to follow a naming convention that avoids such conflicts.
2864 Something you should know about the way search paths are implemented
2865 is that each directory is read, and its contents cached, exactly once
2866 \&\*- when it is first encountered \*- so any changes to the
2867 directories while PMake is running will not be noted when searching
2868 for implicit sources, nor will they be found when PMake attempts to
2869 discover when the file was last modified, unless the file was created in the
2870 current directory. While people have suggested that PMake should read
2871 the directories each time, my experience suggests that the caching seldom
2872 causes problems. In addition, not caching the directories slows things
2873 down enormously because of PMake's attempts to apply transformation
2874 rules through non-existent files \*- the number of extra file-system
2875 searches is truly staggering, especially if many files without
2876 suffixes are used and the null suffix isn't changed from
2878 .xH 2 Archives and Libraries
2881 and Sprite allow you to merge files into an archive using the
2883 command. Further, if the files are relocatable object files, you can
2886 on the archive and get yourself a library that you can link into any
2887 program you want. The main problem with archives is they double the
2888 space you need to store the archived files, since there's one copy in
2889 the archive and one copy out by itself. The problem with libraries is
2890 you usually think of them as
2894 and the linker thinks they're out-of-date if you so much as look at
2897 PMake solves the problem with archives by allowing you to tell it to
2898 examine the files in the archives (so you can remove the individual
2899 files without having to regenerate them later). To handle the problem
2900 with libraries, PMake adds an additional way of deciding if a library
2903 If the table of contents is older than the library, or is missing, the
2904 library is out-of-date.
2906 A library is any target that looks like
2908 or that ends in a suffix that was marked as a library using the
2912 is so marked in the system makefile.
2914 Members of an archive are specified as
2915 ``\fIarchive\fP(\fImember\fP[ \fImember\fP...])''.
2917 .CW libdix.a(window.o) '' ``'
2922 You may also use wildcards to specify the members of the archive. Just
2923 remember that most the wildcard characters will only find
2927 A file that is a member of an archive is treated specially. If the
2928 file doesn't exist, but it is in the archive, the modification time
2929 recorded in the archive is used for the file when determining if the
2930 file is out-of-date. When figuring out how to make an archived member target
2931 (not the file itself, but the file in the archive \*- the
2932 \fIarchive\fP(\fImember\fP) target), special care is
2933 taken with the transformation rules, as follows:
2935 \&\fIarchive\fP(\fImember\fP) is made to depend on \fImember\fP.
2937 The transformation from the \fImember\fP's suffix to the
2938 \fIarchive\fP's suffix is applied to the \fIarchive\fP(\fImember\fP) target.
2940 The \fIarchive\fP(\fImember\fP)'s
2942 variable is set to the name of the \fImember\fP if \fImember\fP is
2943 actually a target, or the path to the member file if \fImember\fP is
2948 variable for the \fIarchive\fP(\fImember\fP) target is set to the name
2949 of the \fIarchive\fP.
2950 .Ix 0 def variable local .ARCHIVE
2955 variable is set to the actual string inside the parentheses. In most
2956 cases, this will be the same as the
2959 .Ix 0 def variable local .MEMBER
2962 The \fIarchive\fP(\fImember\fP)'s place in the local variables of the
2963 targets that depend on it is taken by the value of its
2967 Thus, a program library could be created with the following makefile:
2972 OBJS = obj1.o obj2.o obj3.o
2973 libprog.a : libprog.a($(OBJS))
2974 ar cru $(.TARGET) $(.OODATE)
2977 This will cause the three object files to be compiled (if the
2978 corresponding source files were modified after the object file or, if
2979 that doesn't exist, the archived object file), the out-of-date ones
2982 a table of contents placed in the archive and the newly-archived
2983 object files to be removed.
2985 All this is used in the
2987 system makefile to create a single library with ease. This makefile
2992 # Rules for making libraries. The object files that make up the library
2993 # are removed once they are archived.
2995 # To make several libraries in parallel, you should define the variable
2996 # "many_libraries". This will serialize the invocations of ranlib.
2998 # To use, do something like this:
3000 # OBJECTS = <files in the library>
3002 # fish.a: fish.a($(OBJECTS)) MAKELIB
3018 # Re-archive the out-of-date members and recreate the library's table of
3019 # contents using ranlib. If many_libraries is defined, put the ranlib
3020 # off til the end so many libraries can be made at once.
3022 MAKELIB : .USE .PRECIOUS
3023 ar $(ARFLAGS) $(.TARGET) $(.OODATE)
3025 # ifdef many_libraries
3027 # endif /* many_libraries */
3029 #endif /* no_ranlib */
3031 #endif /* _MAKELIB_MK */
3033 .xH 2 On the Condition...
3036 Like the C compiler before it, PMake allows you to configure the makefile,
3037 based on the current environment, using conditional statements. A
3038 conditional looks like this:
3040 #if \fIboolean expression\fP
3042 #elif \fIanother boolean expression\fP
3045 \fIstill more lines\fP
3048 They may be nested to a maximum depth of 30 and may occur anywhere
3049 (except in a comment, of course). The
3051 must the very first character on the line.
3054 .I "boolean expression"
3055 is made up of terms that look like function calls, the standard C
3061 and the standard relational operators
3073 being overloaded to allow string comparisons as well.
3075 represents logical AND;
3079 is logical NOT. The arithmetic and string operators take precedence
3080 over all three of these operators, while NOT takes precedence over
3081 AND, which takes precedence over OR. This precedence may be
3082 overridden with parentheses, and an expression may be parenthesized to
3083 your heart's content. Each term looks like a call on one of four
3087 .Ix 0 def conditional make
3091 .CW make( \fItarget\fP\c
3095 is a target in the makefile. This is true if the given target was
3096 specified on the command line, or as the source for a
3098 target (note that the sources for
3100 are only used if no targets were given on the command line).
3103 .Ix 0 def conditional defined
3104 .Ix 0 def if defined
3106 .CW defined( \fIvariable\fP\c
3110 is defined. Certain variables are defined in the system makefile that
3111 identify the system on which PMake is being run.
3114 .Ix 0 def conditional exists
3117 .CW exists( \fIfile\fP\c
3119 and is true if the file can be found on the global search path
3120 (i.e. that defined by
3123 .CW .PATH \fIsuffix\fP
3127 .Ix 0 def conditional empty
3129 This syntax is much like the others, except the string inside the
3130 parentheses is of the same form as you would put between parentheses
3131 when expanding a variable, complete with modifiers and everything. The
3132 function returns true if the resulting string is empty (NOTE: an undefined
3133 variable in this context will cause at the very least a warning
3134 message about a malformed conditional, and at the worst will cause the
3135 process to stop once it has read the makefile. If you want to check
3136 for a variable being defined or empty, use the expression
3137 .CW !defined( \fIvar\fP\c ``
3138 .CW ") || empty(" \fIvar\fP\c
3140 as the definition of
3144 from being evaluated and causing an error, if the variable is
3145 undefined). This can be used to see if a variable contains a given
3148 #if !empty(\fIvar\fP:M\fIword\fP)
3151 The arithmetic and string operators may only be used to test the value
3152 of a variable. The lefthand side must contain the variable expansion,
3153 while the righthand side contains either a string, enclosed in
3154 double-quotes, or a number. The standard C numeric conventions (except
3155 for specifying an octal number) apply to both sides. E.g.
3159 #if $(MACHINE) == "sun3"
3161 #if $(LOAD_ADDR) < 0xc000
3163 are all valid conditionals. In addition, the numeric value of a
3164 variable can be tested as a boolean as follows:
3170 contains a non-zero value and
3176 contains a zero value.
3178 In addition to the bare
3180 there are other forms that apply one of the first two functions to each
3181 term. They are as follows:
3184 ifndef \fR!defined\fP
3188 There are also the ``else if'' forms:
3196 For instance, if you wish to create two versions of a program, one of which
3197 is optimized (the production version) and the other of which is for debugging
3198 (has symbols for dbx), you have two choices: you can create two
3199 makefiles, one of which uses the
3201 flag for the compilation, while the other uses the
3203 flag, or you can use another target (call it
3205 to create the debug version. The construct below will take care of
3206 this for you. I have also made it so defining the variable
3209 .CW "pmake -D DEBUG" )
3210 will also cause the debug version to be made.
3212 #if defined(DEBUG) || make(debug)
3218 There are, of course, problems with this approach. The most glaring
3219 annoyance is that if you want to go from making a debug version to
3220 making a production version, you have to remove all the object files,
3221 or you will get some optimized and some debug versions in the same
3222 program. Another annoyance is you have to be careful not to make two
3223 targets that ``conflict'' because of some conditionals in the
3224 makefile. For instance
3227 FORMATTER = ditroff -Plaser_printer
3230 FORMATTER = nroff -Pdot_matrix_printer
3233 would wreak havoc if you tried
3234 .CW "pmake draft print" '' ``
3235 since you would use the same formatter for each target. As I said,
3236 this all gets somewhat complicated.
3237 .xH 2 A Shell is a Shell is a Shell
3240 In normal operation, the Bourne Shell (better known as
3242 is used to execute the commands to re-create targets. PMake also allows you
3243 to specify a different shell for it to use when executing these
3244 commands. There are several things PMake must know about the shell you
3245 wish to use. These things are specified as the sources for the
3248 .Ix 0 ref target .SHELL
3249 target by keyword, as follows:
3250 .IP "\fBpath=\fP\fIpath\fP"
3251 PMake needs to know where the shell actually resides, so it can
3252 execute it. If you specify this and nothing else, PMake will use the
3253 last component of the path and look in its table of the shells it
3254 knows and use the specification it finds, if any. Use this if you just
3255 want to use a different version of the Bourne or C Shell (yes, PMake knows
3256 how to use the C Shell too).
3257 .IP "\fBname=\fP\fIname\fP"
3258 This is the name by which the shell is to be known. It is a single
3259 word and, if no other keywords are specified (other than
3261 it is the name by which PMake attempts to find a specification for
3262 it (as mentioned above). You can use this if you would just rather use
3263 the C Shell than the Bourne Shell
3264 .CW ".SHELL: name=csh" '' (``
3266 .IP "\fBquiet=\fP\fIecho-off command\fP"
3267 As mentioned before, PMake actually controls whether commands are
3268 printed by introducing commands into the shell's input stream. This
3269 keyword, and the next two, control what those commands are. The
3271 keyword is the command used to turn echoing off. Once it is turned
3272 off, echoing is expected to remain off until the echo-on command is given.
3273 .IP "\fBecho=\fP\fIecho-on command\fP"
3274 The command PMake should give to turn echoing back on again.
3275 .IP "\fBfilter=\fP\fIprinted echo-off command\fP"
3276 Many shells will echo the echo-off command when it is given. This
3277 keyword tells PMake in what format the shell actually prints the
3278 echo-off command. Wherever PMake sees this string in the shell's
3279 output, it will delete it and any following whitespace, up to and
3280 including the next newline. See the example at the end of this section
3282 .IP "\fBechoFlag=\fP\fIflag to turn echoing on\fP"
3283 Unless a target has been marked
3285 PMake wants to start the shell running with echoing on. To do this, it
3286 passes this flag to the shell as one of its arguments. If either this
3287 or the next flag begins with a `\-', the flags will be passed to the
3288 shell as separate arguments. Otherwise, the two will be concatenated
3289 (if they are used at the same time, of course).
3290 .IP "\fBerrFlag=\fP\fIflag to turn error checking on\fP"
3291 Likewise, unless a target is marked
3293 PMake wishes error-checking to be on from the very start. To this end,
3294 it will pass this flag to the shell as an argument. The same rules for
3295 an initial `\-' apply as for the
3297 .IP "\fBcheck=\fP\fIcommand to turn error checking on\fP"
3298 Just as for echo-control, error-control is achieved by inserting
3299 commands into the shell's input stream. This is the command to make
3300 the shell check for errors. It also serves another purpose if the
3301 shell doesn't have error-control as commands, but I'll get into that
3302 in a minute. Again, once error checking has been turned on, it is
3303 expected to remain on until it is turned off again.
3304 .IP "\fBignore=\fP\fIcommand to turn error checking off\fP"
3305 This is the command PMake uses to turn error checking off. It has
3306 another use if the shell doesn't do error-control, but I'll tell you
3307 about that.\|.\|.\|now.
3308 .IP "\fBhasErrCtl=\fP\fIyes or no\fP"
3309 This takes a value that is either
3313 Now you might think that the existence of the
3317 keywords would be enough to tell PMake if the shell can do
3318 error-control, but you'd be wrong. If
3322 PMake uses the check and ignore commands in a straight-forward manner.
3325 however, their use is rather different. In this case, the check
3326 command is used as a template, in which the string
3328 is replaced by the command that's about to be executed, to produce a
3329 command for the shell that will echo the command to be executed. The
3330 ignore command is also used as a template, again with
3332 replaced by the command to be executed, to produce a command that will
3333 execute the command to be executed and ignore any error it returns.
3334 When these strings are used as templates, you must provide newline(s)
3336 in the appropriate place(s).
3338 The strings that follow these keywords may be enclosed in single or
3339 double quotes (the quotes will be stripped off) and may contain the
3340 usual C backslash-characters (\en is newline, \er is return, \eb is
3341 backspace, \e' escapes a single-quote inside single-quotes, \e"
3342 escapes a double-quote inside double-quotes). Now for an example.
3344 This is actually the contents of the
3346 system makefile, and causes PMake to use the Bourne Shell in such a
3347 way that each command is printed as it is executed. That is, if more
3348 than one command is given on a line, each will be printed separately.
3349 Similarly, each time the body of a loop is executed, the commands
3350 within that loop will be printed, etc. The specification runs like
3354 # This is a shell specification to have the Bourne shell echo
3355 # the commands just before executing them, rather than when it reads
3356 # them. Useful if you want to see how variables are being expanded, etc.
3358 \&.SHELL : path=/bin/sh \e
3361 filter="+ set - " \e
3369 It tells PMake the following:
3371 The shell is located in the file
3373 It need not tell PMake that the name of the shell is
3375 as PMake can figure that out for itself (it's the last component of
3378 The command to stop echoing is
3381 The command to start echoing is
3384 When the echo off command is executed, the shell will print
3386 (The `+' comes from using the
3388 flag (rather than the
3390 flag PMake usually uses)). PMake will remove all occurrences of this
3391 string from the output, so you don't notice extra commands you didn't
3394 The flag the Bourne Shell will take to start echoing in this way is
3397 flag. The Bourne Shell will only take its flag arguments concatenated
3398 as its first argument, so neither this nor the
3400 specification begins with a \-.
3402 The flag to use to turn error-checking on from the start is
3405 The shell can turn error-checking on and off, and the commands to do
3412 I should note that this specification is for Bourne Shells that are
3413 not part of Berkeley
3415 as shells from Berkeley don't do error control. You can get a similar
3416 effect, however, by changing the last three lines to be:
3419 check="echo \e"+ %s\e"\en" \e
3420 ignore="sh -c '%s || exit 0\en"
3423 This will cause PMake to execute the two commands
3426 sh -c '\fIcmd\fP || true'
3428 for each command for which errors are to be ignored. (In case you are
3429 wondering, the thing for
3431 tells the shell to execute another shell without error checking on and
3432 always exit 0, since the
3436 to be executed only if the first command exited non-zero, and if the
3437 first command exited zero, the shell will also exit zero, since that's
3438 the last command it executed).
3440 .Ix 0 ref compatibility
3442 There are three (well, 3 \(12) levels of backwards-compatibility built
3443 into PMake. Most makefiles will need none at all. Some may need a
3444 little bit of work to operate correctly when run in parallel. Each
3445 level encompasses the previous levels (e.g.
3447 (one shell per command) implies
3449 The three levels are described in the following three sections.
3450 .xH 3 DEFCON 3 \*- Variable Expansion
3451 .Ix 0 ref compatibility
3453 As noted before, PMake will not expand a variable unless it knows of a
3454 value for it. This can cause problems for makefiles that expect to
3455 leave variables undefined except in special circumstances (e.g. if
3456 more flags need to be passed to the C compiler or the output from a
3457 text processor should be sent to a different printer). If the
3458 variables are enclosed in curly braces
3459 .CW ${PRINTER} ''), (``
3460 the shell will let them pass. If they are enclosed in parentheses,
3461 however, the shell will declare a syntax error and the make will come
3464 You have two choices: change the makefile to define the variables
3465 (their values can be overridden on the command line, since that's
3466 where they would have been set if you used Make, anyway) or always give the
3468 flag (this can be done with the
3470 target, if you want).
3471 .xH 3 DEFCON 2 \*- The Number of the Beast
3472 .Ix 0 ref compatibility
3474 Then there are the makefiles that expect certain commands, such as
3475 changing to a different directory, to not affect other commands in a
3476 target's creation script. You can solve this is either by going
3477 back to executing one shell per command (which is what the
3479 flag forces PMake to do), which slows the process down a good bit and
3480 requires you to use semicolons and escaped newlines for shell constructs, or
3481 by changing the makefile to execute the offending command(s) in a subshell
3482 (by placing the line inside parentheses), like so:
3485 (cd src; $(.PMAKE) install)
3486 (cd lib; $(.PMAKE) install)
3487 (cd man; $(.PMAKE) install)
3489 .Ix 0 ref operator double-colon
3490 .Ix 0 ref variable global .PMAKE
3493 .Ix 0 ref attribute .MAKE
3494 This will always execute the three makes (even if the
3496 flag was given) because of the combination of the ``::'' operator and
3499 attribute. Each command will change to the proper directory to perform
3500 the install, leaving the main shell in the directory in which it started.
3501 .xH 3 "DEFCON 1 \*- Imitation is the Not the Highest Form of Flattery"
3502 .Ix 0 ref compatibility
3504 The final category of makefile is the one where every command requires
3505 input, the dependencies are incompletely specified, or you simply
3506 cannot create more than one target at a time, as mentioned earlier. In
3507 addition, you may not have the time or desire to upgrade the makefile
3508 to run smoothly with PMake. If you are the conservative sort, this is
3509 the compatibility mode for you. It is entered either by giving PMake
3512 flag (for Make), or by executing PMake as
3514 In either case, PMake performs things exactly like Make (while still
3515 supporting most of the nice new features PMake provides). This
3518 No parallel execution.
3520 Targets are made in the exact order specified by the makefile. The
3521 sources for each target are made in strict left-to-right order, etc.
3523 A single Bourne shell is used to execute each command, thus the
3526 variable is useless, changing directories doesn't work across command
3529 If no special characters exist in a command line, PMake will break the
3530 command into words itself and execute the command directly, without
3531 executing a shell first. The characters that cause PMake to execute a
3554 You should notice that these are all the characters that are given
3555 special meaning by the shell (except
3559 which PMake deals with all by its lonesome).
3561 The use of the null suffix is turned off.
3562 .Ix 0 ref "null suffix"
3563 .Ix 0 ref suffix null
3564 .xH 2 The Way Things Work
3566 When PMake reads the makefile, it parses sources and targets into
3567 nodes in a graph. The graph is directed only in the sense that PMake
3568 knows which way is up. Each node contains not only links to all its
3569 parents and children (the nodes that depend on it and those on which
3570 it depends, respectively), but also a count of the number of its
3571 children that have already been processed.
3573 The most important thing to know about how PMake uses this graph is
3574 that the traversal is breadth-first and occurs in two passes.
3576 After PMake has parsed the makefile, it begins with the nodes the user
3577 has told it to make (either on the command line, or via a
3579 target, or by the target being the first in the file not labeled with
3582 attribute) placed in a queue. It continues to take the node off the
3583 front of the queue, mark it as something that needs to be made, pass
3586 (mentioned earlier) to find any implicit sources for the node, and
3587 place all the node's children that have yet to be marked at the end of
3588 the queue. If any of the children is a
3590 rule, its attributes are applied to the parent, then its commands are
3591 appended to the parent's list of commands and its children are linked
3592 to its parent. The parent's unmade children counter is then decremented
3595 node has been processed). You will note that this allows a
3597 node to have children that are
3599 nodes and the rules will be applied in sequence.
3600 If the node has no children, it is placed at the end of
3601 another queue to be examined in the second pass. This process
3602 continues until the first queue is empty.
3604 At this point, all the leaves of the graph are in the examination
3605 queue. PMake removes the node at the head of the queue and sees if it
3606 is out-of-date. If it is, it is passed to a function that will execute
3607 the commands for the node asynchronously. When the commands have
3608 completed, all the node's parents have their unmade children counter
3609 decremented and, if the counter is then 0, they are placed on the
3610 examination queue. Likewise, if the node is up-to-date. Only those
3611 parents that were marked on the downward pass are processed in this
3612 way. Thus PMake traverses the graph back up to the nodes the user
3613 instructed it to create. When the examination queue is empty and no
3614 shells are running to create a target, PMake is finished.
3616 Once all targets have been processed, PMake executes the commands
3619 target, either explicitly or through the use of an ellipsis in a shell
3620 script. If there were no errors during the entire process but there
3621 are still some targets unmade (PMake keeps a running count of how many
3622 targets are left to be made), there is a cycle in the graph. PMake does
3623 a depth-first traversal of the graph to find all the targets that
3624 weren't made and prints them out one by one.
3625 .xH 1 Answers to Exercises
3627 This is something of a trick question, for which I apologize. The
3628 trick comes from the UNIX definition of a suffix, which PMake doesn't
3629 necessarily share. You will have noticed that all the suffixes used in
3630 this tutorial (and in UNIX in general) begin with a period
3633 etc.). Now, PMake's idea of a suffix is more like English's: it's the
3634 characters at the end of a word. With this in mind, one possible
3636 solution to this problem goes as follows:
3638 \&.SUFFIXES : ec.exe .exe ec.obj .obj .asm
3639 ec.objec.exe .obj.exe :
3640 link -o $(.TARGET) $(.IMPSRC)
3642 asm -o $(.TARGET) -DDO_ERROR_CHECKING $(.IMPSRC)
3644 asm -o $(.TARGET) $(.IMPSRC)
3647 The trick to this one lies in the ``:='' variable-assignment operator
3648 and the ``:S'' variable-expansion modifier.
3649 .Ix 0 ref variable assignment expanded
3650 .Ix 0 ref variable expansion modified
3651 .Ix 0 ref modifier substitute
3654 Basically what you want is to take the pointer variable, so to speak,
3655 and transform it into an invocation of the variable at which it
3656 points. You might try something like
3658 $(PTR:S/^/\e$(/:S/$/))
3662 at the front of the variable name and
3664 at the end, thus transforming
3668 which is just what we want. Unfortunately (as you know if you've tried
3669 it), since, as it says in the hint, PMake does no further substitution
3670 on the result of a modified expansion, that's \fIall\fP you get. The
3671 solution is to make use of ``:='' to place that string into yet
3672 another variable, then invoke the other variable directly:
3674 *PTR := $(PTR:S/^/\e$(/:S/$/)/)
3678 to your heart's content.
3683 .xH 1 Glossary of Jargon
3685 A property given to a target that causes PMake to treat it differently.
3686 .Gp "command script"
3687 The lines immediately following a dependency line that specify
3688 commands to execute to create each of the targets on the dependency
3689 line. Each line in the command script must begin with a tab.
3690 .Gp "command-line variable"
3691 A variable defined in an argument when PMake is first executed.
3692 Overrides all assignments to the same variable name in the makefile.
3694 A construct much like that used in C that allows a makefile to be
3695 configured on the fly based on the local environment, or on what is being
3696 made by that invocation of PMake.
3697 .Gp "creation script"
3698 Commands used to create a target. See ``command script.''
3700 The relationship between a source and a target. This comes in three
3701 flavors, as indicated by the operator between the target and the
3702 source. `:' gives a straight time-wise dependency (if the target is
3703 older than the source, the target is out-of-date), while `!' provides
3704 simply an ordering and always considers the target out-of-date. `::'
3705 is much like `:', save it creates multiple instances of a target each
3706 of which depends on its own list of sources.
3707 .Gp "dynamic source"
3708 This refers to a source that has a local variable invocation in it. It
3709 allows a single dependency line to specify a different source for each
3711 .Gp "global variable"
3712 Any variable defined in a makefile. Takes precedence over variables
3713 defined in the environment, but not over command-line or local variables.
3715 What PMake constructs from a makefile. Consists of nodes made of the
3716 targets in the makefile, and the links between them (the
3717 dependencies). The links are directed (from source to target) and
3718 there may not be any cycles (loops) in the graph.
3719 .Gp "local variable"
3720 A variable defined by PMake visible only in a target's shell script.
3721 There are seven local variables, not all of which are defined for
3736 may be used on dependency lines to create ``dynamic sources.''
3738 A file that describes how a system is built. If you don't know what it
3739 is after reading this tutorial.\|.\|.\|.
3741 A letter, following a colon, used to alter how a variable is expanded.
3742 It has no effect on the variable itself.
3744 What separates a source from a target (on a dependency line) and specifies
3745 the relationship between the two. There are three:
3751 A list of directories in which a file should be sought. PMake's view
3752 of the contents of directories in a search path does not change once
3753 the makefile has been read. A file is sought on a search path only if
3754 it is exclusively a source.
3756 A program to which commands are passed in order to create targets.
3758 Anything to the right of an operator on a dependency line. Targets on
3759 the dependency line are usually created from the sources.
3760 .Gp "special target"
3761 A target that causes PMake to do special things when it's encountered.
3763 The tail end of a file name. Usually begins with a period,
3769 A word to the left of the operator on a dependency line. More
3770 generally, any file that PMake might create. A file may be (and often
3771 is) both a target and a source (what it is depends on how PMake is
3772 looking at it at the time \*- sort of like the wave/particle duality
3773 of light, you know).
3774 .Gp "transformation rule"
3775 A special construct in a makefile that specifies how to create a file
3776 of one type from a file of another, as indicated by their suffixes.
3777 .Gp "variable expansion"
3778 The process of substituting the value of a variable for a reference to
3779 it. Expansion may be altered by means of modifiers.
3781 A place in which to store text that may be retrieved later. Also used
3782 to define the local environment. Conditionals exist that test whether
3783 a variable is defined or not.
3785 .\" Output table of contents last, with an entry for the index, making
3786 .\" sure to save and restore the last real page number for the index...
3788 .\" We are not generating an index
projects / FreeBSD / stable / 10.git / blob