mkfiles.ms 17 KB

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