ref: 4ec93f94c92eec46433a962eb0f86b6f27909e6c
dir: /sys/doc/mkfiles.ms/
.HTML "Plan 9 Mkfiles .TL Plan 9 Mkfiles .AU Bob Flandrena [email protected] .SH Introduction .LP Every Plan 9 source directory contains a file, called .CW mkfile , specifying the rules for building the executable or library that is the product of the directory. .I Mk (1) interprets the rules in the file, calculates the dependencies, and executes an .I rc (1) script to construct the product. If necessary components are supplied by neighboring directories or sub-directories, the mkfiles in those directories are first executed to build the components before the local construction proceeds. .LP Most application source directories produce one of four types of product: a single executable, several executables, a local library, or a system library. Four generic mkfiles define the normal rules for building each type of product. The simplest mkfiles need only list the components and include the appropriate generic mkfile to do the work. More complex mkfiles may supply additional rules to augment, modify, or override the generic rules. .SH Using a Mkfile .LP To build a product, change to the directory containing its source and invoke .I mk with the appropriate target as an argument. All mkfiles provide the following standard targets: .TS lw(1i) lw(4.5i). \f(CWall\fP T{ Build a local version of the product or products for the current architecture. If the product is a single program, the result is stored in file .CW $O.out . If the directory produces multiple executables, they are stored in the files named .CW $O.\fIprogname,\fP where .I progname is the name of each executable. A product may be built for a different architecture by prefacing the .CW mk command with \f(CWobjtype=\fP\fIarchitecture\fP, where .I architecture is the name of the target architecture. Directories producing system libraries always operate directly on the installed version of the library; in this case the target .CW all is equivalent to the target .CW install . T} \f(CWinstall\fP T{ Build and install the product or products for the current architecture. T} \f(CWinstallall\fP T{ Build and install the product or products for all architectures. T} \f(CWclean\fP T{ Rid the directory and its subdirectories of the by-products of the build process. Intermediate files that are easily reproduced (e.g., object files, .CW yacc intermediates, target executables) are always removed. Complicated intermediates, such as local libraries, are usually preserved. T} \f(CWnuke\fP T{ Remove all intermediates from the directory and any subdirectories. This target guarantees that a subsequent build for the architecture is performed from scratch. T} .TE .LP If no target is specified on the .CW mk command line, the .CW all target is built by default. In a directory producing multiple executables, there is no default target. .LP In addition to the five standard targets, additional targets may be supplied by each generic mkfile or by the directory's mkfile. .LP The environment variable .CW NPROC is set by the system to the number of available processors. Setting this variable, either in the environment or in a mkfile, controls the amount of parallelism in the build. For example, the command .P1 NPROC=1 mk .P2 restricts a build to a single thread of execution. .SH Creating a Mkfile .LP The easiest way to build a new mkfile is to copy and modify an existing mkfile of the same type. Failing that, it is usually possible to create a new mkfile with minimal effort, since the appropriate generic mkfile predefines the rules that do all the work. In the simplest and most common cases, the new mkfile need only define a couple of variables and include the appropriate architecture-specific and generic mkfiles. .SH The Generic Mkfiles .LP There are four generic mkfiles containing commonly used rules for building a product: .CW mkone , .CW mkmany , .CW mklib , and .CW mksyslib . These rules perform such actions as compiling C source files, loading object files, archiving libraries, and installing executables in the .CW bin directory of the appropriate architecture. The generic mkfiles are stored in directory .CW /sys/src/cmd . Mkfile .CW mkone builds a single executable, .CW mkmany builds several executables from the source in a single directory, and .CW mklib and \f(CWmksyslib\fP, maintain local and system libraries, respectively. The rules in the generic mkfiles are driven by the values of variables, some of which must be set by the product mkfile and some of which are supplied by the generic mkfile. Variables in the latter class include: .TS center; ri ci li rw(1i) cw(0.5i) lw(2i). Variable Default Meaning .sp .5 \f(CWCFLAGS\fP \f(CW-FVw\fP C compiler flags \f(CWLDFLAGS\fP Loader flags \f(CWYFLAGS\fP \f(CW-d\fP Yacc flags \f(CWAFLAGS\fP Assembler flags .TE .LP The following variables are set by the product mkfile and used by the generic mkfile. Any may be empty depending on the specific product being made. .TS center; lw(1i) lw(2.5i). \f(CWTARG\fP Name(s) of the executable(s) to be built \f(CWLIB\fP Library name(s) \f(CWOFILES\fP Object files \f(CWHFILES\fP Header files included by all source files \f(CWYFILES\fP \f(CWYacc\fP input files \f(CWBIN\fP Directory where executables are installed .TE .SH Mkfile Organization .LP All mkfiles share the following common structure: .P1 </$objtype/mkfile # \f1architecture-dependent definitions\fP .sp \fIvariable definitions\fP # TARG\f1, \fPOFILES\f1, \fPHFILES\f1, etc.\fP .sp </sys/src/cmd/\fIgeneric\fP # mkone\f1, \fPmkmany\f1, \fPmklib\f1, or \fPmksyslib .sp \fIvariable overrides\fP # CFLAGS\f1, \fPobjtype\f1, etc.\fP .sp \fIextra rules\fP # \f1overrides, augmented rules, additional targets\fP .P2 Note that the architecture-dependent mkfiles include file .CW /sys/src/mkfile.proto for system-wide variables that are common to all architectures. .LP The variables driving the expansion of the generic mkfile may be specified in any order as long as they are defined before the inclusion of the generic mkfile. The value of a variable may be changed by assigning a new value following the inclusion of the generic mkfile, but the effects are sometimes counter-intuitive. Such variable assignments do not apply to the target and prerequisite portions of any previously defined rules; the new values only apply to the recipes of rules preceding the assignment statement and to all parts of any rules following it. .LP The rules supplied by the generic mkfile may be overridden or augmented. The new rules must be specified after the inclusion of the generic mkfile. If the target and prerequisite portion of the rule exactly match the target and prerequisite portion of a previously defined rule and the new rule contains a recipe, the new rule replaces the old one. If the target of a new rule exactly matches the target of a previous rule and one or more new prerequisites are specified and the new rule contains no recipe, the new prerequisites are added to the prerequisites of the old rule. .LP Following sections discuss each generic mkfile in detail. .SH Mkone .LP The .CW mkone generic mkfile contains rules for building a single executable from one or more files in a directory. The variable .CW TARG specifies the name of the executable and variables .CW OFILES and .CW YFILES specify the object files and .CW yacc source files used to build it. .CW HFILES contains the names of the local header files included in all source files. .CW BIN is the name of the directory where the executable is installed. .CW LIB contains the names of local libraries used by the linker. This variable is rarely needed as libraries referenced by a .CW #pragma directive in an associated header file, including all system libraries, are automatically searched by the loader. .LP If .CW mk is executed without a target, the .CW all target is built; it produces an executable in .CW $O.out . Variable .CW HFILES identifies the header files that are included in all or most or the C source files. Occasionally, a program has other header files that are only used in some source files. A header can be added to the prerequisites for those object files by adding a rule of the following form following the inclusion of generic mkfile .CW mkone : .P1 file.$O: header.h .P2 .LP The mkfile for a directory producing a single executable using the normal set of rules is trivial: a list of some files followed by the inclusion of .I mkone. For example, .CW /sys/src/cmd/diff/mkfile contains: .P1 < /$objtype/mkfile TARG=diff OFILES=\e diffdir.$O\e diffio.$O\e diffreg.$O\e main.$O\e HFILES=diff.h BIN=/$objtype/bin </sys/src/cmd/mkone .P2 The more complex mkfile in .CW /sys/src/cmd/awk overrides compiler and loader variables to select the ANSI/POSIX Computing Environment with appropriately defined command line variables. It also overrides the default .CW yacc rule to place the output soure in file .CW awkgram.c and the .CW clean and .CW nuke rules, so it can remove the non-standard intermediate files. Finally, the last three rules build a version of .CW maketab appropriate for the architecture where the .CW mk is being run and then executes it to create source file .CW proctab.c : .P1 </$objtype/mkfile TARG=awk OFILES=re.$O\e lex.$O\e main.$O\e parse.$O\e proctab.$O\e tran.$O\e lib.$O\e run.$O\e awkgram.$O\e HFILES=awk.h\e y.tab.h\e proto.h\e YFILES=awkgram.y BIN=/$objtype/bin </sys/src/cmd/mkone CFLAGS=-c -D_REGEXP_EXTENSION -D_RESEARCH_SOURCE \e -D_BSD_EXTENSION -DUTF YFLAGS=-S -d -v CC=pcc LD=pcc cpuobjtype=`{sed -n 's/^O=//p' /$cputype/mkfile} y.tab.h awkgram.c: $YFILES $YACC -o awkgram.c $YFLAGS $prereq clean:V: rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e y.output $TARG nuke:V: rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e y.output awkgram.c $TARG proctab.c: $cpuobjtype.maketab ./$cpuobjtype.maketab >proctab.c $cpuobjtype.maketab: y.tab.h maketab.c objtype=$cputype mk maketab.$cputype maketab.$cputype:V: y.tab.h maketab.$O $LD -o $O.maketab maketab.$O .P2 .SH Mkmany .LP The .CW mkmany generic mkfile builds several executables from the files in a directory. It differs from the operation of .CW mkone in three respects: .CW TARG specifies the names of all executables, there is no default command-line target, and additional rules allow a single executable to be built or installed. .LP The .CW TARG variable specifies the names of all executables produced by the mkfile. The rules assume the name of each executable is also the name of the file containing its .CW main function. .CW OFILES specifies files containing common subroutines loaded with all executables. Consider the mkfile: .P1 </$objtype/mkfile TARG=alpha beta OFILES=common.$O BIN=/$objtype/bin </sys/src/cmd/mkmany .P2 It assumes the main functions for executables .CW alpha and .CW beta are in files .CW alpha.$O and .CW beta.$O and that both programs use the subroutines in file .CW common.$O . The .CW all target builds all executables, leaving each in a file with a name of the form .CW $O.\fIprogname\fP where .I progname is the name of the executable. In this example the .CW all target produces executables .CW $O.alpha and .CW $O.beta . .LP The .CW mkmany rules provide additional targets for building a single executable: .TS lw(1i) lw(3.8i). \f(CW$O.progname\fP T{ Builds executable \f(CW$O.\fP\fIprogname\fP in the current directory. When the target architecture is not the current architecture the .CW mk command must be prefixed with the customary .CW objtype=\fIarchitecture\fP assignment to select the proper compilers and loaders. T} \f(CWprogname.install\fP T{ Installs executable .I progname for the target architecture. T} \f(CWprogname.installall\fP T{ Installs executable .I progname for all architectures. T} .TE .SH Mklib .LP The .CW mklib generic mkfile builds a local library. Since this form of mkfile constructs no executable, the .CW TARG and .CW BIN variables are not needed. Instead, the .CW LIB variable specifies the library to be built or updated. Variable .CW OFILES contains the names of the object files to be archived in the library. The use of variables .CW YFILES and .CW HFILES does not change. When possible, only the out-of-date members of the library are updated. .LP The variable .CW LIBDIR contains the name of the directory where the library is installed; by default it selects the current directory. It can be overridden by assigning the new directory name after the point where .CW mklib is included. .LP The .CW clean target removes object files and .CW yacc intermediate files but does not touch the library. The .CW nuke target removes the library as well as the files removed by the .CW clean target. The command .RS .CW "mk -s clean all" .RE causes the existing library to be updated, or created if it doesn't already exist. The command .RS .CW "mk -s nuke all" .RE forces the library to be rebuilt from scratch. .LP The mkfile from .CW /sys/src/cmd/upas/libString contains the following specifications to build the local library .CW libString.a$O for the object architecture referenced by .CW $O\fR\:\fP .P1 </$objtype/mkfile LIB=libString.a$O OFILES= s_alloc.$O\e s_append.$O\e s_array.$O\e s_copy.$O\e s_getline.$O\e s_grow.$O\e s_nappend.$O\e s_parse.$O\e s_read.$O\e s_read_line.$O\e s_tolower.$O\e </sys/src/cmd/mklib nuke:V: mk clean rm -f libString.a[$OS] .P2 The override of the rule for target .CW nuke removes the libraries for all architectures as opposed to the default recipe for this target which removes the library for the current architecture. .SH Mksyslib .LP The .CW mksyslib generic mkfile is similar to the .CW mklib mkfile except that it operates on a system library instead of a local library. The .CW install and .CW all targets are the same; since there is no local copy of the library, all updates are performed on the installed library. The rule for the .CW nuke target is identical to that of the .CW clean target; unlike the .CW nuke target for local libraries, the library is never removed. .LP No attempt is made to determine if individual library members are up-to-date; all members of a library are always updated. Special targets support manipulation of a single object file; the target .CW objfile updates file .CW objfile\f(CW.$O\fP in the library of the current architecture and the target .CW objfile.all updates .CW objfile\f(CW.$O\fP in the libraries of all architectures. .SH Overrides .LP The rules provided by a generic mkfile or the variables used to control the evaluation of those rules may be overridden in most circumstances. Overrides must be specified in the product mkfile after the point where the generic mkfile is included; in general, variable and rule overrides occupy the end of a product mkfile. .LP The value of a variable is overridden by assigning a new value to the variable. Most variable overrides modify the values of flags or the names of commands executed in recipes. For example, the default value of .CW CFLAGS is often overridden or augmented and the ANSI/POSIX Computing Environment is selected by setting the .CW CC and .CW LD variables to .CW pcc. .LP Modifying rules is trickier than modifying variables. Additional constraints can be added to a rule by specifying the target and the new prerequisite. For example, .P1 %.$O: header.h .P2 adds file .CW header.h the set of prerequisites for all object files. There is no mechanism for adding additional commands to an existing recipe; if a recipe is unsatisfactory, the rule and its recipe must be completely overridden. A rule is overridden only when the replacement rule matches the target and prerequisite portions of the original rule exactly. The recipe associated with the new rule then replaces the recipe of the original rule. For example, .CW /sys/src/cmd/lex/mkfile overrides the default .CW installall rule to perform the normal loop on all architectures and then copy a prototype file to the system library directory. .P1 </$objtype/mkfile TARG=lex OFILES=lmain.$O\e y.tab.$O\e sub1.$O\e sub2.$O\e header.$O\e HFILES=ldefs.h\e YFILES=parser.y\e BIN=/$objtype/bin </sys/src/cmd/mkone installall:V: for(objtype in $CPUS) mk install cp ncform /sys/lib/lex .P2 Another way to perform the same override is to add a dependency to the default .CW installall rule that executes an additional rule to install the prototype file: .P1 installall:V: ncform.install ncform.install:V: cp ncform /sys/lib/lex .P2 .SH Special Tricks .LP Two special cases require extra deviousness. .LP In the first, a file needed to build an executable is generated by a program that, in turn, is built from a source file that is not part of the product. In this case, the executable must be built for the target architecture, but the intermediate executable must be built for the architecture .CW mk is executing on. The intermediate executable is built by recursively invoking .CW mk with the appropriate target and the executing architecture as the target architecture. When that .CW mk completes, the intermediate is executed to generate the source file to complete the build for the target architecture. The earlier example of .CW /sys/src/cmd/awk/mkfile illustrates this technique. .LP Another awkward situation occurs when a directory contains source to build an executable as well as source for auxiliary executables that are not to be installed. In this case the .CW mkmany generic rules are inappropriate, because all executables would be built and installed. Instead, use the .CW mkone generic file to build the primary executable and provide extra targets to build the auxiliary files. This approach is also useful when the auxiliary files are not executables; .CW /sys/src/cmd/spell/mkfile augments the default rules to build and install the .CW spell executable with elaborate rules to generate and maintain the auxiliary spelling lists.