dist-3.0at70/jmake/jmake.man

   1 ''' $Id: jmake.man,v 3.0.1.1 1995/05/12 11:57:58 ram Exp $
   2 '''
   3 '''  Copyright (c) 1991-1993, Raphael Manfredi
   4 '''
   5 '''  You may redistribute only under the terms of the Artistic Licence,
   6 '''  as specified in the README file that comes with the distribution.
   7 '''  You may reuse parts of this distribution only within the terms of
   8 '''  that same Artistic Licence; a copy of which may be found at the root
   9 '''  of the source tree for dist 3.0.
  10 '''
  11 ''' $Log: jmake.man,v $
  12 ''' Revision 3.0.1.1  1995/05/12  11:57:58  ram
  13 ''' patch54: updated my e-mail address
  14 '''
  15 ''' Revision 3.0  1993/08/18  12:04:18  ram
  16 ''' Baseline for dist 3.0 netwide release.
  17 '''
  18 .TH JMAKE 1 ram
  19 .SH NAME
  20 jmake \- a generic makefile builder
  21 .SH SYNOPSIS
  22 .B jmake
  23 [
  24 .I cpp options
  25 ]
  26 .SH DESCRIPTION
  27 .I Jmake
  28 builds a makefile out of a rather high level description held in a
  29 .I Jmakefile
  30 file. The generated file is a
  31 .I Makefile.SH
  32 rather than a simple makefile, which means it is ready to be used in
  33 conjonction with
  34 .I metaconfig.
  35 In particular, parameters such as "where to install executables" will
  36 be automatically determined by
  37 .I Configure
  38 and only the needed parameters will be taken into account.
  39 .PP
  40 To use
  41 .I jmake
  42 you have to write a
  43 .I Jmakefile
  44 first, which describes the way things are to be built. Your
  45 .I Jmakefile
  46 will be included inside a generic template through the C pre-processor.
  47 This means you may use the usual C /**/ comments, but not the shell # comments.
  48 The C comments will not appear in the generated
  49 .I Makefile.SH
  50 but lines starting with ;# will finally appear as shell comments. If you
  51 have to write the string /* in the generated
  52 .I Makefile.SH
  53 then you have to escape it (otherwise
  54 .I jmake
  55 will think of it as the start of a C comment). Simply put a # in front
  56 of the *, as in /#*.
  57 .PP
  58 You have a set of macros at your disposal, and all these macros are
  59 listed in the Index file, along with the piece of code they will
  60 expand to. Usually, a
  61 .I Jmakefile
  62 is fairly small and thus easier to maintain than a huge
  63 .I Makefile.
  64 Some internal powerful commands allow you to write
  65 portable makefiles easily, without having to spend many efforts, because
  66 someone else already did the job for you :-).
  67 .PP
  68 When you want to generate your makefile, you usually do not run
  69 .I jmake
  70 but use the
  71 .I jmkmf
  72 script which is a wrapper and will invoke
  73 .I jmake
  74 with the correct options.
  75 .PP
  76 All the knowledge of
  77 .I jmake
  78 is held in two files: the template
  79 .I Jmake.tmpl
  80 and the macro definition file
  81 .I Jmake.rules.
  82 The first file includes the second, along with the
  83 .I Jmakefile.
  84 It is sometimes necessary to know how things works to be able to correctly
  85 use all the features provided. For instance, you may have to write your
  86 own rules for a specific project. Although you cannot overwrite the
  87 predefined rules, you can extent the
  88 .I Jmake.rules
  89 file or simply add your macros in your
  90 .I Jmakefile.
  91 You may also use
  92 .I #include
  93 statements when you want to share these macros and do not want to duplicate
  94 the code.
  95 .PP
  96 The syntax in Jmake.rules is not elegant at all, but:
  97 .sp
  98 .PD 0
  99 .IP -
 100 It is easy to parse (like sendmail.cf or troff files).
 101 .IP -
 102 The rules are not supposed to change very often.
 103 .IP -
 104 It is simple enough to be mastered in five minutes. :-)
 105 .sp
 106 Here is a small description:
 107 .sp
 108 .IP 1)
 109 To deal with various \fIcpp\fR implementations:
 110 .sp
 111 .RS
 112 .IP \(bu
 113 Final @!\\ means: end of line, next line starts at the left margin.
 114 .IP \(bu
 115 Final @@\\ means: end of line, next line is to be indented by one tab.
 116 .sp
 117 .PP
 118 There should always be one of @!\\ or @@\\ at the end of each line.
 119 The only exception is for macros that are to be used as part of a
 120 rule body (e.g. \fIRemoveTargetProgram\fR). In that case, the first
 121 line (which holds the \fI#define\fR) should end with a single backslash.
 122 .RE
 123 .sp
 124 .IP 2)
 125 Symbol definitions:
 126 .sp
 127 .RS
 128 .IP \(bu
 129 >SYMBOL: defines the symbol.
 130 .IP \(bu
 131 ?SYMBOL:<text>: keeps <text> iff SYMBOL is defined.
 132 .IP \(bu
 133 %SYMBOL:<text>: keeps <text> iff SYMBOL is not defined.
 134 .sp
 135 .PP
 136 The ?SYM can be nested (logical AND), as in:
 137 .sp
 138 .in +5
 139 ?SYMBOL:%TOKEN:text
 140 .in -5
 141 .sp
 142 which will keep text if SYMBOL is defined and TOKEN undefined.
 143 To implement a logical OR, see below.
 144 .RE
 145 .sp
 146 .IP 3)
 147 Commands:
 148 .sp
 149 .RS
 150 Commands can be passed to \fIjmake\fR. They start with a leading '|'.
 151 Available commands are:
 152 .sp
 153 .IP \(bu
 154 |suffix <sx>: adds <sx> to the .SUFFIXES: list in the makefile.
 155 .IP \(bu
 156 |rule:<text>: adds <text> to the building rule section.
 157 .IP \(bu
 158 |rule: <text>: same as before, with a leading tab.
 159 .IP \(bu
 160 |skip: skips text until a line starting with '-skip' is found.
 161 .IP \(bu
 162 |expand <pattern>: expand lines until '-expand' with <pattern>. A
 163 complete example is shown below.
 164 .IP \(bu
 165 |once <symbol>: text up to '-once' appears only the first time.
 166 .sp
 167 .PP
 168 Here is a way to implement a logical OR:
 169 .sp
 170 .in +5
 171 .nf
 172 /* Implements SYMBOL or not TOKEN */
 173 ?SYMBOL:text            /* Keeps text if SYMBOL */
 174 %SYMBOL:|skip
 175         %TOKEN:text             /* Keeps text if not TOKEN */
 176 -skip
 177 .fi
 178 .in -5
 179 .sp
 180 Actually, this is ugly, because the text has to appear twice.
 181 Fortunately, I did not use it. :-)
 182 .sp
 183 .PP
 184 The '|' commands cannot be nested. In particular, due to the simple
 185 implementation of \fI|skip\fR, it is impossible to put \fI|skip\fR inside
 186 a skipped part. However, a \fI|once\fR section may have \fI|skip\fR sections.
 187 .sp
 188 But actually, as you have surely already guessed, the best way to
 189 implement a logical OR is to use De Morgan's Law:
 190 .sp
 191 .in +5
 192 .nf
 193 not (p or q) <=> not p and not q
 194
 195 /* Implements SYMBOL or not TOKEN (attempt #2) */
 196 %SYMBOL:?TOKEN:|skip
 197 text                                    /* If SYMBOL or not TOKEN */
 198 -skip
 199 .sp
 200 .in -5
 201 .fi
 202 Who said they don't care ? ;-)
 203 .sp
 204 .PP
 205 Expansion is done with the \fIexpand\fR command.  It has been provided to
 206 avoid some cumbersome writings in makefiles when you have to repeat some
 207 silly lines that only differ in file names, for instance.  Let's look at
 208 an example first:
 209 .sp
 210 .in +5
 211 .nf
 212 |expand a!foo bar! b!yes no!
 213 !a::
 214         echo !a, !b
 215 -expand
 216 .fi
 217 .in -5
 218 .sp
 219 .PP
 220 Then two rules will be printed, and the values of (a,b) for the first
 221 will be (foo, yes), for the second (bar, no).  Substitution is controled
 222 by the '!' character.  If the word to be substituted is part of another
 223 one, detach with the ^^ construct as in:  !b^^c.  It is possible to
 224 use Makefile macros in the <pattern>, and they will be expanded by
 225 jmake.  If this is not what you want, escape the first '$' sign (this is
 226 a Makefile escape, i.e. you must double the '$', not precede it with a
 227 backslash). A // stands for the null substitution value.
 228 .sp
 229 .PP
 230 Here is another example which shows how the macro Expand can be used.
 231 It is defined in \fIJmake.rules\fR as:
 232 .sp
 233 .in +5
 234 .nf
 235 #define Expand(rule, pattern) @!\\
 236 |expand pattern @!\\
 237 rule @!\\
 238 -expand
 239 .sp
 240 .in -5
 241 .fi
 242 So we can write in the \fIJmakefile\fR:
 243 .sp
 244 .in +5
 245 .nf
 246 |skip
 247 A = foo bar
 248 -skip
 249
 250 #define Rule @!\\
 251 $(DIR)/!a^^.o: !a^^.o @@\\
 252         $(CC) -c !a^^.c @@\\
 253         $(MV) !a^^.o $(DIR)
 254
 255 Expand(Rule, a!$(A)!)
 256 .sp
 257 .in -5
 258 .fi
 259 which will generate in \fIMakefile.SH\fR:
 260 .sp
 261 .in +5
 262 .nf
 263 $(DIR)/foo.o: foo.o
 264         $(CC) -c foo.c
 265         $(MV) foo.o $(DIR)
 266
 267 $(DIR)/bar.o: bar.o
 268         $(CC) -c bar.c
 269         $(MV) bar.o $$(DIR)
 270 .sp
 271 .in -5
 272 .fi
 273 .sp
 274 .PP
 275 The 'A' declaration has been surrounded by \fIskip\fR, so that it does
 276 not appear in the generated Makefile.SH, but it will be taken into
 277 account by \fIjmake\fR for the substitution in the pattern.
 278 .sp
 279 .PP
 280 The number of expansions is determined by the number of possible
 281 values for the \fBfirst\fR parameter. If other parameters have less
 282 substitution values, they will get void ones.
 283 .sp
 284 .PP
 285 It is possible to add a regular expression at the end of '-expand'. This
 286 regular expression will be removed from the final set of expansion at the
 287 end of each line. It is also possible to do substitutions in the expanded
 288 item, by using the syntax (if 'f' is the expanded variable)
 289 !f:\fI<p>\fR=\fI<q>\fR
 290 where \fI<p>\fR and \fI<q>\fR are two regular expressions (without spaces).
 291 The pattern \fI<p>\fR will be replaced by the pattern \fI<q>\fR (only the first
 292 occurrence will be replaced).
 293 .sp
 294 .PP
 295 Finally, you may refer in the expanded section to variables whose value is
 296 computed via another expansion, which makes it easy to define generic
 297 \fIJmakefiles\fR.
 298 .sp
 299 Example:
 300 .sp
 301 .in +5
 302 .nf
 303 SRC = foo.c bar.c
 304 OBJ = \\
 305 |expand f!$(SRC)!
 306         !f:\\.c=\\.o \\
 307 -expand \\\\
 308 INC = \\
 309 |expand f!$(OBJ)!
 310         !f:\\.o=\\.h \\
 311 -expand \\\\
 312 .fi
 313 .in -5
 314 .sp
 315 which will generate in \fIMakefile.SH\fR:
 316 .sp
 317 .in +5
 318 .nf
 319 SRC = foo.c bar.c
 320 OBJ = \\
 321         foo.o \\
 322         bar.o
 323 INC = \\
 324         foo.h \\
 325         bar.h
 326 .in -5
 327 .fi
 328 .sp
 329 Do not forget to protect special characters in your regular expressions such
 330 as backslash, point, etc...
 331 .sp
 332 .PP
 333 The \fIonce\fR command is tagged with a name. The first time the name
 334 appears, the once construct is ignored and the text up to '-once' will
 335 be copied in the generated Makefile.SH.  However, future occurences of
 336 the same name will be ignored (\fIonce\fR will behave like \fIskip\fR).
 337 .sp
 338 Example:
 339 .sp
 340 .in +5
 341 .nf
 342 |once this_is_a_name
 343 <text>
 344 -once
 345 .sp
 346 .in -5
 347 .fi
 348 .sp
 349 .RE
 350 .IP 4)
 351 Initializations:
 352 .sp
 353 .RS
 354 .IP \(bu
 355 +<line>: Puts the whole line in the initialization section.
 356 .IP \(bu
 357 ++SYMBOL <value>: Adds <value> to the SYMBOL macro.
 358 .RE
 359 .sp
 360 .IP 5)
 361 User-defined variables:
 362 .sp
 363 The user may define CFLAGS, LDFLAGS or DPFLAGS as additional flags to be used
 364 in C compilation, linking phase or depend target. It is thus possible to add
 365 some extra flags such as -I or libraries for Makefiles in specific
 366 sub-directories.
 367 .sp
 368 .PD
 369 .SH AUTHOR
 370 Raphael Manfredi <ram@hptnos02.grenoble.hp.com>
 371 .SH FILES
 372 .PD 0
 373 .TP 20
 374 Jmakefile
 375 High level description of Makefile.SH
 376 .TP
 377 Jmake.rules
 378 File holding the macro definitions
 379 .TP
 380 Jmake.tmpl
 381 Template used to mould Makefile.SH
 382 .PD
 383 .SH BUGS
 384 On systems whose
 385 .I cpp
 386 reduces multiple tabs and spaces to a single space,
 387 .I jmake
 388 attempts to put back any necessary tabs (which
 389 .I make
 390 expects in front of rules) but does not properly formats the
 391 body of the rule itself.
 392 .PP
 393 There is a bootstraping problem when creating the first Makefile.SH, because
 394 you cannot run it through a shell until there is a decent Configure
 395 script, but you can't run \fImetaconfig\fR before there is a Makefile.SH
 396 or some needed symbols will not be defined.
 397 .SH "SEE ALSO"
 398 jmkmf(1), metaconfig(1).