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