6 bobf@plan9.bell-labs.com
10 Every Plan 9 source directory contains a file, called
12 specifying the rules for building the executable or
13 library that is the product of the directory.
15 interprets the rules in the file, calculates
16 the dependencies, and executes an
18 script to construct the product.
19 If necessary components are supplied by
20 neighboring directories or sub-directories, the mkfiles in those
21 directories are first executed to build the components
22 before the local construction proceeds.
24 Most application source directories produce one of
25 four types of product:
26 a single executable, several
27 executables, a local library, or
31 define the normal rules
32 for building each type of product. The simplest
35 and include the appropriate
41 may supply additional rules
42 to augment, modify, or override the generic rules.
46 To build a product, change to the directory containing
49 with the appropriate target as an argument.
50 All mkfiles provide the following standard targets:
54 Build a local version of the product or products for the
55 current architecture. If the product is a single program,
56 the result is stored in file
58 If the directory produces multiple executables, they are
59 stored in the files named
60 .CW $O.\fIprogname,\fP
63 is the name of each executable.
64 A product may be built for a different architecture by
68 \f(CWobjtype=\fP\fIarchitecture\fP,
71 is the name of the target architecture.
72 Directories producing system
73 libraries always operate directly on the installed version of the
74 library; in this case the target
76 is equivalent to the target
80 Build and install the product or products for the current
84 Build and install the product or products for all architectures.
87 Rid the directory and its subdirectories of the by-products of
88 the build process. Intermediate files that are easily reproduced
91 intermediates, target executables) are always
92 removed. Complicated intermediates, such as local libraries, are
96 Remove all intermediates from the directory and any subdirectories.
97 This target guarantees that a subsequent build for the
98 architecture is performed
103 If no target is specified on the
107 target is built by default. In a directory
108 producing multiple executables, there is
111 In addition to the five standard targets,
112 additional targets may be supplied by each
113 generic mkfile or by the directory's mkfile.
115 The environment variable
117 is set by the system to the number of
118 available processors.
120 this variable, either in the environment or in
121 a mkfile, controls the amount of parallelism in
122 the build. For example, the command
126 restricts a build to a single thread of execution.
130 The easiest way to build a new mkfile is to copy and modify
131 an existing mkfile of the same type.
132 Failing that, it is usually possible to create a new
133 mkfile with minimal effort, since the appropriate
134 generic mkfile predefines the rules that do all the work.
135 In the simplest and most common cases, the new mkfile
136 need only define a couple of variables and include the appropriate
137 architecture-specific
139 .SH The Generic Mkfiles
141 There are four generic mkfiles containing commonly
142 used rules for building a product:
149 perform such actions as compiling C source files,
150 loading object files, archiving libraries, and
151 installing executables in the
153 directory of the appropriate architecture.
154 The generic mkfiles are stored in directory
158 builds a single executable,
160 builds several executables from the source in a single
165 maintain local and system libraries, respectively.
166 The rules in the generic mkfiles are driven by
167 the values of variables, some of which must be
168 set by the product mkfile and some of which are
169 supplied by the generic mkfile. Variables in the
170 latter class include:
174 rw(1i) cw(0.5i) lw(2i).
175 Variable Default Meaning
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
183 The following variables are set by the product mkfile
184 and used by the generic mkfile.
185 Any may be empty depending on the specific product being
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
202 share the following common structure:
204 </$objtype/mkfile # \f1architecture-dependent definitions\fP
206 \fIvariable definitions\fP # TARG\f1, \fPOFILES\f1, \fPHFILES\f1, etc.\fP
208 </sys/src/cmd/\fIgeneric\fP # mkone\f1, \fPmkmany\f1, \fPmklib\f1, or \fPmksyslib
210 \fIvariable overrides\fP # CFLAGS\f1, \fPobjtype\f1, etc.\fP
212 \fIextra rules\fP # \f1overrides, augmented rules, additional targets\fP
214 Note that the architecture-dependent mkfiles include file
215 .CW /sys/src/mkfile.proto
216 for system-wide variables that are common to all architectures.
218 The variables driving the expansion of the generic mkfile
219 may be specified in any order as long as they are defined
220 before the inclusion of the generic mkfile. The value
221 of a variable may be changed by assigning a new value
222 following the inclusion of the generic mkfile, but the
223 effects are sometimes counter-intuitive.
224 Such variable assignments do not apply to the target and
225 prerequisite portions of any previously defined rules;
226 the new values only apply to the recipes of rules preceding
227 the assignment statement and
228 to all parts of any rules following it.
230 The rules supplied by the generic mkfile may
231 be overridden or augmented. The new rules must
232 be specified after the inclusion of the generic
233 mkfile. If the target and prerequisite portion
234 of the rule exactly match the target and prerequisite
235 portion of a previously defined rule and the new rule contains
236 a recipe, the new rule replaces the old one.
237 If the target of a new rule exactly matches the
238 target of a previous rule and one or more new
239 prerequisites are specified and the new rule contains
240 no recipe, the new prerequisites are added to the prerequisites
243 Following sections discuss
244 each generic mkfile in detail.
250 generic mkfile contains rules for building
251 a single executable from one or more files
255 specifies the name of the executable and
260 specify the object files and
262 source files used to build it.
264 contains the names of the local header files
265 included in all source files.
267 is the name of the directory where the executable
270 contains the names of local libraries used by the
271 linker. This variable is rarely needed
272 as libraries referenced by a
274 directive in an associated header file, including
275 all system libraries, are automatically
276 searched by the loader.
280 is executed without a target, the
283 produces an executable in
287 identifies the header files that
288 are included in all or most or
289 the C source files. Occasionally,
290 a program has other header files
291 that are only used in some
293 header can be added to the prerequisites for
294 those object files by adding a rule of
295 the following form following the inclusion of generic mkfile
301 The mkfile for a directory producing a single
302 executable using the normal set of rules is
303 trivial: a list of some files followed by the
307 .CW /sys/src/cmd/diff/mkfile
324 The more complex mkfile in
326 overrides compiler and loader variables to
327 select the ANSI/POSIX Computing Environment with appropriately
328 defined command line variables. It also overrides
331 rule to place the output soure in file
337 rules, so it can remove the non-standard intermediate
338 files. Finally, the last three rules build a version of
340 appropriate for the architecture where the
343 run and then executes it to create source file
367 CFLAGS=-c -D_REGEXP_EXTENSION -D_RESEARCH_SOURCE \e
368 -D_BSD_EXTENSION -DUTF
372 cpuobjtype=`{sed -n 's/^O=//p' /$cputype/mkfile}
374 y.tab.h awkgram.c: $YFILES
375 $YACC -o awkgram.c $YFLAGS $prereq
378 rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e
382 rm -f *.[$OS] [$OS].out [$OS].maketab y.tab.? y.debug\e
383 y.output awkgram.c $TARG
385 proctab.c: $cpuobjtype.maketab
386 ./$cpuobjtype.maketab >proctab.c
388 $cpuobjtype.maketab: y.tab.h maketab.c
392 maketab.$cputype:V: y.tab.h maketab.$O
393 $LD -o $O.maketab maketab.$O
400 generic mkfile builds several
401 executables from the files in a
402 directory. It differs from the operation of
406 specifies the names of all executables,
407 there is no default command-line target,
408 and additional rules allow a single executable to
409 be built or installed.
413 variable specifies the names of all
414 executables produced by the mkfile. The
415 rules assume the name of each executable is also
416 the name of the file containing its
420 specifies files containing
421 common subroutines loaded with all executables.
431 It assumes the main functions for executables
439 and that both programs use the subroutines
444 target builds all executables, leaving each in
445 a file with a name of the form
446 .CW $O.\fIprogname\fP
449 is the name of the executable. In this
452 target produces executables
459 rules provide additional
460 targets for building a single
464 \f(CW$O.progname\fP T{
466 \f(CW$O.\fP\fIprogname\fP
467 in the current directory. When the target
468 architecture is not the current architecture
472 must be prefixed with the customary
473 .CW objtype=\fIarchitecture\fP
474 assignment to select the proper compilers and loaders.
476 \f(CWprogname.install\fP T{
479 for the target architecture.
481 \f(CWprogname.installall\fP T{
484 for all architectures.
492 generic mkfile builds a local library.
493 Since this form of mkfile constructs no
498 variables are not needed. Instead, the
500 variable specifies the library
501 to be built or updated. Variable
503 contains the names of the object files to be archived
504 in the library. The use of variables
508 does not change. When possible, only the
509 out-of-date members of the library are updated.
513 contains the name of the directory where the
514 library is installed; by default it selects
515 the current directory. It can be overridden
516 by assigning the new directory name after the
523 target removes object files and
525 intermediate files but does not touch the
528 target removes the library as well as the
533 .CW "mk -s clean all"
535 causes the existing library to be updated, or
536 created if it doesn't already exist. The command
540 forces the library to be rebuilt from scratch.
543 .CW /sys/src/cmd/upas/libString
544 contains the following specifications to
545 build the local library
547 for the object architecture referenced by
569 rm -f libString.a[$OS]
571 The override of the rule for target
573 removes the libraries for all architectures as
574 opposed to the default recipe for this target
575 which removes the library for the current architecture.
581 generic mkfile is similar to the
583 mkfile except that it operates on a system library
584 instead of a local library.
589 targets are the same; since there is no local copy of
590 the library, all updates are performed on the
594 target is identical to that of the
598 target for local libraries,
599 the library is never removed.
601 No attempt is made to determine if individual library
602 members are up-to-date; all members of a
603 library are always updated.
604 Special targets support manipulation of a single
605 object file; the target
608 .CW objfile\f(CW.$O\fP
609 in the library of the current architecture and the target
612 .CW objfile\f(CW.$O\fP
613 in the libraries of all architectures.
617 The rules provided by a generic mkfile or
618 the variables used to control the evaluation
619 of those rules may be overridden in most
620 circumstances. Overrides
621 must be specified in the product mkfile
622 after the point where the generic
623 mkfile is included; in general, variable
624 and rule overrides occupy the end of a
627 The value of a variable is overridden by
628 assigning a new value to the variable.
629 Most variable overrides modify the
630 values of flags or the names of commands executed
631 in recipes. For example, the default value of
633 is often overridden or augmented and
634 the ANSI/POSIX Computing Environment is selected by
642 Modifying rules is trickier than modifying
643 variables. Additional constraints can be added
644 to a rule by specifying the target and
645 the new prerequisite. For example,
651 the set of prerequisites for all object files.
652 There is no mechanism for adding additional
653 commands to an existing recipe; if a
654 recipe is unsatisfactory, the rule and its recipe
655 must be completely overridden.
656 A rule is overridden only when the replacement rule
657 matches the target and prerequisite portions
658 of the original rule exactly. The recipe
659 associated with the new rule
660 then replaces the recipe of the original rule.
662 .CW /sys/src/cmd/lex/mkfile
663 overrides the default
665 rule to perform the normal loop on all
666 architectures and then copy a prototype file
667 to the system library directory.
686 for(objtype in $CPUS)
688 cp ncform /sys/lib/lex
690 Another way to perform the same override is to
691 add a dependency to the default
693 rule that executes an additional rule to
694 install the prototype file:
696 installall:V: ncform.install
699 cp ncform /sys/lib/lex
705 require extra deviousness.
707 In the first, a file needed to build an
708 executable is generated by a program that,
709 in turn, is built from a source file that
710 is not part of the product. In this case,
712 executable must be built for the
713 target architecture, but the intermediate
714 executable must be built for the architecture
716 is executing on. The intermediate executable
717 is built by recursively invoking
719 with the appropriate target and the
720 executing architecture as the target
721 architecture. When that
723 completes, the intermediate is
724 executed to generate the source file to
725 complete the build for the target architecture.
726 The earlier example of
727 .CW /sys/src/cmd/awk/mkfile
728 illustrates this technique.
730 Another awkward situation
731 occurs when a directory contains
732 source to build an executable as
733 well as source for auxiliary executables
734 that are not to be installed. In this case
737 generic rules are inappropriate, because
738 all executables would be built and installed.
741 generic file to build the primary executable
742 and provide extra targets to
743 build the auxiliary files. This
744 approach is also useful when the auxiliary
745 files are not executables;
746 .CW /sys/src/cmd/spell/mkfile
747 augments the default rules to build and install the
750 elaborate rules to generate
751 and maintain the auxiliary spelling lists.
projects / plan9front.git / blob