1BMAKE(1) FreeBSD General Commands Manual BMAKE(1) 2 3[1mNAME[0m 4 [1mbmake [22m-- maintain program dependencies 5 6[1mSYNOPSIS[0m 7 [1mbmake [22m[[1m-BeikNnqrSstWwX[22m] [[1m-C [4m[22mdirectory[24m] [[1m-D [4m[22mvariable[24m] [[1m-d [4m[22mflags[24m] 8 [[1m-f [4m[22mmakefile[24m] [[1m-I [4m[22mdirectory[24m] [[1m-J [4m[22mprivate[24m] [[1m-j [4m[22mmax_jobs[24m] 9 [[1m-m [4m[22mdirectory[24m] [[1m-T [4m[22mfile[24m] [[1m-V [4m[22mvariable[24m] [[1m-v [4m[22mvariable[24m] 10 [[4mvariable=value[24m] [[4mtarget[24m [4m...[24m] 11 12[1mDESCRIPTION[0m 13 [1mbmake [22mis a program designed to simplify the maintenance of other pro- 14 grams. Its input is a list of specifications as to the files upon which 15 programs and other files depend. If no [1m-f [4m[22mmakefile[24m makefile option is 16 given, [1mbmake [22mwill try to open `[4mmakefile[24m' then `[4mMakefile[24m' in order to find 17 the specifications. If the file `[4m.depend[24m' exists, it is read (see 18 mkdep(1)). 19 20 This manual page is intended as a reference document only. For a more 21 thorough description of [1mbmake [22mand makefiles, please refer to [4mPMake[24m [4m-[24m [4mA[0m 22 [4mTutorial[24m. 23 24 [1mbmake [22mwill prepend the contents of the [4mMAKEFLAGS[24m environment variable to 25 the command line arguments before parsing them. 26 27 The options are as follows: 28 29 [1m-B [22mTry to be backwards compatible by executing a single shell per 30 command and by executing the commands to make the sources of a 31 dependency line in sequence. 32 33 [1m-C [4m[22mdirectory[0m 34 Change to [4mdirectory[24m before reading the makefiles or doing any- 35 thing else. If multiple [1m-C [22moptions are specified, each is inter- 36 preted relative to the previous one: [1m-C [4m[22m/[24m [1m-C [4m[22metc[24m is equivalent to 37 [1m-C [4m[22m/etc[24m. 38 39 [1m-D [4m[22mvariable[0m 40 Define [4mvariable[24m to be 1, in the global scope. 41 42 [1m-d [4m[22m[-]flags[0m 43 Turn on debugging, and specify which portions of [1mbmake [22mare to 44 print debugging information. Unless the flags are preceded by 45 `-' they are added to the [4mMAKEFLAGS[24m environment variable and will 46 be processed by any child make processes. By default, debugging 47 information is printed to standard error, but this can be changed 48 using the [4mF[24m debugging flag. The debugging output is always un- 49 buffered; in addition, if debugging is enabled but debugging out- 50 put is not directed to standard output, then the standard output 51 is line buffered. [4mFlags[24m is one or more of the following: 52 53 [4mA[24m Print all possible debugging information; equivalent to 54 specifying all of the debugging flags. 55 56 [4ma[24m Print debugging information about archive searching and 57 caching. 58 59 [4mC[24m Print debugging information about current working direc- 60 tory. 61 62 [4mc[24m Print debugging information about conditional evaluation. 63 64 [4md[24m Print debugging information about directory searching and 65 caching. 66 67 [4me[24m Print debugging information about failed commands and 68 targets. 69 70 [4mF[24m[[1m+[22m][4mfilename[0m 71 Specify where debugging output is written. This must be 72 the last flag, because it consumes the remainder of the 73 argument. If the character immediately after the `F' 74 flag is `+', then the file will be opened in append mode; 75 otherwise the file will be overwritten. If the file name 76 is `stdout' or `stderr' then debugging output will be 77 written to the standard output or standard error output 78 file descriptors respectively (and the `+' option has no 79 effect). Otherwise, the output will be written to the 80 named file. If the file name ends `.%d' then the `%d' is 81 replaced by the pid. 82 83 [4mf[24m Print debugging information about loop evaluation. 84 85 [4mg1[24m Print the input graph before making anything. 86 87 [4mg2[24m Print the input graph after making everything, or before 88 exiting on error. 89 90 [4mg3[24m Print the input graph before exiting on error. 91 92 [4mh[24m Print debugging information about hash table operations. 93 94 [4mj[24m Print debugging information about running multiple 95 shells. 96 97 [4mL[24m Turn on lint checks. This will throw errors for variable 98 assignments that do not parse correctly, at the time of 99 assignment so the file and line number are available. 100 101 [4ml[24m Print commands in Makefiles regardless of whether or not 102 they are prefixed by `@' or other "quiet" flags. Also 103 known as "loud" behavior. 104 105 [4mM[24m Print debugging information about "meta" mode decisions 106 about targets. 107 108 [4mm[24m Print debugging information about making targets, includ- 109 ing modification dates. 110 111 [4mn[24m Don't delete the temporary command scripts created when 112 running commands. These temporary scripts are created in 113 the directory referred to by the TMPDIR environment vari- 114 able, or in [4m/tmp[24m if TMPDIR is unset or set to the empty 115 string. The temporary scripts are created by mkstemp(3), 116 and have names of the form [4mmakeXXXXXX[24m. [4mNOTE[24m: This can 117 create many files in TMPDIR or [4m/tmp[24m, so use with care. 118 119 [4mp[24m Print debugging information about makefile parsing. 120 121 [4ms[24m Print debugging information about suffix-transformation 122 rules. 123 124 [4mt[24m Print debugging information about target list mainte- 125 nance. 126 127 [4mV[24m Force the [1m-V [22moption to print raw values of variables, 128 overriding the default behavior set via 129 [4m.MAKE.EXPAND_VARIABLES[24m. 130 131 [4mv[24m Print debugging information about variable assignment. 132 133 [4mx[24m Run shell commands with [1m-x [22mso the actual commands are 134 printed as they are executed. 135 136 [1m-e [22mSpecify that environment variables override macro assignments 137 within makefiles. 138 139 [1m-f [4m[22mmakefile[0m 140 Specify a makefile to read instead of the default `[4mmakefile[24m'. If 141 [4mmakefile[24m is `[1m-[22m', standard input is read. Multiple makefiles may 142 be specified, and are read in the order specified. 143 144 [1m-I [4m[22mdirectory[0m 145 Specify a directory in which to search for makefiles and included 146 makefiles. The system makefile directory (or directories, see 147 the [1m-m [22moption) is automatically included as part of this list. 148 149 [1m-i [22mIgnore non-zero exit of shell commands in the makefile. Equiva- 150 lent to specifying `[1m-[22m' before each command line in the makefile. 151 152 [1m-J [4m[22mprivate[0m 153 This option should [4mnot[24m be specified by the user. 154 155 When the [4mj[24m option is in use in a recursive build, this option is 156 passed by a make to child makes to allow all the make processes 157 in the build to cooperate to avoid overloading the system. 158 159 [1m-j [4m[22mmax_jobs[0m 160 Specify the maximum number of jobs that [1mbmake [22mmay have running at 161 any one time. The value is saved in [4m.MAKE.JOBS[24m. Turns compati- 162 bility mode off, unless the [4mB[24m flag is also specified. When com- 163 patibility mode is off, all commands associated with a target are 164 executed in a single shell invocation as opposed to the tradi- 165 tional one shell invocation per line. This can break traditional 166 scripts which change directories on each command invocation and 167 then expect to start with a fresh environment on the next line. 168 It is more efficient to correct the scripts rather than turn 169 backwards compatibility on. 170 171 [1m-k [22mContinue processing after errors are encountered, but only on 172 those targets that do not depend on the target whose creation 173 caused the error. 174 175 [1m-m [4m[22mdirectory[0m 176 Specify a directory in which to search for sys.mk and makefiles 177 included via the <[4mfile[24m>-style include statement. The [1m-m [22moption 178 can be used multiple times to form a search path. This path will 179 override the default system include path: /usr/share/mk. Fur- 180 thermore the system include path will be appended to the search 181 path used for "[4mfile[24m"-style include statements (see the [1m-I [22mop- 182 tion). 183 184 If a file or directory name in the [1m-m [22margument (or the 185 MAKESYSPATH environment variable) starts with the string ".../" 186 then [1mbmake [22mwill search for the specified file or directory named 187 in the remaining part of the argument string. The search starts 188 with the current directory of the Makefile and then works upward 189 towards the root of the file system. If the search is success- 190 ful, then the resulting directory replaces the ".../" specifica- 191 tion in the [1m-m [22margument. If used, this feature allows [1mbmake [22mto 192 easily search in the current source tree for customized sys.mk 193 files (e.g., by using ".../mk/sys.mk" as an argument). 194 195 [1m-n [22mDisplay the commands that would have been executed, but do not 196 actually execute them unless the target depends on the .MAKE spe- 197 cial source (see below) or the command is prefixed with `[1m+[22m'. 198 199 [1m-N [22mDisplay the commands which would have been executed, but do not 200 actually execute any of them; useful for debugging top-level 201 makefiles without descending into subdirectories. 202 203 [1m-q [22mDo not execute any commands, but exit 0 if the specified targets 204 are up-to-date and 1, otherwise. 205 206 [1m-r [22mDo not use the built-in rules specified in the system makefile. 207 208 [1m-S [22mStop processing if an error is encountered. This is the default 209 behavior and the opposite of [1m-k[22m. 210 211 [1m-s [22mDo not echo any commands as they are executed. Equivalent to 212 specifying `[1m@[22m' before each command line in the makefile. 213 214 [1m-T [4m[22mtracefile[0m 215 When used with the [1m-j [22mflag, append a trace record to [4mtracefile[0m 216 for each job started and completed. 217 218 [1m-t [22mRather than re-building a target as specified in the makefile, 219 create it or update its modification time to make it appear up- 220 to-date. 221 222 [1m-V [4m[22mvariable[0m 223 Print the value of [4mvariable[24m. Do not build any targets. Multiple 224 instances of this option may be specified; the variables will be 225 printed one per line, with a blank line for each null or unde- 226 fined variable. The value printed is extracted from the global 227 scope after all makefiles have been read. By default, the raw 228 variable contents (which may include additional unexpanded vari- 229 able references) are shown. If [4mvariable[24m contains a `$' then the 230 value will be recursively expanded to its complete resultant text 231 before printing. The expanded value will also be printed if 232 [4m.MAKE.EXPAND_VARIABLES[24m is set to true and the [1m-dV [22moption has not 233 been used to override it. Note that loop-local and target-local 234 variables, as well as values taken temporarily by global vari- 235 ables during makefile processing, are not accessible via this op- 236 tion. The [1m-dv [22mdebug mode can be used to see these at the cost of 237 generating substantial extraneous output. 238 239 [1m-v [4m[22mvariable[0m 240 Like [1m-V [22mbut the variable is always expanded to its complete 241 value. 242 243 [1m-W [22mTreat any warnings during makefile parsing as errors. 244 245 [1m-w [22mPrint entering and leaving directory messages, pre and post pro- 246 cessing. 247 248 [1m-X [22mDon't export variables passed on the command line to the environ- 249 ment individually. Variables passed on the command line are 250 still exported via the [4mMAKEFLAGS[24m environment variable. This op- 251 tion may be useful on systems which have a small limit on the 252 size of command arguments. 253 254 [4mvariable=value[0m 255 Set the value of the variable [4mvariable[24m to [4mvalue[24m. Normally, all 256 values passed on the command line are also exported to sub-makes 257 in the environment. The [1m-X [22mflag disables this behavior. Vari- 258 able assignments should follow options for POSIX compatibility 259 but no ordering is enforced. 260 261 There are seven different types of lines in a makefile: file dependency 262 specifications, shell commands, variable assignments, include statements, 263 conditional directives, for loops, and comments. 264 265 In general, lines may be continued from one line to the next by ending 266 them with a backslash (`\'). The trailing newline character and initial 267 whitespace on the following line are compressed into a single space. 268 269[1mFILE DEPENDENCY SPECIFICATIONS[0m 270 Dependency lines consist of one or more targets, an operator, and zero or 271 more sources. This creates a relationship where the targets "depend" on 272 the sources and are customarily created from them. A target is consid- 273 ered out-of-date if it does not exist, or if its modification time is 274 less than that of any of its sources. An out-of-date target will be re- 275 created, but not until all sources have been examined and themselves re- 276 created as needed. Three operators may be used: 277 278 [1m: [22mMany dependency lines may name this target but only one may have 279 attached shell commands. All sources named in all dependency lines 280 are considered together, and if needed the attached shell commands 281 are run to create or re-create the target. If [1mbmake [22mis inter- 282 rupted, the target is removed. 283 284 [1m! [22mThe same, but the target is always re-created whether or not it is 285 out of date. 286 287 [1m:: [22mAny dependency line may have attached shell commands, but each one 288 is handled independently: its sources are considered and the at- 289 tached shell commands are run if the target is out of date with re- 290 spect to (only) those sources. Thus, different groups of the at- 291 tached shell commands may be run depending on the circumstances. 292 Furthermore, unlike [1m:, [22mfor dependency lines with no sources, the 293 attached shell commands are always run. Also unlike [1m:, [22mthe target 294 will not be removed if [1mbmake [22mis interrupted. 295 All dependency lines mentioning a particular target must use the same op- 296 erator. 297 298 Targets and sources may contain the shell wildcard values `?', `*', `[]', 299 and `{}'. The values `?', `*', and `[]' may only be used as part of the 300 final component of the target or source, and must be used to describe ex- 301 isting files. The value `{}' need not necessarily be used to describe 302 existing files. Expansion is in directory order, not alphabetically as 303 done in the shell. 304 305[1mSHELL COMMANDS[0m 306 Each target may have associated with it one or more lines of shell com- 307 mands, normally used to create the target. Each of the lines in this 308 script [4mmust[24m be preceded by a tab. (For historical reasons, spaces are 309 not accepted.) While targets can appear in many dependency lines if de- 310 sired, by default only one of these rules may be followed by a creation 311 script. If the `[1m::[22m' operator is used, however, all rules may include 312 scripts and the scripts are executed in the order found. 313 314 Each line is treated as a separate shell command, unless the end of line 315 is escaped with a backslash (`\') in which case that line and the next 316 are combined. If the first characters of the command are any combination 317 of `[1m@[22m', `[1m+[22m', or `[1m-[22m', the command is treated specially. A `[1m@[22m' causes the 318 command not to be echoed before it is executed. A `[1m+[22m' causes the command 319 to be executed even when [1m-n [22mis given. This is similar to the effect of 320 the .MAKE special source, except that the effect can be limited to a sin- 321 gle line of a script. A `[1m-[22m' in compatibility mode causes any non-zero 322 exit status of the command line to be ignored. 323 324 When [1mbmake [22mis run in jobs mode with [1m-j [4m[22mmax_jobs[24m, the entire script for 325 the target is fed to a single instance of the shell. In compatibility 326 (non-jobs) mode, each command is run in a separate process. If the com- 327 mand contains any shell meta characters (`#=|^(){};&<>*?[]:$`\\n') it 328 will be passed to the shell; otherwise [1mbmake [22mwill attempt direct execu- 329 tion. If a line starts with `[1m-[22m' and the shell has ErrCtl enabled then 330 failure of the command line will be ignored as in compatibility mode. 331 Otherwise `[1m-[22m' affects the entire job; the script will stop at the first 332 command line that fails, but the target will not be deemed to have 333 failed. 334 335 Makefiles should be written so that the mode of [1mbmake [22moperation does not 336 change their behavior. For example, any command which needs to use "cd" 337 or "chdir" without potentially changing the directory for subsequent com- 338 mands should be put in parentheses so it executes in a subshell. To 339 force the use of one shell, escape the line breaks so as to make the 340 whole script one command. For example: 341 342 avoid-chdir-side-effects: 343 @echo Building $@ in `pwd` 344 @(cd ${.CURDIR} && ${MAKE} $@) 345 @echo Back in `pwd` 346 347 ensure-one-shell-regardless-of-mode: 348 @echo Building $@ in `pwd`; \ 349 (cd ${.CURDIR} && ${MAKE} $@); \ 350 echo Back in `pwd` 351 352 Since [1mbmake [22mwill chdir(2) to `[4m.OBJDIR[24m' before executing any targets, each 353 child process starts with that as its current working directory. 354 355[1mVARIABLE ASSIGNMENTS[0m 356 Variables in make are much like variables in the shell, and, by tradi- 357 tion, consist of all upper-case letters. 358 359 [1mVariable assignment modifiers[0m 360 The five operators that can be used to assign values to variables are as 361 follows: 362 363 [1m= [22mAssign the value to the variable. Any previous value is overrid- 364 den. 365 366 [1m+= [22mAppend the value to the current value of the variable. 367 368 [1m?= [22mAssign the value to the variable if it is not already defined. 369 370 [1m:= [22mAssign with expansion, i.e. expand the value before assigning it 371 to the variable. Normally, expansion is not done until the vari- 372 able is referenced. [4mNOTE[24m: References to undefined variables are 373 [4mnot[24m expanded. This can cause problems when variable modifiers 374 are used. 375 376 [1m!= [22mExpand the value and pass it to the shell for execution and as- 377 sign the result to the variable. Any newlines in the result are 378 replaced with spaces. 379 380 Any white-space before the assigned [4mvalue[24m is removed; if the value is be- 381 ing appended, a single space is inserted between the previous contents of 382 the variable and the appended value. 383 384 Variables are expanded by surrounding the variable name with either curly 385 braces (`{}') or parentheses (`()') and preceding it with a dollar sign 386 (`$'). If the variable name contains only a single letter, the surround- 387 ing braces or parentheses are not required. This shorter form is not 388 recommended. 389 390 If the variable name contains a dollar, then the name itself is expanded 391 first. This allows almost arbitrary variable names, however names con- 392 taining dollar, braces, parentheses, or whitespace are really best 393 avoided! 394 395 If the result of expanding a variable contains a dollar sign (`$') the 396 string is expanded again. 397 398 Variable substitution occurs at three distinct times, depending on where 399 the variable is being used. 400 401 1. Variables in dependency lines are expanded as the line is read. 402 403 2. Variables in shell commands are expanded when the shell command is 404 executed. 405 406 3. ".for" loop index variables are expanded on each loop iteration. 407 Note that other variables are not expanded inside loops so the fol- 408 lowing example code: 409 410 411 .for i in 1 2 3 412 a+= ${i} 413 j= ${i} 414 b+= ${j} 415 .endfor 416 417 all: 418 @echo ${a} 419 @echo ${b} 420 421 will print: 422 423 1 2 3 424 3 3 3 425 426 Because while ${a} contains "1 2 3" after the loop is executed, ${b} 427 contains "${j} ${j} ${j}" which expands to "3 3 3" since after the 428 loop completes ${j} contains "3". 429 430 [1mVariable classes[0m 431 The four different classes of variables (in order of increasing prece- 432 dence) are: 433 434 Environment variables 435 Variables defined as part of [1mbmake[22m's environment. 436 437 Global variables 438 Variables defined in the makefile or in included makefiles. 439 440 Command line variables 441 Variables defined as part of the command line. 442 443 Local variables 444 Variables that are defined specific to a certain target. 445 446 Local variables are all built in and their values vary magically from 447 target to target. It is not currently possible to define new local vari- 448 ables. The seven local variables are as follows: 449 450 [4m.ALLSRC[24m The list of all sources for this target; also known as 451 `[4m>[24m'. 452 453 [4m.ARCHIVE[24m The name of the archive file; also known as `[4m![24m'. 454 455 [4m.IMPSRC[24m In suffix-transformation rules, the name/path of the 456 source from which the target is to be transformed (the 457 "implied" source); also known as `[4m<[24m'. It is not defined 458 in explicit rules. 459 460 [4m.MEMBER[24m The name of the archive member; also known as `[4m%[24m'. 461 462 [4m.OODATE[24m The list of sources for this target that were deemed out- 463 of-date; also known as `[4m?[24m'. 464 465 [4m.PREFIX[24m The file prefix of the target, containing only the file 466 portion, no suffix or preceding directory components; 467 also known as `[4m*[24m'. The suffix must be one of the known 468 suffixes declared with [1m.SUFFIXES [22mor it will not be recog- 469 nized. 470 471 [4m.TARGET[24m The name of the target; also known as `[4m@[24m'. For compati- 472 bility with other makes this is an alias for [1m.ARCHIVE [22min 473 archive member rules. 474 475 The shorter forms (`[4m>[24m', `[4m![24m', `[4m<[24m', `[4m%[24m', `[4m?[24m', `[4m*[24m', and `[4m@[24m') are permitted 476 for backward compatibility with historical makefiles and legacy POSIX 477 make and are not recommended. 478 479 Variants of these variables with the punctuation followed immediately by 480 `D' or `F', e.g. `[4m$(@D)[24m', are legacy forms equivalent to using the `:H' 481 and `:T' modifiers. These forms are accepted for compatibility with AT&T 482 System V UNIX makefiles and POSIX but are not recommended. 483 484 Four of the local variables may be used in sources on dependency lines 485 because they expand to the proper value for each target on the line. 486 These variables are `[4m.TARGET[24m', `[4m.PREFIX[24m', `[4m.ARCHIVE[24m', and `[4m.MEMBER[24m'. 487 488 [1mAdditional built-in variables[0m 489 In addition, [1mbmake [22msets or knows about the following variables: 490 491 [4m$[24m A single dollar sign `$', i.e. `$$' expands to a single 492 dollar sign. 493 494 [4m.ALLTARGETS[24m The list of all targets encountered in the Makefile. If 495 evaluated during Makefile parsing, lists only those tar- 496 gets encountered thus far. 497 498 [4m.CURDIR[24m A path to the directory where [1mbmake [22mwas executed. Refer 499 to the description of `PWD' for more details. 500 501 [4m.INCLUDEDFROMDIR[0m 502 The directory of the file this Makefile was included 503 from. 504 505 [4m.INCLUDEDFROMFILE[0m 506 The filename of the file this Makefile was included from. 507 508 MAKE The name that [1mbmake [22mwas executed with ([4margv[0][24m). For 509 compatibility [1mbmake [22malso sets [4m.MAKE[24m with the same value. 510 The preferred variable to use is the environment variable 511 MAKE because it is more compatible with other versions of 512 [1mbmake [22mand cannot be confused with the special target with 513 the same name. 514 515 [4m.MAKE.DEPENDFILE[0m 516 Names the makefile (default `[4m.depend[24m') from which gener- 517 ated dependencies are read. 518 519 [4m.MAKE.EXPAND_VARIABLES[0m 520 A boolean that controls the default behavior of the [1m-V[0m 521 option. If true, variable values printed with [1m-V [22mare 522 fully expanded; if false, the raw variable contents 523 (which may include additional unexpanded variable refer- 524 ences) are shown. 525 526 [4m.MAKE.EXPORTED[24m The list of variables exported by [1mbmake[22m. 527 528 [4m.MAKE.JOBS[24m The argument to the [1m-j [22moption. 529 530 [4m.MAKE.JOB.PREFIX[0m 531 If [1mbmake [22mis run with [4mj[24m then output for each target is 532 prefixed with a token `--- target ---' the first part of 533 which can be controlled via [4m.MAKE.JOB.PREFIX[24m. If 534 [4m.MAKE.JOB.PREFIX[24m is empty, no token is printed. 535 For example: 536 .MAKE.JOB.PREFIX=${.newline}---${.MAKE:T}[${.MAKE.PID}] 537 would produce tokens like `---make[1234] target ---' mak- 538 ing it easier to track the degree of parallelism being 539 achieved. 540 541 MAKEFLAGS The environment variable `MAKEFLAGS' may contain anything 542 that may be specified on [1mbmake[22m's command line. Anything 543 specified on [1mbmake[22m's command line is appended to the 544 `MAKEFLAGS' variable which is then entered into the envi- 545 ronment for all programs which [1mbmake [22mexecutes. 546 547 [4m.MAKE.LEVEL[24m The recursion depth of [1mbmake[22m. The initial instance of 548 [1mbmake [22mwill be 0, and an incremented value is put into the 549 environment to be seen by the next generation. This al- 550 lows tests like: .if ${.MAKE.LEVEL} == 0 to protect 551 things which should only be evaluated in the initial in- 552 stance of [1mbmake[22m. 553 554 [4m.MAKE.MAKEFILE_PREFERENCE[0m 555 The ordered list of makefile names (default `[4mmakefile[24m', 556 `[4mMakefile[24m') that [1mbmake [22mwill look for. 557 558 [4m.MAKE.MAKEFILES[0m 559 The list of makefiles read by [1mbmake[22m, which is useful for 560 tracking dependencies. Each makefile is recorded only 561 once, regardless of the number of times read. 562 563 [4m.MAKE.MODE[24m Processed after reading all makefiles. Can affect the 564 mode that [1mbmake [22mruns in. It can contain a number of key- 565 words: 566 567 [4mcompat[24m Like [1m-B[22m, puts [1mbmake [22minto "compat" 568 mode. 569 570 [4mmeta[24m Puts [1mbmake [22minto "meta" mode, where 571 meta files are created for each tar- 572 get to capture the command run, the 573 output generated and if filemon(4) 574 is available, the system calls which 575 are of interest to [1mbmake[22m. The cap- 576 tured output can be very useful when 577 diagnosing errors. 578 579 [4mcurdirOk=[24m [4mbf[24m Normally [1mbmake [22mwill not create .meta 580 files in `[4m.CURDIR[24m'. This can be 581 overridden by setting [4mbf[24m to a value 582 which represents True. 583 584 [4mmissing-meta=[24m [4mbf[24m If [4mbf[24m is True, then a missing .meta 585 file makes the target out-of-date. 586 587 [4mmissing-filemon=[24m [4mbf[24m If [4mbf[24m is True, then missing filemon 588 data makes the target out-of-date. 589 590 [4mnofilemon[24m Do not use filemon(4). 591 592 [4menv[24m For debugging, it can be useful to 593 include the environment in the .meta 594 file. 595 596 [4mverbose[24m If in "meta" mode, print a clue 597 about the target being built. This 598 is useful if the build is otherwise 599 running silently. The message 600 printed the value of: 601 [4m.MAKE.META.PREFIX[24m. 602 603 [4mignore-cmd[24m Some makefiles have commands which 604 are simply not stable. This keyword 605 causes them to be ignored for deter- 606 mining whether a target is out of 607 date in "meta" mode. See also 608 [1m.NOMETA_CMP[22m. 609 610 [4msilent=[24m [4mbf[24m If [4mbf[24m is True, when a .meta file is 611 created, mark the target [1m.SILENT[22m. 612 613 [4m.MAKE.META.BAILIWICK[0m 614 In "meta" mode, provides a list of prefixes which match 615 the directories controlled by [1mbmake[22m. If a file that was 616 generated outside of [4m.OBJDIR[24m but within said bailiwick is 617 missing, the current target is considered out-of-date. 618 619 [4m.MAKE.META.CREATED[0m 620 In "meta" mode, this variable contains a list of all the 621 meta files updated. If not empty, it can be used to 622 trigger processing of [4m.MAKE.META.FILES[24m. 623 624 [4m.MAKE.META.FILES[0m 625 In "meta" mode, this variable contains a list of all the 626 meta files used (updated or not). This list can be used 627 to process the meta files to extract dependency informa- 628 tion. 629 630 [4m.MAKE.META.IGNORE_PATHS[0m 631 Provides a list of path prefixes that should be ignored; 632 because the contents are expected to change over time. 633 The default list includes: `[4m/dev[24m [4m/etc[24m [4m/proc[24m [4m/tmp[24m [4m/var/run[0m 634 [4m/var/tmp[24m' 635 636 [4m.MAKE.META.IGNORE_PATTERNS[0m 637 Provides a list of patterns to match against pathnames. 638 Ignore any that match. 639 640 [4m.MAKE.META.IGNORE_FILTER[0m 641 Provides a list of variable modifiers to apply to each 642 pathname. Ignore if the expansion is an empty string. 643 644 [4m.MAKE.META.PREFIX[0m 645 Defines the message printed for each meta file updated in 646 "meta verbose" mode. The default value is: 647 Building ${.TARGET:H:tA}/${.TARGET:T} 648 649 [4m.MAKEOVERRIDES[24m This variable is used to record the names of variables 650 assigned to on the command line, so that they may be ex- 651 ported as part of `MAKEFLAGS'. This behavior can be dis- 652 abled by assigning an empty value to `[4m.MAKEOVERRIDES[24m' 653 within a makefile. Extra variables can be exported from 654 a makefile by appending their names to `[4m.MAKEOVERRIDES[24m'. 655 `MAKEFLAGS' is re-exported whenever `[4m.MAKEOVERRIDES[24m' is 656 modified. 657 658 [4m.MAKE.PATH_FILEMON[0m 659 If [1mbmake [22mwas built with filemon(4) support, this is set 660 to the path of the device node. This allows makefiles to 661 test for this support. 662 663 [4m.MAKE.PID[24m The process-id of [1mbmake[22m. 664 665 [4m.MAKE.PPID[24m The parent process-id of [1mbmake[22m. 666 667 [4m.MAKE.SAVE_DOLLARS[0m 668 value should be a boolean that controls whether `$$' are 669 preserved when doing `:=' assignments. The default is 670 false, for backwards compatibility. Set to true for com- 671 patability with other makes. If set to false, `$$' be- 672 comes `$' per normal evaluation rules. 673 674 [4m.MAKE.UID[24m The user-id running [1mbmake[22m. 675 676 [4m.MAKE.GID[24m The group-id running [1mbmake[22m. 677 678 [4mMAKE_PRINT_VAR_ON_ERROR[0m 679 When [1mbmake [22mstops due to an error, it sets `[4m.ERROR_TARGET[24m' 680 to the name of the target that failed, `[4m.ERROR_CMD[24m' to 681 the commands of the failed target, and in "meta" mode, it 682 also sets `[4m.ERROR_CWD[24m' to the getcwd(3), and 683 `[4m.ERROR_META_FILE[24m' to the path of the meta file (if any) 684 describing the failed target. It then prints its name 685 and the value of `[4m.CURDIR[24m' as well as the value of any 686 variables named in `[4mMAKE_PRINT_VAR_ON_ERROR[24m'. 687 688 [4m.newline[24m This variable is simply assigned a newline character as 689 its value. This allows expansions using the [1m:@ [22mmodifier 690 to put a newline between iterations of the loop rather 691 than a space. For example, the printing of 692 `[4mMAKE_PRINT_VAR_ON_ERROR[24m' could be done as 693 ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@}. 694 695 [4m.OBJDIR[24m A path to the directory where the targets are built. Its 696 value is determined by trying to chdir(2) to the follow- 697 ing directories in order and using the first match: 698 699 1. ${MAKEOBJDIRPREFIX}${.CURDIR} 700 701 (Only if `MAKEOBJDIRPREFIX' is set in the environ- 702 ment or on the command line.) 703 704 2. ${MAKEOBJDIR} 705 706 (Only if `MAKEOBJDIR' is set in the environment or 707 on the command line.) 708 709 3. ${.CURDIR}[4m/obj.[24m${MACHINE} 710 711 4. ${.CURDIR}[4m/obj[0m 712 713 5. [4m/usr/obj/[24m${.CURDIR} 714 715 6. ${.CURDIR} 716 717 Variable expansion is performed on the value before it's 718 used, so expressions such as 719 ${.CURDIR:S,^/usr/src,/var/obj,} 720 may be used. This is especially useful with 721 `MAKEOBJDIR'. 722 723 `[4m.OBJDIR[24m' may be modified in the makefile via the special 724 target `[1m.OBJDIR[22m'. In all cases, [1mbmake [22mwill chdir(2) to 725 the specified directory if it exists, and set `[4m.OBJDIR[24m' 726 and `PWD' to that directory before executing any targets. 727 728 Except in the case of an explicit `[1m.OBJDIR[22m' target, [1mbmake[0m 729 will check that the specified directory is writable and 730 ignore it if not. This check can be skipped by setting 731 the environment variable `MAKE_OBJDIR_CHECK_WRITABLE' to 732 "no". 733 734 [4m.PARSEDIR[24m A path to the directory of the current `[4mMakefile[24m' being 735 parsed. 736 737 [4m.PARSEFILE[24m The basename of the current `[4mMakefile[24m' being parsed. 738 This variable and `[4m.PARSEDIR[24m' are both set only while the 739 `[4mMakefiles[24m' are being parsed. If you want to retain 740 their current values, assign them to a variable using as- 741 signment with expansion: (`[1m:=[22m'). 742 743 [4m.PATH[24m A variable that represents the list of directories that 744 [1mbmake [22mwill search for files. The search list should be 745 updated using the target `[4m.PATH[24m' rather than the vari- 746 able. 747 748 PWD Alternate path to the current directory. [1mbmake [22mnormally 749 sets `[4m.CURDIR[24m' to the canonical path given by getcwd(3). 750 However, if the environment variable `PWD' is set and 751 gives a path to the current directory, then [1mbmake [22msets 752 `[4m.CURDIR[24m' to the value of `PWD' instead. This behavior 753 is disabled if `MAKEOBJDIRPREFIX' is set or `MAKEOBJDIR' 754 contains a variable transform. `PWD' is set to the value 755 of `[4m.OBJDIR[24m' for all programs which [1mbmake [22mexecutes. 756 757 .SHELL The pathname of the shell used to run target scripts. It 758 is read-only. 759 760 .SUFFIXES The list of known suffixes. It is read-only. 761 762 .TARGETS The list of targets explicitly specified on the command 763 line, if any. 764 765 VPATH Colon-separated (":") lists of directories that [1mbmake[0m 766 will search for files. The variable is supported for 767 compatibility with old make programs only, use `[4m.PATH[24m' 768 instead. 769 770 [1mVariable modifiers[0m 771 Variable expansion may be modified to select or modify each word of the 772 variable (where a "word" is white-space delimited sequence of charac- 773 ters). The general format of a variable expansion is as follows: 774 775 ${variable[:modifier[:...]]} 776 777 Each modifier begins with a colon, which may be escaped with a backslash 778 (`\'). 779 780 A set of modifiers can be specified via a variable, as follows: 781 782 modifier_variable=modifier[:...] 783 ${variable:${modifier_variable}[:...]} 784 785 In this case the first modifier in the modifier_variable does not start 786 with a colon, since that must appear in the referencing variable. If any 787 of the modifiers in the modifier_variable contain a dollar sign (`$'), 788 these must be doubled to avoid early expansion. 789 790 The supported modifiers are: 791 792 [1m:E [22mReplaces each word in the variable with its suffix. 793 794 [1m:H [22mReplaces each word in the variable with everything but the last com- 795 ponent. 796 797 [1m:M[4m[22mpattern[0m 798 Selects only those words that match [4mpattern[24m. The standard shell 799 wildcard characters (`*', `?', and `[]') may be used. The wildcard 800 characters may be escaped with a backslash (`\'). As a consequence 801 of the way values are split into words, matched, and then joined, a 802 construct like 803 ${VAR:M*} 804 will normalize the inter-word spacing, removing all leading and 805 trailing space, and converting multiple consecutive spaces to single 806 spaces. 807 808 [1m:N[4m[22mpattern[0m 809 This is identical to `[1m:M[22m', but selects all words which do not match 810 [4mpattern[24m. 811 812 [1m:O [22mOrders every word in variable alphabetically. 813 814 [1m:On [22mOrders every word in variable numerically. A number followed by one 815 of `k', `M' or `G' is multiplied by the appropriate factor (1024 816 (k), 1048576 (M), or 1073741824 (G)). Both upper- and lower-case 817 letters are accepted. 818 819 [1m:Or [22mOrders every word in variable in reverse alphabetical order. 820 821 [1m:Orn[0m 822 Orders every word in variable in reverse numerical order. 823 824 [1m:Ox [22mShuffles the words in variable. The results will be different each 825 time you are referring to the modified variable; use the assignment 826 with expansion (`[1m:=[22m') to prevent such behavior. For example, 827 828 LIST= uno due tre quattro 829 RANDOM_LIST= ${LIST:Ox} 830 STATIC_RANDOM_LIST:= ${LIST:Ox} 831 832 all: 833 @echo "${RANDOM_LIST}" 834 @echo "${RANDOM_LIST}" 835 @echo "${STATIC_RANDOM_LIST}" 836 @echo "${STATIC_RANDOM_LIST}" 837 may produce output similar to: 838 839 quattro due tre uno 840 tre due quattro uno 841 due uno quattro tre 842 due uno quattro tre 843 844 [1m:Q [22mQuotes every shell meta-character in the variable, so that it can be 845 passed safely to the shell. 846 847 [1m:q [22mQuotes every shell meta-character in the variable, and also doubles 848 `$' characters so that it can be passed safely through recursive in- 849 vocations of [1mbmake[22m. This is equivalent to: `:S/\$/&&/g:Q'. 850 851 [1m:R [22mReplaces each word in the variable with everything but its suffix. 852 853 [1m:range[=count][0m 854 The value is an integer sequence representing the words of the orig- 855 inal value, or the supplied [4mcount[24m. 856 857 [1m:gmtime[=utc][0m 858 The value is a format string for strftime(3), using gmtime(3). If a 859 [4mutc[24m value is not provided or is 0, the current time is used. 860 861 [1m:hash[0m 862 Computes a 32-bit hash of the value and encode it as hex digits. 863 864 [1m:localtime[=utc][0m 865 The value is a format string for strftime(3), using localtime(3). 866 If a [4mutc[24m value is not provided or is 0, the current time is used. 867 868 [1m:tA [22mAttempts to convert variable to an absolute path using realpath(3), 869 if that fails, the value is unchanged. 870 871 [1m:tl [22mConverts variable to lower-case letters. 872 873 [1m:ts[4m[22mc[0m 874 Words in the variable are normally separated by a space on expan- 875 sion. This modifier sets the separator to the character [4mc[24m. If [4mc[24m is 876 omitted, then no separator is used. The common escapes (including 877 octal numeric codes) work as expected. 878 879 [1m:tu [22mConverts variable to upper-case letters. 880 881 [1m:tW [22mCauses the value to be treated as a single word (possibly containing 882 embedded white space). See also `[1m:[*][22m'. 883 884 [1m:tw [22mCauses the value to be treated as a sequence of words delimited by 885 white space. See also `[1m:[@][22m'. 886 887 [1m:S[22m/[4mold_string[24m/[4mnew_string[24m/[[1m1gW[22m] 888 Modifies the first occurrence of [4mold_string[24m in each word of the 889 variable's value, replacing it with [4mnew_string[24m. If a `g' is ap- 890 pended to the last delimiter of the pattern, all occurrences in each 891 word are replaced. If a `1' is appended to the last delimiter of 892 the pattern, only the first occurrence is affected. If a `W' is ap- 893 pended to the last delimiter of the pattern, then the value is 894 treated as a single word (possibly containing embedded white space). 895 If [4mold_string[24m begins with a caret (`^'), [4mold_string[24m is anchored at 896 the beginning of each word. If [4mold_string[24m ends with a dollar sign 897 (`$'), it is anchored at the end of each word. Inside [4mnew_string[24m, 898 an ampersand (`&') is replaced by [4mold_string[24m (without any `^' or 899 `$'). Any character may be used as a delimiter for the parts of the 900 modifier string. The anchoring, ampersand and delimiter characters 901 may be escaped with a backslash (`\'). 902 903 Variable expansion occurs in the normal fashion inside both 904 [4mold_string[24m and [4mnew_string[24m with the single exception that a backslash 905 is used to prevent the expansion of a dollar sign (`$'), not a pre- 906 ceding dollar sign as is usual. 907 908 [1m:C[22m/[4mpattern[24m/[4mreplacement[24m/[[1m1gW[22m] 909 The [1m:C [22mmodifier is just like the [1m:S [22mmodifier except that the old and 910 new strings, instead of being simple strings, are an extended regu- 911 lar expression (see regex(3)) string [4mpattern[24m and an ed(1)-style 912 string [4mreplacement[24m. Normally, the first occurrence of the pattern 913 [4mpattern[24m in each word of the value is substituted with [4mreplacement[24m. 914 The `1' modifier causes the substitution to apply to at most one 915 word; the `g' modifier causes the substitution to apply to as many 916 instances of the search pattern [4mpattern[24m as occur in the word or 917 words it is found in; the `W' modifier causes the value to be 918 treated as a single word (possibly containing embedded white space). 919 920 As for the [1m:S [22mmodifier, the [4mpattern[24m and [4mreplacement[24m are subjected to 921 variable expansion before being parsed as regular expressions. 922 923 [1m:T [22mReplaces each word in the variable with its last path component. 924 925 [1m:u [22mRemoves adjacent duplicate words (like uniq(1)). 926 927 [1m:?[4m[22mtrue_string[24m[1m:[4m[22mfalse_string[0m 928 If the variable name (not its value), when parsed as a .if condi- 929 tional expression, evaluates to true, return as its value the 930 [4mtrue_string[24m, otherwise return the [4mfalse_string[24m. Since the variable 931 name is used as the expression, :? must be the first modifier after 932 the variable name itself - which will, of course, usually contain 933 variable expansions. A common error is trying to use expressions 934 like 935 ${NUMBERS:M42:?match:no} 936 which actually tests defined(NUMBERS), to determine if any words 937 match "42" you need to use something like: 938 ${"${NUMBERS:M42}" != "":?match:no}. 939 940 [4m:old_string=new_string[0m 941 This is the AT&T System V UNIX style variable substitution. It must 942 be the last modifier specified. If [4mold_string[24m or [4mnew_string[24m do not 943 contain the pattern matching character [4m%[24m then it is assumed that 944 they are anchored at the end of each word, so only suffixes or en- 945 tire words may be replaced. Otherwise [4m%[24m is the substring of 946 [4mold_string[24m to be replaced in [4mnew_string[24m. If only [4mold_string[24m con- 947 tains the pattern matching character [4m%[24m, and [4mold_string[24m matches, then 948 the result is the [4mnew_string[24m. If only the [4mnew_string[24m contains the 949 pattern matching character [4m%[24m, then it is not treated specially and 950 it is printed as a literal [4m%[24m on match. If there is more than one 951 pattern matching character ([4m%[24m) in either the [4mnew_string[24m or 952 [4mold_string[24m, only the first instance is treated specially (as the 953 pattern character); all subsequent instances are treated as regular 954 characters. 955 956 Variable expansion occurs in the normal fashion inside both 957 [4mold_string[24m and [4mnew_string[24m with the single exception that a backslash 958 is used to prevent the expansion of a dollar sign (`$'), not a pre- 959 ceding dollar sign as is usual. 960 961 [1m:@[4m[22mtemp[24m[1m@[4m[22mstring[24m[1m@[0m 962 This is the loop expansion mechanism from the OSF Development Envi- 963 ronment (ODE) make. Unlike [1m.for [22mloops, expansion occurs at the time 964 of reference. Assigns [4mtemp[24m to each word in the variable and evalu- 965 ates [4mstring[24m. The ODE convention is that [4mtemp[24m should start and end 966 with a period. For example. 967 ${LINKS:@.LINK.@${LN} ${TARGET} ${.LINK.}@} 968 969 However a single character variable is often more readable: 970 ${MAKE_PRINT_VAR_ON_ERROR:@v@$v='${$v}'${.newline}@} 971 972 [1m:_[=var][0m 973 Saves the current variable value in `$_' or the named [4mvar[24m for later 974 reference. Example usage: 975 976 M_cmpv.units = 1 1000 1000000 977 M_cmpv = S,., ,g:_:range:@i@+ $${_:[-$$i]} \ 978 \* $${M_cmpv.units:[$$i]}@:S,^,expr 0 ,1:sh 979 980 .if ${VERSION:${M_cmpv}} < ${3.1.12:L:${M_cmpv}} 981 982 Here `$_' is used to save the result of the `:S' modifier which is 983 later referenced using the index values from `:range'. 984 985 [1m:U[4m[22mnewval[0m 986 If the variable is undefined, [4mnewval[24m is the value. If the variable 987 is defined, the existing value is returned. This is another ODE 988 make feature. It is handy for setting per-target CFLAGS for in- 989 stance: 990 ${_${.TARGET:T}_CFLAGS:U${DEF_CFLAGS}} 991 If a value is only required if the variable is undefined, use: 992 ${VAR:D:Unewval} 993 994 [1m:D[4m[22mnewval[0m 995 If the variable is defined, [4mnewval[24m is the value. 996 997 [1m:L [22mThe name of the variable is the value. 998 999 [1m:P [22mThe path of the node which has the same name as the variable is the 1000 value. If no such node exists or its path is null, then the name of 1001 the variable is used. In order for this modifier to work, the name 1002 (node) must at least have appeared on the rhs of a dependency. 1003 1004 [1m:![4m[22mcmd[24m[1m![0m 1005 The output of running [4mcmd[24m is the value. 1006 1007 [1m:sh [22mIf the variable is non-empty it is run as a command and the output 1008 becomes the new value. 1009 1010 [1m::=[4m[22mstr[0m 1011 The variable is assigned the value [4mstr[24m after substitution. This 1012 modifier and its variations are useful in obscure situations such as 1013 wanting to set a variable when shell commands are being parsed. 1014 These assignment modifiers always expand to nothing, so if appearing 1015 in a rule line by themselves should be preceded with something to 1016 keep [1mbmake [22mhappy. 1017 1018 The `[1m::[22m' helps avoid false matches with the AT&T System V UNIX style 1019 [1m:= [22mmodifier and since substitution always occurs the [1m::= [22mform is 1020 vaguely appropriate. 1021 1022 [1m::?=[4m[22mstr[0m 1023 As for [1m::= [22mbut only if the variable does not already have a value. 1024 1025 [1m::+=[4m[22mstr[0m 1026 Append [4mstr[24m to the variable. 1027 1028 [1m::!=[4m[22mcmd[0m 1029 Assign the output of [4mcmd[24m to the variable. 1030 1031 [1m:[[4m[22mrange[24m[1m][0m 1032 Selects one or more words from the value, or performs other opera- 1033 tions related to the way in which the value is divided into words. 1034 1035 Ordinarily, a value is treated as a sequence of words delimited by 1036 white space. Some modifiers suppress this behavior, causing a value 1037 to be treated as a single word (possibly containing embedded white 1038 space). An empty value, or a value that consists entirely of white- 1039 space, is treated as a single word. For the purposes of the `[1m:[][22m' 1040 modifier, the words are indexed both forwards using positive inte- 1041 gers (where index 1 represents the first word), and backwards using 1042 negative integers (where index -1 represents the last word). 1043 1044 The [4mrange[24m is subjected to variable expansion, and the expanded re- 1045 sult is then interpreted as follows: 1046 1047 [4mindex[24m Selects a single word from the value. 1048 1049 [4mstart[24m[1m..[4m[22mend[0m 1050 Selects all words from [4mstart[24m to [4mend[24m, inclusive. For example, 1051 `[1m:[2..-1][22m' selects all words from the second word to the last 1052 word. If [4mstart[24m is greater than [4mend[24m, then the words are out- 1053 put in reverse order. For example, `[1m:[-1..1][22m' selects all 1054 the words from last to first. If the list is already or- 1055 dered, then this effectively reverses the list, but it is 1056 more efficient to use `[1m:Or[22m' instead of `[1m:O:[-1..1][22m'. 1057 1058 [1m* [22mCauses subsequent modifiers to treat the value as a single 1059 word (possibly containing embedded white space). Analogous 1060 to the effect of "$*" in Bourne shell. 1061 1062 0 Means the same as `[1m:[*][22m'. 1063 1064 [1m@ [22mCauses subsequent modifiers to treat the value as a sequence 1065 of words delimited by white space. Analogous to the effect 1066 of "$@" in Bourne shell. 1067 1068 [1m# [22mReturns the number of words in the value. 1069 1070[1mINCLUDE STATEMENTS, CONDITIONALS AND FOR LOOPS[0m 1071 Makefile inclusion, conditional structures and for loops reminiscent of 1072 the C programming language are provided in [1mbmake[22m. All such structures 1073 are identified by a line beginning with a single dot (`.') character. 1074 Files are included with either [1m.include <[4m[22mfile[24m[1m> [22mor [1m.include "[4m[22mfile[24m[1m"[22m. Vari- 1075 ables between the angle brackets or double quotes are expanded to form 1076 the file name. If angle brackets are used, the included makefile is ex- 1077 pected to be in the system makefile directory. If double quotes are 1078 used, the including makefile's directory and any directories specified 1079 using the [1m-I [22moption are searched before the system makefile directory. 1080 For compatibility with other versions of [1mbmake [22m`include file ...' is also 1081 accepted. 1082 1083 If the include statement is written as [1m.-include [22mor as [1m.sinclude [22mthen er- 1084 rors locating and/or opening include files are ignored. 1085 1086 If the include statement is written as [1m.dinclude [22mnot only are errors lo- 1087 cating and/or opening include files ignored, but stale dependencies 1088 within the included file will be ignored just like [4m.MAKE.DEPENDFILE[24m. 1089 1090 Conditional expressions are also preceded by a single dot as the first 1091 character of a line. The possible conditionals are as follows: 1092 1093 [1m.error [4m[22mmessage[0m 1094 The message is printed along with the name of the makefile and 1095 line number, then [1mbmake [22mwill exit immediately. 1096 1097 [1m.export [4m[22mvariable[24m [4m...[0m 1098 Export the specified global variable. If no variable list is 1099 provided, all globals are exported except for internal variables 1100 (those that start with `.'). This is not affected by the [1m-X[0m 1101 flag, so should be used with caution. For compatibility with 1102 other [1mbmake [22mprograms `export variable=value' is also accepted. 1103 1104 Appending a variable name to [4m.MAKE.EXPORTED[24m is equivalent to ex- 1105 porting a variable. 1106 1107 [1m.export-env [4m[22mvariable[24m [4m...[0m 1108 The same as `.export', except that the variable is not appended 1109 to [4m.MAKE.EXPORTED[24m. This allows exporting a value to the environ- 1110 ment which is different from that used by [1mbmake [22minternally. 1111 1112 [1m.export-literal [4m[22mvariable[24m [4m...[0m 1113 The same as `.export-env', except that variables in the value are 1114 not expanded. 1115 1116 [1m.info [4m[22mmessage[0m 1117 The message is printed along with the name of the makefile and 1118 line number. 1119 1120 [1m.undef [4m[22mvariable[24m [4m...[0m 1121 Un-define the specified global variables. Only global variables 1122 can be un-defined. 1123 1124 [1m.unexport [4m[22mvariable[24m [4m...[0m 1125 The opposite of `.export'. The specified global [4mvariable[24m will be 1126 removed from [4m.MAKE.EXPORTED[24m. If no variable list is provided, 1127 all globals are unexported, and [4m.MAKE.EXPORTED[24m deleted. 1128 1129 [1m.unexport-env[0m 1130 Unexport all globals previously exported and clear the environ- 1131 ment inherited from the parent. This operation will cause a mem- 1132 ory leak of the original environment, so should be used spar- 1133 ingly. Testing for [4m.MAKE.LEVEL[24m being 0, would make sense. Also 1134 note that any variables which originated in the parent environ- 1135 ment should be explicitly preserved if desired. For example: 1136 1137 .if ${.MAKE.LEVEL} == 0 1138 PATH := ${PATH} 1139 .unexport-env 1140 .export PATH 1141 .endif 1142 1143 Would result in an environment containing only `PATH', which is 1144 the minimal useful environment. Actually `.MAKE.LEVEL' will also 1145 be pushed into the new environment. 1146 1147 [1m.warning [4m[22mmessage[0m 1148 The message prefixed by `[4mwarning:[24m' is printed along with the name 1149 of the makefile and line number. 1150 1151 [1m.if [22m[!][4mexpression[24m [[4moperator[24m [4mexpression[24m [4m...[24m] 1152 Test the value of an expression. 1153 1154 [1m.ifdef [22m[!][4mvariable[24m [[4moperator[24m [4mvariable[24m [4m...[24m] 1155 Test the value of a variable. 1156 1157 [1m.ifndef [22m[!][4mvariable[24m [[4moperator[24m [4mvariable[24m [4m...[24m] 1158 Test the value of a variable. 1159 1160 [1m.ifmake [22m[!][4mtarget[24m [[4moperator[24m [4mtarget[24m [4m...[24m] 1161 Test the target being built. 1162 1163 [1m.ifnmake [22m[!] [4mtarget[24m [[4moperator[24m [4mtarget[24m [4m...[24m] 1164 Test the target being built. 1165 1166 [1m.else [22mReverse the sense of the last conditional. 1167 1168 [1m.elif [22m[!] [4mexpression[24m [[4moperator[24m [4mexpression[24m [4m...[24m] 1169 A combination of `[1m.else[22m' followed by `[1m.if[22m'. 1170 1171 [1m.elifdef [22m[!][4mvariable[24m [[4moperator[24m [4mvariable[24m [4m...[24m] 1172 A combination of `[1m.else[22m' followed by `[1m.ifdef[22m'. 1173 1174 [1m.elifndef [22m[!][4mvariable[24m [[4moperator[24m [4mvariable[24m [4m...[24m] 1175 A combination of `[1m.else[22m' followed by `[1m.ifndef[22m'. 1176 1177 [1m.elifmake [22m[!][4mtarget[24m [[4moperator[24m [4mtarget[24m [4m...[24m] 1178 A combination of `[1m.else[22m' followed by `[1m.ifmake[22m'. 1179 1180 [1m.elifnmake [22m[!][4mtarget[24m [[4moperator[24m [4mtarget[24m [4m...[24m] 1181 A combination of `[1m.else[22m' followed by `[1m.ifnmake[22m'. 1182 1183 [1m.endif [22mEnd the body of the conditional. 1184 1185 The [4moperator[24m may be any one of the following: 1186 1187 [1m|| [22mLogical OR. 1188 1189 [1m&& [22mLogical AND; of higher precedence than "||". 1190 1191 As in C, [1mbmake [22mwill only evaluate a conditional as far as is necessary to 1192 determine its value. Parentheses may be used to change the order of 1193 evaluation. The boolean operator `[1m![22m' may be used to logically negate an 1194 entire conditional. It is of higher precedence than `[1m&&[22m'. 1195 1196 The value of [4mexpression[24m may be any of the following: 1197 1198 [1mdefined [22mTakes a variable name as an argument and evaluates to true if 1199 the variable has been defined. 1200 1201 [1mmake [22mTakes a target name as an argument and evaluates to true if the 1202 target was specified as part of [1mbmake[22m's command line or was de- 1203 clared the default target (either implicitly or explicitly, see 1204 [4m.MAIN[24m) before the line containing the conditional. 1205 1206 [1mempty [22mTakes a variable, with possible modifiers, and evaluates to true 1207 if the expansion of the variable would result in an empty 1208 string. 1209 1210 [1mexists [22mTakes a file name as an argument and evaluates to true if the 1211 file exists. The file is searched for on the system search path 1212 (see [4m.PATH[24m). 1213 1214 [1mtarget [22mTakes a target name as an argument and evaluates to true if the 1215 target has been defined. 1216 1217 [1mcommands[0m 1218 Takes a target name as an argument and evaluates to true if the 1219 target has been defined and has commands associated with it. 1220 1221 [4mExpression[24m may also be an arithmetic or string comparison. Variable ex- 1222 pansion is performed on both sides of the comparison, after which the nu- 1223 merical values are compared. A value is interpreted as hexadecimal if it 1224 is preceded by 0x, otherwise it is decimal; octal numbers are not sup- 1225 ported. The standard C relational operators are all supported. If after 1226 variable expansion, either the left or right hand side of a `[1m==[22m' or `[1m!=[22m' 1227 operator is not a numerical value, then string comparison is performed 1228 between the expanded variables. If no relational operator is given, it 1229 is assumed that the expanded variable is being compared against 0, or an 1230 empty string in the case of a string comparison. 1231 1232 When [1mbmake [22mis evaluating one of these conditional expressions, and it en- 1233 counters a (white-space separated) word it doesn't recognize, either the 1234 "make" or "defined" expression is applied to it, depending on the form of 1235 the conditional. If the form is `[1m.ifdef[22m', `[1m.ifndef[22m', or `[1m.if[22m' the 1236 "defined" expression is applied. Similarly, if the form is `[1m.ifmake[22m' or 1237 `[1m.ifnmake[22m', the "make" expression is applied. 1238 1239 If the conditional evaluates to true the parsing of the makefile contin- 1240 ues as before. If it evaluates to false, the following lines are 1241 skipped. In both cases this continues until a `[1m.else[22m' or `[1m.endif[22m' is 1242 found. 1243 1244 For loops are typically used to apply a set of rules to a list of files. 1245 The syntax of a for loop is: 1246 1247 [1m.for [4m[22mvariable[24m [[4mvariable[24m [4m...[24m] [1min [4m[22mexpression[0m 1248 <make-lines> 1249 [1m.endfor[0m 1250 1251 After the for [1mexpression [22mis evaluated, it is split into words. On each 1252 iteration of the loop, one word is taken and assigned to each [1mvariable[22m, 1253 in order, and these [1mvariables [22mare substituted into the [1mmake-lines [22minside 1254 the body of the for loop. The number of words must come out even; that 1255 is, if there are three iteration variables, the number of words provided 1256 must be a multiple of three. 1257 1258[1mCOMMENTS[0m 1259 Comments begin with a hash (`#') character, anywhere but in a shell com- 1260 mand line, and continue to the end of an unescaped new line. 1261 1262[1mSPECIAL SOURCES (ATTRIBUTES)[0m 1263 [1m.EXEC [22mTarget is never out of date, but always execute commands any- 1264 way. 1265 1266 [1m.IGNORE [22mIgnore any errors from the commands associated with this tar- 1267 get, exactly as if they all were preceded by a dash (`-'). 1268 1269 [1m.MADE [22mMark all sources of this target as being up-to-date. 1270 1271 [1m.MAKE [22mExecute the commands associated with this target even if the [1m-n[0m 1272 or [1m-t [22moptions were specified. Normally used to mark recursive 1273 [1mbmake[22ms. 1274 1275 [1m.META [22mCreate a meta file for the target, even if it is flagged as 1276 [1m.PHONY[22m, [1m.MAKE[22m, or [1m.SPECIAL[22m. Usage in conjunction with [1m.MAKE [22mis 1277 the most likely case. In "meta" mode, the target is out-of- 1278 date if the meta file is missing. 1279 1280 [1m.NOMETA [22mDo not create a meta file for the target. Meta files are also 1281 not created for [1m.PHONY[22m, [1m.MAKE[22m, or [1m.SPECIAL [22mtargets. 1282 1283 [1m.NOMETA_CMP[0m 1284 Ignore differences in commands when deciding if target is out 1285 of date. This is useful if the command contains a value which 1286 always changes. If the number of commands change, though, the 1287 target will still be out of date. The same effect applies to 1288 any command line that uses the variable [4m.OODATE[24m, which can be 1289 used for that purpose even when not otherwise needed or de- 1290 sired: 1291 1292 1293 skip-compare-for-some: 1294 @echo this will be compared 1295 @echo this will not ${.OODATE:M.NOMETA_CMP} 1296 @echo this will also be compared 1297 1298 The [1m:M [22mpattern suppresses any expansion of the unwanted vari- 1299 able. 1300 1301 [1m.NOPATH [22mDo not search for the target in the directories specified by 1302 [1m.PATH[22m. 1303 1304 [1m.NOTMAIN [22mNormally [1mbmake [22mselects the first target it encounters as the 1305 default target to be built if no target was specified. This 1306 source prevents this target from being selected. 1307 1308 [1m.OPTIONAL[0m 1309 If a target is marked with this attribute and [1mbmake [22mcan't fig- 1310 ure out how to create it, it will ignore this fact and assume 1311 the file isn't needed or already exists. 1312 1313 [1m.PHONY [22mThe target does not correspond to an actual file; it is always 1314 considered to be out of date, and will not be created with the 1315 [1m-t [22moption. Suffix-transformation rules are not applied to 1316 [1m.PHONY [22mtargets. 1317 1318 [1m.PRECIOUS[0m 1319 When [1mbmake [22mis interrupted, it normally removes any partially 1320 made targets. This source prevents the target from being re- 1321 moved. 1322 1323 [1m.RECURSIVE[0m 1324 Synonym for [1m.MAKE[22m. 1325 1326 [1m.SILENT [22mDo not echo any of the commands associated with this target, 1327 exactly as if they all were preceded by an at sign (`@'). 1328 1329 [1m.USE [22mTurn the target into [1mbmake[22m's version of a macro. When the tar- 1330 get is used as a source for another target, the other target 1331 acquires the commands, sources, and attributes (except for 1332 [1m.USE[22m) of the source. If the target already has commands, the 1333 [1m.USE [22mtarget's commands are appended to them. 1334 1335 [1m.USEBEFORE[0m 1336 Exactly like [1m.USE[22m, but prepend the [1m.USEBEFORE [22mtarget commands 1337 to the target. 1338 1339 [1m.WAIT [22mIf [1m.WAIT [22mappears in a dependency line, the sources that precede 1340 it are made before the sources that succeed it in the line. 1341 Since the dependents of files are not made until the file it- 1342 self could be made, this also stops the dependents being built 1343 unless they are needed for another branch of the dependency 1344 tree. So given: 1345 1346 x: a .WAIT b 1347 echo x 1348 a: 1349 echo a 1350 b: b1 1351 echo b 1352 b1: 1353 echo b1 1354 1355 the output is always `a', `b1', `b', `x'. 1356 The ordering imposed by [1m.WAIT [22mis only relevant for parallel 1357 makes. 1358 1359[1mSPECIAL TARGETS[0m 1360 Special targets may not be included with other targets, i.e. they must be 1361 the only target specified. 1362 1363 [1m.BEGIN [22mAny command lines attached to this target are executed before 1364 anything else is done. 1365 1366 [1m.DEFAULT[0m 1367 This is sort of a [1m.USE [22mrule for any target (that was used only 1368 as a source) that [1mbmake [22mcan't figure out any other way to cre- 1369 ate. Only the shell script is used. The [1m.IMPSRC [22mvariable of a 1370 target that inherits [1m.DEFAULT[22m's commands is set to the target's 1371 own name. 1372 1373 [1m.DELETE_ON_ERROR[0m 1374 If this target is present in the makefile, it globally causes 1375 make to delete targets whose commands fail. (By default, only 1376 targets whose commands are interrupted during execution are 1377 deleted. This is the historical behavior.) This setting can be 1378 used to help prevent half-finished or malformed targets from be- 1379 ing left around and corrupting future rebuilds. 1380 1381 [1m.END [22mAny command lines attached to this target are executed after ev- 1382 erything else is done. 1383 1384 [1m.ERROR [22mAny command lines attached to this target are executed when an- 1385 other target fails. The [1m.ERROR_TARGET [22mvariable is set to the 1386 target that failed. See also [1mMAKE_PRINT_VAR_ON_ERROR[22m. 1387 1388 [1m.IGNORE [22mMark each of the sources with the [1m.IGNORE [22mattribute. If no 1389 sources are specified, this is the equivalent of specifying the 1390 [1m-i [22moption. 1391 1392 [1m.INTERRUPT[0m 1393 If [1mbmake [22mis interrupted, the commands for this target will be 1394 executed. 1395 1396 [1m.MAIN [22mIf no target is specified when [1mbmake [22mis invoked, this target 1397 will be built. 1398 1399 [1m.MAKEFLAGS[0m 1400 This target provides a way to specify flags for [1mbmake [22mwhen the 1401 makefile is used. The flags are as if typed to the shell, 1402 though the [1m-f [22moption will have no effect. 1403 1404 [1m.NOPATH [22mApply the [1m.NOPATH [22mattribute to any specified sources. 1405 1406 [1m.NOTPARALLEL[0m 1407 Disable parallel mode. 1408 1409 [1m.NO_PARALLEL[0m 1410 Synonym for [1m.NOTPARALLEL[22m, for compatibility with other pmake 1411 variants. 1412 1413 [1m.OBJDIR [22mThe source is a new value for `[4m.OBJDIR[24m'. If it exists, [1mbmake[0m 1414 will chdir(2) to it and update the value of `[4m.OBJDIR[24m'. 1415 1416 [1m.ORDER [22mThe named targets are made in sequence. This ordering does not 1417 add targets to the list of targets to be made. Since the depen- 1418 dents of a target do not get built until the target itself could 1419 be built, unless `a' is built by another part of the dependency 1420 graph, the following is a dependency loop: 1421 1422 .ORDER: b a 1423 b: a 1424 1425 The ordering imposed by [1m.ORDER [22mis only relevant for parallel 1426 makes. 1427 1428 [1m.PATH [22mThe sources are directories which are to be searched for files 1429 not found in the current directory. If no sources are speci- 1430 fied, any previously specified directories are deleted. If the 1431 source is the special [1m.DOTLAST [22mtarget, then the current working 1432 directory is searched last. 1433 1434 [1m.PATH.[4m[22msuffix[0m 1435 Like [1m.PATH [22mbut applies only to files with a particular suffix. 1436 The suffix must have been previously declared with [1m.SUFFIXES[22m. 1437 1438 [1m.PHONY [22mApply the [1m.PHONY [22mattribute to any specified sources. 1439 1440 [1m.PRECIOUS[0m 1441 Apply the [1m.PRECIOUS [22mattribute to any specified sources. If no 1442 sources are specified, the [1m.PRECIOUS [22mattribute is applied to ev- 1443 ery target in the file. 1444 1445 [1m.SHELL [22mSets the shell that [1mbmake [22mwill use to execute commands. The 1446 sources are a set of [4mfield=value[24m pairs. 1447 1448 [4mname[24m This is the minimal specification, used to select 1449 one of the built-in shell specs; [4msh[24m, [4mksh[24m, and [4mcsh[24m. 1450 1451 [4mpath[24m Specifies the path to the shell. 1452 1453 [4mhasErrCtl[24m Indicates whether the shell supports exit on error. 1454 1455 [4mcheck[24m The command to turn on error checking. 1456 1457 [4mignore[24m The command to disable error checking. 1458 1459 [4mecho[24m The command to turn on echoing of commands executed. 1460 1461 [4mquiet[24m The command to turn off echoing of commands exe- 1462 cuted. 1463 1464 [4mfilter[24m The output to filter after issuing the [4mquiet[24m com- 1465 mand. It is typically identical to [4mquiet[24m. 1466 1467 [4merrFlag[24m The flag to pass the shell to enable error checking. 1468 1469 [4mechoFlag[24m The flag to pass the shell to enable command echo- 1470 ing. 1471 1472 [4mnewline[24m The string literal to pass the shell that results in 1473 a single newline character when used outside of any 1474 quoting characters. 1475 Example: 1476 1477 .SHELL: name=ksh path=/bin/ksh hasErrCtl=true \ 1478 check="set -e" ignore="set +e" \ 1479 echo="set -v" quiet="set +v" filter="set +v" \ 1480 echoFlag=v errFlag=e newline="'\n'" 1481 1482 [1m.SILENT [22mApply the [1m.SILENT [22mattribute to any specified sources. If no 1483 sources are specified, the [1m.SILENT [22mattribute is applied to every 1484 command in the file. 1485 1486 [1m.STALE [22mThis target gets run when a dependency file contains stale en- 1487 tries, having [4m.ALLSRC[24m set to the name of that dependency file. 1488 1489 [1m.SUFFIXES[0m 1490 Each source specifies a suffix to [1mbmake[22m. If no sources are 1491 specified, any previously specified suffixes are deleted. It 1492 allows the creation of suffix-transformation rules. 1493 1494 Example: 1495 1496 .SUFFIXES: .o 1497 .c.o: 1498 cc -o ${.TARGET} -c ${.IMPSRC} 1499 1500[1mENVIRONMENT[0m 1501 [1mbmake [22muses the following environment variables, if they exist: MACHINE, 1502 MACHINE_ARCH, MAKE, MAKEFLAGS, MAKEOBJDIR, MAKEOBJDIRPREFIX, MAKESYSPATH, 1503 PWD, and TMPDIR. 1504 1505 MAKEOBJDIRPREFIX and MAKEOBJDIR may only be set in the environment or on 1506 the command line to [1mbmake [22mand not as makefile variables; see the descrip- 1507 tion of `[4m.OBJDIR[24m' for more details. 1508 1509[1mFILES[0m 1510 .depend list of dependencies 1511 Makefile list of dependencies 1512 makefile list of dependencies 1513 sys.mk system makefile 1514 /usr/share/mk system makefile directory 1515 1516[1mCOMPATIBILITY[0m 1517 The basic make syntax is compatible between different versions of make; 1518 however the special variables, variable modifiers and conditionals are 1519 not. 1520 1521 [1mOlder versions[0m 1522 An incomplete list of changes in older versions of [1mbmake[22m: 1523 1524 The way that .for loop variables are substituted changed after NetBSD 5.0 1525 so that they still appear to be variable expansions. In particular this 1526 stops them being treated as syntax, and removes some obscure problems us- 1527 ing them in .if statements. 1528 1529 The way that parallel makes are scheduled changed in NetBSD 4.0 so that 1530 .ORDER and .WAIT apply recursively to the dependent nodes. The algo- 1531 rithms used may change again in the future. 1532 1533 [1mOther make dialects[0m 1534 Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not sup- 1535 port most of the features of [1mbmake [22mas described in this manual. Most no- 1536 tably: 1537 1538 [1m+o [22mThe [1m.WAIT [22mand [1m.ORDER [22mdeclarations and most functionality per- 1539 taining to parallelization. (GNU make supports parallelization 1540 but lacks these features needed to control it effectively.) 1541 1542 [1m+o [22mDirectives, including for loops and conditionals and most of 1543 the forms of include files. (GNU make has its own incompatible 1544 and less powerful syntax for conditionals.) 1545 1546 [1m+o [22mAll built-in variables that begin with a dot. 1547 1548 [1m+o [22mMost of the special sources and targets that begin with a dot, 1549 with the notable exception of [1m.PHONY[22m, [1m.PRECIOUS[22m, and [1m.SUFFIXES[22m. 1550 1551 [1m+o [22mVariable modifiers, except for the 1552 :old=new 1553 string substitution, which does not portably support globbing 1554 with `%' and historically only works on declared suffixes. 1555 1556 [1m+o [22mThe [1m$> [22mvariable even in its short form; most makes support this 1557 functionality but its name varies. 1558 1559 Some features are somewhat more portable, such as assignment with [1m+=[22m, [1m?=[22m, 1560 and [1m!=[22m. The [1m.PATH [22mfunctionality is based on an older feature [1mVPATH [22mfound 1561 in GNU make and many versions of SVR4 make; however, historically its be- 1562 havior is too ill-defined (and too buggy) to rely upon. 1563 1564 The [1m$@ [22mand [1m$< [22mvariables are more or less universally portable, as is the 1565 [1m$(MAKE) [22mvariable. Basic use of suffix rules (for files only in the cur- 1566 rent directory, not trying to chain transformations together, etc.) is 1567 also reasonably portable. 1568 1569[1mSEE ALSO[0m 1570 mkdep(1) 1571 1572[1mHISTORY[0m 1573 [1mbmake [22mis derived from NetBSD make(1). It uses autoconf to facilitate 1574 portability to other platforms. 1575 1576 A make command appeared in Version 7 AT&T UNIX. This make implementation 1577 is based on Adam De Boor's pmake program which was written for Sprite at 1578 Berkeley. It was designed to be a parallel distributed make running jobs 1579 on different machines using a daemon called "customs". 1580 1581 Historically the target/dependency "FRC" has been used to FoRCe rebuild- 1582 ing (since the target/dependency does not exist... unless someone creates 1583 an "FRC" file). 1584 1585[1mBUGS[0m 1586 The make syntax is difficult to parse without actually acting on the 1587 data. For instance, finding the end of a variable's use should involve 1588 scanning each of the modifiers, using the correct terminator for each 1589 field. In many places make just counts {} and () in order to find the 1590 end of a variable expansion. 1591 1592 There is no way of escaping a space character in a filename. 1593 1594FreeBSD 13.0 December 12, 2021 FreeBSD 13.0 1595