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