1.HTML "Plan 9 Mkfiles 2.TL 3Plan 9 Mkfiles 4.AU 5Bob Flandrena 6bobf@plan9.bell-labs.com 7.SH 8Introduction 9.LP 10Every Plan 9 source directory contains a file, called 11.CW mkfile , 12specifying the rules for building the executable or 13library that is the product of the directory. 14.I Mk (1) 15interprets the rules in the file, calculates 16the dependencies, and executes an 17.I rc (1) 18script to construct the product. 19If necessary components are supplied by 20neighboring directories or sub-directories, the mkfiles in those 21directories are first executed to build the components 22before the local construction proceeds. 23.LP 24Most application source directories produce one of 25four types of product: 26a single executable, several 27executables, a local library, or 28a system library. 29Four generic 30mkfiles 31define the normal rules 32for building each type of product. The simplest 33mkfiles need only 34list the components 35and include the appropriate 36generic 37mkfile 38to do the work. 39More complex 40mkfiles 41may supply additional rules 42to augment, modify, or override the generic rules. 43.SH 44Using a Mkfile 45.LP 46To build a product, change to the directory containing 47its source and invoke 48.I mk 49with the appropriate target as an argument. 50All mkfiles provide the following standard targets: 51.TS 52lw(1i) lw(4.5i). 53\f(CWall\fP T{ 54Build a local version of the product or products for the 55current architecture. If the product is a single program, 56the result is stored in file 57.CW $O.out . 58If the directory produces multiple executables, they are 59stored in the files named 60.CW $O.\fIprogname,\fP 61where 62.I progname 63is the name of each executable. 64A product may be built for a different architecture by 65prefacing the 66.CW mk 67command with 68\f(CWobjtype=\fP\fIarchitecture\fP, 69where 70.I architecture 71is the name of the target architecture. 72Directories producing system 73libraries always operate directly on the installed version of the 74library; in this case the target 75.CW all 76is equivalent to the target 77.CW install . 78T} 79\f(CWinstall\fP T{ 80Build and install the product or products for the current 81architecture. 82T} 83\f(CWinstallall\fP T{ 84Build and install the product or products for all architectures. 85T} 86\f(CWclean\fP T{ 87Rid the directory and its subdirectories of the by-products of 88the build process. Intermediate files that are easily reproduced 89(e.g., object files, 90.CW yacc 91intermediates, target executables) are always 92removed. Complicated intermediates, such as local libraries, are 93usually preserved. 94T} 95\f(CWnuke\fP T{ 96Remove all intermediates from the directory and any subdirectories. 97This target guarantees that a subsequent build for the 98architecture is performed 99from scratch. 100T} 101.TE 102.LP 103If no target is specified on the 104.CW mk 105command line, the 106.CW all 107target is built by default. In a directory 108producing multiple executables, there is 109no default target. 110.LP 111In addition to the five standard targets, 112additional targets may be supplied by each 113generic mkfile or by the directory's mkfile. 114.LP 115The environment variable 116.CW NPROC 117is set by the system to the number of 118available processors. 119Setting 120this variable, either in the environment or in 121a mkfile, controls the amount of parallelism in 122the build. For example, the command 123.P1 124 NPROC=1 mk 125.P2 126restricts a build to a single thread of execution. 127.SH 128Creating a Mkfile 129.LP 130The easiest way to build a new mkfile is to copy and modify 131an existing mkfile of the same type. 132Failing that, it is usually possible to create a new 133mkfile with minimal effort, since the appropriate 134generic mkfile predefines the rules that do all the work. 135In the simplest and most common cases, the new mkfile 136need only define a couple of variables and include the appropriate 137architecture-specific 138and generic mkfiles. 139.SH The Generic Mkfiles 140.LP 141There are four generic mkfiles containing commonly 142used rules for building a product: 143.CW mkone , 144.CW mkmany , 145.CW mklib , 146and 147.CW mksyslib . 148These rules 149perform such actions as compiling C source files, 150loading object files, archiving libraries, and 151installing executables in the 152.CW bin 153directory of the appropriate architecture. 154The generic mkfiles are stored in directory 155.CW /sys/src/cmd . 156Mkfile 157.CW mkone 158builds a single executable, 159.CW mkmany 160builds several executables from the source in a single 161directory, and 162.CW mklib 163and 164\f(CWmksyslib\fP, 165maintain local and system libraries, respectively. 166The rules in the generic mkfiles are driven by 167the values of variables, some of which must be 168set by the product mkfile and some of which are 169supplied by the generic mkfile. Variables in the 170latter class include: 171.TS 172center; 173ri ci li 174rw(1i) cw(0.5i) lw(2i). 175Variable Default Meaning 176.sp .5 177\f(CWCFLAGS\fP \f(CW-FVw\fP C compiler flags 178\f(CWLDFLAGS\fP Loader flags 179\f(CWYFLAGS\fP \f(CW-d\fP Yacc flags 180\f(CWAFLAGS\fP Assembler flags 181.TE 182.LP 183The following variables are set by the product mkfile 184and used by the generic mkfile. 185Any may be empty depending on the specific product being 186made. 187.TS 188center; 189lw(1i) lw(2.5i). 190\f(CWTARG\fP Name(s) of the executable(s) to be built 191\f(CWLIB\fP Library name(s) 192\f(CWOFILES\fP Object files 193\f(CWHFILES\fP Header files included by all source files 194\f(CWYFILES\fP \f(CWYacc\fP input files 195\f(CWBIN\fP Directory where executables are installed 196.TE 197.SH 198Mkfile Organization 199.LP 200All 201mkfiles 202share the following common structure: 203.P1 204</$objtype/mkfile # \f1architecture-dependent definitions\fP 205.sp 206\fIvariable definitions\fP # TARG\f1, \fPOFILES\f1, \fPHFILES\f1, etc.\fP 207.sp 208</sys/src/cmd/\fIgeneric\fP # mkone\f1, \fPmkmany\f1, \fPmklib\f1, or \fPmksyslib 209.sp 210\fIvariable overrides\fP # CFLAGS\f1, \fPobjtype\f1, etc.\fP 211.sp 212\fIextra rules\fP # \f1overrides, augmented rules, additional targets\fP 213.P2 214Note that the architecture-dependent mkfiles include file 215.CW /sys/src/mkfile.proto 216for system-wide variables that are common to all architectures. 217.LP 218The variables driving the expansion of the generic mkfile 219may be specified in any order as long as they are defined 220before the inclusion of the generic mkfile. The value 221of a variable may be changed by assigning a new value 222following the inclusion of the generic mkfile, but the 223effects are sometimes counter-intuitive. 224Such variable assignments do not apply to the target and 225prerequisite portions of any previously defined rules; 226the new values only apply to the recipes of rules preceding 227the assignment statement and 228to all parts of any rules following it. 229.LP 230The rules supplied by the generic mkfile may 231be overridden or augmented. The new rules must 232be specified after the inclusion of the generic 233mkfile. If the target and prerequisite portion 234of the rule exactly match the target and prerequisite 235portion of a previously defined rule and the new rule contains 236a recipe, the new rule replaces the old one. 237If the target of a new rule exactly matches the 238target of a previous rule and one or more new 239prerequisites are specified and the new rule contains 240no recipe, the new prerequisites are added to the prerequisites 241of the old rule. 242.LP 243Following sections discuss 244each generic mkfile in detail. 245.SH 246Mkone 247.LP 248The 249.CW mkone 250generic mkfile contains rules for building 251a single executable from one or more files 252in a directory. 253The variable 254.CW TARG 255specifies the name of the executable and 256variables 257.CW OFILES 258and 259.CW YFILES 260specify the object files and 261.CW yacc 262source files used to build it. 263.CW HFILES 264contains the names of the local header files 265included in all source files. 266.CW BIN 267is the name of the directory where the executable 268is installed. 269.CW LIB 270contains the names of local libraries used by the 271linker. This variable is rarely needed 272as libraries referenced by a 273.CW #pragma 274directive in an associated header file, including 275all system libraries, are automatically 276searched by the loader. 277.LP 278If 279.CW mk 280is executed without a target, the 281.CW all 282target is built; it 283produces an executable in 284.CW $O.out . 285Variable 286.CW HFILES 287identifies the header files that 288are included in all or most or 289the C source files. Occasionally, 290a program has other header files 291that are only used in some 292source files. A 293header can be added to the prerequisites for 294those object files by adding a rule of 295the following form following the inclusion of generic mkfile 296.CW mkone : 297.P1 298file.$O: header.h 299.P2 300.LP 301The mkfile for a directory producing a single 302executable using the normal set of rules is 303trivial: a list of some files followed by the 304inclusion of 305.I mkone. 306For example, 307.CW /sys/src/cmd/diff/mkfile 308contains: 309.P1 310< /$objtype/mkfile 311 312TARG=diff 313OFILES=\e 314 diffdir.$O\e 315 diffio.$O\e 316 diffreg.$O\e 317 main.$O\e 318 319HFILES=diff.h 320 321BIN=/$objtype/bin 322</sys/src/cmd/mkone 323.P2 324The more complex mkfile in 325.CW /sys/src/cmd/awk 326overrides compiler and loader variables to 327select the ANSI/POSIX Computing Environment with appropriately 328defined command line variables. It also overrides 329the default 330.CW yacc 331rule to place the output soure in file 332.CW awkgram.c 333and the 334.CW clean 335and 336.CW nuke 337rules, so it can remove the non-standard intermediate 338files. Finally, the last three rules build a version of 339.CW maketab 340appropriate for the architecture where the 341.CW mk 342is being 343run and then executes it to create source file 344.CW proctab.c : 345.P1 346</$objtype/mkfile 347 348TARG=awk 349OFILES=re.$O\e 350 lex.$O\e 351 main.$O\e 352 parse.$O\e 353 proctab.$O\e 354 tran.$O\e 355 lib.$O\e 356 run.$O\e 357 awkgram.$O\e 358 359HFILES=awk.h\e 360 y.tab.h\e 361 proto.h\e 362 363YFILES=awkgram.y 364 365BIN=/$objtype/bin 366</sys/src/cmd/mkone 367CFLAGS=-c -D_REGEXP_EXTENSION -D_RESEARCH_SOURCE \e 368 -D_BSD_EXTENSION -DUTF 369YFLAGS=-S -d -v 370CC=pcc 371LD=pcc 372cpuobjtype=`{sed -n 's/^O=//p' /$cputype/mkfile} 373 374y.tab.h awkgram.c: $YFILES 375 $YACC -o awkgram.c $YFLAGS $prereq 376 377clean:V: 378 rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e 379 y.output $TARG 380 381nuke:V: 382 rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e 383 y.output awkgram.c $TARG 384 385proctab.c: $cpuobjtype.maketab 386 ./$cpuobjtype.maketab >proctab.c 387 388$cpuobjtype.maketab: y.tab.h maketab.c 389 objtype=$cputype 390 mk maketab.$cputype 391 392maketab.$cputype:V: y.tab.h maketab.$O 393 $LD -o $O.maketab maketab.$O 394.P2 395.SH 396Mkmany 397.LP 398The 399.CW mkmany 400generic mkfile builds several 401executables from the files in a 402directory. It differs from the operation of 403.CW mkone 404in three respects: 405.CW TARG 406specifies the names of all executables, 407there is no default command-line target, 408and additional rules allow a single executable to 409be built or installed. 410.LP 411The 412.CW TARG 413variable specifies the names of all 414executables produced by the mkfile. The 415rules assume the name of each executable is also 416the name of the file containing its 417.CW main 418function. 419.CW OFILES 420specifies files containing 421common subroutines loaded with all executables. 422Consider the mkfile: 423.P1 424</$objtype/mkfile 425 426TARG=alpha beta 427OFILES=common.$O 428BIN=/$objtype/bin 429</sys/src/cmd/mkmany 430.P2 431It assumes the main functions for executables 432.CW alpha 433and 434.CW beta 435are in files 436.CW alpha.$O 437and 438.CW beta.$O 439and that both programs use the subroutines 440in file 441.CW common.$O . 442The 443.CW all 444target builds all executables, leaving each in 445a file with a name of the form 446.CW $O.\fIprogname\fP 447where 448.I progname 449is the name of the executable. In this 450example the 451.CW all 452target produces executables 453.CW $O.alpha 454and 455.CW $O.beta . 456.LP 457The 458.CW mkmany 459rules provide additional 460targets for building a single 461executable: 462.TS 463lw(1i) lw(3.8i). 464\f(CW$O.progname\fP T{ 465Builds executable 466\f(CW$O.\fP\fIprogname\fP 467in the current directory. When the target 468architecture is not the current architecture 469the 470.CW mk 471command 472must be prefixed with the customary 473.CW objtype=\fIarchitecture\fP 474assignment to select the proper compilers and loaders. 475T} 476\f(CWprogname.install\fP T{ 477Installs executable 478.I progname 479for the target architecture. 480T} 481\f(CWprogname.installall\fP T{ 482Installs executable 483.I progname 484for all architectures. 485T} 486.TE 487.SH 488Mklib 489.LP 490The 491.CW mklib 492generic mkfile builds a local library. 493Since this form of mkfile constructs no 494executable, the 495.CW TARG 496and 497.CW BIN 498variables are not needed. Instead, the 499.CW LIB 500variable specifies the library 501to be built or updated. Variable 502.CW OFILES 503contains the names of the object files to be archived 504in the library. The use of variables 505.CW YFILES 506and 507.CW HFILES 508does not change. When possible, only the 509out-of-date members of the library are updated. 510.LP 511The variable 512.CW LIBDIR 513contains the name of the directory where the 514library is installed; by default it selects 515the current directory. It can be overridden 516by assigning the new directory name after the 517point where 518.CW mklib 519is included. 520.LP 521The 522.CW clean 523target removes object files and 524.CW yacc 525intermediate files but does not touch the 526library. The 527.CW nuke 528target removes the library as well as the 529files removed by the 530.CW clean 531target. The command 532.P1 533mk -s clean all 534.P2 535causes the existing library to be updated, or 536created if it doesn't already exist. The command 537.P1 538mk -s nuke all 539.P2 540forces the library to be rebuilt from scratch. 541.LP 542The mkfile from 543.CW /sys/src/cmd/upas/libString 544contains the following specifications to 545build the local library 546.CW libString.a$O 547for the object architecture referenced by 548.CW $O\fR\:\fP 549.P1 550</$objtype/mkfile 551 552LIB=libString.a$O 553OFILES= s_alloc.$O\e 554 s_append.$O\e 555 s_array.$O\e 556 s_copy.$O\e 557 s_getline.$O\e 558 s_grow.$O\e 559 s_nappend.$O\e 560 s_parse.$O\e 561 s_read.$O\e 562 s_read_line.$O\e 563 s_tolower.$O\e 564 565</sys/src/cmd/mklib 566 567nuke:V: 568 mk clean 569 rm -f libString.a[$OS] 570.P2 571The override of the rule for target 572.CW nuke 573removes the libraries for all architectures as 574opposed to the default recipe for this target 575which removes the library for the current architecture. 576.SH 577Mksyslib 578.LP 579The 580.CW mksyslib 581generic mkfile is similar to the 582.CW mklib 583mkfile except that it operates on a system library 584instead of a local library. 585The 586.CW install 587and 588.CW all 589targets are the same; since there is no local copy of 590the library, all updates are performed on the 591installed library. 592The rule for the 593.CW nuke 594target is identical to that of the 595.CW clean 596target; unlike the 597.CW nuke 598target for local libraries, 599the library is never removed. 600.LP 601No attempt is made to determine if individual library 602members are up-to-date; all members of a 603library are always updated. 604Special targets support manipulation of a single 605object file; the target 606.CW objfile 607updates file 608.CW objfile\f(CW.$O\fP 609in the library of the current architecture and the target 610.CW objfile.all 611updates 612.CW objfile\f(CW.$O\fP 613in the libraries of all architectures. 614.SH 615Overrides 616.LP 617The rules provided by a generic mkfile or 618the variables used to control the evaluation 619of those rules may be overridden in most 620circumstances. Overrides 621must be specified in the product mkfile 622after the point where the generic 623mkfile is included; in general, variable 624and rule overrides occupy the end of a 625product mkfile. 626.LP 627The value of a variable is overridden by 628assigning a new value to the variable. 629Most variable overrides modify the 630values of flags or the names of commands executed 631in recipes. For example, the default value of 632.CW CFLAGS 633is often overridden or augmented and 634the ANSI/POSIX Computing Environment is selected by 635setting the 636.CW CC 637and 638.CW LD 639variables to 640.CW pcc. 641.LP 642Modifying rules is trickier than modifying 643variables. Additional constraints can be added 644to a rule by specifying the target and 645the new prerequisite. For example, 646.P1 647%.$O: header.h 648.P2 649adds file 650.CW header.h 651the set of prerequisites for all object files. 652There is no mechanism for adding additional 653commands to an existing recipe; if a 654recipe is unsatisfactory, the rule and its recipe 655must be completely overridden. 656A rule is overridden only when the replacement rule 657matches the target and prerequisite portions 658of the original rule exactly. The recipe 659associated with the new rule 660then replaces the recipe of the original rule. 661For example, 662.CW /sys/src/cmd/lex/mkfile 663overrides the default 664.CW installall 665rule to perform the normal loop on all 666architectures and then copy a prototype file 667to the system library directory. 668.P1 669</$objtype/mkfile 670 671TARG=lex 672OFILES=lmain.$O\e 673 y.tab.$O\e 674 sub1.$O\e 675 sub2.$O\e 676 header.$O\e 677 678HFILES=ldefs.h\e 679 680YFILES=parser.y\e 681 682BIN=/$objtype/bin 683</sys/src/cmd/mkone 684 685installall:V: 686 for(objtype in $CPUS) 687 mk install 688 cp ncform /sys/lib/lex 689.P2 690Another way to perform the same override is to 691add a dependency to the default 692.CW installall 693rule that executes an additional rule to 694install the prototype file: 695.P1 696installall:V: ncform.install 697 698ncform.install:V: 699 cp ncform /sys/lib/lex 700.P2 701.SH 702Special Tricks 703.LP 704Two special cases 705require extra deviousness. 706.LP 707In the first, a file needed to build an 708executable is generated by a program that, 709in turn, is built from a source file that 710is not part of the product. In this case, 711the 712executable must be built for the 713target architecture, but the intermediate 714executable must be built for the architecture 715.CW mk 716is executing on. The intermediate executable 717is built by recursively invoking 718.CW mk 719with the appropriate target and the 720executing architecture as the target 721architecture. When that 722.CW mk 723completes, the intermediate is 724executed to generate the source file to 725complete the build for the target architecture. 726The earlier example of 727.CW /sys/src/cmd/awk/mkfile 728illustrates this technique. 729.LP 730Another awkward situation 731occurs when a directory contains 732source to build an executable as 733well as source for auxiliary executables 734that are not to be installed. In this case 735the 736.CW mkmany 737generic rules are inappropriate, because 738all executables would be built and installed. 739Instead, use the 740.CW mkone 741generic file to build the primary executable 742and provide extra targets to 743build the auxiliary files. This 744approach is also useful when the auxiliary 745files are not executables; 746.CW /sys/src/cmd/spell/mkfile 747augments the default rules to build and install the 748.CW spell 749executable with 750elaborate rules to generate 751and maintain the auxiliary spelling lists. 752