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