Spelling corrections.
[dragonfly.git] / usr.bin / make / PSD.doc / tutorial.ms
1 .\" Copyright (c) 1988, 1989 by Adam de Boor
2 .\" Copyright (c) 1989 by Berkeley Softworks
3 .\" Copyright (c) 1988, 1989, 1993
4 .\"     The Regents of the University of California.  All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" Adam de Boor.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\"    notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\"    notice, this list of conditions and the following disclaimer in the
16 .\"    documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\"    must display the following acknowledgement:
19 .\"     This product includes software developed by the University of
20 .\"     California, Berkeley and its contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\"    may be used to endorse or promote products derived from this software
23 .\"    without specific prior written permission.
24 .\"
36 .\"
37 .\"     @(#)tutorial.ms 8.1 (Berkeley) 8/18/93
38 .\" $FreeBSD: src/usr.bin/make/PSD.doc/tutorial.ms,v 2000/11/24 10:08:45 ru Exp $
39 .\" $DragonFly: src/usr.bin/make/PSD.doc/tutorial.ms,v 1.3 2004/11/13 22:42:43 dillon Exp $
40 .\"
41 .so stubs
42 .EH 'PSD:12-%''PMake \*- A Tutorial'
43 .OH 'PMake \*- A Tutorial''PSD:12-%'
44 .\" xH is a macro to provide numbered headers that are automatically stuffed
45 .\" into a table-of-contents, properly indented, etc. If the first argument
46 .\" is numeric, it is taken as the depth for numbering (as for .NH), else
47 .\" the default (1) is assumed.
48 .\"
49 .\" @P The initial paragraph distance.
50 .\" @Q The piece of section number to increment (or 0 if none given)
51 .\" @R Section header.
52 .\" @S Indent for toc entry
53 .\" @T Argument to NH (can't use @Q b/c giving 0 to NH resets the counter)
54 .de xH
55 .NH \\$1
56 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
57 .nr PD .1v
58 .XS \\n%
59 .ta 0.6i
60 \\*(SN  \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
61 .XE
62 .nr PD .3v
63 ..
64 .ig
65 .\" CW is used to place a string in fixed-width or switch to a
66 .\" fixed-width font.
67 .\" C is a typewriter font for a laserwriter. Use something else if
68 .\" you don't have one...
69 .de CW
70 .ie !\\n(.$ .ft S
71 .el \&\\$3\fS\\$1\fP\\$2
72 ..
73 .\" Anything I put in a display I want to be in fixed-width
74 .am DS
75 .CW
76 ..
77 .\" The stuff in .No produces a little stop sign in the left margin
78 .\" that says NOTE in it. Unfortunately, it does cause a break, but
79 .\" hey. Can't have everything. In case you're wondering how I came
80 .\" up with such weird commands, they came from running grn on a
81 .\" gremlin file...
82 .de No
83 .br
84 .ne 0.5i
85 .po -0.5i
86 .br
87 .mk 
88 .nr g3 \\n(.f
89 .nr g4 \\n(.s
90 .ig ft
91 .sp -1
92 .\" .st cf
93 \D's -1u'\D't 5u'
94 .sp -1
95 \h'50u'\D'l 71u 0u'\D'l 50u 50u'\D'l 0u 71u'\D'l -50u 50u'\D'l -71u 0u'\D'l -50u -50u'\D'l 0u -71u'\D'l 50u -50u'
96 .sp -1
97 \D't 3u'
98 .sp -1
99 .sp 7u
100 \h'53u'\D'p 14 68u 0u 46u 46u 0u 68u -46u 46u -68u 0u -47u -46u 0u -68u 47u -46u'
101 .sp -1
102 .ft R
103 .ps 6
104 .nr g8 \\n(.d
105 .ds g9 "NOTE
106 .sp 74u
107 \h'85u'\v'0.85n'\h\a-\w\a\\*(g9\au/2u\a\&\\*(g9
108 .sp |\\n(g8u
109 .sp 166u
110 .ig br
111 \D't 3u'\D's -1u'
112 .br
113 .po
114 .rt 
115 .ft \\n(g3
116 .ps \\n(g4
117 ..
118 .de Bp
119 .ie !\\n(.$ .IP \(bu 2
120 .el .IP "\&" 2
121 ..
122 .po +.3i
123 .TL
124 PMake \*- A Tutorial
125 .AU
126 Adam de Boor
127 .AI
128 Berkeley Softworks
129 2150 Shattuck Ave, Penthouse
130 Berkeley, CA 94704
131 adam@bsw.uu.net
132 \&...!uunet!bsw!adam
133 .FS
134 Permission to use, copy, modify, and distribute this software and its
135 documentation for any purpose and without fee is hereby granted,
136 provided that the above copyright notice appears in all copies.
137 The University of California, Berkeley Softworks, and Adam de Boor make no
138 representations about the suitability of this software for any
139 purpose.  It is provided "as is" without express or implied warranty.
140 .FE
141 .PP
142 .xH 1 Introduction
143 .LP
144 PMake is a program for creating other programs, or anything else you
145 can think of for it to do.  The basic idea behind PMake is that, for
146 any given system, be it a program or a document or whatever, there
147 will be some files that depend on the state of other files (on when
148 they were last modified). PMake takes these dependencies, which you
149 must specify, and uses them to build whatever it is you want it to
150 build.
151 .LP
152 PMake is almost fully-compatible with Make, with which you may already
153 be familiar. PMake's most important feature is its ability to run
154 several different jobs at once, making the creation of systems
155 considerably faster. It also has a great deal more functionality than
156 Make. Throughout the text, whenever something is mentioned that is an
157 important difference between PMake and Make (i.e.  something that will
158 cause a makefile to fail if you don't do something about it), or is
159 simply important, it will be flagged with a little sign in the left
160 margin, like this:
161 .No
162 .LP
163 This tutorial is divided into three main sections corresponding to basic,
164 intermediate and advanced PMake usage. If you already know Make well,
165 you will only need to skim chapter 2 (there are some aspects of
166 PMake that I consider basic to its use that didn't exist in Make).
167 Things in chapter 3 make life much easier, while those in chapter 4
168 are strictly for those who know what they are doing. Chapter 5 has
169 definitions for the jargon I use and chapter 6 contains possible
170 solutions to the problems presented throughout the tutorial.
171 .xH 1 The Basics of PMake
172 .LP
173 PMake takes as input a file that tells a) which files depend on which
174 other files to be complete and b) what to do about files that are
175 ``out-of-date.'' This file is known as a ``makefile'' and is usually
176 .Ix 0 def makefile
177 kept in the top-most directory of the system to be built. While you
178 can call the makefile anything you want, PMake will look for
179 .CW Makefile
180 and
181 .CW makefile
182 (in that order) in the current directory if you don't tell it
183 otherwise.
184 .Ix 0 def makefile default
185 To specify a different makefile, use the
186 .B \-f
187 flag (e.g.
188 .CW "pmake -f program.mk" ''). ``
189 .Ix 0 ref flags -f
190 .Ix 0 ref makefile other
191 .LP
192 A makefile has four different types of lines in it:
193 .RS
194 .IP \(bu 2
195 File dependency specifications
196 .IP \(bu 2
197 Creation commands
198 .IP \(bu 2
199 Variable assignments
200 .IP \(bu 2
201 Comments, include statements and conditional directives
202 .RE
203 .LP
204 Any line may be continued over multiple lines by ending it with a
205 backslash.
206 .Ix 0 def "continuation line"
207 The backslash, following newline and any initial whitespace
208 on the following line are compressed into a single space before the
209 input line is examined by PMake.
210 .xH 2 Dependency Lines
211 .LP
212 As mentioned in the introduction, in any system, there are
213 dependencies between the files that make up the system.  For instance,
214 in a program made up of several C source files and one header file,
215 the C files will need to be re-compiled should the header file be
216 changed. For a document of several chapters and one macro file, the
217 chapters will need to be reprocessed if any of the macros changes.
218 .Ix 0 def "dependency"
219 These are dependencies and are specified by means of dependency lines in
220 the makefile.
221 .LP
222 .Ix 0 def "dependency line"
223 On a dependency line, there are targets and sources, separated by a
224 one- or two-character operator.
225 The targets ``depend'' on the sources and are usually created from
226 them.
227 .Ix 0 def target
228 .Ix 0 def source
229 .Ix 0 ref operator
230 Any number of targets and sources may be specified on a dependency line.
231 All the targets in the line are made to depend on all the sources.
232 Targets and sources need not be actual files, but every source must be
233 either an actual file or another target in the makefile.
234 If you run out of room, use a backslash at the end of the line to continue onto
235 the next one.
236 .LP
237 Any file may be a target and any file may be a source, but the
238 relationship between the two (or however many) is determined by the
239 ``operator'' that separates them.
240 .Ix 0 def operator
241 Three types of operators exist: one specifies that the datedness of a
242 target is determined by the state of its sources, while another
243 specifies other files (the sources) that need to be dealt with before
244 the target can be re-created. The third operator is very similar to
245 the first, with the additional condition that the target is
246 out-of-date if it has no sources. These operations are represented by
247 the colon, the exclamation point and the double-colon, respectively, and are
248 mutually exclusive. Their exact semantics are as follows:
249 .IP ":"
250 .Ix 0 def operator colon
251 .Ix 0 def :
252 If a colon is used, a target on the line is considered to be
253 ``out-of-date'' (and in need of creation) if 
254 .RS
255 .IP \(bu 2
256 any of the sources has been modified more recently than the target, or
257 .IP \(bu 2
258 the target doesn't exist.
259 .RE
260 .Ix 0 def out-of-date
261 .IP "\&"
262 Under this operation, steps will be taken to re-create the target only
263 if it is found to be out-of-date by using these two rules.
264 .IP "!"
265 .Ix 0 def operator force
266 .Ix 0 def !
267 If an exclamation point is used, the target will always be re-created,
268 but this will not happen until all of its sources have been examined
269 and re-created, if necessary.
270 .IP "::"
271 .Ix 0 def operator double-colon
272 .Ix 0 def ::
273 If a double-colon is used, a target is out-of-date if:
274 .RS
275 .IP \(bu 2
276 any of the sources has been modified more recently than the target, or
277 .IP \(bu 2
278 the target doesn't exist, or
279 .IP \(bu 2
280 the target has no sources.
281 .RE
282 .IP "\&"
283 If the target is out-of-date according to these rules, it will be re-created.
284 This operator also does something else to the targets, but I'll go
285 into that in the next section (``Shell Commands'').
286 .LP
287 Enough words, now for an example. Take that C program I mentioned
288 earlier. Say there are three C files
289 .CW a.c , (
290 .CW b.c
291 and
292 .CW  c.c )
293 each of which
294 includes the file
295 .CW defs.h .
296 The dependencies between the files could then be expressed as follows:
297 .DS
298 program         : a.o b.o c.o
299 a.o b.o c.o     : defs.h
300 a.o             : a.c
301 b.o             : b.c
302 c.o             : c.c
303 .DE
304 .LP
305 You may be wondering at this point, where
306 .CW a.o ,
307 .CW b.o
308 and
309 .CW c.o
310 came in and why
311 .I they
312 depend on
313 .CW defs.h
314 and the C files don't. The reason is quite simple:
315 .CW program
316 cannot be made by linking together .c files \*- it must be
317 made from .o files. Likewise, if you change
318 .CW defs.h ,
319 it isn't the .c files that need to be re-created, it's the .o files.
320 If you think of dependencies in these terms \*- which files (targets)
321 need to be created from which files (sources) \*- you should have no problems.
322 .LP
323 An important thing to notice about the above example, is that all the
324 \&.o files appear as targets on more than one line. This is perfectly
325 all right: the target is made to depend on all the sources mentioned
326 on all the dependency lines. E.g.
327 .CW a.o
328 depends on both
329 .CW defs.h
330 and
331 .CW a.c .
332 .Ix 0 ref dependency
333 .No
334 .LP
335 The order of the dependency lines in the makefile is
336 important: the first target on the first dependency line in the
337 makefile will be the one that gets made if you don't say otherwise.
338 That's why
339 .CW program
340 comes first in the example makefile, above.
341 .LP
342 Both targets and sources may contain the standard C-Shell wildcard
343 characters
344 .CW { , (
345 .CW } ,
346 .CW * ,
347 .CW ? ,
348 .CW [ ,
349 and
350 .CW ] ),
351 but the non-curly-brace ones may only appear in the final component
352 (the file portion) of the target or source. The characters mean the
353 following things:
354 .IP \fB{}\fP
355 These enclose a comma-separated list of options and cause the pattern
356 to be expanded once for each element of the list. Each expansion
357 contains a different element. For example, 
358 .CW src/{whiffle,beep,fish}.c
359 expands to the three words
360 .CW src/whiffle.c ,
361 .CW src/beep.c ,
362 and 
363 .CW src/fish.c .
364 These braces may be nested and, unlike the other wildcard characters,
365 the resulting words need not be actual files. All other wildcard
366 characters are expanded using the files that exist when PMake is
367 started.
368 .IP \fB*\fP
369 This matches zero or more characters of any sort. 
370 .CW src/*.c
371 will expand to the same three words as above as long as 
372 .CW src
373 contains those three files (and no other files that end in 
374 .CW .c ).
375 .IP \fB?\fP
376 Matches any single character.
377 .IP \fB[]\fP
378 This is known as a character class and contains either a list of
379 single characters, or a series of character ranges 
380 .CW a-z , (
381 for example means all characters between a and z), or both. It matches
382 any single character contained in the list. E.g.
383 .CW [A-Za-z]
384 will match all letters, while
385 .CW [0123456789]
386 will match all numbers.
387 .xH 2 Shell Commands
388 .LP
389 ``Isn't that nice,'' you say to yourself, ``but how are files
390 actually `re-created,' as he likes to spell it?''
391 The re-creation is accomplished by commands you place in the makefile.
392 These commands are passed to the Bourne shell (better known as
393 ``/bin/sh'') to be executed and are
394 .Ix 0 ref shell
395 .Ix 0 ref re-creation
396 .Ix 0 ref update
397 expected to do what's necessary to update the target file (PMake
398 doesn't actually check to see if the target was created. It just
399 assumes it's there).
400 .Ix 0 ref target
401 .LP
402 Shell commands in a makefile look a lot like shell commands you would
403 type at a terminal, with one important exception: each command in a
404 makefile
405 .I must
406 be preceded by at least one tab.
407 .LP
408 Each target has associated with it a shell script made up of
409 one or more of these shell commands. The creation script for a target
410 should immediately follow the dependency line for that target. While
411 any given target may appear on more than one dependency line, only one
412 of these dependency lines may be followed by a creation script, unless
413 the `::' operator was used on the dependency line.
414 .Ix 0 ref operator double-colon
415 .Ix 0 ref ::
416 .No
417 .LP
418 If the double-colon was used, each dependency line for the target
419 may be followed by a shell script. That script will only be executed
420 if the target on the associated dependency line is out-of-date with
421 respect to the sources on that line, according to the rules I gave
422 earlier.
423 I'll give you a good example of this later on.
424 .LP
425 To expand on the earlier makefile, you might add commands as follows:
426 .DS
427 program         : a.o b.o c.o
428         cc a.o b.o c.o \-o program
429 a.o b.o c.o     : defs.h
430 a.o             : a.c
431         cc \-c a.c
432 b.o             : b.c
433         cc \-c b.c
434 c.o             : c.c
435         cc \-c c.c
436 .DE
437 .LP
438 Something you should remember when writing a makefile is, the
439 commands will be executed if the
440 .I target
441 on the dependency line is out-of-date, not the sources.
442 .Ix 0 ref target
443 .Ix 0 ref source
444 .Ix 0 ref out-of-date
445 In this example, the command
446 .CW "cc \-c a.c" '' ``
447 will be executed if
448 .CW a.o
449 is out-of-date. Because of the `:' operator,
450 .Ix 0 ref :
451 .Ix 0 ref operator colon
452 this means that should
453 .CW a.c
454 .I or
455 .CW defs.h
456 have been modified more recently than
457 .CW a.o ,
458 the command will be executed
459 .CW a.o "\&" (
460 will be considered out-of-date).
461 .Ix 0 ref out-of-date
462 .LP
463 Remember how I said the only difference between a makefile shell
464 command and a regular shell command was the leading tab? I lied. There
465 is another way in which makefile commands differ from regular ones.
466 The first two characters after the initial whitespace are treated
467 specially.
468 If they are any combination of `@' and `\-', they cause PMake to do
469 different things.
470 .LP
471 In most cases, shell commands are printed before they're
472 actually executed. This is to keep you informed of what's going on. If
473 an `@' appears, however, this echoing is suppressed. In the case of an
474 .CW echo
475 command, say
476 .CW "echo Linking index" ,'' ``
477 it would be
478 rather silly to see
479 .DS
480 echo Linking index
481 Linking index
482 .DE
483 .LP
484 so PMake allows you to place an `@' before the command
485 .CW "@echo Linking index" '') (``
486 to prevent the command from being printed.
487 .LP
488 The other special character is the `\-'. In case you didn't know,
489 shell commands finish with a certain ``exit status.'' This status is
490 made available by the operating system to whatever program invoked the
491 command. Normally this status will be 0 if everything went ok and
492 non-zero if something went wrong. For this reason, PMake will consider
493 an error to have occurred if one of the shells it invokes returns a non-zero
494 status. When it detects an error, PMake's usual action is to abort
495 whatever it's doing and exit with a non-zero status itself (any other
496 targets that were being created will continue being made, but nothing
497 new will be started. PMake will exit after the last job finishes).
498 This behavior can be altered, however, by placing a `\-' at the front
499 of a command
500 .CW "\-mv index index.old" ''), (``
501 certain command-line arguments,
502 or doing other things, to be detailed later. In such
503 a case, the non-zero status is simply ignored and PMake keeps chugging
504 along.
505 .No
506 .LP
507 Because all the commands are given to a single shell to execute, such
508 things as setting shell variables, changing directories, etc., last
509 beyond the command in which they are found. This also allows shell
510 compound commands (like
511 .CW for
512 loops) to be entered in a natural manner.
513 Since this could cause problems for some makefiles that depend on
514 each command being executed by a single shell, PMake has a
515 .B \-B
516 .Ix 0 ref compatibility
517 .Ix 0 ref flags -B
518 flag (it stands for backwards-compatible) that forces each command to
519 be given to a separate shell. It also does several other things, all
520 of which I discourage since they are now old-fashioned.\|.\|.\|.
521 .No
522 .LP
523 A target's shell script is fed to the shell on its (the shell's) input stream.
524 This means that any commands, such as
525 .CW ci
526 that need to get input from the terminal won't work right \*- they'll
527 get the shell's input, something they probably won't find to their
528 liking. A simple way around this is to give a command like this:
529 .DS
530 ci $(SRCS) < /dev/tty
531 .DE
532 This would force the program's input to come from the terminal. If you
533 can't do this for some reason, your only other alternative is to use
534 PMake in its fullest compatibility mode. See 
535 .B Compatibility
536 in chapter 4.
537 .Ix 0 ref compatibility
538 .LP
539 .xH 2 Variables
540 .LP
541 PMake, like Make before it, has the ability to save text in variables
542 to be recalled later at your convenience. Variables in PMake are used
543 much like variables in the shell and, by tradition, consist of
544 all upper-case letters (you don't
545 .I have
546 to use all upper-case letters.
547 In fact there's nothing to stop you from calling a variable
548 .CW @^&$%$ .
549 Just tradition). Variables are assigned-to using lines of the form
550 .Ix 0 def variable assignment
551 .DS
552 VARIABLE = value
553 .DE
554 .Ix 0 def variable assignment
555 appended-to by
556 .DS
557 VARIABLE += value
558 .DE
559 .Ix 0 def variable appending
560 .Ix 0 def variable assignment appended
561 .Ix 0 def +=
562 conditionally assigned-to (if the variable isn't already defined) by
563 .DS
564 VARIABLE ?= value
565 .DE
566 .Ix 0 def variable assignment conditional
567 .Ix 0 def ?=
568 and assigned-to with expansion (i.e. the value is expanded (see below)
569 before being assigned to the variable\*-useful for placing a value at
570 the beginning of a variable, or other things) by
571 .DS
572 VARIABLE := value
573 .DE
574 .Ix 0 def variable assignment expanded
575 .Ix 0 def :=
576 .LP
577 Any whitespace before
578 .I value
579 is stripped off. When appending, a space is placed between the old
580 value and the stuff being appended.
581 .LP
582 The final way a variable may be assigned to is using
583 .DS
584 VARIABLE != shell-command
585 .DE
586 .Ix 0 def variable assignment shell-output
587 .Ix 0 def !=
588 In this case, 
589 .I shell-command
590 has all its variables expanded (see below) and is passed off to a
591 shell to execute. The output of the shell is then placed in the
592 variable. Any newlines (other than the final one) are replaced by
593 spaces before the assignment is made. This is typically used to find
594 the current directory via a line like:
595 .DS
596 CWD             != pwd
597 .DE
598 .LP
599 .B Note:
600 this is intended to be used to execute commands that produce small amounts
601 of output (e.g. ``pwd''). The implementation is less than intelligent and will
602 likely freeze if you execute something that produces thousands of
603 bytes of output (8 Kb is the limit on many UNIX systems).
604 .LP
605 The value of a variable may be retrieved by enclosing the variable
606 name in parentheses or curly braces and preceding the whole thing
607 with a dollar sign.
608 .LP
609 For example, to set the variable CFLAGS to the string
610 .CW "\-I/sprite/src/lib/libc \-O" ,'' ``
611 you would place a line
612 .DS
613 CFLAGS = \-I/sprite/src/lib/libc \-O
614 .DE
615 in the makefile and use the word
616 .CW "$(CFLAGS)"
617 wherever you would like the string
618 .CW "\-I/sprite/src/lib/libc \-O"
619 to appear. This is called variable expansion.
620 .Ix 0 def variable expansion
621 .No
622 .LP
623 Unlike Make, PMake will not expand a variable unless it knows
624 the variable exists. E.g. if you have a
625 .CW "${i}"
626 in a shell command and you have not assigned a value to the variable
627 .CW i 
628 (the empty string is considered a value, by the way), where Make would have
629 substituted the empty string, PMake will leave the
630 .CW "${i}"
631 alone.
632 To keep PMake from substituting for a variable it knows, precede the
633 dollar sign with another dollar sign.
634 (e.g. to pass
635 .CW "${HOME}"
636 to the shell, use
637 .CW "$${HOME}" ).
638 This causes PMake, in effect, to expand the
639 .CW $
640 macro, which expands to a single
641 .CW $ .
642 For compatibility, Make's style of variable expansion will be used
643 if you invoke PMake with any of the compatibility flags (\c
644 .B \-V ,
645 .B \-B
646 or
647 .B \-M .
648 The
649 .B \-V
650 flag alters just the variable expansion).
651 .Ix 0 ref flags -V
652 .Ix 0 ref flags -B
653 .Ix 0 ref flags -M
654 .Ix 0 ref compatibility
655 .LP
656 .Ix 0 ref variable expansion
657 There are two different times at which variable expansion occurs:
658 When parsing a dependency line, the expansion occurs immediately
659 upon reading the line. If any variable used on a dependency line is
660 undefined, PMake will print a message and exit.
661 Variables in shell commands are expanded when the command is
662 executed.
663 Variables used inside another variable are expanded whenever the outer
664 variable is expanded (the expansion of an inner variable has no effect
665 on the outer variable. I.e. if the outer variable is used on a dependency
666 line and in a shell command, and the inner variable changes value
667 between when the dependency line is read and the shell command is
668 executed, two different values will be substituted for the outer
669 variable).
670 .Ix 0 def variable types
671 .LP
672 Variables come in four flavors, though they are all expanded the same
673 and all look about the same. They are (in order of expanding scope):
674 .RS
675 .IP \(bu 2
676 Local variables.
677 .Ix 0 ref variable local
678 .IP \(bu 2
679 Command-line variables.
680 .Ix 0 ref variable command-line
681 .IP \(bu 2
682 Global variables.
683 .Ix 0 ref variable global
684 .IP \(bu 2
685 Environment variables.
686 .Ix 0 ref variable environment
687 .RE
688 .LP
689 The classification of variables doesn't matter much, except that the
690 classes are searched from the top (local) to the bottom (environment)
691 when looking up a variable. The first one found wins.
692 .xH 3 Local Variables
693 .LP
694 .Ix 0 def variable local
695 Each target can have as many as seven local variables. These are
696 variables that are only ``visible'' within that target's shell script
697 and contain such things as the target's name, all of its sources (from
698 all its dependency lines), those sources that were out-of-date, etc.
699 Four local variables are defined for all targets. They are:
700 .RS
701 .IP ".TARGET"
702 .Ix 0 def variable local .TARGET
703 .Ix 0 def .TARGET
704 The name of the target.
705 .IP ".OODATE"
706 .Ix 0 def variable local .OODATE
707 .Ix 0 def .OODATE
708 The list of the sources for the target that were considered out-of-date.
709 The order in the list is not guaranteed to be the same as the order in
710 which the dependencies were given.
711 .IP ".ALLSRC"
712 .Ix 0 def variable local .ALLSRC
713 .Ix 0 def .ALLSRC
714 The list of all sources for this target in the order in which they
715 were given.
716 .IP ".PREFIX"
717 .Ix 0 def variable local .PREFIX
718 .Ix 0 def .PREFIX
719 The target without its suffix and without any leading path. E.g. for
720 the target
721 .CW ../../lib/compat/fsRead.c ,
722 this variable would contain
723 .CW fsRead .
724 .RE
725 .LP
726 Three other local variables are set only for certain targets under
727 special circumstances. These are the ``.IMPSRC,''
728 .Ix 0 ref variable local .IMPSRC
729 .Ix 0 ref .IMPSRC
730 ``.ARCHIVE,''
731 .Ix 0 ref variable local .ARCHIVE
732 .Ix 0 ref .ARCHIVE
733 and ``.MEMBER''
734 .Ix 0 ref variable local .MEMBER
735 .Ix 0 ref .MEMBER
736 variables. When they are set and how they are used is described later.
737 .LP
738 Four of these variables may be used in sources as well as in shell
739 scripts.
740 .Ix 0 def "dynamic source"
741 .Ix 0 def source dynamic
742 These are ``.TARGET'', ``.PREFIX'', ``.ARCHIVE'' and ``.MEMBER''. The
743 variables in the sources are expanded once for each target on the
744 dependency line, providing what is known as a ``dynamic source,''
745 .Rd 0
746 allowing you to specify several dependency lines at once. For example,
747 .DS
748 $(OBJS)         : $(.PREFIX).c
749 .DE
750 will create a dependency between each object file and its
751 corresponding C source file.
752 .xH 3 Command-line Variables
753 .LP
754 .Ix 0 def variable command-line
755 Command-line variables are set when PMake is first invoked by giving a
756 variable assignment as one of the arguments. For example,
757 .DS
758 pmake "CFLAGS = -I/sprite/src/lib/libc -O"
759 .DE
760 would make 
762 be a command-line variable with the given value. Any assignments to
764 in the makefile will have no effect, because once it
765 is set, there is (almost) nothing you can do to change a command-line
766 variable (the search order, you see). Command-line variables may be
767 set using any of the four assignment operators, though only
768 .CW =
769 and
770 .CW ?=
771 behave as you would expect them to, mostly because assignments to
772 command-line variables are performed before the makefile is read, thus
773 the values set in the makefile are unavailable at the time.
774 .CW +=
775 .Ix 0 ref +=
776 .Ix 0 ref variable assignment appended
777 is the same as
778 .CW = ,
779 because the old value of the variable is sought only in the scope in
780 which the assignment is taking place (for reasons of efficiency that I
781 won't get into here).
782 .CW :=
783 and
784 .CW ?=
785 .Ix 0 ref :=
786 .Ix 0 ref ?=
787 .Ix 0 ref variable assignment expanded
788 .Ix 0 ref variable assignment conditional
789 will work if the only variables used are in the environment.
790 .CW !=
791 is sort of pointless to use from the command line, since the same
792 effect can no doubt be accomplished using the shell's own command
793 substitution mechanisms (backquotes and all that).
794 .xH 3 Global Variables
795 .LP
796 .Ix 0 def variable global
797 Global variables are those set or appended-to in the makefile.
798 There are two classes of global variables: those you set and those PMake sets.
799 As I said before, the ones you set can have any name you want them to have,
800 except they may not contain a colon or an exclamation point.
801 The variables PMake sets (almost) always begin with a
802 period and always contain upper-case letters, only. The variables are
803 as follows:
804 .RS
805 .IP .PMAKE
806 .Ix 0 def variable global .PMAKE
807 .Ix 0 def .PMAKE
808 .Ix 0 def variable global MAKE
809 .Ix 0 def MAKE
810 The name by which PMake was invoked is stored in this variable. For
811 compatibility, the name is also stored in the MAKE variable.
813 .Ix 0 def variable global .MAKEFLAGS
814 .Ix 0 def .MAKEFLAGS variable
815 .Ix 0 def variable global MFLAGS
816 .Ix 0 def MFLAGS
817 All the relevant flags with which PMake was invoked. This does not
818 include such things as
819 .B \-f
820 or variable assignments. Again for compatibility, this value is stored
821 in the MFLAGS variable as well.
822 .RE
823 .LP
824 Two other variables, ``.INCLUDES'' and ``.LIBS,'' are covered in the
825 section on special targets in chapter 3.
826 .Ix 0 ref variable global .INCLUDES
827 .Ix 0 ref variable global .LIBS
828 .LP
829 Global variables may be deleted using lines of the form:
830 .Ix 0 def #undef
831 .Ix 0 def variable deletion
832 .DS
833 #undef \fIvariable\fP
834 .DE
835 The
836 .CW # ' `
837 must be the first character on the line. Note that this may only be
838 done on global variables.
839 .xH 3 Environment Variables
840 .LP
841 .Ix 0 def variable environment
842 Environment variables are passed by the shell that invoked PMake and
843 are given by PMake to each shell it invokes. They are expanded like
844 any other variable, but they cannot be altered in any way.
845 .LP
846 One special environment variable,
847 .CW PMAKE ,
848 .Ix 0 def variable environment PMAKE
849 is examined by PMake for command-line flags, variable assignments,
850 etc., it should always use. This variable is examined before the
851 actual arguments to PMake are. In addition, all flags given to PMake,
852 either through the
854 variable or on the command line, are placed in this environment
855 variable and exported to each shell PMake executes. Thus recursive
856 invocations of PMake automatically receive the same flags as the
857 top-most one.
858 .LP
859 Using all these variables, you can compress the sample makefile even more:
860 .DS
861 OBJS            = a.o b.o c.o
862 program         : $(OBJS)
863         cc $(.ALLSRC) \-o $(.TARGET)
864 $(OBJS)         : defs.h
865 a.o             : a.c
866         cc \-c a.c
867 b.o             : b.c
868         cc \-c b.c
869 c.o             : c.c
870         cc \-c c.c
871 .DE
872 .Ix 0 ref variable local .ALLSRC
873 .Ix 0 ref .ALLSRC
874 .Ix 0 ref variable local .TARGET
875 .Ix 0 ref .TARGET
876 .Rd 3
877 .xH 2 Comments
878 .LP
879 .Ix 0 def comments
880 Comments in a makefile start with a `#' character and extend to the
881 end of the line. They may appear
882 anywhere you want them, except in a shell command (though the shell
883 will treat it as a comment, too). If, for some reason, you need to use the `#'
884 in a variable or on a dependency line, put a backslash in front of it.
885 PMake will compress the two into a single `#' (Note: this isn't true
886 if PMake is operating in full-compatibility mode).
887 .Ix 0 ref flags -M
888 .Ix 0 ref compatibility
889 .xH 2 Parallelism
890 .No
891 .LP
892 PMake was specifically designed to re-create several targets at once,
893 when possible. You do not have to do anything special to cause this to
894 happen (unless PMake was configured to not act in parallel, in which
895 case you will have to make use of the
896 .B \-L
897 and
898 .B \-J
899 flags (see below)),
900 .Ix 0 ref flags -L
901 .Ix 0 ref flags -J
902 but you do have to be careful at times.
903 .LP
904 There are several problems you are likely to encounter. One is
905 that some makefiles (and programs) are written in such a way that it is
906 impossible for two targets to be made at once. The program
907 .CW xstr ,
908 for example,
909 always modifies the files
910 .CW strings
911 and
912 .CW x.c .
913 There is no way to change it. Thus you cannot run two of them at once
914 without something being trashed. Similarly, if you have commands
915 in the makefile that always send output to the same file, you will not
916 be able to make more than one target at once unless you change the
917 file you use. You can, for instance, add a
918 .CW $$$$
919 to the end of the file name to tack on the process ID of the shell
920 executing the command (each
921 .CW $$
922 expands to a single
923 .CW $ ,
924 thus giving you the shell variable
925 .CW $$ ).
926 Since only one shell is used for all the
927 commands, you'll get the same file name for each command in the
928 script.
929 .LP
930 The other problem comes from improperly-specified dependencies that
931 worked in Make because of its sequential, depth-first way of examining
932 them. While I don't want to go into depth on how PMake
933 works (look in chapter 4 if you're interested), I will warn you that
934 files in two different ``levels'' of the dependency tree may be
935 examined in a different order in PMake than they were in Make. For
936 example, given the makefile
937 .DS
938 a               : b c
939 b               : d
940 .DE
941 PMake will examine the targets in the order
942 .CW c ,
943 .CW d ,
944 .CW b ,
945 .CW a .
946 If the makefile's author expected PMake to abort before making
947 .CW c
948 if an error occurred while making
949 .CW b ,
950 or if
951 .CW b
952 needed to exist before
953 .CW c
954 was made,
955 s/he will be sorely disappointed. The dependencies are
956 incomplete, since in both these cases,
957 .CW c
958 would depend on
959 .CW b .
960 So watch out.
961 .LP
962 Another problem you may face is that, while PMake is set up to handle the
963 output from multiple jobs in a graceful fashion, the same is not so for input.
964 It has no way to regulate input to different jobs,
965 so if you use the redirection from
966 .CW /dev/tty
967 I mentioned earlier, you must be careful not to run two of the jobs at once.
968 .xH 2 Writing and Debugging a Makefile
969 .LP
970 Now you know most of what's in a makefile, what do you do next? There
971 are two choices: (1) use one of the uncommonly-available makefile
972 generators or (2) write your own makefile (I leave out the third choice of
973 ignoring PMake and doing everything by hand as being beyond the bounds
974 of common sense).
975 .LP
976 When faced with the writing of a makefile, it is usually best to start
977 from first principles: just what
978 .I are
979 you trying to do? What do you want the makefile finally to produce?
980 .LP
981 To begin with a somewhat traditional example, let's say you need to
982 write a makefile to create a program,
983 .CW expr ,
984 that takes standard infix expressions and converts them to prefix form (for
985 no readily apparent reason). You've got three source files, in C, that
986 make up the program:
987 .CW main.c ,
988 .CW parse.c ,
989 and
990 .CW output.c .
991 Harking back to my pithy advice about dependency lines, you write the
992 first line of the file:
993 .DS
994 expr            : main.o parse.o output.o
995 .DE
996 because you remember
997 .CW expr
998 is made from
999 .CW .o
1000 files, not
1001 .CW .c
1002 files. Similarly for the
1003 .CW .o
1004 files you produce the lines:
1005 .DS
1006 main.o          : main.c
1007 parse.o         : parse.c
1008 output.o        : output.c
1009 main.o parse.o output.o : defs.h
1010 .DE
1011 .LP
1012 Great. You've now got the dependencies specified. What you need now is
1013 commands. These commands, remember, must produce the target on the
1014 dependency line, usually by using the sources you've listed.
1015 You remember about local variables? Good, so it should come
1016 to you as no surprise when you write
1017 .DS
1018 expr            : main.o parse.o output.o
1019         cc -o $(.TARGET) $(.ALLSRC)
1020 .DE
1021 Why use the variables? If your program grows to produce postfix
1022 expressions too (which, of course, requires a name change or two), it
1023 is one fewer place you have to change the file. You cannot do this for
1024 the object files, however, because they depend on their corresponding
1025 source files
1026 .I and
1027 .CW defs.h ,
1028 thus if you said
1029 .DS
1030         cc -c $(.ALLSRC)
1031 .DE
1032 you'd get (for
1033 .CW main.o ):
1034 .DS
1035         cc -c main.c defs.h
1036 .DE
1037 which is wrong. So you round out the makefile with these lines:
1038 .DS
1039 main.o          : main.c
1040         cc -c main.c
1041 parse.o         : parse.c
1042         cc -c parse.c
1043 output.o        : output.c
1044         cc -c output.c
1045 .DE
1046 .LP
1047 The makefile is now complete and will, in fact, create the program you
1048 want it to without unnecessary compilations or excessive typing on
1049 your part. There are two things wrong with it, however (aside from it
1050 being altogether too long, something I'll address in chapter 3):
1051 .IP 1)
1052 The string
1053 .CW "main.o parse.o output.o" '' ``
1054 is repeated twice, necessitating two changes when you add postfix
1055 (you were planning on that, weren't you?). This is in direct violation
1056 of de Boor's First Rule of writing makefiles:
1057 .QP
1058 .I
1059 Anything that needs to be written more than once
1060 should be placed in a variable.
1061 .IP "\&"
1062 I cannot emphasize this enough as being very important to the
1063 maintenance of a makefile and its program.
1064 .IP 2)
1065 There is no way to alter the way compilations are performed short of
1066 editing the makefile and making the change in all places. This is evil
1067 and violates de Boor's Second Rule, which follows directly from the
1068 first:
1069 .QP
1070 .I
1071 Any flags or programs used inside a makefile should be placed in a variable so
1072 they may be changed, temporarily or permanently, with the greatest ease.
1073 .LP
1074 The makefile should more properly read:
1075 .DS
1076 OBJS            = main.o parse.o output.o
1077 expr            : $(OBJS)
1078         $(CC) $(CFLAGS) -o $(.TARGET) $(.ALLSRC)
1079 main.o          : main.c
1080         $(CC) $(CFLAGS) -c main.c
1081 parse.o         : parse.c
1082         $(CC) $(CFLAGS) -c parse.c
1083 output.o        : output.c
1084         $(CC) $(CFLAGS) -c output.c
1085 $(OBJS)         : defs.h
1086 .DE
1087 Alternatively, if you like the idea of dynamic sources mentioned in
1088 section 2.3.1,
1089 .Rm 0 2.3.1
1090 .Rd 4
1091 .Ix 0 ref "dynamic source"
1092 .Ix 0 ref source dynamic
1093 you could write it like this:
1094 .DS
1095 OBJS            = main.o parse.o output.o
1096 expr            : $(OBJS)
1097         $(CC) $(CFLAGS) -o $(.TARGET) $(.ALLSRC)
1098 $(OBJS)         : $(.PREFIX).c defs.h
1099         $(CC) $(CFLAGS) -c $(.PREFIX).c
1100 .DE
1101 These two rules and examples lead to de Boor's First Corollary:
1102 .QP
1103 .I
1104 Variables are your friends.
1105 .LP
1106 Once you've written the makefile comes the sometimes-difficult task of
1107 .Ix 0 ref debugging
1108 making sure the darn thing works. Your most helpful tool to make sure
1109 the makefile is at least syntactically correct is the
1110 .B \-n
1111 .Ix 0 ref flags -n
1112 flag, which allows you to see if PMake will choke on the makefile. The
1113 second thing the
1114 .B \-n
1115 flag lets you do is see what PMake would do without it actually doing
1116 it, thus you can make sure the right commands would be executed were
1117 you to give PMake its head.
1118 .LP
1119 When you find your makefile isn't behaving as you hoped, the first
1120 question that comes to mind (after ``What time is it, anyway?'') is
1121 ``Why not?'' In answering this, two flags will serve you well:
1122 .CW "-d m" '' ``
1123 .Ix 0 ref flags -d
1124 and
1125 .CW "-p 2" .'' ``
1126 .Ix 0 ref flags -p
1127 The first causes PMake to tell you as it examines each target in the
1128 makefile and indicate why it is deciding whatever it is deciding. You
1129 can then use the information printed for other targets to see where
1130 you went wrong. The
1131 .CW "-p 2" '' ``
1132 flag makes PMake print out its internal state when it is done,
1133 allowing you to see that you forgot to make that one chapter depend on
1134 that file of macros you just got a new version of. The output from
1135 .CW "-p 2" '' ``
1136 is intended to resemble closely a real makefile, but with additional
1137 information provided and with variables expanded in those commands
1138 PMake actually printed or executed.
1139 .LP
1140 Something to be especially careful about is circular dependencies.
1141 .Ix 0 def dependency circular
1142 E.g.
1143 .DS
1144 a               : b
1145 b               : c d
1146 d               : a
1147 .DE
1148 In this case, because of how PMake works,
1149 .CW c
1150 is the only thing PMake will examine, because
1151 .CW d
1152 and
1153 .CW a
1154 will effectively fall off the edge of the universe, making it
1155 impossible to examine
1156 .CW b
1157 (or them, for that matter).
1158 PMake will tell you (if run in its normal mode) all the targets
1159 involved in any cycle it looked at (i.e. if you have two cycles in the
1160 graph (naughty, naughty), but only try to make a target in one of
1161 them, PMake will only tell you about that one. You'll have to try to
1162 make the other to find the second cycle). When run as Make, it will
1163 only print the first target in the cycle.
1164 .xH 2 Invoking PMake
1165 .LP
1166 .Ix 0 ref flags
1167 .Ix 0 ref arguments
1168 .Ix 0 ref usage
1169 PMake comes with a wide variety of flags to choose from.
1170 They may appear in any order, interspersed with command-line variable
1171 assignments and targets to create.
1172 The flags are as follows:
1173 .IP "\fB\-d\fP \fIwhat\fP"
1174 .Ix 0 def flags -d
1175 .Ix 0 ref debugging
1176 This causes PMake to spew out debugging information that
1177 may prove useful to you. If you can't
1178 figure out why PMake is doing what it's doing, you might try using
1179 this flag. The
1180 .I what
1181 parameter is a string of single characters that tell PMake what
1182 aspects you are interested in. Most of what I describe will make
1183 little sense to you, unless you've dealt with Make before. Just
1184 remember where this table is and come back to it as you read on.
1185 The characters and the information they produce are as follows:
1186 .RS
1187 .IP a
1188 Archive searching and caching.
1189 .IP c
1190 Conditional evaluation.
1191 .IP d
1192 The searching and caching of directories.
1193 .IP j
1194 Various snippets of information related to the running of the multiple
1195 shells. Not particularly interesting.
1196 .IP m
1197 The making of each target: what target is being examined; when it was
1198 last modified; whether it is out-of-date; etc.
1199 .IP p
1200 Makefile parsing.
1201 .IP r
1202 Remote execution.
1203 .IP s
1204 The application of suffix-transformation rules. (See chapter 3)
1205 .IP t
1206 The maintenance of the list of targets.
1207 .IP v
1208 Variable assignment.
1209 .RE
1210 .IP "\&"
1211 Of these all, the
1212 .CW m
1213 and
1214 .CW s
1215 letters will be most useful to you.
1216 If the
1217 .B \-d
1218 is the final argument or the argument from which it would get these
1219 key letters (see below for a note about which argument would be used)
1220 begins with a
1221 .B \- ,
1222 all of these debugging flags will be set, resulting in massive amounts
1223 of output.
1224 .IP "\fB\-f\fP \fImakefile\fP"
1225 .Ix 0 def flags -f
1226 Specify a makefile to read different from the standard makefiles
1227 .CW Makefile "\&" (
1228 or
1229 .CW makefile ).
1230 .Ix 0 ref makefile default
1231 .Ix 0 ref makefile other
1232 If
1233 .I makefile
1234 is ``\-'', PMake uses the standard input. This is useful for making
1235 quick and dirty makefiles.\|.\|.
1236 .Ix 0 ref makefile "quick and dirty"
1237 .IP \fB\-h\fP
1238 .Ix 0 def flags -h
1239 Prints out a summary of the various flags PMake accepts. It can also
1240 be used to find out what level of concurrency was compiled into the
1241 version of PMake you are using (look at
1242 .B \-J
1243 and
1244 .B \-L )
1245 and various other information on how PMake was configured.
1246 .Ix 0 ref configuration
1247 .Ix 0 ref makefile system
1248 .IP \fB\-i\fP
1249 .Ix 0 def flags -i
1250 If you give this flag, PMake will ignore non-zero status returned
1251 by any of its shells. It's like placing a `\-' before all the commands
1252 in the makefile.
1253 .IP \fB\-k\fP
1254 .Ix 0 def flags -k
1255 This is similar to
1256 .B \-i
1257 in that it allows PMake to continue when it sees an error, but unlike
1258 .B \-i ,
1259 where PMake continues blithely as if nothing went wrong,
1260 .B \-k
1261 causes it to recognize the error and only continue work on those
1262 things that don't depend on the target, either directly or indirectly (through
1263 depending on something that depends on it), whose creation returned the error.
1264 The `k' is for ``keep going''.\|.\|.
1265 .Ix 0 ref target
1266 .IP \fB\-l\fP
1267 .Ix 0 def flags -l
1268 PMake has the ability to lock a directory against other
1269 people executing it in the same directory (by means of a file called
1270 ``LOCK.make'' that it creates and checks for in the directory). This
1271 is a Good Thing because two people doing the same thing in the same place
1272 can be disastrous for the final product (too many cooks and all that).
1273 Whether this locking is the default is up to your system
1274 administrator. If locking is on,
1275 .B \-l
1276 will turn it off, and vice versa. Note that this locking will not
1277 prevent \fIyou\fP from invoking PMake twice in the same place \*- if
1278 you own the lock file, PMake will warn you about it but continue to execute.
1279 .IP "\fB\-m\fP \fIdirectory\fP"
1280 .Ix 0 def flags -m
1281 Tells PMake another place to search for included makefiles via the <...>
1282 style.  Several
1283 .B \-m
1284 options can be given to form a search path.  If this construct is used the
1285 default system makefile search path is completely overridden.
1286 To be explained in chapter 3, section 3.2.
1287 .Rm 2 3.2
1288 .IP \fB\-n\fP
1289 .Ix 0 def flags -n
1290 This flag tells PMake not to execute the commands needed to update the
1291 out-of-date targets in the makefile. Rather, PMake will simply print
1292 the commands it would have executed and exit. This is particularly
1293 useful for checking the correctness of a makefile. If PMake doesn't do
1294 what you expect it to, it's a good chance the makefile is wrong.
1295 .IP "\fB\-p\fP \fInumber\fP"
1296 .Ix 0 def flags -p
1297 .Ix 0 ref debugging
1298 This causes PMake to print its input in a reasonable form, though
1299 not necessarily one that would make immediate sense to anyone but me. The
1300 .I number
1301 is a bitwise-or of 1 and 2 where 1 means it should print the input
1302 before doing any processing and 2 says it should print it after
1303 everything has been re-created. Thus
1304 .CW "\-p 3"
1305 would print it twice\*-once before processing and once after (you
1306 might find the difference between the two interesting). This is mostly
1307 useful to me, but you may find it informative in some bizarre circumstances.
1308 .IP \fB\-q\fP
1309 .Ix 0 def flags -q
1310 If you give PMake this flag, it will not try to re-create anything. It
1311 will just see if anything is out-of-date and exit non-zero if so.
1312 .IP \fB\-r\fP
1313 .Ix 0 def flags -r
1314 When PMake starts up, it reads a default makefile that tells it what
1315 sort of system it's on and gives it some idea of what to do if you
1316 don't tell it anything. I'll tell you about it in chapter 3. If you
1317 give this flag, PMake won't read the default makefile.
1318 .IP \fB\-s\fP
1319 .Ix 0 def flags -s
1320 This causes PMake to not print commands before they're executed. It
1321 is the equivalent of putting an `@' before every command in the
1322 makefile.
1323 .IP \fB\-t\fP
1324 .Ix 0 def flags -t
1325 Rather than try to re-create a target, PMake will simply ``touch'' it
1326 so as to make it appear up-to-date. If the target didn't exist before,
1327 it will when PMake finishes, but if the target did exist, it will
1328 appear to have been updated.
1329 .IP \fB\-v\fP
1330 .Ix 0 def flags -v
1331 This is a mixed-compatibility flag intended to mimic the System V
1332 version of Make. It is the same as giving
1333 .B \-B ,
1334 and
1335 .B \-V
1336 as well as turning off directory locking. Targets can still be created
1337 in parallel, however. This is the mode PMake will enter if it is
1338 invoked either as
1339 .CW smake '' ``
1340 or
1341 .CW vmake ''. ``
1342 .IP \fB\-x\fP
1343 .Ix 0 def flags -x
1344 This tells PMake it's ok to export jobs to other machines, if they're
1345 available. It is used when running in Make mode, as exporting in this
1346 mode tends to make things run slower than if the commands were just
1347 executed locally.
1348 .IP \fB\-B\fP
1349 .Ix 0 ref compatibility
1350 .Ix 0 def flags -B
1351 Forces PMake to be as backwards-compatible with Make as possible while
1352 still being itself.
1353 This includes:
1354 .RS
1355 .IP \(bu 2
1356 Executing one shell per shell command
1357 .IP \(bu 2
1358 Expanding anything that looks even vaguely like a variable, with the
1359 empty string replacing any variable PMake doesn't know.
1360 .IP \(bu 2
1361 Refusing to allow you to escape a `#' with a backslash.
1362 .IP \(bu 2
1363 Permitting undefined variables on dependency lines and conditionals
1364 (see below). Normally this causes PMake to abort.
1365 .RE
1366 .IP \fB\-C\fP
1367 .Ix 0 def flags -C
1368 This nullifies any and all compatibility mode flags you may have given
1369 or implied up to the time the
1370 .B \-C
1371 is encountered. It is useful mostly in a makefile that you wrote for PMake
1372 to avoid bad things happening when someone runs PMake as
1373 .CW make '' ``
1374 or has things set in the environment that tell it to be compatible.
1375 .B \-C
1376 is
1377 .I not
1378 placed in the
1379 .CW PMAKE
1380 environment variable or the
1382 or
1384 global variables.
1385 .Ix 0 ref variable environment PMAKE
1386 .Ix 0 ref variable global .MAKEFLAGS
1387 .Ix 0 ref variable global MFLAGS
1388 .Ix 0 ref .MAKEFLAGS variable
1389 .Ix 0 ref MFLAGS
1390 .IP "\fB\-D\fP \fIvariable\fP"
1391 .Ix 0 def flags -D
1392 Allows you to define a variable to have 
1393 .CW 1 '' ``
1394 as its value.  The variable is a global variable, not a command-line
1395 variable. This is useful mostly for people who are used to the C
1396 compiler arguments and those using conditionals, which I'll get into
1397 in section 4.3
1398 .Rm 1 4.3
1399 .IP "\fB\-I\fP \fIdirectory\fP"
1400 .Ix 0 def flags -I
1401 Tells PMake another place to search for included makefiles. Yet
1402 another thing to be explained in chapter 3 (section 3.2, to be
1403 precise).
1404 .Rm 2 3.2
1405 .IP "\fB\-J\fP \fInumber\fP"
1406 .Ix 0 def flags -J
1407 Gives the absolute maximum number of targets to create at once on both
1408 local and remote machines.
1409 .IP "\fB\-L\fP \fInumber\fP"
1410 .Ix 0 def flags -L
1411 This specifies the maximum number of targets to create on the local
1412 machine at once. This may be 0, though you should be wary of doing
1413 this, as PMake may hang until a remote machine becomes available, if
1414 one is not available when it is started.
1415 .IP \fB\-M\fP
1416 .Ix 0 ref compatibility
1417 .Ix 0 def flags -M
1418 This is the flag that provides absolute, complete, full compatibility
1419 with Make. It still allows you to use all but a few of the features of
1420 PMake, but it is non-parallel. This is the mode PMake enters if you
1421 call it
1422 .CW make .'' ``
1423 .IP \fB\-P\fP
1424 .Ix 0 def flags -P
1425 .Ix 0 ref "output control"
1426 When creating targets in parallel, several shells are executing at
1427 once, each wanting to write its own two cent's-worth to the screen.
1428 This output must be captured by PMake in some way in order to prevent
1429 the screen from being filled with garbage even more indecipherable
1430 than you usually see. PMake has two ways of doing this, one of which
1431 provides for much cleaner output and a clear separation between the
1432 output of different jobs, the other of which provides a more immediate
1433 response so one can tell what is really happening. The former is done
1434 by notifying you when the creation of a target starts, capturing the
1435 output and transferring it to the screen all at once when the job
1436 finishes. The latter is done by catching the output of the shell (and
1437 its children) and buffering it until an entire line is received, then
1438 printing that line preceded by an indication of which job produced
1439 the output. Since I prefer this second method, it is the one used by
1440 default. The first method will be used if you give the
1441 .B \-P
1442 flag to PMake.
1443 .IP \fB\-V\fP
1444 .Ix 0 def flags -V
1445 As mentioned before, the
1446 .B \-V
1447 flag tells PMake to use Make's style of expanding variables,
1448 substituting the empty string for any variable it doesn't know.
1449 .IP \fB\-W\fP
1450 .Ix 0 def flags -W
1451 There are several times when PMake will print a message at you that is
1452 only a warning, i.e. it can continue to work in spite of your having
1453 done something silly (such as forgotten a leading tab for a shell
1454 command). Sometimes you are well aware of silly things you have done
1455 and would like PMake to stop bothering you. This flag tells it to shut
1456 up about anything non-fatal.
1457 .IP \fB\-X\fP
1458 .Ix 0 def flags -X
1459 This flag causes PMake to not attempt to export any jobs to another
1460 machine.
1461 .LP
1462 Several flags may follow a single `\-'. Those flags that require
1463 arguments take them from successive parameters. E.g.
1464 .DS
1465 pmake -fDnI server.mk DEBUG /chip2/X/server/include
1466 .DE
1467 will cause PMake to read
1468 .CW server.mk
1469 as the input makefile, define the variable
1470 .CW DEBUG
1471 as a global variable and look for included makefiles in the directory
1472 .CW /chip2/X/server/include .
1473 .xH 2 Summary
1474 .LP
1475 A makefile is made of four types of lines:
1476 .RS
1477 .IP \(bu 2
1478 Dependency lines
1479 .IP \(bu 2
1480 Creation commands
1481 .IP \(bu 2
1482 Variable assignments
1483 .IP \(bu 2
1484 Comments, include statements and conditional directives
1485 .RE
1486 .LP
1487 A dependency line is a list of one or more targets, an operator
1488 .CW : ', (`
1489 .CW :: ', `
1490 or
1491 .CW ! '), `
1492 and a list of zero or more sources. Sources may contain wildcards and
1493 certain local variables.
1494 .LP
1495 A creation command is a regular shell command preceded by a tab. In
1496 addition, if the first two characters after the tab (and other
1497 whitespace) are a combination of
1498 .CW @ ' `
1499 or
1500 .CW - ', `
1501 PMake will cause the command to not be printed (if the character is
1502 .CW @ ') `
1503 or errors from it to be ignored (if
1504 .CW - '). `
1505 A blank line, dependency line or variable assignment terminates a
1506 creation script. There may be only one creation script for each target
1507 with a
1508 .CW : ' `
1509 or
1510 .CW ! ' `
1511 operator.
1512 .LP
1513 Variables are places to store text. They may be unconditionally
1514 assigned-to using the
1515 .CW = ' `
1516 .Ix 0 ref =
1517 .Ix 0 ref variable assignment
1518 operator, appended-to using the
1519 .CW += ' `
1520 .Ix 0 ref +=
1521 .Ix 0 ref variable assignment appended
1522 operator, conditionally (if the variable is undefined) assigned-to
1523 with the
1524 .CW ?= ' `
1525 .Ix 0 ref ?=
1526 .Ix 0 ref variable assignment conditional
1527 operator, and assigned-to with variable expansion with the
1528 .CW := ' `
1529 .Ix 0 ref :=
1530 .Ix 0 ref variable assignment expanded
1531 operator. The output of a shell command may be assigned to a variable
1532 using the
1533 .CW != ' `
1534 .Ix 0 ref !=
1535 .Ix 0 ref variable assignment shell-output
1536 operator.  Variables may be expanded (their value inserted) by enclosing
1537 their name in parentheses or curly braces, preceded by a dollar sign.
1538 A dollar sign may be escaped with another dollar sign. Variables are
1539 not expanded if PMake doesn't know about them. There are seven local
1540 variables:
1541 .CW .TARGET ,
1542 .CW .ALLSRC ,
1543 .CW .OODATE ,
1544 .CW .PREFIX ,
1545 .CW .IMPSRC ,
1546 .CW .ARCHIVE ,
1547 and
1548 .CW .MEMBER .
1549 Four of them
1550 .CW .TARGET , (
1551 .CW .PREFIX ,
1552 .CW .ARCHIVE ,
1553 and
1554 .CW .MEMBER )
1555 may be used to specify ``dynamic sources.''
1556 .Ix 0 ref "dynamic source"
1557 .Ix 0 ref source dynamic
1558 Variables are good. Know them. Love them. Live them.
1559 .LP
1560 Debugging of makefiles is best accomplished using the
1561 .B \-n ,
1562 .B "\-d m" ,
1563 and
1564 .B "\-p 2"
1565 flags.
1566 .xH 2 Exercises
1567 .ce
1568 \s+4\fBTBA\fP\s0
1569 .xH 1 Short-cuts and Other Nice Things
1570 .LP
1571 Based on what I've told you so far, you may have gotten the impression
1572 that PMake is just a way of storing away commands and making sure you
1573 don't forget to compile something. Good. That's just what it is.
1574 However, the ways I've described have been inelegant, at best, and
1575 painful, at worst.
1576 This chapter contains things that make the
1577 writing of makefiles easier and the makefiles themselves shorter and
1578 easier to modify (and, occasionally, simpler). In this chapter, I
1579 assume you are somewhat more
1580 familiar with Sprite (or UNIX, if that's what you're using) than I did
1581 in chapter 2, just so you're on your toes.
1582 So without further ado...
1583 .xH 2 Transformation Rules
1584 .LP
1585 As you know, a file's name consists of two parts: a base name, which
1586 gives some hint as to the contents of the file, and a suffix, which
1587 usually indicates the format of the file.
1588 Over the years, as
1589 .UX
1590 has developed,
1591 naming conventions, with regard to suffixes, have also developed that have
1592 become almost as incontrovertible as Law. E.g. a file ending in
1593 .CW .c
1594 is assumed to contain C source code; one with a
1595 .CW .o
1596 suffix is assumed to be a compiled, relocatable object file that may
1597 be linked into any program; a file with a
1598 .CW .ms
1599 suffix is usually a text file to be processed by Troff with the \-ms
1600 macro package, and so on.
1601 One of the best aspects of both Make and PMake comes from their
1602 understanding of how the suffix of a file pertains to its contents and
1603 their ability to do things with a file based solely on its suffix. This
1604 ability comes from something known as a transformation rule. A
1605 transformation rule specifies how to change a file with one suffix
1606 into a file with another suffix.
1607 .LP
1608 A transformation rule looks much like a dependency line, except the
1609 target is made of two known suffixes stuck together. Suffixes are made
1610 known to PMake by placing them as sources on a dependency line whose
1611 target is the special target
1612 .CW .SUFFIXES .
1613 E.g.
1614 .DS
1615 \&.SUFFIXES       : .o .c
1616 \&.c.o            :
1617         $(CC) $(CFLAGS) -c $(.IMPSRC)
1618 .DE
1619 The creation script attached to the target is used to transform a file with
1620 the first suffix (in this case,
1621 .CW .c )
1622 into a file with the second suffix (here,
1623 .CW .o ).
1624 In addition, the target inherits whatever attributes have been applied
1625 to the transformation rule.
1626 The simple rule given above says that to transform a C source file
1627 into an object file, you compile it using
1628 .CW cc
1629 with the
1630 .CW \-c
1631 flag.
1632 This rule is taken straight from the system makefile. Many
1633 transformation rules (and suffixes) are defined there, and I refer you
1634 to it for more examples (type
1635 .CW "pmake -h" '' ``
1636 to find out where it is).
1637 .LP
1638 There are several things to note about the transformation rule given
1639 above:
1640 .RS
1641 .IP 1)
1642 The
1643 .CW .IMPSRC 
1644 variable.
1645 .Ix 0 def variable local .IMPSRC
1646 .Ix 0 def .IMPSRC
1647 This variable is set to the ``implied source'' (the file from which
1648 the target is being created; the one with the first suffix), which, in this
1649 case, is the .c file.
1650 .IP 2)
1651 The
1653 variable. Almost all of the transformation rules in the system
1654 makefile are set up using variables that you can alter in your
1655 makefile to tailor the rule to your needs. In this case, if you want
1656 all your C files to be compiled with the
1657 .B \-g
1658 flag, to provide information for
1659 .CW dbx ,
1660 you would set the
1662 variable to contain
1663 .CW -g
1664 .CW "CFLAGS = -g" '') (``
1665 and PMake would take care of the rest.
1666 .RE
1667 .LP
1668 To give you a quick example, the makefile in 2.3.4 
1669 .Rm 3 2.3.4
1670 could be changed to this:
1671 .DS
1672 OBJS            = a.o b.o c.o
1673 program         : $(OBJS)
1674         $(CC) -o $(.TARGET) $(.ALLSRC)
1675 $(OBJS)         : defs.h
1676 .DE
1677 The transformation rule I gave above takes the place of the 6 lines\**
1678 .FS
1679 This is also somewhat cleaner, I think, than the dynamic source
1680 solution presented in 2.6
1681 .FE
1682 .Rm 4 2.6
1683 .DS
1684 a.o             : a.c
1685         cc -c a.c
1686 b.o             : b.c
1687         cc -c b.c
1688 c.o             : c.c
1689         cc -c c.c
1690 .DE
1691 .LP
1692 Now you may be wondering about the dependency between the
1693 .CW .o
1694 and
1695 .CW .c
1696 files \*- it's not mentioned anywhere in the new makefile. This is
1697 because it isn't needed: one of the effects of applying a
1698 transformation rule is the target comes to depend on the implied
1699 source. That's why it's called the implied
1700 .I source .
1701 .LP
1702 For a more detailed example. Say you have a makefile like this:
1703 .DS
1704 a.out           : a.o b.o
1705         $(CC) $(.ALLSRC)
1706 .DE
1707 and a directory set up like this:
1708 .DS
1709 total 4
1710 -rw-rw-r--  1 deboor         34 Sep  7 00:43 Makefile
1711 -rw-rw-r--  1 deboor        119 Oct  3 19:39 a.c
1712 -rw-rw-r--  1 deboor        201 Sep  7 00:43 a.o
1713 -rw-rw-r--  1 deboor         69 Sep  7 00:43 b.c
1714 .DE
1715 While just typing
1716 .CW pmake '' ``
1717 will do the right thing, it's much more informative to type
1718 .CW "pmake -d s" ''. ``
1719 This will show you what PMake is up to as it processes the files. In
1720 this case, PMake prints the following:
1721 .DS
1722 Suff_FindDeps (a.out)
1723         using existing source a.o
1724         applying .o -> .out to "a.o"
1725 Suff_FindDeps (a.o)
1726         trying a.c...got it
1727         applying .c -> .o to "a.c"
1728 Suff_FindDeps (b.o)
1729         trying b.c...got it
1730         applying .c -> .o to "b.c"
1731 Suff_FindDeps (a.c)
1732         trying a.y...not there
1733         trying a.l...not there
1734         trying a.c,v...not there
1735         trying a.y,v...not there
1736         trying a.l,v...not there
1737 Suff_FindDeps (b.c)
1738         trying b.y...not there
1739         trying b.l...not there
1740         trying b.c,v...not there
1741         trying b.y,v...not there
1742         trying b.l,v...not there
1743 --- a.o ---
1744 cc  -c a.c
1745 --- b.o ---
1746 cc  -c b.c
1747 --- a.out ---
1748 cc a.o b.o
1749 .DE
1750 .LP
1751 .CW Suff_FindDeps
1752 is the name of a function in PMake that is called to check for implied
1753 sources for a target using transformation rules.
1754 The transformations it tries are, naturally
1755 enough, limited to the ones that have been defined (a transformation
1756 may be defined multiple times, by the way, but only the most recent
1757 one will be used). You will notice, however, that there is a definite
1758 order to the suffixes that are tried. This order is set by the
1759 relative positions of the suffixes on the
1761 line \*- the earlier a suffix appears, the earlier it is checked as
1762 the source of a transformation. Once a suffix has been defined, the
1763 only way to change its position in the pecking order is to remove all
1764 the suffixes (by having a
1766 dependency line with no sources) and redefine them in the order you
1767 want. (Previously-defined transformation rules will be automatically
1768 redefined as the suffixes they involve are re-entered.)
1769 .LP
1770 Another way to affect the search order is to make the dependency
1771 explicit. In the above example,
1772 .CW a.out
1773 depends on
1774 .CW a.o
1775 and
1776 .CW b.o .
1777 Since a transformation exists from
1778 .CW .o
1779 to
1780 .CW .out ,
1781 PMake uses that, as indicated by the
1782 .CW "using existing source a.o" '' ``
1783 message.
1784 .LP
1785 The search for a transformation starts from the suffix of the target
1786 and continues through all the defined transformations, in the order
1787 dictated by the suffix ranking, until an existing file with the same
1788 base (the target name minus the suffix and any leading directories) is
1789 found. At that point, one or more transformation rules will have been
1790 found to change the one existing file into the target.
1791 .LP
1792 For example, ignoring what's in the system makefile for now, say you
1793 have a makefile like this:
1794 .DS
1795 \&.SUFFIXES       : .out .o .c .y .l
1796 \&.l.c            :
1797         lex $(.IMPSRC)
1798         mv lex.yy.c $(.TARGET)
1799 \&.y.c            :
1800         yacc $(.IMPSRC)
1801         mv y.tab.c $(.TARGET)
1802 \&.c.o            :
1803         cc -c $(.IMPSRC)
1804 \&.o.out          :
1805         cc -o $(.TARGET) $(.IMPSRC)
1806 .DE
1807 and the single file
1808 .CW jive.l .
1809 If you were to type
1810 .CW "pmake -rd ms jive.out" ,'' ``
1811 you would get the following output for
1812 .CW jive.out :
1813 .DS
1814 Suff_FindDeps (jive.out)
1815         trying jive.o...not there
1816         trying jive.c...not there
1817         trying jive.y...not there
1818         trying jive.l...got it
1819         applying .l -> .c to "jive.l"
1820         applying .c -> .o to "jive.c"
1821         applying .o -> .out to "jive.o"
1822 .DE
1823 and this is why: PMake starts with the target
1824 .CW jive.out ,
1825 figures out its suffix
1826 .CW .out ) (
1827 and looks for things it can transform to a
1828 .CW .out
1829 file. In this case, it only finds
1830 .CW .o ,
1831 so it looks for the file
1832 .CW jive.o .
1833 It fails to find it, so it looks for transformations into a
1834 .CW .o
1835 file. Again it has only one choice:
1836 .CW .c .
1837 So it looks for
1838 .CW jive.c
1839 and, as you know, fails to find it. At this point it has two choices:
1840 it can create the
1841 .CW .c
1842 file from either a
1843 .CW .y
1844 file or a
1845 .CW .l
1846 file. Since
1847 .CW .y
1848 came first on the
1850 line, it checks for
1851 .CW jive.y
1852 first, but can't find it, so it looks for
1853 .CW jive.l
1854 and, lo and behold, there it is.
1855 At this point, it has defined a transformation path as follows:
1856 .CW .l
1857 \(->
1858 .CW .c
1859 \(->
1860 .CW .o
1861 \(->
1862 .CW .out
1863 and applies the transformation rules accordingly. For completeness,
1864 and to give you a better idea of what PMake actually did with this
1865 three-step transformation, this is what PMake printed for the rest of
1866 the process:
1867 .DS
1868 Suff_FindDeps (jive.o)
1869         using existing source jive.c
1870         applying .c -> .o to "jive.c"
1871 Suff_FindDeps (jive.c)
1872         using existing source jive.l
1873         applying .l -> .c to "jive.l"
1874 Suff_FindDeps (jive.l)
1875 Examining jive.l...modified 17:16:01 Oct 4, 1987...up-to-date
1876 Examining jive.c...non-existent...out-of-date
1877 --- jive.c ---
1878 lex jive.l
1879 \&.\|.\|. meaningless lex output deleted .\|.\|.
1880 mv lex.yy.c jive.c
1881 Examining jive.o...non-existent...out-of-date
1882 --- jive.o ---
1883 cc -c jive.c
1884 Examining jive.out...non-existent...out-of-date
1885 --- jive.out ---
1886 cc -o jive.out jive.o
1887 .DE
1888 .LP
1889 One final question remains: what does PMake do with targets that have
1890 no known suffix? PMake simply pretends it actually has a known suffix
1891 and searches for transformations accordingly.
1892 The suffix it chooses is the source for the
1893 .CW .NULL
1894 .Ix 0 ref .NULL
1895 target mentioned later. In the system makefile, 
1896 .CW .out
1897 is chosen as the ``null suffix''
1898 .Ix 0 def suffix null
1899 .Ix 0 def "null suffix"
1900 because most people use PMake to create programs. You are, however,
1901 free and welcome to change it to a suffix of your own choosing.
1902 The null suffix is ignored, however, when PMake is in compatibility
1903 mode (see chapter 4).
1904 .xH 2 Including Other Makefiles
1905 .Ix 0 def makefile inclusion
1906 .Rd 2
1907 .LP
1908 Just as for programs, it is often useful to extract certain parts of a
1909 makefile into another file and just include it in other makefiles
1910 somehow. Many compilers allow you say something like
1911 .DS
1912 #include "defs.h"
1913 .DE
1914 to include the contents of
1915 .CW defs.h
1916 in the source file. PMake allows you to do the same thing for
1917 makefiles, with the added ability to use variables in the filenames.
1918 An include directive in a makefile looks either like this:
1919 .DS
1920 #include <file>
1921 .DE
1922 or this
1923 .DS
1924 #include "file"
1925 .DE
1926 The difference between the two is where PMake searches for the file:
1927 the first way, PMake will look for
1928 the file only in the system makefile directory (or directories)
1929 (to find out what that directory is, give PMake the
1930 .B \-h
1931 flag).
1932 .Ix 0 ref flags -h
1933 The system makefile directory search path can be overridden via the
1934 .B \-m
1935 option.
1936 .Ix 0 ref flags -m
1937 For files in double-quotes, the search is more complex:
1938 .RS
1939 .IP 1)
1940 The directory of the makefile that's including the file.
1941 .IP 2)
1942 The current directory (the one in which you invoked PMake).
1943 .IP 3)
1944 The directories given by you using
1945 .B \-I
1946 flags, in the order in which you gave them.
1947 .IP 4)
1948 Directories given by
1949 .CW .PATH
1950 dependency lines (see chapter 4).
1951 .IP 5)
1952 The system makefile directory.
1953 .RE
1954 .LP
1955 in that order.
1956 .LP
1957 You are free to use PMake variables in the filename\*-PMake will
1958 expand them before searching for the file. You must specify the
1959 searching method with either angle brackets or double-quotes
1960 .I outside
1961 of a variable expansion. I.e. the following
1962 .DS
1963 SYSTEM  = <command.mk>
1965 #include $(SYSTEM)
1966 .DE
1967 won't work.
1968 .xH 2 Saving Commands
1969 .LP
1970 .Ix 0 def ...
1971 There may come a time when you will want to save certain commands to
1972 be executed when everything else is done. For instance: you're
1973 making several different libraries at one time and you want to create the
1974 members in parallel. Problem is,
1975 .CW ranlib
1976 is another one of those programs that can't be run more than once in
1977 the same directory at the same time (each one creates a file called
1978 .CW __.SYMDEF
1979 into which it stuffs information for the linker to use. Two of them
1980 running at once will overwrite each other's file and the result will
1981 be garbage for both parties). You might want a way to save the ranlib
1982 commands til the end so they can be run one after the other, thus
1983 keeping them from trashing each other's file. PMake allows you to do
1984 this by inserting an ellipsis (``.\|.\|.'') as a command between
1985 commands to be run at once and those to be run later.
1986 .LP
1987 So for the
1988 .CW ranlib
1989 case above, you might do this:
1990 .Rd 5
1991 .DS
1992 lib1.a          : $(LIB1OBJS)
1993         rm -f $(.TARGET)
1994         ar cr $(.TARGET) $(.ALLSRC)
1995         ...
1996         ranlib $(.TARGET)
1998 lib2.a          : $(LIB2OBJS)
1999         rm -f $(.TARGET)
2000         ar cr $(.TARGET) $(.ALLSRC)
2001         ...
2002         ranlib $(.TARGET)
2003 .DE
2004 .Ix 0 ref variable local .TARGET
2005 .Ix 0 ref variable local .ALLSRC
2006 This would save both
2007 .DS
2008 ranlib $(.TARGET)
2009 .DE
2010 commands until the end, when they would run one after the other
2011 (using the correct value for the
2012 .CW .TARGET
2013 variable, of course).
2014 .LP
2015 Commands saved in this manner are only executed if PMake manages to
2016 re-create everything without an error.
2017 .xH 2 Target Attributes
2018 .LP
2019 PMake allows you to give attributes to targets by means of special
2020 sources. Like everything else PMake uses, these sources begin with a
2021 period and are made up of all upper-case letters. There are various
2022 reasons for using them, and I will try to give examples for most of
2023 them. Others you'll have to find uses for yourself. Think of it as ``an
2024 exercise for the reader.'' By placing one (or more) of these as a source on a
2025 dependency line, you are ``marking the target(s) with that
2026 attribute.'' That's just the way I phrase it, so you know.
2027 .LP
2028 Any attributes given as sources for a transformation rule are applied
2029 to the target of the transformation rule when the rule is applied.
2030 .Ix 0 def attributes
2031 .Ix 0 ref source
2032 .Ix 0 ref target
2033 .nr pw 12
2034 .IP .DONTCARE \n(pw
2035 .Ix 0 def attributes .DONTCARE
2036 .Ix 0 def .DONTCARE
2037 If a target is marked with this attribute and PMake can't figure out
2038 how to create it, it will ignore this fact and assume the file isn't
2039 really needed or actually exists and PMake just can't find it. This may prove
2040 wrong, but the error will be noted later on, not when PMake tries to create
2041 the target so marked. This attribute also prevents PMake from
2042 attempting to touch the target if it is given the
2043 .B \-t
2044 flag.
2045 .Ix 0 ref flags -t
2046 .IP .EXEC \n(pw
2047 .Ix 0 def attributes .EXEC
2048 .Ix 0 def .EXEC
2049 This attribute causes its shell script to be executed while having no
2050 effect on targets that depend on it. This makes the target into a sort
2051 of subroutine.  An example. Say you have some LISP files that need to
2052 be compiled and loaded into a LISP process. To do this, you echo LISP
2053 commands into a file and execute a LISP with this file as its input
2054 when everything's done. Say also that you have to load other files
2055 from another system before you can compile your files and further,
2056 that you don't want to go through the loading and dumping unless one
2057 of
2058 .I your
2059 files has changed. Your makefile might look a little bit
2060 like this (remember, this is an educational example, and don't worry
2061 about the
2063 rule, all will soon become clear, grasshopper):
2064 .DS
2065 system          : init a.fasl b.fasl c.fasl
2066         for i in $(.ALLSRC);
2067         do
2068                 echo -n '(load "' >> input
2069                 echo -n ${i} >> input
2070                 echo '")' >> input
2071         done
2072         echo '(dump "$(.TARGET)")' >> input
2073         lisp < input
2075 a.fasl          : a.l init COMPILE
2076 b.fasl          : b.l init COMPILE
2077 c.fasl          : c.l init COMPILE
2078 COMPILE         : .USE
2079         echo '(compile "$(.ALLSRC)")' >> input
2080 init            : .EXEC
2081         echo '(load-system)' > input
2082 .DE
2083 .Ix 0 ref .USE
2084 .Ix 0 ref attributes .USE
2085 .Ix 0 ref variable local .ALLSRC
2086 .IP "\&"
2087 .CW .EXEC
2088 sources, don't appear in the local variables of targets that depend on
2089 them (nor are they touched if PMake is given the
2090 .B \-t
2091 flag).
2092 .Ix 0 ref flags -t
2093 Note that all the rules, not just that for
2094 .CW system ,
2095 include
2096 .CW init
2097 as a source. This is because none of the other targets can be made
2098 until
2099 .CW init
2100 has been made, thus they depend on it.
2101 .IP .EXPORT \n(pw
2102 .Ix 0 def attributes .EXPORT
2103 .Ix 0 def .EXPORT
2104 This is used to mark those targets whose creation should be sent to
2105 another machine if at all possible. This may be used by some
2106 exportation schemes if the exportation is expensive. You should ask
2107 your system administrator if it is necessary.
2108 .IP .EXPORTSAME \n(pw
2109 .Ix 0 def attributes .EXPORTSAME
2110 .Ix 0 def .EXPORTSAME
2111 Tells the export system that the job should be exported to a machine
2112 of the same architecture as the current one. Certain operations (e.g.
2113 running text through
2114 .CW nroff )
2115 can be performed the same on any architecture (CPU and
2116 operating system type), while others (e.g. compiling a program with
2117 .CW cc )
2118 must be performed on a machine with the same architecture. Not all
2119 export systems will support this attribute.
2120 .IP .IGNORE \n(pw
2121 .Ix 0 def attributes .IGNORE
2122 .Ix 0 def .IGNORE attribute
2123 Giving a target the
2124 .CW .IGNORE
2125 attribute causes PMake to ignore errors from any of the target's commands, as
2126 if they all had `\-' before them.
2127 .IP .INVISIBLE \n(pw
2128 .Ix 0 def attributes .INVISIBLE
2129 .Ix 0 def .INVISIBLE
2130 This allows you to specify one target as a source for another without
2131 the one affecting the other's local variables. Useful if, say, you
2132 have a makefile that creates two programs, one of which is used to
2133 create the other, so it must exist before the other is created. You
2134 could say
2135 .DS
2136 prog1           : $(PROG1OBJS) prog2 MAKEINSTALL
2137 prog2           : $(PROG2OBJS) .INVISIBLE MAKEINSTALL
2138 .DE
2139 where
2141 is some complex .USE rule (see below) that depends on the
2142 .Ix 0 ref .USE
2143 .CW .ALLSRC
2144 variable containing the right things. Without the
2146 attribute for
2147 .CW prog2 ,
2148 the
2150 rule couldn't be applied. This is not as useful as it should be, and
2151 the semantics may change (or the whole thing go away) in the
2152 not-too-distant future.
2153 .IP .JOIN \n(pw
2154 .Ix 0 def attributes .JOIN
2155 .Ix 0 def .JOIN
2156 This is another way to avoid performing some operations in parallel
2157 while permitting everything else to be done so. Specifically it
2158 forces the target's shell script to be executed only if one or more of the
2159 sources was out-of-date. In addition, the target's name,
2160 in both its
2161 .CW .TARGET
2162 variable and all the local variables of any target that depends on it,
2163 is replaced by the value of its
2164 .CW .ALLSRC
2165 variable.
2166 As an example, suppose you have a program that has four libraries that
2167 compile in the same directory along with, and at the same time as, the
2168 program. You again have the problem with
2169 .CW ranlib
2170 that I mentioned earlier, only this time it's more severe: you
2171 can't just put the ranlib off to the end since the program
2172 will need those libraries before it can be re-created. You can do
2173 something like this:
2174 .DS
2175 program         : $(OBJS) libraries
2176         cc -o $(.TARGET) $(.ALLSRC)
2178 libraries       : lib1.a lib2.a lib3.a lib4.a .JOIN
2179         ranlib $(.OODATE)
2180 .DE
2181 .Ix 0 ref variable local .TARGET
2182 .Ix 0 ref variable local .ALLSRC
2183 .Ix 0 ref variable local .OODATE
2184 .Ix 0 ref .TARGET
2185 .Ix 0 ref .ALLSRC
2186 .Ix 0 ref .OODATE
2187 In this case, PMake will re-create the
2188 .CW $(OBJS)
2189 as necessary, along with
2190 .CW lib1.a ,
2191 .CW lib2.a ,
2192 .CW lib3.a
2193 and
2194 .CW lib4.a .
2195 It will then execute
2196 .CW ranlib
2197 on any library that was changed and set
2198 .CW program 's
2199 .CW .ALLSRC
2200 variable to contain what's in
2201 .CW $(OBJS)
2202 followed by
2203 .CW "lib1.a lib2.a lib3.a lib4.a" .'' ``
2204 In case you're wondering, it's called
2205 .CW .JOIN
2206 because it joins together different threads of the ``input graph'' at
2207 the target marked with the attribute.
2208 Another aspect of the .JOIN attribute is it keeps the target from
2209 being created if the
2210 .B \-t
2211 flag was given.
2212 .Ix 0 ref flags -t
2213 .IP .MAKE \n(pw
2214 .Ix 0 def attributes .MAKE
2215 .Ix 0 def .MAKE
2216 The
2217 .CW .MAKE
2218 attribute marks its target as being a recursive invocation of PMake.
2219 This forces PMake to execute the script associated with the target (if
2220 it's out-of-date) even if you gave the
2221 .B \-n
2222 or
2223 .B \-t
2224 flag. By doing this, you can start at the top of a system and type
2225 .DS
2226 pmake -n
2227 .DE
2228 and have it descend the directory tree (if your makefiles are set up
2229 correctly), printing what it would have executed if you hadn't
2230 included the
2231 .B \-n
2232 flag.
2233 .IP .NOEXPORT \n(pw
2234 .Ix 0 def attributes .NOEXPORT
2235 .Ix 0 def .NOEXPORT attribute
2236 If possible, PMake will attempt to export the creation of all targets to
2237 another machine (this depends on how PMake was configured). Sometimes,
2238 the creation is so simple, it is pointless to send it to another
2239 machine. If you give the target the
2241 attribute, it will be run locally, even if you've given PMake the
2242 .B "\-L 0"
2243 flag.
2244 .IP .NOTMAIN \n(pw
2245 .Ix 0 def attributes .NOTMAIN
2246 .Ix 0 def .NOTMAIN
2247 Normally, if you do not specify a target to make in any other way,
2248 PMake will take the first target on the first dependency line of a
2249 makefile as the target to create. That target is known as the ``Main
2250 Target'' and is labeled as such if you print the dependencies out
2251 using the
2252 .B \-p
2253 flag.
2254 .Ix 0 ref flags -p
2255 Giving a target this attribute tells PMake that the target is
2256 definitely
2257 .I not
2258 the Main Target.
2259 This allows you to place targets in an included makefile and
2260 have PMake create something else by default.
2261 .IP .PRECIOUS \n(pw
2262 .Ix 0 def attributes .PRECIOUS
2263 .Ix 0 def .PRECIOUS attribute
2264 When PMake is interrupted (you type control-C at the keyboard), it
2265 will attempt to clean up after itself by removing any half-made
2266 targets. If a target has the
2268 attribute, however, PMake will leave it alone. An additional side
2269 effect of the `::' operator is to mark the targets as
2270 .CW .PRECIOUS .
2271 .Ix 0 ref operator double-colon
2272 .Ix 0 ref ::
2273 .IP .SILENT \n(pw
2274 .Ix 0 def attributes .SILENT
2275 .Ix 0 def .SILENT attribute
2276 Marking a target with this attribute keeps its commands from being
2277 printed when they're executed, just as if they had an `@' in front of them.
2278 .IP .USE \n(pw
2279 .Ix 0 def attributes .USE
2280 .Ix 0 def .USE
2281 By giving a target this attribute, you turn it into PMake's equivalent
2282 of a macro. When the target is used as a source for another target,
2283 the other target acquires the commands, sources and attributes (except
2284 .CW .USE )
2285 of the source.
2286 If the target already has commands, the
2287 .CW .USE
2288 target's commands are added to the end. If more than one .USE-marked
2289 source is given to a target, the rules are applied sequentially.
2290 .IP "\&" \n(pw
2291 The typical .USE rule (as I call them) will use the sources of the
2292 target to which it is applied (as stored in the
2293 .CW .ALLSRC
2294 variable for the target) as its ``arguments,'' if you will.
2295 For example, you probably noticed that the commands for creating
2296 .CW lib1.a
2297 and
2298 .CW lib2.a
2299 in the example in section 3.3
2300 .Rm 5 3.3
2301 were exactly the same. You can use the
2302 .CW .USE
2303 attribute to eliminate the repetition, like so:
2304 .DS
2305 lib1.a          : $(LIB1OBJS) MAKELIB
2306 lib2.a          : $(LIB2OBJS) MAKELIB
2308 MAKELIB         : .USE
2309         rm -f $(.TARGET)
2310         ar cr $(.TARGET) $(.ALLSRC)
2311         ...
2312         ranlib $(.TARGET)
2313 .DE
2314 .Ix 0 ref variable local .TARGET
2315 .Ix 0 ref variable local .ALLSRC
2316 .IP "\&" \n(pw
2317 Several system makefiles (not to be confused with The System Makefile)
2318 make use of these  .USE rules to make your
2319 life easier (they're in the default, system makefile directory...take a look).
2320 Note that the .USE rule source itself
2321 .CW MAKELIB ) (
2322 does not appear in any of the targets's local variables.
2323 There is no limit to the number of times I could use the
2325 rule. If there were more libraries, I could continue with
2326 .CW "lib3.a : $(LIB3OBJS) MAKELIB" '' ``
2327 and so on and so forth.
2328 .xH 2 Special Targets
2329 .LP
2330 As there were in Make, so there are certain targets that have special
2331 meaning to PMake. When you use one on a dependency line, it is the
2332 only target that may appear on the left-hand-side of the operator.
2333 .Ix 0 ref target
2334 .Ix 0 ref operator
2335 As for the attributes and variables, all the special targets
2336 begin with a period and consist of upper-case letters only.
2337 I won't describe them all in detail because some of them are rather
2338 complex and I'll describe them in more detail than you'll want in
2339 chapter 4.
2340 The targets are as follows:
2341 .nr pw 10
2342 .IP .BEGIN \n(pw
2343 .Ix 0 def .BEGIN
2344 Any commands attached to this target are executed before anything else
2345 is done. You can use it for any initialization that needs doing.
2346 .IP .DEFAULT \n(pw
2347 .Ix 0 def .DEFAULT
2348 This is sort of a .USE rule for any target (that was used only as a
2349 source) that PMake can't figure out any other way to create. It's only
2350 ``sort of'' a .USE rule because only the shell script attached to the
2352 target is used. The
2353 .CW .IMPSRC
2354 variable of a target that inherits
2355 .CW .DEFAULT 's
2356 commands is set to the target's own name.
2357 .Ix 0 ref .IMPSRC
2358 .Ix 0 ref variable local .IMPSRC
2359 .IP .END \n(pw
2360 .Ix 0 def .END
2361 This serves a function similar to
2362 .CW .BEGIN ,
2363 in that commands attached to it are executed once everything has been
2364 re-created (so long as no errors occurred). It also serves the extra
2365 function of being a place on which PMake can hang commands you put off
2366 to the end. Thus the script for this target will be executed before
2367 any of the commands you save with the ``.\|.\|.''.
2368 .Ix 0 ref ...
2369 .IP .EXPORT \n(pw
2370 The sources for this target are passed to the exportation system compiled
2371 into PMake. Some systems will use these sources to configure
2372 themselves. You should ask your system administrator about this.
2373 .IP .IGNORE \n(pw
2374 .Ix 0 def .IGNORE target
2375 .Ix 0 ref .IGNORE attribute
2376 .Ix 0 ref attributes .IGNORE
2377 This target marks each of its sources with the
2378 .CW .IGNORE
2379 attribute. If you don't give it any sources, then it is like
2380 giving the
2381 .B \-i
2382 flag when you invoke PMake \*- errors are ignored for all commands.
2383 .Ix 0 ref flags -i
2384 .IP .INCLUDES \n(pw
2385 .Ix 0 def .INCLUDES target
2386 .Ix 0 def variable global .INCLUDES
2387 .Ix 0 def .INCLUDES variable
2388 The sources for this target are taken to be suffixes that indicate a
2389 file that can be included in a program source file.
2390 The suffix must have already been declared with
2392 (see below).
2393 Any suffix so marked will have the directories on its search path
2394 (see
2395 .CW .PATH ,
2396 below) placed in the
2398 variable, each preceded by a
2399 .B \-I
2400 flag. This variable can then be used as an argument for the compiler
2401 in the normal fashion. The
2402 .CW .h
2403 suffix is already marked in this way in the system makefile.
2404 .Ix 0 ref makefile system
2405 E.g. if you have
2406 .DS
2407 \&.SUFFIXES       : .bitmap
2408 \&.PATH.bitmap    : /usr/local/X/lib/bitmaps
2409 \&.INCLUDES       : .bitmap
2410 .DE
2411 PMake will place
2412 .CW "-I/usr/local/X/lib/bitmaps" '' ``
2413 in the
2415 variable and you can then say
2416 .DS
2417 cc $(.INCLUDES) -c xprogram.c
2418 .DE
2419 (Note: the
2421 variable is not actually filled in until the entire makefile has been read.)
2422 .IP .INTERRUPT \n(pw
2423 .Ix 0 def .INTERRUPT
2424 When PMake is interrupted,
2425 it will execute the commands in the script for this target, if it
2426 exists.
2427 .IP .LIBS \n(pw
2428 .Ix 0 def .LIBS target
2429 .Ix 0 def .LIBS variable
2430 .Ix 0 def variable global .LIBS
2431 This does for libraries what
2433 does for include files, except the flag used is
2434 .B \-L ,
2435 as required by those linkers that allow you to tell them where to find
2436 libraries. The variable used is
2437 .CW .LIBS .
2438 Be forewarned that PMake may not have been compiled to do this if the
2439 linker on your system doesn't accept the
2440 .B \-L
2441 flag, though the
2442 .CW .LIBS
2443 variable will always be defined once the makefile has been read.
2444 .IP .MAIN \n(pw
2445 .Ix 0 def .MAIN
2446 If you didn't give a target (or targets) to create when you invoked
2447 PMake, it will take the sources of this target as the targets to
2448 create.
2449 .IP .MAKEFLAGS \n(pw
2450 .Ix 0 def .MAKEFLAGS target
2451 This target provides a way for you to always specify flags for PMake
2452 when the makefile is used. The flags are just as they would be typed
2453 to the shell (except you can't use shell variables unless they're in
2454 the environment),
2455 though the
2456 .B \-f
2457 and
2458 .B \-r
2459 flags have no effect.
2460 .IP .NULL \n(pw
2461 .Ix 0 def .NULL
2462 .Ix 0 ref suffix null
2463 .Ix 0 ref "null suffix"
2464 This allows you to specify what suffix PMake should pretend a file has
2465 if, in fact, it has no known suffix. Only one suffix may be so
2466 designated. The last source on the dependency line is the suffix that
2467 is used (you should, however, only give one suffix.\|.\|.).
2468 .IP .PATH \n(pw
2469 .Ix 0 def .PATH
2470 If you give sources for this target, PMake will take them as
2471 directories in which to search for files it cannot find in the current
2472 directory. If you give no sources, it will clear out any directories
2473 added to the search path before. Since the effects of this all get
2474 very complex, I'll leave it til chapter four to give you a complete
2475 explanation.
2476 .IP .PATH\fIsuffix\fP \n(pw
2477 .Ix 0 ref .PATH
2478 This does a similar thing to
2479 .CW .PATH ,
2480 but it does it only for files with the given suffix. The suffix must
2481 have been defined already. Look at
2482 .B "Search Paths"
2483 (section 4.1)
2484 .Rm 6 4.1
2485 for more information.
2486 .IP .PRECIOUS \n(pw
2487 .Ix 0 def .PRECIOUS target
2488 .Ix 0 ref .PRECIOUS attribute
2489 .Ix 0 ref attributes .PRECIOUS
2490 Similar to
2491 .CW .IGNORE ,
2492 this gives the
2494 attribute to each source on the dependency line, unless there are no
2495 sources, in which case the
2497 attribute is given to every target in the file.
2498 .IP .RECURSIVE \n(pw
2499 .Ix 0 def .RECURSIVE
2500 .Ix 0 ref attributes .MAKE
2501 .Ix 0 ref .MAKE
2502 This target applies the
2503 .CW .MAKE
2504 attribute to all its sources. It does nothing if you don't give it any sources.
2505 .IP .SHELL \n(pw
2506 .Ix 0 def .SHELL
2507 PMake is not constrained to only using the Bourne shell to execute
2508 the commands you put in the makefile. You can tell it some other shell
2509 to use with this target. Check out
2510 .B "A Shell is a Shell is a Shell"
2511 (section 4.4)
2512 .Rm 7 4.4
2513 for more information.
2514 .IP .SILENT \n(pw
2515 .Ix 0 def .SILENT target
2516 .Ix 0 ref .SILENT attribute
2517 .Ix 0 ref attributes .SILENT
2518 When you use
2519 .CW .SILENT
2520 as a target, it applies the
2521 .CW .SILENT
2522 attribute to each of its sources. If there are no sources on the
2523 dependency line, then it is as if you gave PMake the
2524 .B \-s
2525 flag and no commands will be echoed.
2526 .IP .SUFFIXES \n(pw
2527 .Ix 0 def .SUFFIXES
2528 This is used to give new file suffixes for PMake to handle. Each
2529 source is a suffix PMake should recognize. If you give a
2531 dependency line with no sources, PMake will forget about all the
2532 suffixes it knew (this also nukes the null suffix).
2533 For those targets that need to have suffixes defined, this is how you do it.
2534 .LP
2535 In addition to these targets, a line of the form
2536 .DS
2537 \fIattribute\fP : \fIsources\fP
2538 .DE
2539 applies the
2540 .I attribute
2541 to all the targets listed as
2542 .I sources .
2543 .xH 2 Modifying Variable Expansion
2544 .LP
2545 .Ix 0 def variable expansion modified
2546 .Ix 0 ref variable expansion
2547 .Ix 0 def variable modifiers
2548 Variables need not always be expanded verbatim. PMake defines several
2549 modifiers that may be applied to a variable's value before it is
2550 expanded. You apply a modifier by placing it after the variable name
2551 with a colon between the two, like so:
2552 .DS
2553 ${\fIVARIABLE\fP:\fImodifier\fP}
2554 .DE
2555 Each modifier is a single character followed by something specific to
2556 the modifier itself.
2557 You may apply as many modifiers as you want \*- each one is applied to
2558 the result of the previous and is separated from the previous by
2559 another colon.
2560 .LP
2561 There are seven ways to modify a variable's expansion, most of which
2562 come from the C shell variable modification characters:
2563 .RS
2564 .IP "M\fIpattern\fP"
2565 .Ix 0 def :M
2566 .Ix 0 def modifier match
2567 This is used to select only those words (a word is a series of
2568 characters that are neither spaces nor tabs) that match the given
2569 .I pattern .
2570 The pattern is a wildcard pattern like that used by the shell, where
2571 .CW *
2572 means 0 or more characters of any sort;
2573 .CW ?
2574 is any single character;
2575 .CW [abcd]
2576 matches any single character that is either `a', `b', `c' or `d'
2577 (there may be any number of characters between the brackets);
2578 .CW [0-9]
2579 matches any single character that is between `0' and `9' (i.e. any
2580 digit. This form may be freely mixed with the other bracket form), and
2581 `\\' is used to escape any of the characters `*', `?', `[' or `:',
2582 leaving them as regular characters to match themselves in a word.
2583 For example, the system makefile
2584 .CW <makedepend.mk>
2585 uses
2586 .CW "$(CFLAGS:M-[ID]*)" '' ``
2587 to extract all the
2588 .CW \-I
2589 and
2590 .CW \-D
2591 flags that would be passed to the C compiler. This allows it to
2592 properly locate include files and generate the correct dependencies.
2593 .IP "N\fIpattern\fP"
2594 .Ix 0 def :N
2595 .Ix 0 def modifier nomatch
2596 This is identical to
2597 .CW :M
2598 except it substitutes all words that don't match the given pattern.
2599 .IP "S/\fIsearch-string\fP/\fIreplacement-string\fP/[g]"
2600 .Ix 0 def :S
2601 .Ix 0 def modifier substitute
2602 Causes the first occurrence of
2603 .I search-string
2604 in the variable to be replaced by
2605 .I replacement-string ,
2606 unless the
2607 .CW g
2608 flag is given at the end, in which case all occurrences of the string
2609 are replaced. The substitution is performed on each word in the
2610 variable in turn. If 
2611 .I search-string
2612 begins with a
2613 .CW ^ ,
2614 the string must match starting at the beginning of the word. If
2615 .I search-string
2616 ends with a
2617 .CW $ ,
2618 the string must match to the end of the word (these two may be
2619 combined to force an exact match). If a backslash precedes these two
2620 characters, however, they lose their special meaning. Variable
2621 expansion also occurs in the normal fashion inside both the
2622 .I search-string
2623 and the
2624 .I replacement-string ,
2625 .B except
2626 that a backslash is used to prevent the expansion of a
2627 .CW $ ,
2628 not another dollar sign, as is usual.
2629 Note that
2630 .I search-string
2631 is just a string, not a pattern, so none of the usual
2632 regular-expression/wildcard characters have any special meaning save
2633 .CW ^
2634 and
2635 .CW $ .
2636 In the replacement string,
2637 the
2638 .CW &
2639 character is replaced by the
2640 .I search-string
2641 unless it is preceded by a backslash.
2642 You are allowed to use any character except
2643 colon or exclamation point to separate the two strings. This so-called
2644 delimiter character may be placed in either string by preceding it
2645 with a backslash.
2646 .IP T
2647 .Ix 0 def :T
2648 .Ix 0 def modifier tail
2649 Replaces each word in the variable expansion by its last
2650 component (its ``tail''). For example, given
2651 .DS
2652 OBJS = ../lib/a.o b /usr/lib/libm.a
2653 TAILS = $(OBJS:T)
2654 .DE
2655 the variable
2656 .CW TAILS
2657 would expand to
2658 .CW "a.o b libm.a" .'' ``
2659 .IP H
2660 .Ix 0 def :H
2661 .Ix 0 def modifier head
2662 This is similar to
2663 .CW :T ,
2664 except that every word is replaced by everything but the tail (the
2665 ``head''). Using the same definition of
2666 .CW OBJS ,
2667 the string
2668 .CW "$(OBJS:H)" '' ``
2669 would expand to
2670 .CW "../lib /usr/lib" .'' ``
2671 Note that the final slash on the heads is removed and
2672 anything without a head is replaced by the empty string.
2673 .IP E
2674 .Ix 0 def :E
2675 .Ix 0 def modifier extension
2676 .Ix 0 def modifier suffix
2677 .Ix 0 ref suffix "variable modifier"
2678 .CW :E
2679 replaces each word by its suffix (``extension''). So
2680 .CW "$(OBJS:E)" '' ``
2681 would give you
2682 .CW ".o .a" .'' ``
2683 .IP R
2684 .Ix 0 def :R
2685 .Ix 0 def modifier root
2686 .Ix 0 def modifier base
2687 This replaces each word by everything but the suffix (the ``root'' of
2688 the word).
2689 .CW "$(OBJS:R)" '' ``
2690 expands to ``
2691 .CW "../lib/a b /usr/lib/libm" .''
2692 .RE
2693 .LP
2694 In addition, the System V style of substitution is also supported.
2695 This looks like:
2696 .DS
2697 $(\fIVARIABLE\fP:\fIsearch-string\fP=\fIreplacement\fP)
2698 .DE
2699 It must be the last modifier in the chain. The search is anchored at
2700 the end of each word, so only suffixes or whole words may be replaced.
2701 .xH 2 More on Debugging
2702 .xH 2 More Exercises
2703 .IP (3.1)
2704 You've got a set programs, each of which is created from its own
2705 assembly-language source file (suffix
2706 .CW .asm ).
2707 Each program can be assembled into two versions, one with error-checking
2708 code assembled in and one without. You could assemble them into files
2709 with different suffixes
2710 .CW .eobj \& (
2711 and
2712 .CW .obj ,
2713 for instance), but your linker only understands files that end in
2714 .CW .obj .
2715 To top it all off, the final executables
2716 .I must
2717 have the suffix
2718 .CW .exe .
2719 How can you still use transformation rules to make your life easier
2720 (Hint: assume the error-checking versions have
2721 .CW ec
2722 tacked onto their prefix)?
2723 .IP (3.2)
2724 Assume, for a moment or two, you want to perform a sort of
2725 ``indirection'' by placing the name of a variable into another one,
2726 then you want to get the value of the first by expanding the second
2727 somehow. Unfortunately, PMake doesn't allow constructs like
2728 .DS I
2729 $($(FOO))
2730 .DE
2731 What do you do? Hint: no further variable expansion is performed after
2732 modifiers are applied, thus if you cause a $ to occur in the
2733 expansion, that's what will be in the result.
2734 .xH 1 PMake for Gods
2735 .LP
2736 This chapter is devoted to those facilities in PMake that allow you to
2737 do a great deal in a makefile with very little work, as well as do
2738 some things you couldn't do in Make without a great deal of work (and
2739 perhaps the use of other programs). The problem with these features,
2740 is they must be handled with care, or you will end up with a mess.
2741 .LP
2742 Once more, I assume a greater familiarity with
2743 .UX
2744 or Sprite than I did in the previous two chapters.
2745 .xH 2 Search Paths
2746 .Rd 6
2747 .LP
2748 PMake supports the dispersal of files into multiple directories by
2749 allowing you to specify places to look for sources with
2750 .CW .PATH
2751 targets in the makefile. The directories you give as sources for these
2752 targets make up a ``search path.'' Only those files used exclusively
2753 as sources are actually sought on a search path, the assumption being
2754 that anything listed as a target in the makefile can be created by the
2755 makefile and thus should be in the current directory.
2756 .LP
2757 There are two types of search paths
2758 in PMake: one is used for all types of files (including included
2759 makefiles) and is specified with a plain
2760 .CW .PATH
2761 target (e.g.
2762 .CW ".PATH : RCS" ''), ``
2763 while the other is specific to a certain type of file, as indicated by
2764 the file's suffix. A specific search path is indicated by immediately following
2765 the
2766 .CW .PATH
2767 with the suffix of the file. For instance
2768 .DS
2769 \&.PATH.h         : /sprite/lib/include /sprite/att/lib/include
2770 .DE
2771 would tell PMake to look in the directories
2772 .CW /sprite/lib/include
2773 and
2774 .CW /sprite/att/lib/include
2775 for any files whose suffix is
2776 .CW .h .
2777 .LP
2778 The current directory is always consulted first to see if a file
2779 exists. Only if it cannot be found there are the directories in the
2780 specific search path, followed by those in the general search path,
2781 consulted.
2782 .LP
2783 A search path is also used when expanding wildcard characters. If the
2784 pattern has a recognizable suffix on it, the path for that suffix will
2785 be used for the expansion. Otherwise the default search path is employed.
2786 .LP
2787 When a file is found in some directory other than the current one, all
2788 local variables that would have contained the target's name
2789 .CW .ALLSRC , (
2790 and
2791 .CW .IMPSRC )
2792 will instead contain the path to the file, as found by PMake.
2793 Thus if you have a file
2794 .CW ../lib/mumble.c
2795 and a makefile
2796 .DS
2797 \&.PATH.c         : ../lib
2798 mumble          : mumble.c
2799         $(CC) -o $(.TARGET) $(.ALLSRC)
2800 .DE
2801 the command executed to create
2802 .CW mumble
2803 would be
2804 .CW "cc -o mumble ../lib/mumble.c" .'' ``
2805 (As an aside, the command in this case isn't strictly necessary, since
2806 it will be found using transformation rules if it isn't given. This is because
2807 .CW .out
2808 is the null suffix by default and a transformation exists from
2809 .CW .c
2810 to
2811 .CW .out .
2812 Just thought I'd throw that in.)
2813 .LP
2814 If a file exists in two directories on the same search path, the file
2815 in the first directory on the path will be the one PMake uses. So if
2816 you have a large system spread over many directories, it would behoove
2817 you to follow a naming convention that avoids such conflicts.
2818 .LP
2819 Something you should know about the way search paths are implemented
2820 is that each directory is read, and its contents cached, exactly once
2821 \&\*- when it is first encountered \*- so any changes to the
2822 directories while PMake is running will not be noted when searching
2823 for implicit sources, nor will they be found when PMake attempts to
2824 discover when the file was last modified, unless the file was created in the
2825 current directory. While people have suggested that PMake should read
2826 the directories each time, my experience suggests that the caching seldom
2827 causes problems. In addition, not caching the directories slows things
2828 down enormously because of PMake's attempts to apply transformation
2829 rules through non-existent files \*- the number of extra file-system
2830 searches is truly staggering, especially if many files without
2831 suffixes are used and the null suffix isn't changed from
2832 .CW .out .
2833 .xH 2 Archives and Libraries
2834 .LP
2835 .UX
2836 and Sprite allow you to merge files into an archive using the
2837 .CW ar
2838 command. Further, if the files are relocatable object files, you can
2839 run
2840 .CW ranlib
2841 on the archive and get yourself a library that you can link into any
2842 program you want. The main problem with archives is they double the
2843 space you need to store the archived files, since there's one copy in
2844 the archive and one copy out by itself. The problem with libraries is
2845 you usually think of them as
2846 .CW -lm
2847 rather than
2848 .CW /usr/lib/libm.a
2849 and the linker thinks they're out-of-date if you so much as look at
2850 them.
2851 .LP
2852 PMake solves the problem with archives by allowing you to tell it to
2853 examine the files in the archives (so you can remove the individual
2854 files without having to regenerate them later). To handle the problem
2855 with libraries, PMake adds an additional way of deciding if a library
2856 is out-of-date:
2857 .IP \(bu 2
2858 If the table of contents is older than the library, or is missing, the
2859 library is out-of-date.
2860 .LP
2861 A library is any target that looks like
2862 .CW \-l name'' ``
2863 or that ends in a suffix that was marked as a library using the
2864 .CW .LIBS
2865 target.
2866 .CW .a
2867 is so marked in the system makefile.
2868 .LP
2869 Members of an archive are specified as
2870 ``\fIarchive\fP(\fImember\fP[ \fImember\fP...])''.
2871 Thus
2872 .CW libdix.a(window.o) '' ``'
2873 specifies the file
2874 .CW window.o
2875 in the archive
2876 .CW libdix.a .
2877 You may also use wildcards to specify the members of the archive. Just
2878 remember that most the wildcard characters will only find 
2879 .I existing
2880 files.
2881 .LP
2882 A file that is a member of an archive is treated specially. If the
2883 file doesn't exist, but it is in the archive, the modification time
2884 recorded in the archive is used for the file when determining if the
2885 file is out-of-date. When figuring out how to make an archived member target
2886 (not the file itself, but the file in the archive \*- the
2887 \fIarchive\fP(\fImember\fP) target), special care is
2888 taken with the transformation rules, as follows:
2889 .IP \(bu 2
2890 \&\fIarchive\fP(\fImember\fP) is made to depend on \fImember\fP.
2891 .IP \(bu 2
2892 The transformation from the \fImember\fP's suffix to the
2893 \fIarchive\fP's suffix is applied to the \fIarchive\fP(\fImember\fP) target.
2894 .IP \(bu 2
2895 The \fIarchive\fP(\fImember\fP)'s
2896 .CW .TARGET
2897 variable is set to the name of the \fImember\fP if \fImember\fP is
2898 actually a target, or the path to the member file if \fImember\fP is
2899 only a source.
2900 .IP \(bu 2
2901 The
2903 variable for the \fIarchive\fP(\fImember\fP) target is set to the name
2904 of the \fIarchive\fP.
2905 .Ix 0 def variable local .ARCHIVE
2906 .Ix 0 def .ARCHIVE
2907 .IP \(bu 2
2908 The
2909 .CW .MEMBER
2910 variable is set to the actual string inside the parentheses. In most
2911 cases, this will be the same as the
2912 .CW .TARGET
2913 variable.
2914 .Ix 0 def variable local .MEMBER
2915 .Ix 0 def .MEMBER
2916 .IP \(bu 2
2917 The \fIarchive\fP(\fImember\fP)'s place in the local variables of the
2918 targets that depend on it is taken by the value of its
2919 .CW .TARGET
2920 variable.
2921 .LP
2922 Thus, a program library could be created with the following makefile:
2923 .DS
2924 \&.o.a            :
2925         ...
2926         rm -f $(.TARGET:T)
2927 OBJS            = obj1.o obj2.o obj3.o
2928 libprog.a       : libprog.a($(OBJS))
2929         ar cru $(.TARGET) $(.OODATE)
2930         ranlib $(.TARGET)
2931 .DE
2932 This will cause the three object files to be compiled (if the
2933 corresponding source files were modified after the object file or, if
2934 that doesn't exist, the archived object file), the out-of-date ones
2935 archived in
2936 .CW libprog.a ,
2937 a table of contents placed in the archive and the newly-archived
2938 object files to be removed.
2939 .LP
2940 All this is used in the 
2941 .CW makelib.mk
2942 system makefile to create a single library with ease. This makefile
2943 looks like this:
2944 .DS
2945 .SM
2946 #
2947 # Rules for making libraries. The object files that make up the library
2948 # are removed once they are archived.
2949 #
2950 # To make several libraries in parallel, you should define the variable
2951 # "many_libraries". This will serialize the invocations of ranlib.
2952 #
2953 # To use, do something like this:
2954 #
2955 # OBJECTS = <files in the library>
2956 #
2957 # fish.a: fish.a($(OBJECTS)) MAKELIB
2958 #
2959 #
2961 #ifndef _MAKELIB_MK
2962 _MAKELIB_MK     =
2964 #include        <po.mk>
2966 \&.po.a .o.a    :
2967         ...
2968         rm -f $(.MEMBER)
2970 ARFLAGS         ?= crl
2972 #
2973 # Re-archive the out-of-date members and recreate the library's table of
2974 # contents using ranlib. If many_libraries is defined, put the ranlib
2975 # off til the end so many libraries can be made at once.
2976 #
2977 MAKELIB         : .USE .PRECIOUS
2978         ar $(ARFLAGS) $(.TARGET) $(.OODATE)
2979 #ifndef no_ranlib
2980 # ifdef many_libraries
2981         ...
2982 # endif many_libraries
2983         ranlib $(.TARGET)
2984 #endif no_ranlib
2986 #endif _MAKELIB_MK
2987 .DE
2988 .xH 2 On the Condition...
2989 .Rd 1
2990 .LP
2991 Like the C compiler before it, PMake allows you to configure the makefile,
2992 based on the current environment, using conditional statements. A
2993 conditional looks like this:
2994 .DS
2995 #if \fIboolean expression\fP
2996 \fIlines\fP
2997 #elif \fIanother boolean expression\fP
2998 \fImore lines\fP
2999 #else
3000 \fIstill more lines\fP
3001 #endif
3002 .DE
3003 They may be nested to a maximum depth of 30 and may occur anywhere
3004 (except in a comment, of course). The
3005 .CW # '' ``
3006 must the very first character on the line.
3007 .LP
3008 Each
3009 .I "boolean expression"
3010 is made up of terms that look like function calls, the standard C
3011 boolean operators
3012 .CW && ,
3013 .CW || ,
3014 and
3015 .CW ! ,
3016 and the standard relational operators
3017 .CW == ,
3018 .CW != ,
3019 .CW > ,
3020 .CW >= ,
3021 .CW < ,
3022 and
3023 .CW <= ,
3024 with
3025 .CW ==
3026 and
3027 .CW !=
3028 being overloaded to allow string comparisons as well.
3029 .CW &&
3030 represents logical AND;
3031 .CW ||
3032 is logical OR and
3033 .CW !
3034 is logical NOT.  The arithmetic and string operators take precedence
3035 over all three of these operators, while NOT takes precedence over
3036 AND, which takes precedence over OR.  This precedence may be
3037 overridden with parentheses, and an expression may be parenthesized to
3038 your heart's content.  Each term looks like a call on one of four
3039 functions:
3040 .nr pw 9
3041 .Ix 0 def make
3042 .Ix 0 def conditional make
3043 .Ix 0 def if make
3044 .IP make \n(pw
3045 The syntax is
3046 .CW make( \fItarget\fP\c
3047 .CW )
3048 where
3049 .I target
3050 is a target in the makefile. This is true if the given target was
3051 specified on the command line, or as the source for a
3052 .CW .MAIN
3053 target (note that the sources for
3054 .CW .MAIN
3055 are only used if no targets were given on the command line).
3056 .IP defined \n(pw
3057 .Ix 0 def defined
3058 .Ix 0 def conditional defined
3059 .Ix 0 def if defined
3060 The syntax is
3061 .CW defined( \fIvariable\fP\c
3062 .CW )
3063 and is true if
3064 .I variable
3065 is defined. Certain variables are defined in the system makefile that
3066 identify the system on which PMake is being run.
3067 .IP exists \n(pw
3068 .Ix 0 def exists
3069 .Ix 0 def conditional exists
3070 .Ix 0 def if exists
3071 The syntax is
3072 .CW exists( \fIfile\fP\c
3073 .CW )
3074 and is true if the file can be found on the global search path (i.e.
3075 that defined by
3076 .CW .PATH
3077 targets, not by
3078 .CW .PATH \fIsuffix\fP
3079 targets).
3080 .IP empty \n(pw
3081 .Ix 0 def empty
3082 .Ix 0 def conditional empty
3083 .Ix 0 def if empty
3084 This syntax is much like the others, except the string inside the
3085 parentheses is of the same form as you would put between parentheses
3086 when expanding a variable, complete with modifiers and everything. The
3087 function returns true if the resulting string is empty (NOTE: an undefined
3088 variable in this context will cause at the very least a warning
3089 message about a malformed conditional, and at the worst will cause the
3090 process to stop once it has read the makefile. If you want to check
3091 for a variable being defined or empty, use the expression
3092 .CW !defined( \fIvar\fP\c ``
3093 .CW ") || empty(" \fIvar\fP\c
3094 .CW ) ''
3095 as the definition of
3096 .CW ||
3097 will prevent the
3098 .CW empty()
3099 from being evaluated and causing an error, if the variable is
3100 undefined). This can be used to see if a variable contains a given
3101 word, for example:
3102 .DS
3103 #if !empty(\fIvar\fP:M\fIword\fP)
3104 .DE
3105 .LP
3106 The arithmetic and string operators may only be used to test the value
3107 of a variable. The lefthand side must contain the variable expansion,
3108 while the righthand side contains either a string, enclosed in
3109 double-quotes, or a number. The standard C numeric conventions (except
3110 for specifying an octal number) apply to both sides. E.g.
3111 .DS
3112 #if $(OS) == 4.3
3114 #if $(MACHINE) == "sun3"
3116 #if $(LOAD_ADDR) < 0xc000
3117 .DE
3118 are all valid conditionals. In addition, the numeric value of a
3119 variable can be tested as a boolean as follows:
3120 .DS
3121 #if $(LOAD)
3122 .DE
3123 would see if
3124 .CW LOAD
3125 contains a non-zero value and
3126 .DS
3127 #if !$(LOAD)
3128 .DE
3129 would test if
3130 .CW LOAD
3131 contains a zero value.
3132 .LP
3133 In addition to the bare
3134 .CW #if ,'' ``
3135 there are other forms that apply one of the first two functions to each
3136 term. They are as follows:
3137 .DS
3138         ifdef   \fRdefined\fP
3139         ifndef  \fR!defined\fP
3140         ifmake  \fRmake\fP
3141         ifnmake \fR!make\fP
3142 .DE
3143 There are also the ``else if'' forms:
3144 .CW elif ,
3145 .CW elifdef ,
3146 .CW elifndef ,
3147 .CW elifmake ,
3148 and
3149 .CW elifnmake .
3150 .LP
3151 For instance, if you wish to create two versions of a program, one of which
3152 is optimized (the production version) and the other of which is for debugging
3153 (has symbols for dbx), you have two choices: you can create two
3154 makefiles, one of which uses the
3155 .CW \-g
3156 flag for the compilation, while the other uses the
3157 .CW \-O
3158 flag, or you can use another target (call it
3159 .CW debug )
3160 to create the debug version. The construct below will take care of
3161 this for you. I have also made it so defining the variable
3162 .CW DEBUG
3163 (say with
3164 .CW "pmake -D DEBUG" )
3165 will also cause the debug version to be made.
3166 .DS
3167 #if defined(DEBUG) || make(debug)
3168 CFLAGS          += -g
3169 #else
3170 CFLAGS          += -O
3171 #endif
3172 .DE
3173 There are, of course, problems with this approach. The most glaring
3174 annoyance is that if you want to go from making a debug version to
3175 making a production version, you have to remove all the object files,
3176 or you will get some optimized and some debug versions in the same
3177 program. Another annoyance is you have to be careful not to make two
3178 targets that ``conflict'' because of some conditionals in the
3179 makefile. For instance
3180 .DS
3181 #if make(print)
3182 FORMATTER       = ditroff -Plaser_printer
3183 #endif
3184 #if make(draft)
3185 FORMATTER       = nroff -Pdot_matrix_printer
3186 #endif
3187 .DE
3188 would wreak havoc if you tried
3189 .CW "pmake draft print" '' ``
3190 since you would use the same formatter for each target. As I said,
3191 this all gets somewhat complicated.
3192 .xH 2 A Shell is a Shell is a Shell
3193 .Rd 7
3194 .LP
3195 In normal operation, the Bourne Shell (better known as
3196 .CW sh '') ``
3197 is used to execute the commands to re-create targets. PMake also allows you
3198 to specify a different shell for it to use when executing these
3199 commands. There are several things PMake must know about the shell you
3200 wish to use. These things are specified as the sources for the
3201 .CW .SHELL
3202 .Ix 0 ref .SHELL
3203 .Ix 0 ref target .SHELL
3204 target by keyword, as follows:
3205 .IP "\fBpath=\fP\fIpath\fP"
3206 PMake needs to know where the shell actually resides, so it can
3207 execute it. If you specify this and nothing else, PMake will use the
3208 last component of the path and look in its table of the shells it
3209 knows and use the specification it finds, if any. Use this if you just
3210 want to use a different version of the Bourne or C Shell (yes, PMake knows
3211 how to use the C Shell too).
3212 .IP "\fBname=\fP\fIname\fP"
3213 This is the name by which the shell is to be known. It is a single
3214 word and, if no other keywords are specified (other than
3215 .B path ),
3216 it is the name by which PMake attempts to find a specification for
3217 it (as mentioned above). You can use this if you would just rather use
3218 the C Shell than the Bourne Shell
3219 .CW ".SHELL: name=csh" '' (``
3220 will do it).
3221 .IP "\fBquiet=\fP\fIecho-off command\fP"
3222 As mentioned before, PMake actually controls whether commands are
3223 printed by introducing commands into the shell's input stream. This
3224 keyword, and the next two, control what those commands are. The
3225 .B quiet
3226 keyword is the command used to turn echoing off. Once it is turned
3227 off, echoing is expected to remain off until the echo-on command is given.
3228 .IP "\fBecho=\fP\fIecho-on command\fP"
3229 The command PMake should give to turn echoing back on again.
3230 .IP "\fBfilter=\fP\fIprinted echo-off command\fP"
3231 Many shells will echo the echo-off command when it is given. This
3232 keyword tells PMake in what format the shell actually prints the
3233 echo-off command. Wherever PMake sees this string in the shell's
3234 output, it will delete it and any following whitespace, up to and
3235 including the next newline. See the example at the end of this section
3236 for more details.
3237 .IP "\fBechoFlag=\fP\fIflag to turn echoing on\fP"
3238 Unless a target has been marked
3239 .CW .SILENT ,
3240 PMake wants to start the shell running with echoing on. To do this, it
3241 passes this flag to the shell as one of its arguments. If either this
3242 or the next flag begins with a `\-', the flags will be passed to the
3243 shell as separate arguments. Otherwise, the two will be concatenated
3244 (if they are used at the same time, of course).
3245 .IP "\fBerrFlag=\fP\fIflag to turn error checking on\fP"
3246 Likewise, unless a target is marked
3247 .CW .IGNORE ,
3248 PMake wishes error-checking to be on from the very start. To this end,
3249 it will pass this flag to the shell as an argument. The same rules for
3250 an initial `\-' apply as for the
3251 .B echoFlag .
3252 .IP "\fBcheck=\fP\fIcommand to turn error checking on\fP"
3253 Just as for echo-control, error-control is achieved by inserting
3254 commands into the shell's input stream. This is the command to make
3255 the shell check for errors. It also serves another purpose if the
3256 shell doesn't have error-control as commands, but I'll get into that
3257 in a minute. Again, once error checking has been turned on, it is
3258 expected to remain on until it is turned off again.
3259 .IP "\fBignore=\fP\fIcommand to turn error checking off\fP"
3260 This is the command PMake uses to turn error checking off. It has
3261 another use if the shell doesn't do error-control, but I'll tell you
3262 about that.\|.\|.\|now.
3263 .IP "\fBhasErrCtl=\fP\fIyes or no\fP"
3264 This takes a value that is either
3265 .B yes
3266 or
3267 .B no .
3268 Now you might think that the existence of the
3269 .B check
3270 and
3271 .B ignore
3272 keywords would be enough to tell PMake if the shell can do
3273 error-control, but you'd be wrong. If
3274 .B hasErrCtl
3275 is
3276 .B yes ,
3277 PMake uses the check and ignore commands in a straight-forward manner.
3278 If this is
3279 .B no ,
3280 however, their use is rather different. In this case, the check
3281 command is used as a template, in which the string
3282 .B %s
3283 is replaced by the command that's about to be executed, to produce a
3284 command for the shell that will echo the command to be executed. The
3285 ignore command is also used as a template, again with
3286 .B %s
3287 replaced by the command to be executed, to produce a command that will
3288 execute the command to be executed and ignore any error it returns.
3289 When these strings are used as templates, you must provide newline(s)
3290 .CW \en '') (``
3291 in the appropriate place(s).
3292 .LP
3293 The strings that follow these keywords may be enclosed in single or
3294 double quotes (the quotes will be stripped off) and may contain the
3295 usual C backslash-characters (\en is newline, \er is return, \eb is
3296 backspace, \e' escapes a single-quote inside single-quotes, \e"
3297 escapes a double-quote inside double-quotes). Now for an example.
3298 .LP
3299 This is actually the contents of the
3300 .CW <shx.mk>
3301 system makefile, and causes PMake to use the Bourne Shell in such a
3302 way that each command is printed as it is executed. That is, if more
3303 than one command is given on a line, each will be printed separately.
3304 Similarly, each time the body of a loop is executed, the commands
3305 within that loop will be printed, etc. The specification runs like
3306 this:
3307 .DS
3308 #
3309 # This is a shell specification to have the Bourne shell echo
3310 # the commands just before executing them, rather than when it reads
3311 # them. Useful if you want to see how variables are being expanded, etc.
3312 #
3313 \&.SHELL        : path=/bin/sh \e
3314         quiet="set -" \e
3315         echo="set -x" \e
3316         filter="+ set - " \e
3317         echoFlag=x \e
3318         errFlag=e \e
3319         hasErrCtl=yes \e
3320         check="set -e" \e
3321         ignore="set +e"
3322 .DE
3323 .LP
3324 It tells PMake the following:
3325 .Bp
3326 The shell is located in the file
3327 .CW /bin/sh .
3328 It need not tell PMake that the name of the shell is
3329 .CW sh 
3330 as PMake can figure that out for itself (it's the last component of
3331 the path).
3332 .Bp
3333 The command to stop echoing is
3334 .CW "set -" .
3335 .Bp
3336 The command to start echoing is
3337 .CW "set -x" .
3338 .Bp
3339 When the echo off command is executed, the shell will print
3340 .CW "+ set - " 
3341 (The `+' comes from using the
3342 .CW \-x
3343 flag (rather than the
3344 .CW \-v
3345 flag PMake usually uses)). PMake will remove all occurrences of this
3346 string from the output, so you don't notice extra commands you didn't
3347 put there.
3348 .Bp
3349 The flag the Bourne Shell will take to start echoing in this way is
3350 the
3351 .CW \-x
3352 flag. The Bourne Shell will only take its flag arguments concatenated
3353 as its first argument, so neither this nor the
3354 .B errFlag
3355 specification begins with a \-.
3356 .Bp
3357 The flag to use to turn error-checking on from the start is
3358 .CW \-e .
3359 .Bp
3360 The shell can turn error-checking on and off, and the commands to do
3361 so are
3362 .CW "set +e"
3363 and
3364 .CW "set -e" ,
3365 respectively.
3366 .LP
3367 I should note that this specification is for Bourne Shells that are
3368 not part of Berkeley
3369 .UX ,
3370 as shells from Berkeley don't do error control. You can get a similar
3371 effect, however, by changing the last three lines to be:
3372 .DS
3373         hasErrCtl=no \e
3374         check="echo \e"+ %s\e"\en" \e
3375         ignore="sh -c '%s || exit 0\en"
3376 .DE
3377 .LP
3378 This will cause PMake to execute the two commands
3379 .DS
3380 echo "+ \fIcmd\fP"
3381 sh -c '\fIcmd\fP || true'
3382 .DE
3383 for each command for which errors are to be ignored. (In case you are
3384 wondering, the thing for
3385 .CW ignore
3386 tells the shell to execute another shell without error checking on and
3387 always exit 0, since the
3388 .B ||
3389 causes the
3390 .CW "exit 0"
3391 to be executed only if the first command exited non-zero, and if the
3392 first command exited zero, the shell will also exit zero, since that's
3393 the last command it executed).
3394 .xH 2 Compatibility
3395 .Ix 0 ref compatibility
3396 .LP
3397 There are three (well, 3 \(12) levels of backwards-compatibility built
3398 into PMake.  Most makefiles will need none at all. Some may need a
3399 little bit of work to operate correctly when run in parallel. Each
3400 level encompasses the previous levels (e.g.
3401 .B \-B
3402 (one shell per command) implies
3403 .B \-V )
3404 The three levels are described in the following three sections.
3405 .xH 3 DEFCON 3 \*- Variable Expansion
3406 .Ix 0 ref compatibility
3407 .LP
3408 As noted before, PMake will not expand a variable unless it knows of a
3409 value for it. This can cause problems for makefiles that expect to
3410 leave variables undefined except in special circumstances (e.g. if
3411 more flags need to be passed to the C compiler or the output from a
3412 text processor should be sent to a different printer). If the
3413 variables are enclosed in curly braces
3414 .CW ${PRINTER} ''), (``
3415 the shell will let them pass. If they are enclosed in parentheses,
3416 however, the shell will declare a syntax error and the make will come
3417 to a grinding halt.
3418 .LP
3419 You have two choices: change the makefile to define the variables
3420 (their values can be overridden on the command line, since that's
3421 where they would have been set if you used Make, anyway) or always give the
3422 .B \-V
3423 flag (this can be done with the
3425 target, if you want).
3426 .xH 3 DEFCON 2 \*- The Number of the Beast
3427 .Ix 0 ref compatibility
3428 .LP
3429 Then there are the makefiles that expect certain commands, such as
3430 changing to a different directory, to not affect other commands in a
3431 target's creation script. You can solve this is either by going
3432 back to executing one shell per command (which is what the
3433 .B \-B
3434 flag forces PMake to do), which slows the process down a good bit and
3435 requires you to use semicolons and escaped newlines for shell constructs, or
3436 by changing the makefile to execute the offending command(s) in a subshell
3437 (by placing the line inside parentheses), like so:
3438 .DS
3439 install :: .MAKE
3440         (cd src; $(.PMAKE) install)
3441         (cd lib; $(.PMAKE) install)
3442         (cd man; $(.PMAKE) install)
3443 .DE
3444 .Ix 0 ref operator double-colon
3445 .Ix 0 ref variable global .PMAKE
3446 .Ix 0 ref .PMAKE
3447 .Ix 0 ref .MAKE
3448 .Ix 0 ref attribute .MAKE
3449 This will always execute the three makes (even if the
3450 .B \-n
3451 flag was given) because of the combination of the ``::'' operator and
3452 the
3453 .CW .MAKE
3454 attribute. Each command will change to the proper directory to perform
3455 the install, leaving the main shell in the directory in which it started.
3456 .xH 3 "DEFCON 1 \*- Imitation is the Not the Highest Form of Flattery"
3457 .Ix 0 ref compatibility
3458 .LP
3459 The final category of makefile is the one where every command requires
3460 input, the dependencies are incompletely specified, or you simply
3461 cannot create more than one target at a time, as mentioned earlier. In
3462 addition, you may not have the time or desire to upgrade the makefile
3463 to run smoothly with PMake. If you are the conservative sort, this is
3464 the compatibility mode for you. It is entered either by giving PMake
3465 the
3466 .B \-M
3467 flag (for Make), or by executing PMake as
3468 .CW make .'' ``
3469 In either case, PMake performs things exactly like Make (while still
3470 supporting most of the nice new features PMake provides). This
3471 includes:
3472 .IP \(bu 2
3473 No parallel execution.
3474 .IP \(bu 2
3475 Targets are made in the exact order specified by the makefile. The
3476 sources for each target are made in strict left-to-right order, etc.
3477 .IP \(bu 2
3478 A single Bourne shell is used to execute each command, thus the
3479 shell's
3480 .CW $$
3481 variable is useless, changing directories doesn't work across command
3482 lines, etc.
3483 .IP \(bu 2
3484 If no special characters exist in a command line, PMake will break the
3485 command into words itself and execute the command directly, without
3486 executing a shell first. The characters that cause PMake to execute a
3487 shell are:
3488 .CW # ,
3489 .CW = ,
3490 .CW | ,
3491 .CW ^ ,
3492 .CW ( ,
3493 .CW ) ,
3494 .CW { ,
3495 .CW } ,
3496 .CW ; ,
3497 .CW & ,
3498 .CW < ,
3499 .CW > ,
3500 .CW * ,
3501 .CW ? ,
3502 .CW [ ,
3503 .CW ] ,
3504 .CW : ,
3505 .CW $ ,
3506 .CW ` ,
3507 and
3508 .CW \e .
3509 You should notice that these are all the characters that are given
3510 special meaning by the shell (except
3511 .CW '
3512 and
3513 .CW " ,
3514 which PMake deals with all by its lonesome).
3515 .IP \(bu 2
3516 The use of the null suffix is turned off.
3517 .Ix 0 ref "null suffix"
3518 .Ix 0 ref suffix null
3519 .xH 2 The Way Things Work
3520 .LP
3521 When PMake reads the makefile, it parses sources and targets into
3522 nodes in a graph. The graph is directed only in the sense that PMake
3523 knows which way is up. Each node contains not only links to all its
3524 parents and children (the nodes that depend on it and those on which
3525 it depends, respectively), but also a count of the number of its
3526 children that have already been processed.
3527 .LP
3528 The most important thing to know about how PMake uses this graph is
3529 that the traversal is breadth-first and occurs in two passes.
3530 .LP
3531 After PMake has parsed the makefile, it begins with the nodes the user
3532 has told it to make (either on the command line, or via a 
3533 .CW .MAIN
3534 target, or by the target being the first in the file not labeled with
3535 the
3537 attribute) placed in a queue. It continues to take the node off the
3538 front of the queue, mark it as something that needs to be made, pass
3539 the node to 
3540 .CW Suff_FindDeps
3541 (mentioned earlier) to find any implicit sources for the node, and
3542 place all the node's children that have yet to be marked at the end of
3543 the queue. If any of the children is a
3544 .CW .USE
3545 rule, its attributes are applied to the parent, then its commands are
3546 appended to the parent's list of commands and its children are linked
3547 to its parent. The parent's unmade children counter is then decremented
3548 (since the
3549 .CW .USE
3550 node has been processed). You will note that this allows a
3551 .CW .USE
3552 node to have children that are
3553 .CW .USE
3554 nodes and the rules will be applied in sequence.
3555 If the node has no children, it is placed at the end of
3556 another queue to be examined in the second pass. This process
3557 continues until the first queue is empty.
3558 .LP
3559 At this point, all the leaves of the graph are in the examination
3560 queue. PMake removes the node at the head of the queue and sees if it
3561 is out-of-date. If it is, it is passed to a function that will execute
3562 the commands for the node asynchronously. When the commands have
3563 completed, all the node's parents have their unmade children counter
3564 decremented and, if the counter is then 0, they are placed on the
3565 examination queue. Likewise, if the node is up-to-date. Only those
3566 parents that were marked on the downward pass are processed in this
3567 way. Thus PMake traverses the graph back up to the nodes the user
3568 instructed it to create. When the examination queue is empty and no
3569 shells are running to create a target, PMake is finished.
3570 .LP
3571 Once all targets have been processed, PMake executes the commands
3572 attached to the
3573 .CW .END
3574 target, either explicitly or through the use of an ellipsis in a shell
3575 script. If there were no errors during the entire process but there
3576 are still some targets unmade (PMake keeps a running count of how many
3577 targets are left to be made), there is a cycle in the graph. PMake does
3578 a depth-first traversal of the graph to find all the targets that
3579 weren't made and prints them out one by one.
3580 .xH 1 Answers to Exercises
3581 .IP (3.1)
3582 This is something of a trick question, for which I apologize. The
3583 trick comes from the UNIX definition of a suffix, which PMake doesn't
3584 necessarily share. You will have noticed that all the suffixes used in
3585 this tutorial (and in UNIX in general) begin with a period
3586 .CW .ms , (
3587 .CW .c ,
3588 etc.). Now, PMake's idea of a suffix is more like English's: it's the
3589 characters at the end of a word. With this in mind, one possible
3590 .Ix 0 def suffix
3591 solution to this problem goes as follows:
3592 .DS I
3593 \&.SUFFIXES       : ec.exe .exe ec.obj .obj .asm
3594 ec.objec.exe .obj.exe :
3595         link -o $(.TARGET) $(.IMPSRC)
3596 \&.asmec.obj      :
3597         asm -o $(.TARGET) -DDO_ERROR_CHECKING $(.IMPSRC)
3598 \&.asm.obj        :
3599         asm -o $(.TARGET) $(.IMPSRC)
3600 .DE
3601 .IP (3.2)
3602 The trick to this one lies in the ``:='' variable-assignment operator
3603 and the ``:S'' variable-expansion modifier. 
3604 .Ix 0 ref variable assignment expanded
3605 .Ix 0 ref variable expansion modified
3606 .Ix 0 ref modifier substitute
3607 .Ix 0 ref :S
3608 .Ix 0 ref :=
3609 Basically what you want is to take the pointer variable, so to speak,
3610 and transform it into an invocation of the variable at which it
3611 points. You might try something like
3612 .DS I
3613 $(PTR:S/^/\e$(/:S/$/))
3614 .DE
3615 which places
3616 .CW $( '' ``
3617 at the front of the variable name and
3618 .CW ) '' ``
3619 at the end, thus transforming
3620 .CW VAR ,'' ``
3621 for example, into
3622 .CW $(VAR) ,'' ``
3623 which is just what we want. Unfortunately (as you know if you've tried
3624 it), since, as it says in the hint, PMake does no further substitution
3625 on the result of a modified expansion, that's \fIall\fP you get. The
3626 solution is to make use of ``:='' to place that string into yet
3627 another variable, then invoke the other variable directly:
3628 .DS I
3629 *PTR            := $(PTR:S/^/\e$(/:S/$/)/)
3630 .DE
3631 You can then use
3632 .CW $(*PTR) '' ``
3633 to your heart's content.
3634 .de Gp
3635 .XP
3636 \&\fB\\$1:\fP
3637 ..
3638 .xH 1 Glossary of Jargon
3639 .Gp "attribute"
3640 A property given to a target that causes PMake to treat it differently.
3641 .Gp "command script"
3642 The lines immediately following a dependency line that specify
3643 commands to execute to create each of the targets on the dependency
3644 line. Each line in the command script must begin with a tab.
3645 .Gp "command-line variable"
3646 A variable defined in an argument when PMake is first executed.
3647 Overrides all assignments to the same variable name in the makefile.
3648 .Gp "conditional"
3649 A construct much like that used in C that allows a makefile to be
3650 configured on the fly based on the local environment, or on what is being
3651 made by that invocation of PMake.
3652 .Gp "creation script"
3653 Commands used to create a target. See ``command script.''
3654 .Gp "dependency"
3655 The relationship between a source and a target. This comes in three
3656 flavors, as indicated by the operator between the target and the
3657 source. `:' gives a straight time-wise dependency (if the target is
3658 older than the source, the target is out-of-date), while `!' provides
3659 simply an ordering and always considers the target out-of-date. `::'
3660 is much like `:', save it creates multiple instances of a target each
3661 of which depends on its own list of sources.
3662 .Gp "dynamic source"
3663 This refers to a source that has a local variable invocation in it. It
3664 allows a single dependency line to specify a different source for each
3665 target on the line.
3666 .Gp "global variable"
3667 Any variable defined in a makefile. Takes precedence over variables
3668 defined in the environment, but not over command-line or local variables.
3669 .Gp "input graph"
3670 What PMake constructs from a makefile. Consists of nodes made of the
3671 targets in the makefile, and the links between them (the
3672 dependencies). The links are directed (from source to target) and
3673 there may not be any cycles (loops) in the graph.
3674 .Gp "local variable"
3675 A variable defined by PMake visible only in a target's shell script.
3676 There are seven local variables, not all of which are defined for
3677 every target:
3678 .CW .TARGET ,
3679 .CW .ALLSRC ,
3680 .CW .OODATE ,
3681 .CW .PREFIX ,
3682 .CW .IMPSRC ,
3683 .CW .ARCHIVE ,
3684 and
3685 .CW .MEMBER .
3686 .CW .TARGET ,
3687 .CW .PREFIX ,
3688 .CW .ARCHIVE ,
3689 and 
3690 .CW .MEMBER
3691 may be used on dependency lines to create ``dynamic sources.''
3692 .Gp "makefile"
3693 A file that describes how a system is built. If you don't know what it
3694 is after reading this tutorial.\|.\|.\|.
3695 .Gp "modifier"
3696 A letter, following a colon, used to alter how a variable is expanded.
3697 It has no effect on the variable itself.
3698 .Gp "operator"
3699 What separates a source from a target (on a dependency line) and specifies
3700 the relationship between the two. There are three:
3701 .CW : ', `
3702 .CW :: ', `
3703 and
3704 .CW ! '. `
3705 .Gp "search path"
3706 A list of directories in which a file should be sought. PMake's view
3707 of the contents of directories in a search path does not change once
3708 the makefile has been read. A file is sought on a search path only if
3709 it is exclusively a source.
3710 .Gp "shell"
3711 A program to which commands are passed in order to create targets.
3712 .Gp "source"
3713 Anything to the right of an operator on a dependency line. Targets on
3714 the dependency line are usually created from the sources.
3715 .Gp "special target"
3716 A target that causes PMake to do special things when it's encountered.
3717 .Gp "suffix"
3718 The tail end of a file name. Usually begins with a period,
3719 .CW .c
3720 or
3721 .CW .ms ,
3722 e.g.
3723 .Gp "target"
3724 A word to the left of the operator on a dependency line. More
3725 generally, any file that PMake might create. A file may be (and often
3726 is) both a target and a source (what it is depends on how PMake is
3727 looking at it at the time \*- sort of like the wave/particle duality
3728 of light, you know).
3729 .Gp "transformation rule"
3730 A special construct in a makefile that specifies how to create a file
3731 of one type from a file of another, as indicated by their suffixes.
3732 .Gp "variable expansion"
3733 The process of substituting the value of a variable for a reference to
3734 it. Expansion may be altered by means of modifiers.
3735 .Gp "variable"
3736 A place in which to store text that may be retrieved later. Also used
3737 to define the local environment. Conditionals exist that test whether
3738 a variable is defined or not.
3739 .bp
3740 .\" Output table of contents last, with an entry for the index, making
3741 .\" sure to save and restore the last real page number for the index...
3742 .nr @n \n(PN+1
3743 .\" We are not generating an index
3744 .\" .XS \n(@n
3745 .\" Index
3746 .\" .XE
3747 .nr %% \n%
3748 .PX
3749 .nr % \n(%%