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