mk 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655
  1. .TH MK 1
  2. .SH NAME
  3. mk, membername \- maintain (make) related files
  4. .SH SYNOPSIS
  5. .B mk
  6. [
  7. .B -f
  8. .I mkfile
  9. ] ...
  10. [
  11. .I option ...
  12. ]
  13. [
  14. .I target ...
  15. ]
  16. .PP
  17. .B membername
  18. .I aggregate ...
  19. .SH DESCRIPTION
  20. .I Mk
  21. uses the dependency rules specified in
  22. .I mkfile
  23. to control the update (usually by compilation) of
  24. .I targets
  25. (usually files)
  26. from the source files upon which they depend.
  27. The
  28. .I mkfile
  29. (default
  30. .LR mkfile )
  31. contains a
  32. .I rule
  33. for each target that identifies the files and other
  34. targets upon which it depends and an
  35. .IR rc (1)
  36. script, a
  37. .IR recipe ,
  38. to update the target.
  39. The script is run if the target does not exist
  40. or if it is older than any of the files it depends on.
  41. .I Mkfile
  42. may also contain
  43. .I meta-rules
  44. that define actions for updating implicit targets.
  45. If no
  46. .I target
  47. is specified, the target of the first rule (not meta-rule) in
  48. .I mkfile
  49. is updated.
  50. .PP
  51. The environment variable
  52. .B $NPROC
  53. determines how many targets may be updated simultaneously;
  54. Plan 9 sets
  55. .B $NPROC
  56. automatically to the number of CPUs on the current machine.
  57. .PP
  58. Options are:
  59. .TP \w'\fL-d[egp]\ 'u
  60. .B -a
  61. Assume all targets to be out of date.
  62. Thus, everything is updated.
  63. .PD 0
  64. .TP
  65. .BR -d [ egp ]
  66. Produce debugging output
  67. .RB ( p
  68. is for parsing,
  69. .B g
  70. for graph building,
  71. .B e
  72. for execution).
  73. .TP
  74. .B -e
  75. Explain why each target is made.
  76. .TP
  77. .B -i
  78. Force any missing intermediate targets to be made.
  79. .TP
  80. .B -k
  81. Do as much work as possible in the face of errors.
  82. .TP
  83. .B -n
  84. Print, but do not execute, the commands
  85. needed to update the targets.
  86. .TP
  87. .B -s
  88. Make the command line arguments sequentially rather than in parallel.
  89. .TP
  90. .B -t
  91. Touch (update the modified date of) file targets, without
  92. executing any recipes.
  93. .TP
  94. .BI -w target1 , target2,...
  95. Pretend the modify time for each
  96. .I target
  97. is the current time; useful in conjunction with
  98. .B -n
  99. to learn what updates would be triggered by
  100. modifying the
  101. .IR targets .
  102. .PD
  103. .PP
  104. The
  105. .IR rc (1)
  106. script
  107. .I membername
  108. extracts member names
  109. (see `Aggregates' below)
  110. from its arguments.
  111. .SS The \fLmkfile\fP
  112. A
  113. .I mkfile
  114. consists of
  115. .I assignments
  116. (described under `Environment') and
  117. .IR rules .
  118. A rule contains
  119. .I targets
  120. and a
  121. .IR tail .
  122. A target is a literal string
  123. and is normally a file name.
  124. The tail contains zero or more
  125. .I prerequisites
  126. and an optional
  127. .IR recipe ,
  128. which is an
  129. .B rc
  130. script.
  131. Each line of the recipe must begin with white space.
  132. A rule takes the form
  133. .IP
  134. .EX
  135. target: prereq1 prereq2
  136. rc \f2recipe using\fP prereq1, prereq2 \f2to build\fP target
  137. .EE
  138. .PP
  139. When the recipe is executed,
  140. the first character on every line is elided.
  141. .PP
  142. After the colon on the target line, a rule may specify
  143. .IR attributes ,
  144. described below.
  145. .PP
  146. A
  147. .I meta-rule
  148. has a target of the form
  149. .IB A % B
  150. where
  151. .I A
  152. and
  153. .I B
  154. are (possibly empty) strings.
  155. A meta-rule acts as a rule for any potential target whose
  156. name matches
  157. .IB A % B
  158. with
  159. .B %
  160. replaced by an arbitrary string, called the
  161. .IR stem .
  162. In interpreting a meta-rule,
  163. the stem is substituted for all occurrences of
  164. .B %
  165. in the prerequisite names.
  166. In the recipe of a meta-rule, the environment variable
  167. .B $stem
  168. contains the string matched by the
  169. .BR % .
  170. For example, a meta-rule to compile a C program using
  171. .IR 8c (1)
  172. might be:
  173. .IP
  174. .EX
  175. %: %.c
  176. 8c $stem.c
  177. 8l -o $stem $stem.8
  178. .EE
  179. .PP
  180. Meta-rules may contain an ampersand
  181. .B &
  182. rather than a percent sign
  183. .BR % .
  184. A
  185. .B %
  186. matches a maximal length string of any characters;
  187. an
  188. .B &
  189. matches a maximal length string of any characters except period
  190. or slash.
  191. .PP
  192. The text of the
  193. .I mkfile
  194. is processed as follows.
  195. Lines beginning with
  196. .B <
  197. followed by a file name are replaced by the contents of the named
  198. file.
  199. Lines beginning with
  200. .B "<|"
  201. followed by a file name are replaced by the output
  202. of the execution of the named
  203. file.
  204. Blank lines and comments, which run from unquoted
  205. .B #
  206. characters to the following newline, are deleted.
  207. The character sequence backslash-newline is deleted,
  208. so long lines in
  209. .I mkfile
  210. may be folded.
  211. Non-recipe lines are processed by substituting for
  212. .BI `{ command }
  213. the output of the
  214. .I command
  215. when run by
  216. .IR rc .
  217. References to variables are replaced by the variables' values.
  218. Special characters may be quoted using single quotes
  219. .BR \&''
  220. as in
  221. .IR rc (1).
  222. .PP
  223. Assignments and rules are distinguished by
  224. the first unquoted occurrence of
  225. .B :
  226. (rule)
  227. or
  228. .B =
  229. (assignment).
  230. .PP
  231. A later rule may modify or override an existing rule under the
  232. following conditions:
  233. .TP
  234. \-
  235. If the targets of the rules exactly match and one rule
  236. contains only a prerequisite clause and no recipe, the
  237. clause is added to the prerequisites of the other rule.
  238. If either or both targets are virtual, the recipe is
  239. always executed.
  240. .TP
  241. \-
  242. If the targets of the rules match exactly and the
  243. prerequisites do not match and both rules
  244. contain recipes,
  245. .I mk
  246. reports an ``ambiguous recipe'' error.
  247. .TP
  248. \-
  249. If the target and prerequisites of both rules match exactly,
  250. the second rule overrides the first.
  251. .SS Environment
  252. Rules may make use of
  253. .B rc
  254. environment variables.
  255. A legal reference of the form
  256. .B $OBJ
  257. is expanded as in
  258. .IR rc (1).
  259. A reference of the form
  260. .BI ${name: A % B = C\fL%\fID\fL}\fR,
  261. where
  262. .I A, B, C, D
  263. are (possibly empty) strings,
  264. has the value formed by expanding
  265. .B $name
  266. and substituting
  267. .I C
  268. for
  269. .I A
  270. and
  271. .I D
  272. for
  273. .I B
  274. in each word in
  275. .B $name
  276. that matches pattern
  277. .IB A % B\f1.
  278. .PP
  279. Variables can be set by
  280. assignments of the form
  281. .I
  282. var\fL=\fR[\fIattr\fL=\fR]\fIvalue\fR
  283. .br
  284. Blanks in the
  285. .I value
  286. break it into words, as in
  287. .I rc
  288. but without the surrounding parentheses.
  289. Such variables are exported
  290. to the environment of
  291. recipes as they are executed, unless
  292. .BR U ,
  293. the only legal attribute
  294. .IR attr ,
  295. is present.
  296. The initial value of a variable is
  297. taken from (in increasing order of precedence)
  298. the default values below,
  299. .I mk's
  300. environment, the
  301. .IR mkfiles ,
  302. and any command line assignment as an argument to
  303. .IR mk .
  304. A variable assignment argument overrides the first (but not any subsequent)
  305. assignment to that variable.
  306. .PP
  307. The variable
  308. .B MKFLAGS
  309. contains all the option arguments (arguments starting with
  310. .L -
  311. or containing
  312. .LR = )
  313. and
  314. .B MKARGS
  315. contains all the targets in the call to
  316. .IR mk .
  317. .PP
  318. It is recommended that mkfiles start with
  319. .IP
  320. .EX
  321. </$objtype/mkfile
  322. .EE
  323. .PP
  324. to set
  325. .BR CC ,
  326. .BR LD ,
  327. .BR AS ,
  328. .BR O ,
  329. .BR YACC ,
  330. and
  331. .B MK
  332. to values appropriate to the target architecture (see the examples below).
  333. .SS Execution
  334. .PP
  335. During execution,
  336. .I mk
  337. determines which targets must be updated, and in what order,
  338. to build the
  339. .I names
  340. specified on the command line.
  341. It then runs the associated recipes.
  342. .PP
  343. A target is considered up to date if it has no prerequisites or
  344. if all its prerequisites are up to date and it is newer
  345. than all its prerequisites.
  346. Once the recipe for a target has executed, the target is
  347. considered up to date.
  348. .PP
  349. The date stamp
  350. used to determine if a target is up to date is computed
  351. differently for different types of targets.
  352. If a target is
  353. .I virtual
  354. (the target of a rule with the
  355. .B V
  356. attribute),
  357. its date stamp is initially zero; when the target is
  358. updated the date stamp is set to
  359. the most recent date stamp of its prerequisites.
  360. Otherwise, if a target does not exist as a file,
  361. its date stamp is set to the most recent date stamp of its prerequisites,
  362. or zero if it has no prerequisites.
  363. Otherwise, the target is the name of a file and
  364. the target's date stamp is always that file's modification date.
  365. The date stamp is computed when the target is needed in
  366. the execution of a rule; it is not a static value.
  367. .PP
  368. Nonexistent targets that have prerequisites
  369. and are themselves prerequisites are treated specially.
  370. Such a target
  371. .I t
  372. is given the date stamp of its most recent prerequisite
  373. and if this causes all the targets which have
  374. .I t
  375. as a prerequisite to be up to date,
  376. .I t
  377. is considered up to date.
  378. Otherwise,
  379. .I t
  380. is made in the normal fashion.
  381. The
  382. .B -i
  383. flag overrides this special treatment.
  384. .PP
  385. Files may be made in any order that respects
  386. the preceding restrictions.
  387. .PP
  388. A recipe is executed by supplying the recipe as standard input to
  389. the command
  390. .B
  391. /bin/rc -e -I
  392. .br
  393. (the
  394. .B -e
  395. is omitted if the
  396. .B E
  397. attribute is set).
  398. The environment is augmented by the following variables:
  399. .TP 14
  400. .B $alltarget
  401. all the targets of this rule.
  402. .TP
  403. .B $newprereq
  404. the prerequisites that caused this rule to execute.
  405. .TP
  406. .B $newmember
  407. the prerequisites that are members of an aggregate
  408. that caused this rule to execute.
  409. When the prerequisites of a rule are members of an
  410. aggregate,
  411. .B $newprereq
  412. contains the name of the aggregate and out of date
  413. members, while
  414. .B $newmember
  415. contains only the name of the members.
  416. .TP
  417. .B $nproc
  418. the process slot for this recipe.
  419. It satisfies
  420. .RB 0≤ $nproc < $NPROC .
  421. .TP
  422. .B $pid
  423. the process id for the
  424. .I mk
  425. executing the recipe.
  426. .TP
  427. .B $prereq
  428. all the prerequisites for this rule.
  429. .TP
  430. .B $stem
  431. if this is a meta-rule,
  432. .B $stem
  433. is the string that matched
  434. .B %
  435. or
  436. .BR & .
  437. Otherwise, it is empty.
  438. For regular expression meta-rules (see below), the variables
  439. .LR stem0 ", ...,"
  440. .L stem9
  441. are set to the corresponding subexpressions.
  442. .TP
  443. .B $target
  444. the targets for this rule that need to be remade.
  445. .PP
  446. These variables are available only during the execution of a recipe,
  447. not while evaluating the
  448. .IR mkfile .
  449. .PP
  450. Unless the rule has the
  451. .B Q
  452. attribute,
  453. the recipe is printed prior to execution
  454. with recognizable environment variables expanded.
  455. Commands returning nonempty status (see
  456. .IR intro (1))
  457. cause
  458. .I mk
  459. to terminate.
  460. .PP
  461. Recipes and backquoted
  462. .B rc
  463. commands in places such as assignments
  464. execute in a copy of
  465. .I mk's
  466. environment; changes they make to
  467. environment variables are not visible from
  468. .IR mk .
  469. .PP
  470. Variable substitution in a rule is done when
  471. the rule is read; variable substitution in the recipe is done
  472. when the recipe is executed. For example:
  473. .IP
  474. .EX
  475. bar=a.c
  476. foo: $bar
  477. $CC -o foo $bar
  478. bar=b.c
  479. .EE
  480. .PP
  481. will compile
  482. .B b.c
  483. into
  484. .BR foo ,
  485. if
  486. .B a.c
  487. is newer than
  488. .BR foo .
  489. .SS Aggregates
  490. Names of the form
  491. .IR a ( b )
  492. refer to member
  493. .I b
  494. of the aggregate
  495. .IR a .
  496. Currently, the only aggregates supported are
  497. .IR ar (1)
  498. archives.
  499. .SS Attributes
  500. The colon separating the target from the prerequisites
  501. may be
  502. immediately followed by
  503. .I attributes
  504. and another colon.
  505. The attributes are:
  506. .TP
  507. .B D
  508. If the recipe exits with a non-null status, the target is deleted.
  509. .TP
  510. .B E
  511. Continue execution if the recipe draws errors.
  512. .TP
  513. .B N
  514. If there is no recipe, the target has its time updated.
  515. .TP
  516. .B n
  517. The rule is a meta-rule that cannot be a target of a virtual rule.
  518. Only files match the pattern in the target.
  519. .TP
  520. .B P
  521. The characters after the
  522. .B P
  523. until the terminating
  524. .B :
  525. are taken as a program name.
  526. It will be invoked as
  527. .B "rc -c prog 'arg1' 'arg2'"
  528. and should return a null exit status
  529. if and only if arg1 is up to date with respect to arg2.
  530. Date stamps are still propagated in the normal way.
  531. .TP
  532. .B Q
  533. The recipe is not printed prior to execution.
  534. .TP
  535. .B R
  536. The rule is a meta-rule using regular expressions.
  537. In the rule,
  538. .B %
  539. has no special meaning.
  540. The target is interpreted as a regular expression as defined in
  541. .IR regexp (6).
  542. The prerequisites may contain references
  543. to subexpressions in form
  544. .BI \e n\f1,
  545. as in the substitute command of
  546. .IR sam (1).
  547. .TP
  548. .B U
  549. The targets are considered to have been updated
  550. even if the recipe did not do so.
  551. .TP
  552. .B V
  553. The targets of this rule are marked as virtual.
  554. They are distinct from files of the same name.
  555. .PD
  556. .SH EXAMPLES
  557. A simple mkfile to compile a program:
  558. .IP
  559. .EX
  560. .ta 8n +8n +8n +8n +8n +8n +8n
  561. </$objtype/mkfile
  562. prog: a.$O b.$O c.$O
  563. $LD $LDFLAGS -o $target $prereq
  564. %.$O: %.c
  565. $CC $CFLAGS $stem.c
  566. .EE
  567. .PP
  568. Override flag settings in the mkfile:
  569. .IP
  570. .EX
  571. % mk target 'CFLAGS=-S -w'
  572. .EE
  573. .PP
  574. Maintain a library:
  575. .IP
  576. .EX
  577. libc.a(%.$O):N: %.$O
  578. libc.a: libc.a(abs.$O) libc.a(access.$O) libc.a(alarm.$O) ...
  579. ar r libc.a $newmember
  580. .EE
  581. .PP
  582. String expression variables to derive names from a master list:
  583. .IP
  584. .EX
  585. NAMES=alloc arc bquote builtins expand main match mk var word
  586. OBJ=${NAMES:%=%.$O}
  587. .EE
  588. .PP
  589. Regular expression meta-rules:
  590. .IP
  591. .EX
  592. ([^/]*)/(.*)\e.$O:R: \e1/\e2.c
  593. cd $stem1; $CC $CFLAGS $stem2.c
  594. .EE
  595. .PP
  596. A correct way to deal with
  597. .IR yacc (1)
  598. grammars.
  599. The file
  600. .B lex.c
  601. includes the file
  602. .B x.tab.h
  603. rather than
  604. .B y.tab.h
  605. in order to reflect changes in content, not just modification time.
  606. .IP
  607. .EX
  608. lex.$O: x.tab.h
  609. x.tab.h: y.tab.h
  610. cmp -s x.tab.h y.tab.h || cp y.tab.h x.tab.h
  611. y.tab.c y.tab.h: gram.y
  612. $YACC -d gram.y
  613. .EE
  614. .PP
  615. The above example could also use the
  616. .B P
  617. attribute for the
  618. .B x.tab.h
  619. rule:
  620. .IP
  621. .EX
  622. x.tab.h:Pcmp -s: y.tab.h
  623. cp y.tab.h x.tab.h
  624. .EE
  625. .SH SOURCE
  626. .B /sys/src/cmd/mk
  627. .SH SEE ALSO
  628. .IR rc (1),
  629. .IR regexp (6)
  630. .PP
  631. A. Hume,
  632. ``Mk: a Successor to Make''.
  633. .PP
  634. Andrew G. Hume and Bob Flandrena,
  635. ``Maintaining Files on Plan 9 with Mk''.
  636. .SH BUGS
  637. Identical recipes for regular expression meta-rules only have one target.
  638. .PP
  639. Seemingly appropriate input like
  640. .B CFLAGS=-DHZ=60
  641. is parsed as an erroneous attribute; correct it by inserting
  642. a space after the first
  643. .LR = .
  644. .PP
  645. The recipes printed by
  646. .I mk
  647. before being passed to
  648. .I rc
  649. for execution are sometimes erroneously expanded
  650. for printing. Don't trust what's printed; rely
  651. on what
  652. .I rc
  653. does.