Return to mk CVS log

Up to [Plan 9 NeXT] / lucent / sys / man / 1

Annotation of lucent/sys/man/1/mk, revision 1.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.