mk(1) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man1/mk.html | 621 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 621 insertions(+) create mode 100644 man/man1/mk.html (limited to 'man/man1/mk.html') diff --git a/man/man1/mk.html b/man/man1/mk.html new file mode 100644 index 00000000..3dde6143 --- /dev/null +++ b/man/man1/mk.html @@ -0,0 +1,621 @@ + +mk(1) - Plan 9 from User Space + + + + +

MK(1) MK(1) +

+
+

NAME
+ +
+ + mk – maintain (make) related files
+ +
+

SYNOPSIS
+ +
+ + mk [ −f mkfile ] ... [ option ... ] [ target ... ]
+ +
+

DESCRIPTION
+ +
+ + Mk uses the dependency rules specified in mkfile to control the + update (usually by compilation) of targets (usually files) from + the source files upon which they depend. The mkfile (default mkfile) + contains a rule for each target that identifies the files and + other targets upon which it depends and an sh(1) script, a + recipe, to update the target. The script is run if the target + does not exist or if it is older than any of the files it depends + on. Mkfile may also contain meta-rules that define actions for + updating implicit targets. If no target is specified, the target + of the first rule (not meta-rule) in mkfile is updated. +
+ + The environment variable $NPROC determines how many targets may + be updated simultaneously; Some operating systems, e.g., Plan + 9, set $NPROC automatically to the number of CPUs on the current + machine. +
+ + Options are:
+ −a       Assume all targets to be out of date. Thus, everything is updated.
+ −d[egp]   Produce debugging output (p is for parsing, g for graph + building, e for execution).
+ −e       Explain why each target is made.
+ −i       Force any missing intermediate targets to be made.
+ −k       Do as much work as possible in the face of errors.
+ −n       Print, but do not execute, the commands needed to update the + targets.
+ −s       Make the command line arguments sequentially rather than in + parallel.
+ −t       Touch (update the modified date of) file targets, without executing + any recipes.
+ −wtarget1,target2,...
+ +
+ + +
+ + Pretend the modify time for each target is the current time; useful + in conjunction with −n to learn what updates would be triggered + by modifying the targets.
+ +
+ +
+
The mkfile
+ A mkfile consists of assignments (described under ‘Environment’) + and rules. A rule contains targets and a tail. A target is a literal + string and is normally a file name. The tail contains zero or + more prerequisites and an optional recipe, which is an shell script. + Each line of the recipe must begin with white space. A rule + takes the form
+ +
+ + target: prereq1 prereq2 + +
+ + recipe using prereq1, prereq2 to build target + + + + +
+ +
+ When the recipe is executed, the first character on every line + is elided. +
+ + After the colon on the target line, a rule may specify attributes, + described below. +
+ + A meta-rule has a target of the form A%B where A and B are (possibly + empty) strings. A meta-rule acts as a rule for any potential target + whose name matches A%B with % replaced by an arbitrary string, + called the stem. In interpreting a meta-rule, the stem is substituted + for all occurrences of % in the prerequisite + names. In the recipe of a meta-rule, the environment variable + $stem contains the string matched by the %. For example, a meta-rule + to compile a C program using 9c(1) might be:
+ +
+ + %:      %.c + + + + 9c −c $stem.c + 9l −o $stem $stem.o + + + + + +
+ + + +
+ +
+ Meta-rules may contain an ampersand & rather than a percent sign + %. A % matches a maximal length string of any characters; an & + matches a maximal length string of any characters except period + or slash. +
+ + The text of the mkfile is processed as follows. Lines beginning + with < followed by a file name are replaced by the contents of + the named file. Lines beginning with <| followed by a file name + are replaced by the output of the execution of the named file. + Blank lines and comments, which run from unquoted # characters + to the following newline, are deleted. The character sequence + backslash-newline is deleted, so long lines in mkfile may be folded. + Non-recipe lines are processed by substituting for `{command} + the output of the command when run by sh. References to variables + are replaced by the variables’ values. Special + characters may be quoted using single quotes '' as in sh(1). +
+ + Assignments and rules are distinguished by the first unquoted + occurrence of : (rule) or = (assignment). +
+ + A later rule may modify or override an existing rule under the + following conditions:
+ –     If the targets of the rules exactly match and one rule contains + only a prerequisite clause and no recipe, the clause is added + to the prerequisites of the other rule. If either or both targets + are virtual, the recipe is always executed.
+ –     If the targets of the rules match exactly and the prerequisites + do not match and both rules contain recipes, mk reports an “ambiguous + recipe” error.
+ –     If the target and prerequisites of both rules match exactly, the + second rule overrides the first.
+
Environment
+ Rules may make use of shell environment variables. A legal reference + of the form $OBJ or ${name} is expanded as in sh(1). A reference + of the form ${name:A%B=C%D}, where A, B, C, D are (possibly empty) + strings, has the value formed by expanding $name and substituting + C for A and D for B in each word in + $name that matches pattern A%B. +
+ + Variables can be set by assignments of the form
+ +
+ + var=[attr=]value
+ +
+ Blanks in the value break it into words. Such variables are exported + to the environment of recipes as they are executed, unless U, + the only legal attribute attr, is present. The initial value of + a variable is taken from (in increasing order of precedence) the + default values below, mk’s environment, the mkfiles, and any + command line assignment as an argument to mk. A variable assignment + argument overrides the first (but not any subsequent) assignment + to that variable. +
+ + The variable MKFLAGS contains all the option arguments (arguments + starting with − or containing =) and MKARGS contains all the targets + in the call to mk. +
+ + The variable MKSHELL contains the shell command line mk uses to + run recipes. If the first word of the command ends in rc or rcsh, + mk uses rc(1)’s quoting rules; otherwise it uses sh(1)’s. The + MKSHELL variable is consulted when the mkfile is read, not when + it is executed, so that different shells can be used within + a single mkfile:
+ +
+ + MKSHELL=$PLAN9/bin/rc + use−rc:V: + + + + for(i in a b c) echo $i + + + MKSHELL=sh + use−sh:V: + + + + for i in a b c; do echo $i; done + + + + + +
+ + + +
+ +
+ Mkfiles included via < or <| (q.v.) see their own private copy of + MKSHELL, which always starts set to sh . + + + Dynamic information may be included in the mkfile by using a line + of the form
+ +
+ + <|command args +
+ + +
+ This runs the command command with the given arguments args and + pipes its standard output to mk to be included as part of the + mkfile. For instance, the Inferno kernels use this technique to + run a shell command with an awk script and a configuration file + as arguments in order for the awk script to process the file + and output a set of variables and their values.
+
Execution
+ +
+ + During execution, mk determines which targets must be updated, + and in what order, to build the names specified on the command + line. It then runs the associated recipes. +
+ + A target is considered up to date if it has no prerequisites or + if all its prerequisites are up to date and it is newer than all + its prerequisites. Once the recipe for a target has executed, + the target is considered up to date. +
+ + The date stamp used to determine if a target is up to date is + computed differently for different types of targets. If a target + is virtual (the target of a rule with the V attribute), its date + stamp is initially zero; when the target is updated the date stamp + is set to the most recent date stamp of its prerequisites. Otherwise, + if a + target does not exist as a file, its date stamp is set to the + most recent date stamp of its prerequisites, or zero if it has + no prerequisites. Otherwise, the target is the name of a file + and the target’s date stamp is always that file’s modification + date. The date stamp is computed when the target is needed in + the execution of + a rule; it is not a static value. +
+ + Nonexistent targets that have prerequisites and are themselves + prerequisites are treated specially. Such a target t is given + the date stamp of its most recent prerequisite and if this causes + all the targets which have t as a prerequisite to be up to date, + t is considered up to date. Otherwise, t is made in the normal + fashion. + The −i flag overrides this special treatment. +
+ + Files may be made in any order that respects the preceding restrictions. + +
+ + A recipe is executed by supplying the recipe as standard input + to the command /bin/sh. (Note that unlike make, mk feeds the entire + recipe to the shell rather than running each line of the recipe + separately.) The environment is augmented by the following variables:
+ $alltarget + +
+ + +
+ + all the targets of this rule.
+ +
+ +
+ $newprereq + +
+ + +
+ + the prerequisites that caused this rule to execute.
+ +
+ +
+ $newmember + +
+ + +
+ + the prerequisites that are members of an aggregate that caused + this rule to execute. When the prerequisites of a rule are members + of an aggregate, $newprereq contains the name of the aggregate + and out of date members, while $newmember contains only the name + of the members. + +
+ +
+ $nproc     the process slot for this recipe. It satisfies 0≤$nproc<$NPROC.
+ $pid       the process id for the mk executing the recipe.
+ $prereq    all the prerequisites for this rule.
+ $stem      if this is a meta-rule, $stem is the string that matched + % or &. Otherwise, it is empty. For regular expression meta-rules + (see below), the variables stem0, ..., stem9 are set to the corresponding + subexpressions.
+ $target    the targets for this rule that need to be remade. +
+ + These variables are available only during the execution of a recipe, + not while evaluating the mkfile. +
+ + Unless the rule has the Q attribute, the recipe is printed prior + to execution with recognizable environment variables expanded. + Commands returning error status cause mk to terminate. +
+ + Recipes and backquoted rc commands in places such as assignments + execute in a copy of mk’s environment; changes they make to environment + variables are not visible from mk. +
+ + Variable substitution in a rule is done when the rule is read; + variable substitution in the recipe is done when the recipe is + executed. For example:
+ +
+ + bar=a.c + foo: $bar + + + + $CC −o foo $bar + + + bar=b.c + + + + +
+ will compile b.c into foo, if a.c is newer than foo.
+
Aggregates
+ Names of the form a(b) refer to member b of the aggregate a. Currently, + the only aggregates supported are 9ar (see 9c(1)) archives.
+
Attributes
+ The colon separating the target from the prerequisites may be + immediately followed by attributes and another colon. The attributes + are:
+ D     If the recipe exits with a non-null status, the target is deleted.
+ E     Continue execution if the recipe draws errors.
+ N     If there is no recipe, the target has its time updated.
+ n     The rule is a meta-rule that cannot be a target of a virtual + rule. Only files match the pattern in the target.
+ P     The characters after the P until the terminating : are taken + as a program name. It will be invoked as sh −c prog 'arg1' 'arg2' + and should return a zero exit status if and only if arg1 is up + to date with respect to arg2. Date stamps are still propagated + in the normal way.
+ Q     The recipe is not printed prior to execution.
+ R     The rule is a meta-rule using regular expressions. In the rule, + % has no special meaning. The target is interpreted as a regular + expression as defined in regexp(7). The prerequisites may contain + references to subexpressions in form \n, as in the substitute + command of sed(1).
+ U     The targets are considered to have been updated even if the recipe + did not do so.
+ V     The targets of this rule are marked as virtual. They are distinct + from files of the same name.
+ +
+

