![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mk.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / adm / man1|
Return to mk.1 CVS log | Up to [Research Unix] / researchv10dc / man / adm / man1 |
1.1 root 1: .TH MK 1
2: .CT 1 prog_c writing_troff prog_other
3: .SH NAME
4: mk, mkconv, membername \- maintain (make) related files
5: .SH SYNOPSIS
6: .B mk
7: [
8: .B -f
9: .I mkfile
10: ] ...
11: [
12: .I option ...
13: ]
14: [
15: .I name ...
16: ]
17: .PP
18: .B mkconv
19: .I makefile
20: .PP
21: .B membername
22: .I aggregate ...
23: .SH DESCRIPTION
24: .I Mk
25: is most often used to keep object files current with the
26: source they depend on.
27: .PP
28: .I Mk
29: reads
30: .I mkfile
31: and builds and executes dependency dags (directed acyclic graphs) for the target
32: .IR names .
33: If no target is specified, the targets of the first non-metarule in
34: the first
35: .I mkfile
36: are used.
37: If no
38: .B -f
39: option is present,
40: .L mkfile
41: is tried.
42: Other options are:
43: .TP \w'\fL-d[egp]\ 'u
44: .B -a
45: Assume all targets to be out of date.
46: Thus, everything gets made.
47: .PD 0
48: .TP
49: .BR -d [ egp ]
50: Produce debugging output
51: .RB ( p
52: is for parsing,
53: .B g
54: for graph building,
55: .B e
56: for execution).
57: .TP
58: .B -e
59: Explain why each target is made.
60: .TP
61: .B -i
62: Force any missing intermediate targets to be made.
63: .TP
64: .B -k
65: Do as much work as possible in the face of errors.
66: .TP
67: .B -n
68: Print, but do not execute, the commands
69: needed to update the targets.
70: .TP
71: .B -t
72: Touch (update the modified date of) non-virtual targets, without
73: executing any recipes.
74: .TP
75: .B -u
76: Produce a table of clock seconds spent with
77: .I n
78: recipes running.
79: .TP
80: .BI -w name1,name2,...
81: Set the initial date stamp for each name
82: to the current time.
83: The names may also be separated by blanks or newlines.
84: (Use with
85: .B -n
86: to find what else would need to change if the named files
87: were modified.)
88: .PD
89: .PP
90: .I Mkconv
91: attempts to convert a
92: .IR make (1)
93: .I makefile
94: to a
95: .IR mkfile
96: on standard output.
97: The conversion is not likely to be faithful.
98: .PP
99: The shell script
100: .I membername
101: extracts member names
102: (see `Aggregates' below)
103: from its arguments.
104: .SS Definitions
105: A
106: .I mkfile
107: consists of
108: .I assignments
109: (described under `Environment') and
110: .IR rules .
111: A rule contains
112: .I targets
113: and a
114: .I tail.
115: A target is a literal string, or
116: .I label,
117: and is normally a file name.
118: The tail contains zero or more
119: .I prerequisites
120: and an optional
121: .I recipe,
122: which is a shell script.
123: .PP
124: A
125: .I metarule
126: has a target of the form
127: .IB A % B
128: where
129: .I A
130: and
131: .I B
132: are (possibly empty) strings.
133: A metarule applies to any label that matches the target with
134: .B %
135: replaced by an arbitrary string, called the
136: .IR stem .
137: In interpreting a metarule,
138: the stem is substituted for all occurrences of
139: .B %
140: in the prerequisite names.
141: A metarule may be marked as using regular expressions (described under `Syntax').
142: In this case,
143: .B %
144: has no special meaning;
145: the target is interpreted according to
146: .IR regexp (3).
147: The dependencies may refer to subexpressions in the normal way, using
148: .BI \e n.
149: The
150: .I dependency dag
151: for a target consists of
152: .I nodes
153: connected by directed
154: .IR arcs .
155: A node consists of a label
156: and a set of arcs leading to prerequisite nodes.
157: The root
158: node is labeled with an original target
159: .I name.
160: .SS Building the Dependency Dag
161: .PP
162: Read the
163: .I mkfiles
164: in command line order and distribute rule tails over targets
165: to get single-target rules.
166: .PP
167: For a node
168: .IR n ,
169: for every rule
170: .I r
171: that matches
172: .IR n 's
173: label generate an arc to a prerequisite node.
174: The node
175: .I n
176: is then marked as done.
177: The process is then repeated for each of the prerequisite nodes.
178: The process stops if
179: .I n
180: is already done,
181: or if
182: .I n
183: has no prerequisites,
184: or if any rule would be used more than
185: .B $NREP
186: times on the current path in the dag.
187: A probable node is one where the label exists as a file
188: or is a target of a non-metarule.
189: .PP
190: After the graph is built, it is checked for cycles,
191: and subdags containing no probable nodes are deleted.
192: Also, for any node with arcs generated by a non-metarule with a recipe,
193: arcs generated by a metarule with a recipe
194: are deleted.
195: Disconnected subdags are deleted.
196: .SS Execution
197: Labels have an associated date stamp.
198: A label is
199: .I ready
200: if it has no prerequisites, or
201: all its prerequisites are made.
202: A ready label is
203: .I trivially uptodate
204: if it is not a target and has a nonzero date stamp, or
205: it has a nonzero date stamp,
206: and all its prerequisites are made and predate the ready label.
207: A ready label is marked
208: .I made
209: (and given a date stamp)
210: if it is trivially uptodate or by executing the recipe
211: associated with the arcs leading from the node associated with the ready label.
212: The
213: .B P
214: attribute can be used to generalize
215: .IR mk 's
216: notion of determining if prerequisites predate a label.
217: Rather than comparing date stamps, it executes a specified program
218: and uses the exit status.
219: .PP
220: Date stamps are calculated differently for virtual labels,
221: for labels that correspond to extant files,
222: and for other labels.
223: If a label is
224: .I virtual
225: (target of a rule with the
226: .B V
227: attribute),
228: its date stamp is initially zero and upon being made is set to
229: the most recent date stamp of its prerequisites.
230: Otherwise, if a label is nonexistent
231: (does not exist as a file),
232: its date stamp is set to the most recent date stamp of its prerequisites,
233: or zero if it has no prerequisites.
234: Otherwise, the label is the name of a file and
235: the label's date stamp is always that file's modification date.
236: .PP
237: Nonexistent labels which have prerequisites
238: and are prerequisite to other label(s) are treated specially unless the
239: .B -i
240: flag is used.
241: Such a label
242: .I l
243: is given the date stamp of its most recent prerequisite
244: and if this causes all the labels which have
245: .I l
246: as a prerequisite to be trivially uptodate,
247: .I l
248: is considered to be trivially uptodate.
249: Otherwise,
250: .I l
251: is made in the normal fashion.
252: .PP
253: Two recipes are called identical if they arose by distribution
254: from a single rule as described above.
255: Identical recipes may be executed only when all
256: their prerequisite nodes are ready, and then just one instance of
257: the identical recipes is executed to make all their target nodes.
258: .PP
259: Files may be made in any order that respects
260: the preceding restrictions.
261: .PP
262: A recipe is executed by supplying the recipe as standard input to
263: the command
264: .B
265: /bin/sh -e
266: .br
267: The environment is augmented by the following variables:
268: .TP 14
269: .B $alltarget
270: all the targets of this rule.
271: .TP
272: .B $newprereq
273: the prerequisites that caused this rule to execute.
274: .TP
275: .B $nproc
276: the process slot for this recipe.
277: It satisfies
278: .RB 0\(<= $nproc < $NPROC ,
279: where
280: .B $NPROC
281: is the maximum number of recipes that may be executing
282: simultaneously.
283: .TP
284: .B $pid
285: the process id for the
286: .I mk
287: forking the recipe.
288: .TP
289: .B $prereq
290: all the prerequisites for this rule.
291: .TP
292: .B $stem
293: if this is a metarule,
294: .B $stem
295: is the string that matched
296: .BR % .
297: Otherwise, it is empty.
298: For regular expression metarules, the variables
299: .LR stem0 ", ...,"
300: .L stem9
301: are set to the corresponding subexpressions.
302: .TP
303: .B $target
304: the targets for this rule that need to be remade.
305: .PP
306: Unless the rule has the
307: .B Q
308: attribute,
309: the recipe is printed prior to execution
310: with recognizable shell variables expanded.
311: To see the commands print as they execute,
312: include a
313: .L set -x
314: in your rule.
315: Commands returning nonzero status (see
316: .IR intro (1))
317: cause
318: .I mk
319: to terminate.
320: .SS Aggregates
321: Names of the form
322: .IR a ( b )
323: refer to member
324: .I b
325: of the aggregate
326: .IR a .
327: Currently, the only aggregates supported are
328: .IR ar (1)
329: archives.
330: .SS Environment
331: Rules may make use of shell (or environment) variables.
332: A legal shell variable reference of the form
333: .B $OBJ
334: or
335: .B ${name}
336: is expanded as in
337: .IR sh (1).
338: A reference of the form
339: .BI ${name: A % B = C\fB%\fID\fB}\fR,
340: where
341: .I A, B, C, D
342: are (possibly empty) strings,
343: has the value formed by expanding
344: .B $name
345: and substituting
346: .I C
347: for
348: .I A
349: and
350: .I D
351: for
352: .I B
353: in each word in
354: .B $name
355: that matches pattern
356: .IB A % B .
357: .PP
358: Variables can be set by
359: assignments of the form
360: .I
361: var\fB=\fR[\fIattr\fB=\fR]\fItokens\fR
362: .br
363: where
364: .I tokens
365: and the optional attributes
366: are defined under `Syntax' below.
367: The environment is exported to recipe executions.
368: Variable values are taken from (in increasing order of precedence)
369: the default values below, the environment, the mkfiles,
370: and any command line assignment.
371: A variable assignment argument overrides the first (but not any subsequent)
372: assignment to that variable.
373: .br
374: .ne 1i
375: .EX
376: .ta \n(.lu/3u +\n(.lu/3u
377: .nf
378: AS=as FFLAGS= NPROC=1
379: CC=cc LEX=lex NREP=1
380: CFLAGS= LFLAGS= YACC=yacc
381: FC=f77 LDFLAGS= YFLAGS=
382: BUILTINS='
383: .ta 8n
384: %.o: %.c
385: $CC $CFLAGS -c $stem.c
386: %.o: %.s
387: $AS -o $stem.o $stem.s
388: %.o: %.f
389: $FC $FFLAGS -c $stem.f
390: %.o: %.y
391: $YACC $YFLAGS $stem.y &&
392: $CC $CFLAGS -c y.tab.c && mv y.tab.o $stem.o; rm y.tab.c
393: %.o: %.l
394: $LEX $LFLAGS -t $stem.l > $stem.c &&
395: $CC $CFLAGS -c $stem.c && rm $stem.c'
396: ENVIRON=
397: .EE
398: .PP
399: The builtin rules are obtained from the variable
400: .B BUILTINS
401: after all input has been processed.
402: The
403: .B ENVIRON
404: variable is split into parts at control-A characters,
405: the control-A characters are deleted, and the parts are
406: placed in the environment.
407: The variable
408: .B MKFLAGS
409: contains all the option arguments (arguments starting with
410: .L -
411: or containing
412: .LR = )
413: and
414: .B MKARGS
415: contains all the targets in the call to
416: .IR mk .
417: .SS Syntax
418: Leading white space (blank or tab) is ignored.
419: Input after an unquoted
420: .B #
421: (a comment) is ignored as are blank lines.
422: Lines can be spread over several physical lines by
423: placing a
424: .B \e
425: before newlines to be elided.
426: Non-recipe lines are processed by substituting for
427: .BI ` cmd `
428: and then substituting for variable references.
429: Finally, the filename metacharacters
430: .B []*?
431: are expanded.
432: .tr #"
433: Quoting by
434: .BR \&'' ,
435: .BR ## ,
436: and
437: .B \e
438: is supported.
439: The semantics for substitution and quoting are given in
440: .IR sh (1).
441: .PP
442: The contents of files may be included by lines beginning with
443: .B <
444: followed by a filename.
445: .PP
446: .tr ##
447: Assignments and rule header lines are distinguished by
448: the first unquoted occurrence of
449: .B :
450: (rule header)
451: or
452: .B =
453: (assignment).
454: .PP
455: A rule definition consists of a header line followed by a recipe.
456: The recipe consists of all lines following the header line
457: that start with white space.
458: The recipe may be empty.
459: The first character on every line of the recipe is elided.
460: The header line consists of at least one target followed by the rule separator
461: and a possibly empty list of prerequisites.
462: The rule separator is either a single
463: .LR :
464: or is a
465: .L :
466: immediately followed by attributes and another
467: .LR : .
468: If any prerequisite is more recent than any of the targets,
469: the recipe is executed.
470: This meaning is modified by the following attributes
471: .TP
472: .B <
473: The standard output of the recipe is read by
474: .I mk
475: as an additional mkfile.
476: Assignments take effect immediately.
477: Rule definitions are used when a new dependency dag is constructed.
478: .PD 0
479: .TP
480: .B D
481: If the recipe exits with an error status, the target is deleted.
482: .TP
483: .B N
484: If there is no recipe, the target has its time updated.
485: .TP
486: .B P
487: The characters after the
488: .B P
489: until the terminating
490: .B :
491: are taken as a program name.
492: It will be invoked as
493: .B "sh -c prog 'arg1' 'arg2'"
494: and should return 0 exit status
495: if and only if arg1 is not out of date with respect to arg2.
496: Date stamps are still propagated in the normal way.
497: .TP
498: .B Q
499: The recipe is not printed prior to execution.
500: .TP
501: .B R
502: The rule is a metarule using regular expressions.
503: .TP
504: .B U
505: The targets are considered to have been updated
506: even if the recipe did not do so.
507: .TP
508: .B V
509: The targets of this rule are marked as virtual.
510: They are distinct from files of the same name.
511: .PD
512: .PP
513: Similarly, assignments may have attributes terminated by
514: .BR = .
515: The only assignment attribute is
516: .TP 3
517: .B U
518: Do not export this variable to recipe executions.
519: .SH EXAMPLES
520: A simple mkfile to compile a program.
521: .IP
522: .EX
523: prog: a.o b.o c.o
524: $CC $CFLAGS -o $target $prereq
525: .EE
526: .PP
527: Override flag settings in the mkfile.
528: .IP
529: .EX
530: $ mk target CFLAGS='-O -s'
531: .EE
532: .PP
533: To get the prerequisites for an aggregate.
534: .IP
535: .EX
536: $ membername 'libc.a(read.o)' 'libc.a(write.o)'
537: read.o write.o
538: .EE
539: .PP
540: Maintain a library.
541: .IP
542: .EX
543: libc.a(%.o):N: %.o
544: libc.a: libc.a(abs.o) libc.a(access.o) libc.a(alarm.o) ...
545: names=`membername $newprereq`
546: ar r libc.a $names && rm $names
547: .EE
548: .PP
549: Backquotes used to derive a list from a master list.
550: .IP
551: .EX
552: NAMES=alloc arc bquote builtins expand main match mk var word
553: OBJ=`echo $NAMES|sed -e 's/[^ ][^ ]*/&.o/g'`
554: .EE
555: .PP
556: Regular expression metarules.
557: The single quotes are needed to protect the
558: .BR \e s.
559: .IP
560: .EX
561: \&'([^/]*)/(.*)\e.o':R: '\e1/\e2.c'
562: cd $stem1; $CC $CFLAGS -c $stem2.c
563: .EE
564: .PP
565: A correct way to deal with
566: .IR yacc (1)
567: grammars.
568: The file
569: .B lex.c
570: includes the file
571: .B x.tab.h
572: rather than
573: .B y.tab.h
574: in order to reflect changes in content, not just modification time.
575: .IP
576: .EX
577: YFLAGS=-d
578: lex.o: x.tab.h
579: x.tab.h: y.tab.h
580: cmp -s x.tab.h y.tab.h || cp y.tab.h x.tab.h
581: y.tab.c y.tab.h: gram.y
582: $YACC $YFLAGS gram.y
583: .EE
584: .PP
585: The above example could also use the
586: .B P
587: attribute for the
588: .B x.tab.h
589: rule:
590: .IP
591: .EX
592: x.tab.h:Pcmp -s: y.tab.h
593: cp y.tab.h x.tab.h
594: .EE
595: .SH SEE ALSO
596: .IR make (1),
597: .IR chdate (1),
598: .IR sh (1),
599: .IR regexp (3)
600: .br
601: A. Hume,
602: .RI ` Mk :
603: a Successor to
604: .IR Make ',
605: this manual, Volume 2
606: .SH BUGS
607: Identical recipes for regular expression metarules only have one target.
608: .br
609: Seemingly appropriate input like
610: .B CFLAGS=-DHZ=60
611: is parsed as an erroneous attribute; correct it by inserting
612: a space after the first
613: .LR = .
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.