mk.html 39 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594
  1. <html>
  2. <title>
  3. data
  4. </title>
  5. <body BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#330088" ALINK="#FF0044">
  6. <H1>Maintaining Files on Plan 9 with Mk
  7. </H1>
  8. <DL><DD><I>Andrew G. Hume<br>
  9. andrew@research.att.com<br>
  10. Bob Flandrena<br>
  11. bobf@plan9.bell-labs.com<br>
  12. </I></DL>
  13. <DL><DD><H4>ABSTRACT</H4>
  14. <P>
  15. <TT>Mk</TT>
  16. is a tool
  17. for describing and maintaining dependencies between
  18. files.
  19. It is similar to the
  20. UNIX program
  21. <TT>make</TT>,
  22. but provides several extensions.
  23. <TT>Mk</TT>'<TT>s</TT>
  24. flexible rule specifications, implied
  25. dependency derivation, and parallel
  26. execution of maintenance actions are
  27. well-suited to the Plan 9 environment.
  28. Almost all Plan 9 maintenance procedures
  29. are automated using
  30. <TT>mk</TT>.
  31. </DL>
  32. </P>
  33. <H4>1 Introduction
  34. </H4>
  35. <P>
  36. This document describes how
  37. <TT>mk</TT>,
  38. a program functionally similar to
  39. <TT>make</TT>
  40. [Feld79],
  41. is used to maintain dependencies between
  42. files in Plan 9.
  43. <TT>Mk</TT>
  44. provides several extensions to the
  45. capabilities of its predecessor that work
  46. well in Plan 9's distributed, multi-architecture
  47. environment. It
  48. exploits the power of multiprocessors by executing
  49. maintenance actions in parallel and interacts with
  50. the Plan 9 command interpreter
  51. <TT>rc</TT>
  52. to provide a powerful set of maintenance tools.
  53. It accepts pattern-based dependency specifications
  54. that are not limited to describing
  55. rules for program construction.
  56. The result is a tool that is flexible enough to
  57. perform many maintenance tasks including
  58. database maintenance,
  59. hardware design, and document production.
  60. </P>
  61. <P>
  62. This document begins by discussing
  63. the syntax of the control file,
  64. the pattern matching capabilities, and
  65. the special rules for maintaining archives.
  66. A brief description of
  67. <TT>mk</TT>'<TT>s</TT>
  68. algorithm for deriving dependencies
  69. is followed by a discussion
  70. of the conventions used to resolve ambiguous
  71. specifications. The final sections
  72. describe parallel execution
  73. and special features.
  74. </P>
  75. <P>
  76. An earlier paper [Hume87]
  77. provides a detailed discussion of
  78. <TT>mk</TT>'<TT>s</TT>
  79. design and an appendix summarizes
  80. the differences between
  81. <TT>mk</TT>
  82. and
  83. <TT>make</TT>.
  84. </P>
  85. <H4>2 The <TT>Mkfile</TT>
  86. </H4>
  87. <P>
  88. <TT>Mk</TT>
  89. reads a file describing relationships among files
  90. and executes commands to bring the files up to date.
  91. The specification file, called a
  92. <TT>mkfile</TT>,
  93. contains three types of statements:
  94. assignments, includes, and rules.
  95. Assignment and include statements are similar
  96. to those in C.
  97. Rules specify dependencies between a
  98. <I>target</I>
  99. and its
  100. <I>prerequisites</I>.
  101. When the target and prerequisites are files, their
  102. modification times determine if they
  103. are out of date. Rules often contain a
  104. <I>recipe</I>,
  105. an
  106. <A href="/magic/man2html/1/rc"><I>rc</I>(1)
  107. </A>script that produces the target from
  108. the prerequisites.
  109. </P>
  110. <P>
  111. This simple
  112. <TT>mkfile</TT>
  113. produces an executable
  114. from a C source file:
  115. <DL><DT><DD><TT><PRE>
  116. CC=pcc
  117. f1: f1.c
  118. <I>CC -o f1 f1.c
  119. </PRE></TT></DL>
  120. The first line assigns the name of the portable ANSI/POSIX compiler
  121. to the
  122. </I><TT>mk</TT><I>
  123. variable
  124. </I><TT>CC</TT><I>;
  125. subsequent references of the form
  126. </I><TT></TT><I>CC</I><TT>
  127. select this compiler.
  128. The only rule specifies a dependence between the target file
  129. </TT><TT>f1</TT><TT>
  130. and the prerequisite file
  131. </TT><TT>f1.c</TT><TT>.
  132. If the target does not exist or if the
  133. prerequisite has been modified more recently than
  134. the target,
  135. </TT><TT>mk</TT><TT>
  136. passes the recipe to
  137. </TT><TT>rc</TT><TT>
  138. for execution. Here,
  139. </TT><TT>f1.c</TT><TT>
  140. is compiled and loaded to produce
  141. </TT><TT>f1</TT><TT>.
  142. </P>
  143. </TT><P>
  144. The native Plan 9 environment
  145. requires executables for
  146. all architectures, not only the current one.
  147. The Plan 9 version of the same
  148. <TT>mkfile</TT>
  149. looks like:
  150. <DL><DT><DD><TT><PRE>
  151. &lt;/<I>objtype/mkfile
  152. f1: f1.</I>O
  153. <I>LD </I>LDFLAGS -o f1 f1.<I>O
  154. f1.</I>O: f1.c
  155. <I>CC </I>CFLAGS f1.c
  156. </PRE></TT></DL>
  157. The first line is an include statement
  158. that replaces itself with the contents of the file
  159. <TT>/</TT><I>objtype/mkfile</I><TT>.
  160. The variable
  161. </TT><TT></TT><TT>objtype</TT><TT>
  162. is inherited from the environment and
  163. contains the name of the target architecture.
  164. The prototype
  165. </TT><TT>mkfile</TT><TT>
  166. for that architecture defines architecture-specific variables:
  167. </TT><TT>CC</TT><TT>
  168. and
  169. </TT><TT>LD</TT><TT>
  170. are the names of the compiler and loader,
  171. </TT><TT>O</TT><TT>
  172. is the code character of the architecture.
  173. The rules compile the source file into an object
  174. file and invoke the loader to produce
  175. </TT><TT>f1</TT><TT>.
  176. Invoking
  177. </TT><TT>mk</TT><TT>
  178. from the command line as follows
  179. <DL><DT><DD><TT><PRE>
  180. % objtype=mips mk
  181. vc -w f1.c
  182. vl </TT><I>LDFLAGS -o f1 f1.k
  183. %
  184. </PRE></TT></DL>
  185. produces the
  186. </I><TT>mips</TT><I>
  187. executable of program
  188. </I><TT>f1</TT><I>
  189. regardless of the current architecture type.
  190. </P>
  191. </I><P>
  192. We can extend the
  193. <TT>mkfile</TT>
  194. to build two programs:
  195. <DL><DT><DD><TT><PRE>
  196. &lt;/objtype/mkfile
  197. ALL=f1 f2
  198. all:V: <I>ALL
  199. f1: f1.</I>O
  200. <I>LD </I>LDFLAGS -o f1 f1.<I>O
  201. f1.</I>O: f1.c
  202. <I>CC </I>CFLAGS f1.c
  203. f2: f2.<I>O
  204. </I>LD <I>LDFLAGS -o f2 f2.</I>O
  205. f2.<I>O: f2.c
  206. </I>CC <I>CFLAGS f2.c
  207. </PRE></TT></DL>
  208. The target
  209. </I><TT>all</TT><I>,
  210. modified by the
  211. </I><I>attribute</I><I>
  212. </I><TT>V</TT><I>,
  213. builds both programs.
  214. The attribute identifies
  215. </I><TT>all</TT><I>
  216. as a dummy target that is
  217. not related to a file of the same name;
  218. its precise effect is explained later.
  219. This example describes cascading dependencies:
  220. the first target depends on another which depends on a third and
  221. so on.
  222. Here, individual rules build each
  223. program; later we'll see how to do this with a
  224. general rule.
  225. </P>
  226. </I><H4>3 Variables and the environment
  227. </H4>
  228. <P>
  229. <TT>Mk</TT>
  230. does not distinguish between its
  231. internal variables and
  232. <TT>rc</TT>
  233. variables in the environment.
  234. When
  235. <TT>mk</TT>
  236. starts, it imports each environment variable into a
  237. <TT>mk</TT>
  238. variable of the same name. Before executing a recipe,
  239. <TT>mk</TT>
  240. exports all variables, including those
  241. inherited from the environment,
  242. to the environment in which
  243. <TT>rc</TT>
  244. executes the recipe.
  245. </P>
  246. <P>
  247. There are several ways for a
  248. variable to take a value.
  249. It can be set with an assignment statement,
  250. inherited from the environment, or specified
  251. on the command line.
  252. <TT>Mk</TT>
  253. also maintains several special internal variables
  254. that are described in
  255. <A href="/magic/man2html/1/mk"><I>mk</I>(1).
  256. </A>Assignments have the following decreasing order of precedence:
  257. </P>
  258. <br>&#32;<br>
  259. <DL><DT><DD>
  260. 1) Command line assignment
  261. <br>
  262. 2) Assignment statement
  263. <br>
  264. 3) Imported from the environment
  265. <br>
  266. 4) Implicitly set by <TT>mk</TT>
  267. </DL>
  268. <br>&#32;<br>
  269. For example, a command line assignment overrides
  270. a value imported from the environment.
  271. <P>
  272. All variable values are strings. They can be
  273. used for pattern matching and
  274. comparison but not for arithmetic.
  275. A
  276. <I>list</I>
  277. is a string containing several values separated by
  278. white space. Each member is
  279. handled individually during pattern matching,
  280. target selection, and prerequisite evaluation.
  281. </P>
  282. <P>
  283. A
  284. <I>namelist</I>
  285. is a list produced by
  286. transforming the members of an existing list.
  287. The transform applies a pattern to each member,
  288. replacing each matched string with a new string,
  289. much as in the substitute command in
  290. <A href="/magic/man2html/1/sam"><I>sam</I>(1)
  291. </A>or
  292. <A href="/magic/man2html/1/ed"><I>ed</I>(1).
  293. </A>The syntax is
  294. <DL><DT><DD><TT><PRE>
  295. {<I>var</I>:A%B=C%D}
  296. </PRE></TT></DL>
  297. where
  298. <I>var</I>
  299. is a variable.
  300. The pattern
  301. <TT>A%B</TT>
  302. matches a member beginning with the string
  303. <I>A</I>
  304. and ending with the string
  305. <I>B</I>
  306. with any string in between;
  307. it behaves like the regular expression
  308. <TT>A.*B</TT>.
  309. When a member of the
  310. <I>var</I>
  311. list
  312. matches this pattern,
  313. the string
  314. <I>C</I>
  315. replaces
  316. <I>A</I>,
  317. <I>D</I>
  318. replaces
  319. <I>B</I>,
  320. and the matched string replaces itself.
  321. Any of
  322. <I>A</I>,
  323. <I>B</I>,
  324. <I>C</I>,
  325. or
  326. <I>D</I>
  327. may be the empty string. In effect, a namelist is
  328. generated by applying the
  329. <A href="/magic/man2html/1/ed"><I>ed</I>(1)
  330. </A>substitute command
  331. <DL><DT><DD><TT><PRE>
  332. s/<I>A</I>(.*)<I>B</I>/<I>C</I>\1<I>D</I>/
  333. </PRE></TT></DL>
  334. to each member of a variable list.
  335. </P>
  336. <P>
  337. Namelists are useful for generating
  338. a list based on a predictable transformation.
  339. For example,
  340. <DL><DT><DD><TT><PRE>
  341. SRC=a.c b.c c.c
  342. OBJ=<I>{SRC:%.c=%.v}
  343. </PRE></TT></DL>
  344. assigns the list </I><TT>(a.v b.v c.v)</TT><I> to
  345. </I><TT>OBJ</TT><I>.
  346. A namelist may be used anywhere a variable is allowed
  347. except in a recipe.
  348. </P>
  349. </I><P>
  350. Command output is assigned to a variable
  351. using the normal
  352. <TT>rc</TT>
  353. syntax:
  354. <DL><DT><DD><TT><PRE>
  355. var=`{rc command}
  356. </PRE></TT></DL>
  357. The command executes in an environment populated
  358. with previously assigned variables, including those
  359. inherited from
  360. <TT>mk</TT>'<TT>s</TT>
  361. execution environment.
  362. The command may
  363. be arbitrarily complex; for example,
  364. <DL><DT><DD><TT><PRE>
  365. TARG=`{ls -d *.[cy] | sed 's/..//'}
  366. </PRE></TT></DL>
  367. assigns a list of the C and yacc source files in the current
  368. directory, stripped of their suffix, to the variable
  369. <TT>TARG</TT>.
  370. </P>
  371. <H4>4 The include statement
  372. </H4>
  373. <P>
  374. The include statement
  375. replaces itself with the contents of a file.
  376. It is functionally similar to the C
  377. <TT>#include</TT>
  378. statement but uses a different syntax:
  379. <DL><DT><DD><TT><PRE>
  380. &lt;<I>filename</I>
  381. </PRE></TT></DL>
  382. The contents of the file are evaluated
  383. as they are read.
  384. An include statement may be used anywhere except
  385. in a recipe.
  386. </P>
  387. <P>
  388. Unlike
  389. <TT>make</TT>,
  390. <TT>mk</TT>
  391. has no built-in rules. Instead,
  392. the include statement allows generic rules
  393. to be imported from a prototype
  394. <TT>mkfile</TT>;
  395. most Plan 9
  396. <TT>mkfiles</TT>
  397. use this approach [Flan95].
  398. </P>
  399. <H4>5 Rules
  400. </H4>
  401. <P>
  402. A rule has four elements: targets,
  403. prerequisites, attributes, and a recipe.
  404. It has the form:
  405. <DL><DT><DD><TT><PRE>
  406. <I>targets</I>:<I>attributes</I>:<I>prerequisites</I>
  407. <I>recipe</I>
  408. </PRE></TT></DL>
  409. The first line, containing the
  410. targets, attributes, and prerequisites is
  411. the
  412. <I>rule header</I>;
  413. it
  414. must begin at the left margin.
  415. The recipe contains zero or more lines,
  416. each of which begins with white space.
  417. One or more targets must be specified but the
  418. attributes, prerequisites, and recipe are optional.
  419. A rule specifies
  420. a dependency between the target(s) and its prerequisite(s),
  421. the recipe brings the target(s)
  422. up to date with the prerequisite(s) and
  423. attributes modify
  424. <TT>mk</TT>'<TT>s</TT>
  425. evaluation of the dependency.
  426. </P>
  427. <P>
  428. Normally the target is a file that depends
  429. on one or more prerequisite files.
  430. <TT>Mk</TT>
  431. compares the modification times of each target
  432. and each prerequisite; a target is considered out of date
  433. when it does not exist or when a prerequisite has been modified
  434. more recently.
  435. When a target is out of date,
  436. <TT>mk</TT>
  437. executes the
  438. recipe to bring it up to date.
  439. When the recipe completes,
  440. the modification time of the target is checked and
  441. used in later dependency evaluations.
  442. If the recipe does not update the target,
  443. evaluation continues with the out of date target.
  444. </P>
  445. <P>
  446. A prerequisite of one rule
  447. may be the target of another. When
  448. this happens, the rules cascade
  449. to define a multi-step procedure.
  450. For example,
  451. an executable target depends on prerequisite
  452. object files, each of which is a target
  453. in a rule with a C source file as the prerequisite.
  454. <TT>Mk</TT>
  455. follows a chain of dependencies until it encounters
  456. a prerequisite that is not a target of another rule
  457. or it finds a target that
  458. is up to date. It then
  459. executes the recipes in reverse order to produce
  460. the desired target.
  461. </P>
  462. <P>
  463. The rule header is evaluated when the rule is read.
  464. Variables are replaced by their values, namelists are
  465. generated, and
  466. commands are replaced by their
  467. output at this time.
  468. </P>
  469. <P>
  470. Most attributes modify
  471. <TT>mk</TT>'<TT>s</TT>
  472. evaluation of a rule.
  473. An attribute is usually a single letter but some
  474. are more complicated.
  475. This paper only discusses commonly used attributes;
  476. see
  477. <A href="/magic/man2html/1/mk"><I>mk</I>(1)
  478. </A>for a complete list.
  479. </P>
  480. <P>
  481. The
  482. <TT>V</TT>
  483. attribute identifies a
  484. <I>virtual</I>
  485. target;
  486. that is, a target that is not a file.
  487. For example,
  488. <DL><DT><DD><TT><PRE>
  489. clean:V:
  490. rm *.<I>O </I>O.out
  491. </PRE></TT></DL>
  492. removes executables and compiler intermediate files.
  493. The target is virtual because it does not refer to a file named
  494. <TT>clean</TT>.
  495. Without the attribute, the recipe would not be
  496. executed if a file named
  497. <TT>clean</TT>
  498. existed.
  499. The
  500. <TT>Q</TT>
  501. attribute
  502. silences the printing of a recipe before
  503. execution.
  504. It is useful when the output of a recipe is
  505. similar to the recipe:
  506. <DL><DT><DD><TT><PRE>
  507. default:QV:
  508. echo 'No default target; use mk all or mk install'
  509. </PRE></TT></DL>
  510. </P>
  511. <P>
  512. The recipe is an
  513. <TT>rc</TT>
  514. script. It is optional but when it is
  515. missing, the rule is handled specially, as described later.
  516. Unlike
  517. <TT>make</TT>,
  518. <TT>mk</TT>
  519. executes recipes without interpretation.
  520. After
  521. stripping the first white space character from each line
  522. it passes the entire recipe to
  523. <TT>rc</TT>
  524. on standard input.
  525. Since
  526. <TT>mk</TT>
  527. does not interpret a recipe,
  528. escape conventions are exactly those of
  529. <TT>rc</TT>.
  530. Scripts for
  531. <TT>awk</TT>
  532. and
  533. <TT>sed</TT>
  534. commands can be embedded exactly as they would
  535. be entered from the command line.
  536. <TT>Mk</TT>
  537. invokes
  538. <TT>rc</TT>
  539. with the
  540. <TT>-e</TT>
  541. flag, which causes
  542. <TT>rc</TT>
  543. to stop if any command
  544. in the recipe exits with a non-zero status; the
  545. <TT>E</TT>
  546. attribute overrides this behavior and allows
  547. <TT>rc</TT>
  548. to continue executing in the face of errors.
  549. Before a recipe is executed, variables are exported
  550. to the environment where they are available to
  551. <TT>rc</TT>.
  552. Commands in the recipe may not read from
  553. standard input because
  554. <TT>mk</TT>
  555. uses it internally.
  556. </P>
  557. <P>
  558. References to a variable can yield different
  559. values depending on the location of the
  560. reference in the
  561. <TT>mkfile</TT>.
  562. <TT>Mk</TT>
  563. resolves variable references
  564. in assignment statements and rule headers
  565. when the statement is read. Variable references
  566. in recipes are evaluated by
  567. <TT>rc</TT>
  568. when the recipe is executed; this
  569. happens after the entire
  570. <TT>mkfile</TT>
  571. has been read. The value of a variable in a recipe
  572. is the last value assigned in the file. For example,
  573. <DL><DT><DD><TT><PRE>
  574. STRING=all
  575. all:VQ:
  576. echo <I>STRING
  577. STRING=none
  578. </PRE></TT></DL>
  579. produces the message
  580. </I><TT>none</TT><I>.
  581. A variable assignment in a recipe
  582. does not affect the value of the variable in the
  583. </I><TT>mkfile</TT><I>
  584. for two reasons.
  585. First,
  586. </I><TT>mk</TT><I>
  587. does not import values from
  588. the environment when a recipe completes;
  589. one recipe cannot pass a value through
  590. the environment to another recipe.
  591. Second, no recipe is executed until
  592. </I><TT>mk</TT><I>
  593. has completed its evaluation, so even if a variable
  594. were changed,
  595. it would not affect the dependency evaluation.
  596. </P>
  597. </I><H4>6 Metarules
  598. </H4>
  599. <P>
  600. A
  601. <I>metarule</I>
  602. is a rule based on a pattern.
  603. The pattern selects a class of target(s) and
  604. identifies related prerequisites.
  605. <TT>Mk</TT>
  606. metarules may select targets and prerequisites
  607. based on any criterion that can be described by a pattern, not just
  608. the suffix transformations associated with program
  609. construction.
  610. </P>
  611. <P>
  612. Metarule patterns are either
  613. <I>intrinsic</I>
  614. or regular expressions conforming to the
  615. syntax of
  616. <A href="/magic/man2html/6/regexp"><I>regexp</I>(6).
  617. </A>The intrinsic patterns are shorthand
  618. for common regular expressions.
  619. The intrinsic pattern
  620. <TT>%</TT>
  621. matches one or more of anything; it is equivalent to
  622. the regular expression
  623. <TT>`.+'</TT>.
  624. The other intrinsic pattern,
  625. <TT>&</TT>,
  626. matches one or more of any characters except <TT>`/'</TT>
  627. and <TT>`.'</TT>.
  628. It matches a portion of a path and is
  629. equivalent to the regular expression
  630. <TT>`[^./]+'</TT>.
  631. An intrinsic pattern in a prerequisite references
  632. the string matched by the same intrinsic pattern in the target.
  633. For example, the rule
  634. <DL><DT><DD><TT><PRE>
  635. %.v: %.c
  636. </PRE></TT></DL>
  637. says that a file ending in
  638. <TT>.v</TT>
  639. depends on a file of the same name with a
  640. <TT>.c</TT>
  641. suffix:
  642. <TT>foo.v</TT>
  643. depends on
  644. <TT>foo.c</TT>,
  645. <TT>bar.v</TT>
  646. depends on
  647. <TT>bar.c</TT>,
  648. and so on.
  649. The string matched by an intrinsic pattern in the target
  650. is supplied to the recipe in the variable
  651. <TT></TT>stem<TT>.
  652. Thus the rule
  653. <DL><DT><DD><TT><PRE>
  654. %.</TT><I>O: %.c
  655. </I><TT>CC </TT><I>CFLAGS </I><TT>stem.c
  656. </PRE></TT></DL>
  657. creates an object file for the target architecture from
  658. a similarly named C source file. If several object
  659. files are out of date, the rule is applied repeatedly and
  660. </TT><TT></TT><I>stem</I><TT>
  661. refers to each file in turn.
  662. Since there is only one
  663. </TT><TT>stem</TT><TT>
  664. variable, there can only be one
  665. </TT><TT>%</TT><TT>
  666. or
  667. </TT><TT>&</TT><TT>
  668. pattern in a target;
  669. the pattern
  670. </TT><TT>%-%.c</TT><TT>
  671. is illegal.
  672. </P>
  673. </TT><P>
  674. Metarules simplify the
  675. <TT>mkfile</TT>
  676. for building programs
  677. <TT>f1</TT>
  678. and
  679. <TT>f2</TT>:
  680. <DL><DT><DD><TT><PRE>
  681. &lt;/objtype/mkfile
  682. ALL=f1 f2
  683. all:V: <I>ALL
  684. %: %.</I>O
  685. <I>LD -o </I>target <I>prereq
  686. %.</I>O: %.c
  687. <I>CC </I>CFLAGS <I>stem.c
  688. clean:V:
  689. rm -f </I>ALL *.[<I>OS]
  690. </PRE></TT></DL>
  691. (The variable
  692. </I><TT></TT><I>OS</I><TT>
  693. is a list of code characters for all architectures.)
  694. Here, metarules specify
  695. compile and load steps for all C source files.
  696. The loader rule relies on two internal variables
  697. set by
  698. </TT><TT>mk</TT><TT>
  699. during evaluation of the rule:
  700. </TT><TT></TT><I>target</I><TT>
  701. is the name of the target(s) and
  702. </TT><TT></TT><TT>prereq</TT><TT>
  703. the name of all prerequisite(s).
  704. Metarules allow this
  705. </TT><TT>mkfile</TT><TT>
  706. to be easily extended; a new program
  707. is supported by adding its name to the third line.
  708. </P>
  709. </TT><P>
  710. A regular expression metarule must have an
  711. <TT>R</TT>
  712. attribute.
  713. Prerequisites may reference matching substrings in
  714. the target using the form
  715. <TT>\</TT><I>n</I><TT></TT><I>
  716. where
  717. </I><I>n</I><I>
  718. is a digit from 1 to 9 specifying the
  719. </I><I>n</I><I>th
  720. parenthesized sub-expression. In a recipe,
  721. </I><TT></TT><I>stem</I><I>n</I><I></I><I>
  722. is the equivalent reference.
  723. For example, a compile rule could be
  724. specified using regular expressions:
  725. <DL><DT><DD><TT><PRE>
  726. (.+)\.</I>O:R: \1.c
  727. <I>CC </I>CFLAGS <I>stem1.c
  728. </PRE></TT></DL>
  729. Here,
  730. </I><TT>\1</TT><I>
  731. and
  732. </I><TT></TT><I>stem1</I><TT>
  733. refer to the name of the target object file without the
  734. suffix. The variable
  735. </TT><TT></TT><I>stem</I><TT>
  736. associated with an intrinsic pattern is undefined
  737. in a regular expression metarule.
  738. </P>
  739. </TT><H4>7 Archives
  740. </H4>
  741. <P>
  742. <TT>Mk</TT>
  743. provides a special mechanism for maintaining an archive.
  744. An archive member is referenced using the form
  745. <TT></TT><I>lib</I><TT>(</TT><I>file</I><TT>)</TT><I>
  746. where
  747. </I><I>lib</I><I>
  748. is the name of the archive and
  749. </I><I>file</I><I>
  750. is the name of the member. Two rules define the
  751. dependency between an object file and its membership
  752. in an archive:
  753. <DL><DT><DD><TT><PRE>
  754. </I>LIB(foo.8):N: foo.8
  755. <I>LIB: </I>LIB(foo.8)
  756. ar rv <I>LIB foo.8
  757. </PRE></TT></DL>
  758. The first rule establishes a dependency between the
  759. archive member and the object file.
  760. Normally,
  761. </I><TT>mk</TT><I>
  762. detects an error when a target does not exist and the rule
  763. contains no recipe; the
  764. </I><TT>N</TT><I>
  765. attribute overrides this behavior because the subsequent rule
  766. updates the member.
  767. The second
  768. rule establishes the dependency between the member and
  769. the archive; its recipe inserts the member
  770. into the archive.
  771. This two-step specification allows the modification time
  772. of the archive
  773. to represent the state of its members. Other rules
  774. can then specify the archive as a prerequisite instead of
  775. listing each member.
  776. </P>
  777. </I><P>
  778. A metarule generalizes library maintenance:
  779. <DL><DT><DD><TT><PRE>
  780. LIB=lib.a
  781. OBJS=etoa.O atoe.<I>O ebcdic.</I>O
  782. <I>LIB(%):N: %
  783. </I>LIB: <I>{OBJS:%=</I>LIB(%)}
  784. ar rv <I>LIB </I>OBJS
  785. </PRE></TT></DL>
  786. The namelist prerequisite of the
  787. <TT></TT><I>LIB</I><TT>
  788. target generates archive member names for each object file name;
  789. for example,
  790. </TT><TT>etoa.</TT><TT>O</TT><TT>
  791. becomes
  792. </TT><TT>lib.a(etoa.</TT><I>O)</I><TT>.
  793. This formulation always updates all members.
  794. This is acceptable for a small archive, but may
  795. be slow for a big one.
  796. The rule
  797. <DL><DT><DD><TT><PRE>
  798. </TT><I>LIB: </I><I>{OBJS:%=</I><I>LIB(%)}
  799. ar rv </I><I>LIB `{membername </I><I>newprereq}
  800. </PRE></TT></DL>
  801. only updates out of date object files.
  802. The internal variable
  803. </I><TT></TT><I>newprereq</I><TT>
  804. contains the names of the out of
  805. date prerequisites. The
  806. </TT><TT>rc</TT><TT>
  807. script
  808. </TT><TT>membername</TT><TT>
  809. transforms an archive member specification into a file name:
  810. it translates
  811. </TT><TT>lib.a(etoa.</TT><TT>O)</TT><TT>
  812. into
  813. </TT><TT>etoa.</TT><I>O</I><TT>.
  814. </P>
  815. </TT><P>
  816. The
  817. <TT>mkfile</TT>
  818. <DL><DT><DD><TT><PRE>
  819. &lt;/objtype/mkfile
  820. LIB=lib.a
  821. OBJS=etoa.<I>O atoe.</I>O ebcdic.<I>O
  822. prog: main.</I>O <I>LIB
  823. </I>LD -o <I>target </I>prereq
  824. <I>LIB(%):N: %
  825. </I>LIB: <I>{OBJS:%=</I>LIB(%)}
  826. ar rv <I>LIB </I>OBJS
  827. </PRE></TT></DL>
  828. builds a program by loading it with a library.
  829. </P>
  830. <H4>8 Evaluation algorithm
  831. </H4>
  832. <P>
  833. For each target of interest,
  834. <TT>mk</TT>
  835. uses the rules in a
  836. <TT>mkfile</TT>
  837. to build a data
  838. structure called a dependency graph. The nodes of
  839. the graph represent targets and prerequisites;
  840. a directed arc
  841. from one node to another indicates that
  842. the file associated with the first node depends
  843. on the file associated with the second.
  844. When the
  845. <TT>mkfile</TT>
  846. has been completely read, the graph is analyzed.
  847. In the first step, implied dependencies are resolved by
  848. computing the
  849. <I>transitive closure</I>
  850. of the graph.
  851. This calculation extends the graph to include all
  852. targets that are potentially
  853. derivable from the rules in the
  854. <TT>mkfile</TT>.
  855. Next the graph is checked for cycles;
  856. <TT>make</TT>
  857. accepts cyclic dependencies, but
  858. <TT>mk</TT>
  859. does not allow them.
  860. Subsequent steps
  861. prune subgraphs that are irrelevant for producing the
  862. desired target and verify that there is only one way
  863. to build it.
  864. The recipes associated with the
  865. nodes on the longest path between the
  866. target and an out of date prerequisite
  867. are then executed in reverse order.
  868. </P>
  869. <P>
  870. The transitive closure calculation is sensitive to
  871. metarules; the patterns often select many potential targets
  872. and cause the graph to grow rapidly.
  873. Fortunately,
  874. dependencies associated with the desired target
  875. usually form a small part of the graph, so, after
  876. pruning, analysis is tractable.
  877. For example, the rules
  878. <DL><DT><DD><TT><PRE>
  879. %: x.%
  880. recipe1
  881. x.%: %.k
  882. recipe2
  883. %.k: %.f
  884. recipe3
  885. </PRE></TT></DL>
  886. produce a graph with four nodes for each file in the
  887. current directory.
  888. If the desired target is
  889. <TT>foo</TT>,
  890. <TT>mk</TT>
  891. detects the dependency between it
  892. and the original file
  893. <TT>foo.f</TT>
  894. through intermediate dependencies on
  895. <TT>foo.k</TT>
  896. and
  897. <TT>x.foo</TT>.
  898. Nodes associated with other files are deleted during pruning because
  899. they are irrelevant to the production of
  900. <TT>foo</TT>.
  901. </P>
  902. <P>
  903. <TT>Mk</TT>
  904. avoids infinite cycles by evaluating
  905. each metarule once.
  906. Thus, the rule
  907. <DL><DT><DD><TT><PRE>
  908. %: %.z
  909. cp <I>prereq </I>prereq.z
  910. </PRE></TT></DL>
  911. copies the prerequisite file once.
  912. </P>
  913. <H4>9 Conventions for evaluating rules
  914. </H4>
  915. <P>
  916. There must be only one
  917. way to build each target. However, during evaluation
  918. metarule patterns often select potential targets that
  919. conflict with the
  920. targets of other rules.
  921. <TT>Mk</TT>
  922. uses several conventions to resolve ambiguities
  923. and to select the proper dependencies.
  924. </P>
  925. <P>
  926. When a target selects more than one rule,
  927. <TT>mk</TT>
  928. chooses a regular rule
  929. over a metarule.
  930. For example, the
  931. <TT>mkfile</TT>
  932. <DL><DT><DD><TT><PRE>
  933. &lt;/<I>objtype/mkfile
  934. FILES=f1.</I>O f2.<I>O f3.</I>O
  935. prog: <I>FILES
  936. </I>LD -o <I>target </I>prereq
  937. %.<I>O: %.c
  938. </I>CC <I>CFLAGS </I>stem.c
  939. f2.<I>O: f2.c
  940. </I>CC f2.c
  941. </PRE></TT></DL>
  942. contains two rules that could build
  943. <TT>f2.</TT><I>O</I><TT>.
  944. </TT><TT>Mk</TT><TT>
  945. selects the last rule because its target,
  946. </TT><TT>f2.</TT><TT>O</TT><TT>,
  947. is explicitly specified, while the
  948. </TT><TT>%.</TT><I>O</I><TT>
  949. rule is a metarule. In effect,
  950. the explicit rule for
  951. </TT><TT>f2.</TT><TT>O</TT><TT>
  952. overrides the general rule for building object files from
  953. C source files.
  954. </P>
  955. </TT><P>
  956. When a rule has a target and prerequisites but no recipe,
  957. those prerequisites are added to all other rules with
  958. recipes that have the same target.
  959. All prerequisites, regardless of where they were specified, are
  960. exported to the recipe in variable
  961. <TT></TT><I>prereq</I><TT>.
  962. For example, in
  963. <DL><DT><DD><TT><PRE>
  964. &lt;/</TT>objtype/mkfile
  965. FILES=f1.<I>O f2.</I>O f3.<I>O
  966. prog: </I>FILES
  967. <I>LD -o </I>target <I>prereq
  968. %.</I>O: hdr.h
  969. %.<I>O: %.c
  970. </I>CC <I>CFLAGS </I>stem.c
  971. </PRE></TT></DL>
  972. the second rule adds
  973. <TT>hdr.h</TT>
  974. as a prerequisite of the compile metarule;
  975. an object file produced from a C source file
  976. depends on
  977. <TT>hdr.h</TT>
  978. as well as the source file. Notice that the recipe of
  979. the compile rule uses
  980. <TT></TT><I>stem.c</I><TT>
  981. instead of
  982. </TT><TT></TT><TT>prereq</TT><TT>
  983. because the latter specification would attempt to compile
  984. </TT><TT>hdr.h</TT><TT>.
  985. </P>
  986. </TT><P>
  987. When a target is virtual and there is no other rule with
  988. the same target,
  989. <TT>mk</TT>
  990. evaluates each prerequisite.
  991. For example, adding the rule
  992. <DL><DT><DD><TT><PRE>
  993. all:V: prog
  994. </PRE></TT></DL>
  995. to the preceding example builds the executable
  996. when either
  997. <TT>prog</TT>
  998. or
  999. <TT>all</TT>
  1000. is the specified target. In effect, the
  1001. <TT>all</TT>
  1002. target is an alias for
  1003. <TT>prog</TT>.
  1004. </P>
  1005. <P>
  1006. When two rules have identical rule headers and both have
  1007. recipes, the later rule replaces the former one.
  1008. For example,
  1009. if a file named
  1010. <TT>mkrules</TT>
  1011. contains
  1012. <DL><DT><DD><TT><PRE>
  1013. <I>O.out: </I>OFILES
  1014. <I>LD </I>LFLAGS <I>OFILES
  1015. %.</I>O: %.c
  1016. <I>CC </I>CFLAGS <I>stem.c
  1017. </PRE></TT></DL>
  1018. the
  1019. </I><TT>mkfile</TT><I>
  1020. <DL><DT><DD><TT><PRE>
  1021. OFILES=f1.</I>O f2.<I>O f3.</I>O
  1022. &lt;mkrules
  1023. <I>O.out: </I>OFILES
  1024. <I>LD </I>LFLAGS -l <I>OFILES -lbio -lc
  1025. </PRE></TT></DL>
  1026. overrides the general loader rule with a special
  1027. rule using a non-standard library search sequence.
  1028. A rule is neutralized by overriding it with a rule
  1029. with a null recipe:
  1030. <DL><DT><DD><TT><PRE>
  1031. &lt;mkrules
  1032. </I>O.out:Q: <I>OFILES
  1033. ;
  1034. </PRE></TT></DL>
  1035. The
  1036. </I><TT>Q</TT><I>
  1037. attribute suppresses the printing of the semicolon.
  1038. </P>
  1039. </I><P>
  1040. When a rule has no prerequisites, the recipe is executed
  1041. only when the target does not exist. For example,
  1042. <DL><DT><DD><TT><PRE>
  1043. marker:
  1044. touch target
  1045. </PRE></TT></DL>
  1046. defines a rule to manage a marker file.
  1047. If the file exists, it is considered up to date
  1048. regardless of its modification time.
  1049. When a virtual target has no prerequisites the
  1050. recipe is always executed.
  1051. The
  1052. <TT>clean</TT>
  1053. rule is of this type:
  1054. <DL><DT><DD><TT><PRE>
  1055. clean:V:
  1056. rm -f [<I>OS].out *.[</I>OS]
  1057. </PRE></TT></DL>
  1058. When a rule without prerequisites has multiple targets, the
  1059. extra targets are aliases for the rule.
  1060. For example, in
  1061. <DL><DT><DD><TT><PRE>
  1062. clean tidy nuke:V:
  1063. rm -f [<I>OS].out *.[</I>OS]
  1064. </PRE></TT></DL>
  1065. the
  1066. rule can be invoked by any of three names.
  1067. The first rule in a
  1068. <TT>mkfile</TT>
  1069. is handled specially:
  1070. when
  1071. <TT>mk</TT>
  1072. is invoked without a command line target
  1073. all targets of the first non-metarule are built.
  1074. If that rule has multiple targets, the recipe
  1075. is executed once for each target; normally, the recipe
  1076. of a rule with multiple targets is only executed once.
  1077. </P>
  1078. <P>
  1079. A rule applies to a target only when its prerequisites
  1080. exist or can be derived. More than one rule may have the
  1081. same target as long as only one rule with a recipe
  1082. remains applicable after the dependency evaluation completes.
  1083. For example, consider a program built from C
  1084. and assembler source files. Two rules produce
  1085. object files:
  1086. <DL><DT><DD><TT><PRE>
  1087. %.<I>O: %.c
  1088. </I>CC <I>CFLAGS </I>stem.c
  1089. %.<I>O: %.s
  1090. </I>AS <I>AFLAGS </I>stem.s
  1091. </PRE></TT></DL>
  1092. As long as there are not two source files with names like
  1093. <TT></TT><I>foo</I><TT>.c</TT><I>
  1094. and
  1095. </I><TT></TT><I>foo</I><TT>.s</TT><I>,
  1096. </I><TT>mk</TT><I>
  1097. can unambiguously select the proper rule.
  1098. If both files exist,
  1099. the rules are ambiguous
  1100. and
  1101. </I><TT>mk</TT><I>
  1102. exits with an error message.
  1103. </P>
  1104. </I><P>
  1105. In Plan 9, many programs consist of portable code stored
  1106. in one directory and architecture-specific source stored in
  1107. another.
  1108. For example, the
  1109. <TT>mkfile</TT>
  1110. <DL><DT><DD><TT><PRE>
  1111. &lt;/<I>objtype/mkfile
  1112. FILES=f1.</I>O f2.<I>O f3.</I>O f3.<I>O
  1113. prog: </I>FILES
  1114. <I>LD -o </I>target <I>prereq
  1115. %.</I>O: %.<I>c
  1116. </I>CC <I>CFLAGS </I>stem.c
  1117. %.<I>O: ../port/%.c
  1118. </I>CC <I>CFLAGS ../port/</I>stem.c
  1119. </PRE></TT></DL>
  1120. builds the program named
  1121. <TT>prog</TT>
  1122. using portable code in directory
  1123. <TT>../port</TT>
  1124. and architecture-specific code in the current directory.
  1125. As long as the
  1126. names of the C source files in
  1127. <TT>../port</TT>
  1128. do not conflict with the names of files in the current directory,
  1129. <TT>mk</TT>
  1130. selects the appropriate rule to build the object file.
  1131. If like-named files exist in both directories, the
  1132. specification is ambiguous and an explicit target
  1133. must be specified to resolve the ambiguity.
  1134. For example,
  1135. adding the rule
  1136. <DL><DT><DD><TT><PRE>
  1137. f2.<I>O: f2.c
  1138. </I>CC <I>CFLAGS </I>f2.c
  1139. </PRE></TT></DL>
  1140. to the previous
  1141. <TT>mkfile</TT>
  1142. uses the architecture-specific version of
  1143. <TT>f2.c</TT>
  1144. instead of the portable one.
  1145. Here, the explicit rule unambiguously
  1146. documents which of the
  1147. like-named source files is used to build the program.
  1148. </P>
  1149. <P>
  1150. <TT>Mk</TT>'<TT></TT>s
  1151. heuristics can produce unintended results
  1152. when rules are not carefully specified.
  1153. For example, the rules that build
  1154. object files from C or assembler source files
  1155. <DL><DT><DD><TT><PRE>
  1156. %.<I>O: %.c
  1157. </I>CC <I>CFLAGS </I>stem.c
  1158. %.<I>O: %.s
  1159. </I>AS <I>AFLAGS </I>stem.s
  1160. </PRE></TT></DL>
  1161. illustrate a subtle pratfall.
  1162. Adding a header file dependency to the compile rule
  1163. <DL><DT><DD><TT><PRE>
  1164. %.<I>O: %.c hdr.h
  1165. </I>CC <I>CFLAGS </I>stem.c
  1166. </PRE></TT></DL>
  1167. produces the error message
  1168. <DL><DT><DD><TT><PRE>
  1169. <TT>don't know how to make '</TT><I>file</I><TT>.c'</TT><I>
  1170. </PRE></TT></DL>
  1171. when </I><I>file</I><I>.s is an assembler
  1172. source file.
  1173. This occurs because
  1174. </I><TT></TT><I>file</I><TT>.s</TT><I>
  1175. satisfies the assemble rule and
  1176. </I><TT>hdr.h</TT><I>
  1177. satisfies the compile rule, so
  1178. either rule can potentially produce the target.
  1179. When a prerequisite exists or can be
  1180. derived,
  1181. all other prerequisites in that
  1182. rule header must exist or be derivable; here,
  1183. the existence of
  1184. </I><TT>hdr.h</TT><I>
  1185. forces the evaluation of a C source file.
  1186. Specifying the dependencies in different
  1187. rules avoids this interpretation:
  1188. <DL><DT><DD><TT><PRE>
  1189. %.</I><I>O: hdr.h
  1190. %.</I><I>O: %.c
  1191. </I><I>CC </I><I>CFLAGS </I><I>stem.c
  1192. </PRE></TT></DL>
  1193. Although
  1194. </I><TT>hdr.h</TT><I>
  1195. is an additional prerequisite of the compile rule,
  1196. the two rules are evaluated independently and
  1197. the existence of the C source file is not linked
  1198. to the existence of the header file.
  1199. However, this specification describes a different
  1200. dependency. Originally, only object
  1201. files derived from C files depended on
  1202. </I><TT>hdr.h</TT><I>;
  1203. now all object files, including those built
  1204. from assembler source, depend on the header file.
  1205. </P>
  1206. </I><P>
  1207. Metarule patterns should be as restrictive as possible to
  1208. prevent conflicts with other rules.
  1209. Consider the
  1210. <TT>mkfile</TT>
  1211. <DL><DT><DD><TT><PRE>
  1212. &lt;/objtype/mkfile
  1213. BIN=/<I>objtype/bin
  1214. PROG=foo
  1215. install:V: </I>BIN/<I>PROG
  1216. %: %.c
  1217. </I>CC <I>stem.c
  1218. </I>LD -o <I>target </I>stem.<I>O
  1219. </I>BIN/%: %
  1220. mv <I>stem </I>target
  1221. </PRE></TT></DL>
  1222. The first target builds an executable
  1223. in the local directory; the second
  1224. installs it in the directory
  1225. of executables for the architecture.
  1226. Invoking
  1227. <TT>mk</TT>
  1228. with the
  1229. <TT>install</TT>
  1230. target produces:
  1231. <DL><DT><DD><TT><PRE>
  1232. mk: ambiguous recipes for /mips/bin/foo:
  1233. /mips/bin/foo &lt;-(mkfile:8)- /mips/bin/foo.c &lt;-(mkfile:12)- foo.c
  1234. /mips/bin/foo &lt;-(mkfile:12)- foo &lt;-(mkfile:8)- foo.c
  1235. </PRE></TT></DL>
  1236. The prerequisite of the
  1237. <TT>install</TT>
  1238. rule,
  1239. <TT></TT><I>BIN/</I><TT>PROG</TT><I>,
  1240. matches both metarules because the
  1241. </I><TT>%</TT><I>
  1242. pattern matches everything.
  1243. The
  1244. </I><TT>&</TT><I>
  1245. pattern restricts the compile rule to files in the
  1246. current directory and avoids the conflict:
  1247. <DL><DT><DD><TT><PRE>
  1248. &amp;: &amp;.c
  1249. </I><I>CC </I><I>stem.c
  1250. </I><I>LD -o </I><I>target </I><I>stem.</I><I>O
  1251. </PRE></TT></DL>
  1252. </P>
  1253. </I><H4>10 Missing intermediates
  1254. </H4>
  1255. <P>
  1256. <TT>Mk</TT>
  1257. does not build a missing intermediate file if a target
  1258. is up to date with the prerequisites of the intermediate.
  1259. For example,
  1260. when an executable is up to date with its source file,
  1261. <TT>mk</TT>
  1262. does not compile the source to create a missing object file.
  1263. The evaluation only applies
  1264. when a target is considered up to date by pretending that the
  1265. intermediate exists. Thus, it does not apply
  1266. when the intermediate is a command line target
  1267. or when it has no prerequisites.
  1268. </P>
  1269. <P>
  1270. This capability is useful for
  1271. maintaining archives. We can modify the archive
  1272. update recipe to remove object files after
  1273. they are archived:
  1274. <DL><DT><DD><TT><PRE>
  1275. <I>LIB(%):N: %
  1276. </I>LIB: <I>{OBJS:%=</I>LIB(%)}
  1277. names=`{membername <I>newprereq}
  1278. ar rv </I>LIB <I>names
  1279. rm -f </I>names
  1280. </PRE></TT></DL>
  1281. A subsequent
  1282. <TT>mk</TT>
  1283. does not remake the object files as long as the members
  1284. of the archive remain up to date with the source files.
  1285. The
  1286. <TT>-i</TT>
  1287. command line option overrides this behavior
  1288. and causes all intermediates to be built.
  1289. </P>
  1290. <H4>11 Alternative out-of-date determination
  1291. </H4>
  1292. <P>
  1293. Sometimes the modification time is not useful
  1294. for deciding when a target and prerequisite are out of date.
  1295. The
  1296. <TT>P</TT>
  1297. attribute replaces the default mechanism with the result of
  1298. a command. The command immediately follows the attribute
  1299. and is repeatedly executed with each
  1300. target and each prerequisite as its arguments;
  1301. if its exit status is non-zero, they are considered out of date
  1302. and the recipe is executed. Consider the
  1303. <TT>mkfile</TT>
  1304. <DL><DT><DD><TT><PRE>
  1305. foo.ref:Pcmp -s: foo
  1306. cp <I>prereq </I>target
  1307. </PRE></TT></DL>
  1308. The command
  1309. <DL><DT><DD><TT><PRE>
  1310. cmp -s foo.ref foo
  1311. </PRE></TT></DL>
  1312. is executed and if
  1313. <TT>foo.ref</TT>
  1314. differs from
  1315. <TT>foo</TT>,
  1316. the latter file is copied to the former.
  1317. </P>
  1318. <H4>12 Parallel processing
  1319. </H4>
  1320. <P>
  1321. When possible,
  1322. <TT>mk</TT>
  1323. executes recipes in parallel.
  1324. The variable
  1325. <TT></TT><I>NPROC</I><TT>
  1326. specifies the maximum number of simultaneously executing
  1327. recipes.
  1328. Normally it is imported from the environment,
  1329. where the system has set it to the number of available processors.
  1330. It can be decreased by assigning a new
  1331. value and can be set to 1 to force single-threaded recipe execution.
  1332. This is necessary when several targets access
  1333. a common resource such as
  1334. a status file or data base.
  1335. When there is no dependency between targets,
  1336. </TT><TT>mk</TT><TT>
  1337. assumes the
  1338. recipes can be
  1339. executed concurrently.
  1340. Normally, this allows
  1341. multiple prerequisites to be built simultaneously;
  1342. for example, the object file prerequisites of
  1343. a load rule can be produced by compiling the source files in parallel.
  1344. </TT><TT>Mk</TT><TT>
  1345. does not define the order of execution of independent recipes.
  1346. When the prerequisites of a rule are not independent,
  1347. the dependencies between them should be specified in a rule or the
  1348. </TT><TT>mkfile</TT><TT>
  1349. should be single-threaded.
  1350. For example, the archive update rules
  1351. <DL><DT><DD><TT><PRE>
  1352. </TT>LIB(%):N: %
  1353. <I>LIB: </I>{OBJS:%=<I>LIB(%)}
  1354. ar rv </I>LIB `{membername <I>newprereq}
  1355. </PRE></TT></DL>
  1356. compile source files in parallel but update
  1357. all members of the archive at once.
  1358. It is a mistake to merge the two rules
  1359. <DL><DT><DD><TT><PRE>
  1360. </I>LIB(%): %
  1361. ar rv <I>LIB </I>stem
  1362. </PRE></TT></DL>
  1363. because an
  1364. <TT>ar</TT>
  1365. command is executed for every
  1366. member of the library. Not only is this
  1367. inefficient, but the archive is updated
  1368. in parallel, making interference likely.
  1369. </P>
  1370. <P>
  1371. The
  1372. <TT></TT><I>nproc</I><TT>
  1373. environment variable contains a number associated
  1374. with the processor executing a recipe.
  1375. It can be used to create unique
  1376. names when the
  1377. recipe may be executing simultaneously on several processors.
  1378. Other maintenance tools provide mechanisms to control recipe
  1379. scheduling explicitly [Cmel86], but
  1380. </TT><TT>mk</TT>'<TT>s</TT>
  1381. general rules are sufficient for all but the most unusual cases.
  1382. </P>
  1383. <H4>13 Deleting target files on errors
  1384. </H4>
  1385. <P>
  1386. The
  1387. <TT>D</TT>
  1388. attribute
  1389. causes
  1390. <TT>mk</TT>
  1391. to remove the target file when a
  1392. recipe terminates prematurely.
  1393. The error message describing the
  1394. termination condition warns
  1395. of the deletion.
  1396. A partially built file is doubly dangerous:
  1397. it is not only wrong, but is also
  1398. considered to be up to date so
  1399. a subsequent
  1400. <TT>mk</TT>
  1401. will not rebuild it. For example,
  1402. <DL><DT><DD><TT><PRE>
  1403. pic.out:D: mk.ms
  1404. pic prereq | tbl | troff -ms &gt; <I>target
  1405. </PRE></TT></DL>
  1406. produces the message
  1407. <DL><DT><DD><TT><PRE>
  1408. </I><TT>mk: pic mk.ms | ... : exit status=rc 685: deleting 'pic.out'</TT><I>
  1409. </PRE></TT></DL>
  1410. if any program in the recipe exits with an error status.
  1411. </P>
  1412. </I><H4>14 Unspecified dependencies
  1413. </H4>
  1414. <P>
  1415. The
  1416. <TT>-w</TT>
  1417. command line flag forces the
  1418. files following the flag to be treated
  1419. as if they were just modified.
  1420. We can use this flag with a command that selects files
  1421. to force a build based on the selection criterion.
  1422. For example, if the declaration of
  1423. a global variable named
  1424. <I>var</I>
  1425. is changed in a header file,
  1426. all source files that reference
  1427. it can be rebuilt with the command
  1428. <DL><DT><DD><TT><PRE>
  1429. mk -w`{grep -l <I>var</I> *.[cyl]}
  1430. </PRE></TT></DL>
  1431. </P>
  1432. <H4>15 Conclusion
  1433. </H4>
  1434. <P>
  1435. There are many programs related to
  1436. <TT>make</TT>,
  1437. each choosing a different balance between
  1438. specialization and generality.
  1439. <TT>Mk</TT>
  1440. emphasizes generality but allows
  1441. customization through its pattern specifications and
  1442. include facilities.
  1443. </P>
  1444. <P>
  1445. Plan 9 presents a difficult maintenance environment
  1446. with its heterogeneous
  1447. architectures and languages.
  1448. <TT>Mk</TT>'<TT>s</TT>
  1449. flexible specification language and simple
  1450. interaction with
  1451. <TT>rc</TT>
  1452. work well in this environment.
  1453. As a result,
  1454. Plan 9 relies on
  1455. <TT>mk</TT>
  1456. to automate almost all maintenance.
  1457. Tasks as diverse as updating the
  1458. network data base, producing the manual,
  1459. or building a release are expressed as
  1460. <TT>mk</TT>
  1461. procedures.
  1462. </P>
  1463. <H4>16 References
  1464. </H4>
  1465. <br>&#32;<br>
  1466. [Cmel86] R. F. Cmelik,
  1467. ``Concurrent Make: A Distributed Program in Concurrent C'',
  1468. AT&amp;T Bell Laboratories Technical Report, 1986.
  1469. <br>&#32;<br>
  1470. [Feld79] S. I. Feldman,
  1471. ``Make &#173; a program for maintaining computer programs'',
  1472. Software Practice &amp; Experience ,
  1473. 1979
  1474. Vol 9 #4,
  1475. pp. 255-266.
  1476. <br>&#32;<br>
  1477. [Flan95] Bob Flandrena,
  1478. ``Plan 9 Mkfiles'',
  1479. this volume.
  1480. <br>&#32;<br>
  1481. [Hume87] A. G. Hume,
  1482. ``Mk: A Successor to Make'',
  1483. USENIX Summer Conf. Proc.,
  1484. Phoenix, Az.
  1485. <H4>17 Appendix: Differences between
  1486. <TT>make</TT>
  1487. and
  1488. <TT>mk</TT>
  1489. </H4>
  1490. <P>
  1491. The differences between
  1492. <TT>mk</TT>
  1493. and
  1494. <TT>make</TT>
  1495. are:
  1496. </P>
  1497. <UL>
  1498. <LI>
  1499. <TT>Make</TT>
  1500. builds targets when it needs them, allowing systematic use of side effects.
  1501. <TT>Mk</TT>
  1502. constructs the entire dependency graph before building any target.
  1503. <LI>
  1504. <TT>Make</TT>
  1505. supports suffix rules and
  1506. <TT>%</TT>
  1507. metarules.
  1508. <TT>Mk</TT>
  1509. supports
  1510. <TT>%</TT>
  1511. and regular expression metarules.
  1512. (Older versions of
  1513. <TT>make</TT>
  1514. support only suffix rules.)
  1515. <LI>
  1516. <TT>Mk</TT>
  1517. performs transitive closure on metarules,
  1518. <TT>make</TT>
  1519. does not.
  1520. <LI>
  1521. <TT>Make</TT>
  1522. supports cyclic dependencies,
  1523. <TT>mk</TT>
  1524. does not.
  1525. <LI>
  1526. <TT>Make</TT>
  1527. evaluates recipes one line at a time, replacing variables by their values and
  1528. executing some commands internally.
  1529. <TT>Mk</TT>
  1530. passes the entire recipe to the shell without
  1531. interpretation or internal execution.
  1532. <LI>
  1533. <TT>Make</TT>
  1534. supports parallel execution of single-line recipes when building
  1535. the prerequisites for specified targets.
  1536. <TT>Mk</TT>
  1537. supports parallel execution of all recipes.
  1538. (Older versions of
  1539. <TT>make</TT>
  1540. did not support parallel execution.)
  1541. <LI>
  1542. <TT>Make</TT>
  1543. uses special targets (beginning with a period)
  1544. to indicate special processing.
  1545. <TT>Mk</TT>
  1546. uses attributes to modify rule evaluation.
  1547. <LI>
  1548. <TT>Mk</TT>
  1549. supports virtual
  1550. targets that are independent of the file system.
  1551. <LI>
  1552. <TT>Mk</TT>
  1553. allows non-standard out-of-date determination,
  1554. <TT>make</TT>
  1555. does not.
  1556. </ul>
  1557. <P>
  1558. It is usually easy to convert a
  1559. <TT>makefile</TT>
  1560. to or from an equivalent
  1561. <TT>mkfile</TT>.
  1562. </P>
  1563. <br>&#32;<br>
  1564. <A href=http://www.lucent.com/copyright.html>
  1565. Copyright</A> &#169; 2004 Lucent Technologies Inc. All rights reserved.
  1566. </body></html>