EXAMPLES
+ +
+ + A simple mkfile to compile a program:
+ +
+ + </$objtype/mkfile + prog: a.$O b.$O c.$O + + + + $LD $LDFLAGS −o $target $prereq + + + %.$O: %.c + + + + $CC $CFLAGS $stem.c + + + + + +
+ + + +
+ +
+ Override flag settings in the mkfile:
+ +
+ + % mk target 'CFLAGS=−S −w' + + + + +
+ Maintain a library:
+ +
+ + libc.a(%.$O):N:    %.$O + libc.a:      libc.a(abs.$O) libc.a(access.$O) libc.a(alarm.$O) ... + + + + ar r libc.a $newmember + + + + + +
+ + + +
+ +
+ String expression variables to derive names from a master list:
+ +
+ + NAMES=alloc arc bquote builtins expand main match mk var word + OBJ=${NAMES:%=%.$O} + + + + +
+ Regular expression meta-rules:
+ +
+ + ([^/]*)/(.*)\.$O:R:    \1/\2.c + + + + cd $stem1; $CC $CFLAGS $stem2.c + + + + + +
+ + + +
+ +
+ A correct way to deal with yacc(1) grammars. The file lex.c includes + the file x.tab.h rather than y.tab.h in order to reflect changes + in content, not just modification time.
+ +
+ + lex.$O:      x.tab.h + x.tab.h:     y.tab.h + + + + cmp −s x.tab.h y.tab.h || cp y.tab.h x.tab.h + + + y.tab.c y.tab.h: gram.y + + + + $YACC −d gram.y + + + + + +
+ + + +
+ +
+ The above example could also use the P attribute for the x.tab.h + rule:
+ +
+ + x.tab.h:Pcmp −s: y.tab.h + + + + cp y.tab.h x.tab.h + + + +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/cmd/mk + +
+

SEE ALSO
+ +
+ + sh(1), regexp(7) +
+ + A. Hume, “Mk: a Successor to Make” (Tenth Edition Research Unix + Manuals). +
+ + Andrew G. Hume and Bob Flandrena, “Maintaining Files on Plan 9 + with Mk”. DOCPREFIX/doc/mk.pdf
+ +
+

HISTORY
+ +
+ + Andrew Hume wrote mk for Tenth Edition Research Unix. It was later + ported to Plan 9. This software is a port of the Plan 9 version + back to Unix.
+ +
+

BUGS
+ +
+ + Identical recipes for regular expression meta-rules only have + one target. +
+ + Seemingly appropriate input like CFLAGS=−DHZ=60 is parsed as an + erroneous attribute; correct it by inserting a space after the + first =. +
+ + The recipes printed by mk before being passed to the shell for + execution are sometimes erroneously expanded for printing. Don’t + trust what’s printed; rely on what the shell does.
+ +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3