![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mk CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Plan 9 NeXT] / lucent / sys / man / 1|
Return to mk CVS log | Up to [Plan 9 NeXT] / lucent / sys / man / 1 |
1.1 root 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 2c (1)
172: might be:
173: .IP
174: .EX
175: %.2: %.c
176: 2c $stem.c
177: 2l -o $stem $stem.2
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: Blank lines and comments, which run from unquoted
200: .B #
201: characters to the following newline, are deleted.
202: The character sequence backslash-newline is deleted,
203: so long lines in
204: .I mkfile
205: may be folded.
206: Non-recipe lines are processed by substituting for
207: .BI `{ command }
208: the output of the
209: .I command
210: when run by
211: .IR rc .
212: References to variables are replaced by the variables' values.
213: Special characters may be quoted using single quotes
214: .BR \&''
215: as in
216: .IR rc (1).
217: .PP
218: Assignments and rules are distinguished by
219: the first unquoted occurrence of
220: .B :
221: (rule)
222: or
223: .B =
224: (assignment).
225: .PP
226: A later rule may modify or override an existing rule under the
227: following conditions:
228: .TP
229: \-
230: If the targets of the rules exactly match and one rule
231: contains only a prerequisite clause and no recipe, the
232: clause is added to the prerequisites of the other rule.
233: If either or both targets are virtual, the recipe is
234: always executed.
235: .TP
236: \-
237: If the targets of the rules match exactly and the
238: prerequisites do not match and both rules
239: contain recipes,
240: .I mk
241: reports an ``ambiguous recipe'' error.
242: .TP
243: \-
244: If the target and prerequisites of both rules match exactly,
245: the second rule overrides the first.
246: .SS Environment
247: Rules may make use of
248: .B rc
249: environment variables.
250: A legal reference of the form
251: .B $OBJ
252: or
253: .B ${name}
254: is expanded as in
255: .IR rc (1).
256: A reference of the form
257: .BI ${name: A % B = C\fL%\fID\fL}\fR,
258: where
259: .I A, B, C, D
260: are (possibly empty) strings,
261: has the value formed by expanding
262: .B $name
263: and substituting
264: .I C
265: for
266: .I A
267: and
268: .I D
269: for
270: .I B
271: in each word in
272: .B $name
273: that matches pattern
274: .IB A % B\f1.
275: .PP
276: Variables can be set by
277: assignments of the form
278: .I
279: var\fL=\fR[\fIattr\fL=\fR]\fIvalue\fR
280: .br
281: Blanks in the
282: .I value
283: break it into words, as in
284: .I rc
285: but without the surrounding parentheses.
286: Such variables are exported
287: to the environment of
288: recipes as they are executed, unless
289: .BR U ,
290: the only legal attribute
291: .IR attr ,
292: is present.
293: The initial value of a variable is
294: taken from (in increasing order of precedence)
295: the default values below,
296: .I mk's
297: environment, the
298: .IR mkfiles ,
299: and any command line assignment as an argument to
300: .IR mk .
301: A variable assignment argument overrides the first (but not any subsequent)
302: assignment to that variable.
303: The variable
304: .B MKFLAGS
305: contains all the option arguments (arguments starting with
306: .L -
307: or containing
308: .LR = )
309: and
310: .B MKARGS
311: contains all the targets in the call to
312: .IR mk .
313: .PP
314: It is recommended that mkfiles start with
315: .IP
316: .EX
317: </$objtype/mkfile
318: .EE
319: .PP
320: to set
321: .BR CC ,
322: .BR LD ,
323: .BR AS ,
324: .BR O ,
325: .BR ALEF ,
326: .BR YACC ,
327: and
328: .B MK
329: to values appropriate to the target architecture (see the examples below).
330: .SS Execution
331: .PP
332: During execution,
333: .I mk
334: determines which targets must be updated, and in what order,
335: to build the
336: .I names
337: specified on the command line.
338: It then runs the associated recipes.
339: .PP
340: A target is considered up to date if it has no prerequisites or
341: if all its prerequisites are up to date and it is newer
342: than all its prerequisites.
343: Once the recipe for a target has executed, the target is
344: considered up to date.
345: .PP
346: The date stamp
347: used to determine if a target is up to date is computed
348: differently for different types of targets.
349: If a target is
350: .I virtual
351: (the target of a rule with the
352: .B V
353: attribute),
354: its date stamp is initially zero; when the target is
355: updated the date stamp is set to
356: the most recent date stamp of its prerequisites.
357: Otherwise, if a target does not exist as a file,
358: its date stamp is set to the most recent date stamp of its prerequisites,
359: or zero if it has no prerequisites.
360: Otherwise, the target is the name of a file and
361: the target's date stamp is always that file's modification date.
362: The date stamp is computed when the target is needed in
363: the execution of a rule; it is not a static value.
364: .PP
365: Nonexistent targets that have prerequisites
366: and are themselves prerequisites are treated specially.
367: Such a target
368: .I t
369: is given the date stamp of its most recent prerequisite
370: and if this causes all the targets which have
371: .I t
372: as a prerequisite to be up to date,
373: .I t
374: is considered up to date.
375: Otherwise,
376: .I t
377: is made in the normal fashion.
378: The
379: .B -i
380: flag overrides this special treatment.
381: .PP
382: Files may be made in any order that respects
383: the preceding restrictions.
384: .PP
385: A recipe is executed by supplying the recipe as standard input to
386: the command
387: .B
388: /bin/rc -e -I
389: .br
390: (the
391: .B -e
392: is omitted if the
393: .B E
394: attribute is set).
395: The environment is augmented by the following variables:
396: .TP 14
397: .B $alltarget
398: all the targets of this rule.
399: .TP
400: .B $newprereq
401: the prerequisites that caused this rule to execute.
402: .TP
403: .B $nproc
404: the process slot for this recipe.
405: It satisfies
406: .RB 0≤ $nproc < $NPROC .
407: .TP
408: .B $pid
409: the process id for the
410: .I mk
411: executing the recipe.
412: .TP
413: .B $prereq
414: all the prerequisites for this rule.
415: .TP
416: .B $stem
417: if this is a meta-rule,
418: .B $stem
419: is the string that matched
420: .B %
421: or
422: .BR & .
423: Otherwise, it is empty.
424: For regular expression meta-rules (see below), the variables
425: .LR stem0 ", ...,"
426: .L stem9
427: are set to the corresponding subexpressions.
428: .TP
429: .B $target
430: the targets for this rule that need to be remade.
431: .PP
432: These variables are available only during the execution of a recipe,
433: not while evaluating the
434: .IR mkfile .
435: .PP
436: Unless the rule has the
437: .B Q
438: attribute,
439: the recipe is printed prior to execution
440: with recognizable environment variables expanded.
441: Commands returning nonempty status (see
442: .IR intro (1))
443: cause
444: .I mk
445: to terminate.
446: .PP
447: Recipes and backquoted
448: .B rc
449: commands in places such as assignments
450: execute in a copy of
451: .I mk's
452: environment; changes they make to
453: environment variables are not visible from
454: .IR mk .
455: .PP
456: Variable substitution in a rule is done when
457: the rule is read; variable substitution in the recipe is done
458: when the recipe is executed. For example:
459: .IP
460: .EX
461: bar=a.c
462: foo: $bar
463: $CC -o foo $bar
464: bar=b.c
465: .EE
466: .PP
467: will compile
468: .B b.c
469: into
470: .BR foo ,
471: if
472: .B a.c
473: is newer than
474: .BR foo .
475: .SS Aggregates
476: Names of the form
477: .IR a ( b )
478: refer to member
479: .I b
480: of the aggregate
481: .IR a .
482: Currently, the only aggregates supported are
483: .IR ar (1)
484: archives.
485: .SS Attributes
486: The colon separating the target from the prerequisites
487: may be
488: immediately followed by
489: .I attributes
490: and another colon.
491: The attributes are:
492: .TP
493: .B <
494: The standard output of the recipe is read by
495: .I mk
496: as an additional
497: .IR mkfile .
498: .PD 0
499: .TP
500: .B D
501: If the recipe exits with a non-null status, the target is deleted.
502: .TP
503: .B E
504: Continue execution if the recipe draws errors.
505: .TP
506: .B N
507: If there is no recipe, the target has its time updated.
508: .TP
509: .B n
510: The rule is a meta-rule that cannot be a target of a virtual rule.
511: Only files match the pattern in the target.
512: .TP
513: .B P
514: The characters after the
515: .B P
516: until the terminating
517: .B :
518: are taken as a program name.
519: It will be invoked as
520: .B "rc -c prog 'arg1' 'arg2'"
521: and should return a null exit status
522: if and only if arg1 is not out of date with respect to arg2.
523: Date stamps are still propagated in the normal way.
524: .TP
525: .B Q
526: The recipe is not printed prior to execution.
527: .TP
528: .B R
529: The rule is a meta-rule using regular expressions.
530: In the rule,
531: .B %
532: has no special meaning.
533: The target is interpreted as a regular expression as defined in
534: .IR regexp (6).
535: The prerequisites may contain references
536: to subexpressions in form
537: .BI \e n\f1,
538: as in the substitute command of
539: .IR sam (1).
540: .TP
541: .B U
542: The targets are considered to have been updated
543: even if the recipe did not do so.
544: .TP
545: .B V
546: The targets of this rule are marked as virtual.
547: They are distinct from files of the same name.
548: .PD
549: .SH EXAMPLES
550: A simple mkfile to compile a program:
551: .IP
552: .EX
553: .ta 8n +8n +8n +8n +8n +8n +8n
554: </$objtype/mkfile
555:
556: prog: a.$O b.$O c.$O
557: $LD $CFLAGS -o $target $prereq
558:
559: %.$O: %.c
560: $CC $stem.c
561: .EE
562: .PP
563: Override flag settings in the mkfile:
564: .IP
565: .EX
566: % mk target 'CFLAGS=-S -w'
567: .EE
568: .PP
569: To get the prerequisites for an aggregate:
570: .IP
571: .EX
572: % membername 'libc.a(read.2)' 'libc.a(write.2)'
573: read.2 write.2
574: .EE
575: .PP
576: Maintain a library:
577: .IP
578: .EX
579: libc.a(%.$O):N: %.$O
580: libc.a: libc.a(abs.$O) libc.a(access.$O) libc.a(alarm.$O) ...
581: names=`{membername $newprereq}
582: ar r libc.a $names && rm $names
583: .EE
584: .PP
585: String expression variables to derive names from a master list:
586: .IP
587: .EX
588: NAMES=alloc arc bquote builtins expand main match mk var word
589: OBJ=${NAMES:%=%.$O}
590: .EE
591: .PP
592: Regular expression meta-rules:
593: .IP
594: .EX
595: ([^/]*)/(.*)\e.o:R: \e1/\e2.c
596: cd $stem1; $CC $CFLAGS $stem2.c
597: .EE
598: .PP
599: A correct way to deal with
600: .IR yacc (1)
601: grammars.
602: The file
603: .B lex.c
604: includes the file
605: .B x.tab.h
606: rather than
607: .B y.tab.h
608: in order to reflect changes in content, not just modification time.
609: .IP
610: .EX
611: lex.o: x.tab.h
612: x.tab.h: y.tab.h
613: cmp -s x.tab.h y.tab.h || cp y.tab.h x.tab.h
614: y.tab.c y.tab.h: gram.y
615: $YACC -d gram.y
616: .EE
617: .PP
618: The above example could also use the
619: .B P
620: attribute for the
621: .B x.tab.h
622: rule:
623: .IP
624: .EX
625: x.tab.h:Pcmp -s: y.tab.h
626: cp y.tab.h x.tab.h
627: .EE
628: .SH SOURCE
629: .B /sys/src/cmd/mk
630: .SH SEE ALSO
631: .IR rc (1),
632: .IR regexp (6)
633: .br
634: A. Hume,
635: ``Mk: a Successor to Make''.
636: .br
637: Bob Flandrena,
638: ``Plan 9 Mkfiles''.
639: .SH BUGS
640: Identical recipes for regular expression meta-rules only have one target.
641: .br
642: Seemingly appropriate input like
643: .B CFLAGS=-DHZ=60
644: is parsed as an erroneous attribute; correct it by inserting
645: a space after the first
646: .LR = .
647: .br
648: The recipes printed by
649: .I mk
650: before being passed to
651: .I rc
652: for execution are sometimes erroneously expanded
653: for printing. Don't trust what's printed; rely
654: on what
655: .I rc
656: does.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.