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