VirtualBox

source: kBuild/trunk/src/kmk/PSD.doc/tutorial.ms@ 25

Last change on this file since 25 was 25, checked in by bird, 22 years ago

This commit was generated by cvs2svn to compensate for changes in r24,
which included commits to RCS files with non-trunk default branches.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette