dist-3.0at70b/jmake/NOTES

   1 The syntax in Jmake.rules is not elegant at all, but:
   2
   3         - It is easy to parse (like sendmail.cf or troff files).
   4         - The rules are not supposed to change very often.
   5         - It is simple enough to be mastered in five minutes. :-)
   6
   7 Here is a small description:
   8
   9 o To deal with various cpp implementations:
  10
  11 Final @!\ means: end of line, next line starts at the left margin.
  12 Final @@\ means: end of line, next line is to be indented by one tab.
  13
  14 The conversion occurs during Pass1.
  15
  16
  17 o Symbol definitions
  18
  19 >SYMBOL: defines the symbol (Pass 1).
  20 ?SYMBOL:<text>: keeps <text> iff SYMBOL is defined (Pass 2).
  21 %SYMBOL:<text>: keeps <text> iff SYMBOL is not defined (Pass 2).
  22
  23 The ?SYM can be nested (logical AND), as in:
  24
  25         ?SYMBOL:%TOKEN:text             /* Keeps text if SYMBOL and not TOKEN */
  26
  27 To implement a logical OR, see below.
  28
  29
  30 o Commands
  31
  32 Commands can be passed to 'jmake'. They start with a leading '|'.
  33
  34 Available commands are:
  35
  36 |suffix <sx>: adds <sx> to the .SUFFIXES: list in the makefile (Pass 1 & 2).
  37 |rule:<text>: adds <text> to the building rule section (Pass 1 & 2).
  38 |rule: <text>: same as before, with a leading tab.
  39 |skip: skips text until a line starting with '-skip' is found (Pass 2).
  40 |expand <pattern>: expand lines until '-expand' with <pattern> (Pass 2).
  41 |once <symbol>: text up to '-once' appears only the first time (Pass 1).
  42
  43 Thus, a way to implement a logical OR could be:
  44
  45         /* Implements SYMBOL or not TOKEN */
  46         ?SYMBOL:text                    /* Keeps text if SYMBOL */
  47         %SYMBOL:|skip
  48                 %TOKEN:text                     /* Keeps text if not TOKEN */
  49         -skip
  50
  51 Actually, this is ugly, because the text has to appear twice.
  52 Fortunately, I did not use it. :-)
  53
  54 The '|' commands cannot be nested. In particular, due to the simple
  55 implementation of '|skip', it is impossible to put '|skip' inside
  56 a skipped part. However, a '|once' section may have '|skip' sections.
  57
  58 But actually, as you have surely already guessed, the best way to
  59 implement a logical OR is to use De Morgan's Law:
  60
  61         not (p or q) <=> not p and not q
  62
  63         /* Implements SYMBOL or not TOKEN (attempt #2) */
  64         %SYMBOL:?TOKEN:|skip
  65         text                                    /* If SYMBOL or not TOKEN */
  66         -skip
  67
  68 Who said they don't care ? ;-)
  69
  70 o Expansion
  71
  72 Expansion is done with the 'expand' command.  It has been provided to
  73 avoid some cumbersome writings in makefiles when you have to repeat some
  74 silly lines that only differ in file names, for instance.  Let's look at
  75 an example first:
  76
  77         |expand a!foo bar! b!yes no!
  78         !a::
  79                 echo !a, !b
  80         -expand
  81
  82 Then two rules will be printed, and the values of (a,b) for the first
  83 will be (foo, yes), for the second (bar, no).  Substitution is controled
  84 by the '!' character.  If the word to be substituted is part of another
  85 one, detach with the ^^ construct as in:  !b^^c.  It is possible to
  86 use Makefile macros in the <pattern>, and they will be expanded by
  87 jmake.  If this is not what you want, escape the first '$' sign (this is
  88 a Makefile escape, i.e. you must double the '$', not precede it with a
  89 backslash). A // stands for the null substitution value.
  90
  91 Here is another example which shows how the macro Expand can be used.
  92 It is defined in Jmake.rules as:
  93
  94         #define Expand(rule, pattern) @!\
  95         |expand pattern @!\
  96         rule @!\
  97         -expand
  98
  99 So we can write in the Jmakefile:
 100
 101         |skip
 102         A = foo bar
 103         -skip
 104
 105         #define Rule @!\
 106         $(DIR)/!a^^.o: !a^^.o @@\
 107                 $(CC) -c !a^^.c @@\
 108                 $(MV) !a^^.o $(DIR)
 109
 110         Expand(Rule, a!$(A)!)
 111
 112 which will generate in Makefile.SH:
 113
 114         $(DIR)/foo.o: foo.o
 115                 $(CC) -c foo.c
 116                 $(MV) foo.o $(DIR)
 117
 118         $(DIR)/bar.o: bar.o
 119                 $(CC) -c bar.c
 120                 $(MV) bar.o $$(DIR)
 121
 122 The 'A' declaration has been surrounded by skip, so that it does
 123 not appear in the generated Makefile.SH, but it will be taken into
 124 account by jmake for the substitution in the pattern.
 125
 126 The number of expansions is determined by the number of possible
 127 values for the _first_ parameter. If other parameters have less
 128 substitution values, they will get void ones.
 129
 130 It is possible to add a regular expression at the end of '-expand'.
 131 This regular expression will be removed from the final set of expansion
 132 at the end of each line.  It is also possible to do substitutions in the
 133 expanded item, by using the syntax (if 'f' is the expanded variable)
 134 !f:<p>=<q> where <p> and <q> are two regular expressions (without
 135 spaces).  The pattern <p> will be replaced by pattern <q> (only the
 136 first occurrence will be replaced).
 137
 138 Finally, you may refer in the expanded section to variables whose value
 139 is computed via another expansion, which makes it easy to define generic
 140 Jmakefiles.
 141
 142 Example:
 143
 144         SRC = foo.c bar.c
 145         OBJ = \
 146         |expand f!$(SRC)!
 147                 !f:\.c=\.o \
 148         -expand \\
 149         INC = \
 150         |expand f!$(OBJ)!
 151                 !f:\.o=\.h \
 152         -expand \\
 153
 154 which will generate in Makefile.SH:
 155
 156         SRC = foo.c bar.c
 157         OBJ = \
 158                 foo.o \
 159                 bar.o
 160         INC = \
 161                 foo.h \
 162                 bar.h
 163
 164 Do not forget to protect special characters in your regular expressions such
 165 as backslash, point, etc...
 166
 167 o Once
 168
 169 The once command is tagged with a name. The first time the name appears,
 170 the once construct is ignored and the text up to '-once' will be copied
 171 in the generated Makefile.SH.  However, future occurences of the same
 172 name will be ignored (once will behave like skip).
 173
 174 Example:
 175
 176         |once this_is_a_name
 177         <text>
 178         -once
 179
 180 o Initializations
 181
 182 +<line>: Puts the whole line in the initialization section (Pass 1 & 2).
 183 ++SYMBOL <value>: Adds <value> to the SYMBOL macro (Pass 1 and 2).
 184
 185 o User-defined variables
 186
 187 CFLAGS: added flags to C compiler
 188 DPFLAGS: cpp flags to be added to mkdep for dependency
 189 LDFLAGS: flags/libraries to be added at linking stage