mk.1 (14152B)
1 .TH MK 1 2 .SH NAME 3 mk \- maintain (make) related files 4 .SH SYNOPSIS 5 .B mk 6 [ 7 .B -f 8 .I mkfile 9 ] ... 10 [ 11 .I option ... 12 ] 13 [ 14 .I target ... 15 ] 16 .SH DESCRIPTION 17 .I Mk 18 uses the dependency rules specified in 19 .I mkfile 20 to control the update (usually by compilation) of 21 .I targets 22 (usually files) 23 from the source files upon which they depend. 24 The 25 .I mkfile 26 (default 27 .LR mkfile ) 28 contains a 29 .I rule 30 for each target that identifies the files and other 31 targets upon which it depends and an 32 .IR sh (1) 33 script, a 34 .IR recipe , 35 to update the target. 36 The script is run if the target does not exist 37 or if it is older than any of the files it depends on. 38 .I Mkfile 39 may also contain 40 .I meta-rules 41 that define actions for updating implicit targets. 42 If no 43 .I target 44 is specified, the target of the first rule (not meta-rule) in 45 .I mkfile 46 is updated. 47 .PP 48 The environment variable 49 .B $NPROC 50 determines how many targets may be updated simultaneously; 51 Some operating systems, e.g., Plan 9, set 52 .B $NPROC 53 automatically to the number of CPUs on the current machine. 54 .PP 55 Options are: 56 .TP \w'\fL-d[egp]\ 'u 57 .B -a 58 Assume all targets to be out of date. 59 Thus, everything is updated. 60 .PD 0 61 .TP 62 .BR -d [ egp ] 63 Produce debugging output 64 .RB ( p 65 is for parsing, 66 .B g 67 for graph building, 68 .B e 69 for execution). 70 .TP 71 .B -e 72 Explain why each target is made. 73 .TP 74 .B -i 75 Force any missing intermediate targets to be made. 76 .TP 77 .B -k 78 Do as much work as possible in the face of errors. 79 .TP 80 .B -n 81 Print, but do not execute, the commands 82 needed to update the targets. 83 .TP 84 .B -s 85 Make the command line arguments sequentially rather than in parallel. 86 .TP 87 .B -t 88 Touch (update the modified date of) file targets, without 89 executing any recipes. 90 .TP 91 .BI -w target1 , target2,... 92 Pretend the modify time for each 93 .I target 94 is the current time; useful in conjunction with 95 .B -n 96 to learn what updates would be triggered by 97 modifying the 98 .IR targets . 99 .PD 100 .SS The \fLmkfile\fP 101 A 102 .I mkfile 103 consists of 104 .I assignments 105 (described under `Environment') and 106 .IR rules . 107 A rule contains 108 .I targets 109 and a 110 .IR tail . 111 A target is a literal string 112 and is normally a file name. 113 The tail contains zero or more 114 .I prerequisites 115 and an optional 116 .IR recipe , 117 which is an 118 .B shell 119 script. 120 Each line of the recipe must begin with white space. 121 A rule takes the form 122 .IP 123 .EX 124 target: prereq1 prereq2 125 \f2recipe using\fP prereq1, prereq2 \f2to build\fP target 126 .EE 127 .PP 128 When the recipe is executed, 129 the first character on every line is elided. 130 .PP 131 After the colon on the target line, a rule may specify 132 .IR attributes , 133 described below. 134 .PP 135 A 136 .I meta-rule 137 has a target of the form 138 .IB A % B 139 where 140 .I A 141 and 142 .I B 143 are (possibly empty) strings. 144 A meta-rule acts as a rule for any potential target whose 145 name matches 146 .IB A % B 147 with 148 .B % 149 replaced by an arbitrary string, called the 150 .IR stem . 151 In interpreting a meta-rule, 152 the stem is substituted for all occurrences of 153 .B % 154 in the prerequisite names. 155 In the recipe of a meta-rule, the environment variable 156 .B $stem 157 contains the string matched by the 158 .BR % . 159 For example, a meta-rule to compile a C program 160 might be: 161 .IP 162 .EX 163 %: %.c 164 cc -c $stem.c 165 ld -o $stem $stem.o 166 .EE 167 .PP 168 Meta-rules may contain an ampersand 169 .B & 170 rather than a percent sign 171 .BR % . 172 A 173 .B % 174 matches a maximal length string of any characters; 175 an 176 .B & 177 matches a maximal length string of any characters except period 178 or slash. 179 .PP 180 The text of the 181 .I mkfile 182 is processed as follows. 183 Lines beginning with 184 .B < 185 followed by a file name are replaced by the contents of the named 186 file. 187 Lines beginning with 188 .B "<|" 189 followed by a file name are replaced by the output 190 of the execution of the named 191 file. 192 Blank lines and comments, which run from unquoted 193 .B # 194 characters to the following newline, are deleted. 195 The character sequence backslash-newline is deleted, 196 so long lines in 197 .I mkfile 198 may be folded. 199 Non-recipe lines are processed by substituting for 200 .BI `{ command } 201 the output of the 202 .I command 203 when run by 204 .IR sh . 205 References to variables are replaced by the variables' values. 206 Special characters may be quoted using single quotes 207 .BR \&'' 208 as in 209 .IR sh (1). 210 .PP 211 Assignments and rules are distinguished by 212 the first unquoted occurrence of 213 .B : 214 (rule) 215 or 216 .B = 217 (assignment). 218 .PP 219 A later rule may modify or override an existing rule under the 220 following conditions: 221 .TP 222 \- 223 If the targets of the rules exactly match and one rule 224 contains only a prerequisite clause and no recipe, the 225 clause is added to the prerequisites of the other rule. 226 If either or both targets are virtual, the recipe is 227 always executed. 228 .TP 229 \- 230 If the targets of the rules match exactly and the 231 prerequisites do not match and both rules 232 contain recipes, 233 .I mk 234 reports an ``ambiguous recipe'' error. 235 .TP 236 \- 237 If the target and prerequisites of both rules match exactly, 238 the second rule overrides the first. 239 .SS Environment 240 Rules may make use of 241 shell 242 environment variables. 243 A legal reference of the form 244 .B $OBJ 245 or 246 .B ${name} 247 is expanded as in 248 .IR sh (1). 249 A reference of the form 250 .BI ${name: A % B = C\fL%\fID\fL}\fR, 251 where 252 .I A, B, C, D 253 are (possibly empty) strings, 254 has the value formed by expanding 255 .B $name 256 and substituting 257 .I C 258 for 259 .I A 260 and 261 .I D 262 for 263 .I B 264 in each word in 265 .B $name 266 that matches pattern 267 .IB A % B\f1. 268 .PP 269 Variables can be set by 270 assignments of the form 271 .I 272 var\fL=\fR[\fIattr\fL=\fR]\fIvalue\fR 273 .br 274 Blanks in the 275 .I value 276 break it into words. 277 Such variables are exported 278 to the environment of 279 recipes as they are executed, unless 280 .BR U , 281 the only legal attribute 282 .IR attr , 283 is present. 284 The initial value of a variable is 285 taken from (in increasing order of precedence) 286 the default values below, 287 .I mk's 288 environment, the 289 .IR mkfiles , 290 and any command line assignment as an argument to 291 .IR mk . 292 A variable assignment argument overrides the first (but not any subsequent) 293 assignment to that variable. 294 .PP 295 The variable 296 .B MKFLAGS 297 contains all the option arguments (arguments starting with 298 .L - 299 or containing 300 .LR = ) 301 and 302 .B MKARGS 303 contains all the targets in the call to 304 .IR mk . 305 .PP 306 The variable 307 .B MKSHELL 308 contains the shell command line 309 .I mk 310 uses to run recipes. 311 If the first word of the command ends in 312 .B rc 313 or 314 .BR rcsh , 315 .I mk 316 uses 317 .IR rc (1)'s 318 quoting rules; otherwise it uses 319 .IR sh (1)'s. 320 The 321 .B MKSHELL 322 variable is consulted when the mkfile is read, not when it is executed, 323 so that different shells can be used within a single mkfile: 324 .IP 325 .EX 326 MKSHELL=$PLAN9/bin/rc 327 use-rc:V: 328 for(i in a b c) echo $i 329 330 MKSHELL=sh 331 use-sh:V: 332 for i in a b c; do echo $i; done 333 .EE 334 .LP 335 Mkfiles included via 336 .B < 337 or 338 .B <| 339 .RI ( q.v. ) 340 see their own private copy of 341 .BR MKSHELL , 342 which always starts set to 343 .B sh . 344 .PP 345 Dynamic information may be included in the mkfile by using a line of the form 346 .IP 347 \fR<|\fIcommand\fR \fIargs\fR 348 .LP 349 This runs the command 350 .I command 351 with the given arguments 352 .I args 353 and pipes its standard output to 354 .I mk 355 to be included as part of the mkfile. For instance, the Inferno kernels 356 use this technique 357 to run a shell command with an awk script and a configuration 358 file as arguments in order for 359 the 360 .I awk 361 script to process the file and output a set of variables and their values. 362 .SS Execution 363 .PP 364 During execution, 365 .I mk 366 determines which targets must be updated, and in what order, 367 to build the 368 .I names 369 specified on the command line. 370 It then runs the associated recipes. 371 .PP 372 A target is considered up to date if it has no prerequisites or 373 if all its prerequisites are up to date and it is newer 374 than all its prerequisites. 375 Once the recipe for a target has executed, the target is 376 considered up to date. 377 .PP 378 The date stamp 379 used to determine if a target is up to date is computed 380 differently for different types of targets. 381 If a target is 382 .I virtual 383 (the target of a rule with the 384 .B V 385 attribute), 386 its date stamp is initially zero; when the target is 387 updated the date stamp is set to 388 the most recent date stamp of its prerequisites. 389 Otherwise, if a target does not exist as a file, 390 its date stamp is set to the most recent date stamp of its prerequisites, 391 or zero if it has no prerequisites. 392 Otherwise, the target is the name of a file and 393 the target's date stamp is always that file's modification date. 394 The date stamp is computed when the target is needed in 395 the execution of a rule; it is not a static value. 396 .PP 397 Nonexistent targets that have prerequisites 398 and are themselves prerequisites are treated specially. 399 Such a target 400 .I t 401 is given the date stamp of its most recent prerequisite 402 and if this causes all the targets which have 403 .I t 404 as a prerequisite to be up to date, 405 .I t 406 is considered up to date. 407 Otherwise, 408 .I t 409 is made in the normal fashion. 410 The 411 .B -i 412 flag overrides this special treatment. 413 .PP 414 Files may be made in any order that respects 415 the preceding restrictions. 416 .PP 417 A recipe is executed by supplying the recipe as standard input to 418 the command 419 .BR /bin/sh . 420 (Note that unlike 421 .IR make , 422 .I mk 423 feeds the entire recipe to the shell rather than running each line 424 of the recipe separately.) 425 The environment is augmented by the following variables: 426 .TP 14 427 .B $alltarget 428 all the targets of this rule. 429 .TP 430 .B $newprereq 431 the prerequisites that caused this rule to execute. 432 .TP 433 .B $newmember 434 the prerequisites that are members of an aggregate 435 that caused this rule to execute. 436 When the prerequisites of a rule are members of an 437 aggregate, 438 .B $newprereq 439 contains the name of the aggregate and out of date 440 members, while 441 .B $newmember 442 contains only the name of the members. 443 .TP 444 .B $nproc 445 the process slot for this recipe. 446 It satisfies 447 .RB 0≤ $nproc < $NPROC . 448 .TP 449 .B $pid 450 the process id for the 451 .I mk 452 executing the recipe. 453 .TP 454 .B $prereq 455 all the prerequisites for this rule. 456 .TP 457 .B $stem 458 if this is a meta-rule, 459 .B $stem 460 is the string that matched 461 .B % 462 or 463 .BR & . 464 Otherwise, it is empty. 465 For regular expression meta-rules (see below), the variables 466 .LR stem0 ", ...," 467 .L stem9 468 are set to the corresponding subexpressions. 469 .TP 470 .B $target 471 the targets for this rule that need to be remade. 472 .PP 473 These variables are available only during the execution of a recipe, 474 not while evaluating the 475 .IR mkfile . 476 .PP 477 Unless the rule has the 478 .B Q 479 attribute, 480 the recipe is printed prior to execution 481 with recognizable environment variables expanded. 482 Commands returning error status 483 cause 484 .I mk 485 to terminate. 486 .PP 487 Recipes and backquoted 488 .B rc 489 commands in places such as assignments 490 execute in a copy of 491 .I mk's 492 environment; changes they make to 493 environment variables are not visible from 494 .IR mk . 495 .PP 496 Variable substitution in a rule is done when 497 the rule is read; variable substitution in the recipe is done 498 when the recipe is executed. For example: 499 .IP 500 .EX 501 bar=a.c 502 foo: $bar 503 $CC -o foo $bar 504 bar=b.c 505 .EE 506 .PP 507 will compile 508 .B b.c 509 into 510 .BR foo , 511 if 512 .B a.c 513 is newer than 514 .BR foo . 515 .SS Aggregates 516 Names of the form 517 .IR a ( b ) 518 refer to member 519 .I b 520 of the aggregate 521 .IR a . 522 .SS Attributes 523 The colon separating the target from the prerequisites 524 may be 525 immediately followed by 526 .I attributes 527 and another colon. 528 The attributes are: 529 .TP 530 .B D 531 If the recipe exits with a non-null status, the target is deleted. 532 .TP 533 .B E 534 Continue execution if the recipe draws errors. 535 .TP 536 .B N 537 If there is no recipe, the target has its time updated. 538 .TP 539 .B n 540 The rule is a meta-rule that cannot be a target of a virtual rule. 541 Only files match the pattern in the target. 542 .TP 543 .B P 544 The characters after the 545 .B P 546 until the terminating 547 .B : 548 are taken as a program name. 549 It will be invoked as 550 .B "sh -c prog 'arg1' 'arg2'" 551 and should return a zero exit status 552 if and only if arg1 is up to date with respect to arg2. 553 Date stamps are still propagated in the normal way. 554 .TP 555 .B Q 556 The recipe is not printed prior to execution. 557 .TP 558 .B R 559 The rule is a meta-rule using regular expressions. 560 In the rule, 561 .B % 562 has no special meaning. 563 The target is interpreted as a regular expression as defined in 564 .IR regexp9 (7). 565 The prerequisites may contain references 566 to subexpressions in form 567 .BI \e n\f1, 568 as in the substitute command of 569 .IR sed (1). 570 .TP 571 .B U 572 The targets are considered to have been updated 573 even if the recipe did not do so. 574 .TP 575 .B V 576 The targets of this rule are marked as virtual. 577 They are distinct from files of the same name. 578 .PD 579 .SH EXAMPLES 580 A simple mkfile to compile a program: 581 .IP 582 .EX 583 .ta 8n +8n +8n +8n +8n +8n +8n 584 </$objtype/mkfile 585 586 prog: a.$O b.$O c.$O 587 $LD $LDFLAGS -o $target $prereq 588 589 %.$O: %.c 590 $CC $CFLAGS $stem.c 591 .EE 592 .PP 593 Override flag settings in the mkfile: 594 .IP 595 .EX 596 % mk target 'CFLAGS=-S -w' 597 .EE 598 .PP 599 Maintain a library: 600 .IP 601 .EX 602 libc.a(%.$O):N: %.$O 603 libc.a: libc.a(abs.$O) libc.a(access.$O) libc.a(alarm.$O) ... 604 ar r libc.a $newmember 605 .EE 606 .PP 607 String expression variables to derive names from a master list: 608 .IP 609 .EX 610 NAMES=alloc arc bquote builtins expand main match mk var word 611 OBJ=${NAMES:%=%.$O} 612 .EE 613 .PP 614 Regular expression meta-rules: 615 .IP 616 .EX 617 ([^/]*)/(.*)\e.$O:R: \e1/\e2.c 618 cd $stem1; $CC $CFLAGS $stem2.c 619 .EE 620 .PP 621 A correct way to deal with 622 .IR yacc (1) 623 grammars. 624 The file 625 .B lex.c 626 includes the file 627 .B x.tab.h 628 rather than 629 .B y.tab.h 630 in order to reflect changes in content, not just modification time. 631 .IP 632 .EX 633 lex.$O: x.tab.h 634 x.tab.h: y.tab.h 635 cmp -s x.tab.h y.tab.h || cp y.tab.h x.tab.h 636 y.tab.c y.tab.h: gram.y 637 $YACC -d gram.y 638 .EE 639 .PP 640 The above example could also use the 641 .B P 642 attribute for the 643 .B x.tab.h 644 rule: 645 .IP 646 .EX 647 x.tab.h:Pcmp -s: y.tab.h 648 cp y.tab.h x.tab.h 649 .EE 650 .SH SOURCE 651 .B https://9fans.github.io/plan9port/unix 652 .SH SEE ALSO 653 .IR sh (1), 654 .IR regexp9 (7) 655 .PP 656 A. Hume, 657 ``Mk: a Successor to Make'' 658 (Tenth Edition Research Unix Manuals). 659 .PP 660 Andrew G. Hume and Bob Flandrena, 661 ``Maintaining Files on Plan 9 with Mk''. 662 .BR DOCPREFIX/doc/mk.pdf . 663 .SH HISTORY 664 Andrew Hume wrote 665 .I mk 666 for Tenth Edition Research Unix. 667 It was later ported to Plan 9. 668 This software is a port of the Plan 9 version back to Unix. 669 .SH BUGS 670 Identical recipes for regular expression meta-rules only have one target. 671 .PP 672 Seemingly appropriate input like 673 .B CFLAGS=-DHZ=60 674 is parsed as an erroneous attribute; correct it by inserting 675 a space after the first 676 .LR = . 677 .PP 678 The recipes printed by 679 .I mk 680 before being passed to 681 the shell 682 for execution are sometimes erroneously expanded 683 for printing. Don't trust what's printed; rely 684 on what the shell 685 does.