metaconfig.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">\r
   2 \r
   3 \r
   4 <HTML>\r
   5 <HEAD>\r
   6 \r
   7 \r
   8 \r
   9 \r
  10 \r
  11         <base href="http://linux.com.hk:80/penguin/" />\r
  12         <TITLE>metaconfig - a Configure script generator
  13  Linux Man Page</TITLE>\r
  14 \r
  15 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">\r
  16 <META name="GENERATOR" content="IBM WebSphere Studio">\r
  17 <LINK rel="stylesheet" href="theme/Master.css" type="text/css">\r
  18 <LINK rel="stylesheet" href="theme/layout.css" type="text/css">\r
  19 <script type="text/javascript" src="js/common.js"></script>\r
  20 <!-- google analytics -->\r
  21 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">\r
  22 </script>\r
  23 <script type="text/javascript">\r
  24 _uacct = "UA-90513-1";\r
  25 urchinTracker();\r
  26 </script>\r
  27 </HEAD>\r
  28 <BODY>\r
  29 \r
  30 \r
  31 \r
  32 <DIV class="container">\r
  33 <TABLE class="container">\r
  34         <TR class="container_up">\r
  35                 <TD class="container_up"><!-- topbar -->\r
  36                 <DIV class="topbar"><A href="index.jsp"> <IMG border="0"\r
  37                         src="images/logo.png" /> </A> \r
  38                         <!--topbar ad area-->\r
  39                 <DIV id="topbaradv">                            \r
  40         <script type="text/javascript"><!--\r
  41                         google_ad_client = "pub-2404433452734258";  \r
  42                         google_ad_width = 468;\r
  43                         google_ad_height = 60;\r
  44                         google_ad_format = "468x60_as";\r
  45                         google_ad_channel ="5458575456"; \r
  46                         google_ad_type = "text_image";  \r
  47         //--></script>\r
  48         <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>\r
  49         </DIV>                  \r
  50                 </DIV>\r
  51                 <!--- navbar --->\r
  52                 <CENTER class=navbar><TABLE width="100%" class="navtable">\r
  53         <TR align="center" class="navtable">\r
  54                 <TD class="navtable"><a href=about.jsp class="navtable"> Company</a></TD>\r
  55                 <TD class="navtable"><a href=products.jsp class="navtable"> Products</a></TD>\r
  56                 <TD class="navtable"><a href=innovation.jsp class="navtable"> Innovation</a></TD>\r
  57                 <TD class="navtable"><a href=manpages.jsp class="navtable"> Man pages</a></TD>\r
  58                 <TD class="navtable"><a href=developer.jsp class="navtable"> Developer</a></TD>\r
  59                 <TD class="navtable"><a href=mirrors.jsp class="navtable"> Mirrors</a></TD>\r
  60                 <TD class="navtable"><a href=search.jsp class="navtable"> Search</a></TD>\r
  61         </TR>\r
  62 </TABLE></CENTER>\r
  63                 <DIV  class="sidebar">\r
  64                 \r
  65                 <!--sidebar ---> \r
  66                 \r
  67                 </DIV>\r
  68                 <DIV class="bodypart">\r
  69                 <STYLE>\r
  70                 DIV.bodypart {\r
  71                         margin-left:5px;\r
  72                 }\r
  73                 </STYLE>\r
  74                 \r
  75                 <a href="http://linux.com.hk:80/penguin/man?action=print"><img src='images/printer.gif'></a>\r
  76                         &nbsp;\r
  77                 <a href="http://linux.com.hk:80/penguin/man/1/m/" class="mannavlink">back to section</a>\r
  78                 \r
  79                 <script type="text/javascript"><!--\r
  80                 google_ad_client = "pub-2404433452734258";\r
  81                 google_ad_width = 468;\r
  82                 google_ad_height = 15;\r
  83                 google_ad_format = "468x15_0ads_al";\r
  84                 google_ad_channel ="5458575456";\r
  85                 google_color_border = "336699";\r
  86                 google_color_bg = "FFFFFF";\r
  87                 google_color_link = "0000FF";\r
  88                 google_color_url = "008000";\r
  89                 google_color_text = "000000";\r
  90                 //--></script>\r
  91                 <script type="text/javascript"\r
  92                   src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
  93                 </script>               \r
  94                 \r
  95                 </br>           \r
  96                 <HTML><HEAD>
  97 <link rel="stylesheet" type="text/css" href="theme/manpage.css">
  98 <TITLE>
  99 METACONFIG &nbsp;&nbsp;(1) manpage
 100 </TITLE></HEAD><BODY>
 101
 102 <div class='man_header'><div class='man_header_left'>METACONFIG</div>
 103 <div class='man_header_left'>1</div>
 104
 105 <div class='man_header_right'>Version 3.0 PL70</div>
 106 </div>
 107
 108 <UL>
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190 <LI> <span class="section">  NAME</span> <BR> <UL> metaconfig - a Configure script generator
 191 </UL> </LI> <LI> <span class="section">  SYNOPSIS</span> <BR> <UL> <span class="B">  metaconfig</span> [ -<B>dhkmostvwGMV</B><R> ]
 192 [ -</R><B>L </B><I><FONT color=#001050>dir</I></FONT><R> ]
 193 </UL> </R></LI> <LI> <span class="section">  DESCRIPTION</span> <BR> <UL> <span class="I">  Metaconfig</span> is a program that generates Configure scripts. If you don't know what a
 194 Configure script is, please skip to the <B>TUTORIAL</B><R> section of this
 195 manual page. If you want a full (formal) description of the way to
 196 use </R><I><FONT color=#001050>metaconfig</I></FONT><R> and its units, please look at the </R><B>REFERENCE</B><R>
 197 section. The following is a quick introduction and reference for
 198 knowledgeable users.
 199 <span class="paragraph_brs"> <BR><BR> </span> </R>
 200  <span class="B">  Metaconfig</span> operates from set of
 201 <span class="I">  units</span> which define everything that metaconfig knows about portability.
 202 Each unit is self-contained, and does not have to be registered anywhere
 203 other than by inclusion in either the public U directory or your private
 204 U directory.
 205 If the dist package (of which metaconfig is a part) is installed in LIB,
 206 then the public U directory is LIB/dist/mcon/U. On this machine, the
 207 LIB directory is /usr/share/dist.
 208 Your private U directory, if you have one,
 209 is in the top level directory of your package.
 210 Before you can run <I><FONT color=#001050>metaconfig</I></FONT><R> you must do a several things:
 211 <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Create a .package file in the package's top level directory by running
 212 <I><FONT color=#001050>packinit</I></FONT><R>.
 213 This program will ask you about your package and remember what you tell
 214 it so that all the dist programs can be smart.
 215 </DD> </R></DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Consult the Glossary (in LIB/dist/mcon) and write your shell scripts and
 216 C programs in terms of the symbols that metaconfig knows how to define.
 217 You don't need to tell metaconfig which symbols you used, since metaconfig
 218 will figure that out for you.
 219 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Generate any .SH scripts needed to write Makefiles or shell scripts that
 220 will depend on values defined by Configure.
 221 There is a program called <I><FONT color=#001050>makeSH</I></FONT><R> that will help you convert a plain
 222 script into a script.SH template; some editing will still need to be performed
 223 on the resulting .SH file to move the variable configuration part in the
 224 top part of the script (see inline comments generated by </R><I><FONT color=#001050>makeSH</I></FONT><R> within
 225 your .SH file).
 226 </DD> </R></DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Create a MANIFEST.new file in your top level directory that lists all the
 227 files in your package. This file will remain private and will not be
 228 part of the final distribution.
 229 The filename should be the first field on each line.
 230 After some whitespace you can add a short comment describing your file.
 231 Only source files should be listed in there. The special file
 232 <I><FONT color=#001050>patchlevel.h</I></FONT><R> (which is handled and maintained by the patching tools --
 233 see <a href="man/1/pat.html">pat(1)</a> ) should be part of the MANIFEST.new file, but may be
 234 silently ignored by some tools. As a rule of
 235 thumb, only files maintained by RCS should be listed in there,
 236 the </R><I><FONT color=#001050>patchlevel.h</I></FONT><R> file being one important exception.
 237 </DD> </R></DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Optionally, you may wish to create a MANIFEST file, which will be an
 238 exported version of your MANIFEST.new. That file must be made part of
 239 the release, i.e. listed in both your MANIFEST.new and MANIFEST itself.
 240 One of the <I><FONT color=#001050>metaconfig</I></FONT><R> units knows about this file and will force
 241 Configure to perform a release check, ensuring all the files listed
 242 there are part of the distribution. The MANIFEST and MANIFEST.new
 243 files should be distinct, not links.
 244 </DD> </R></DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Copy any .U files that you want to modify to your private U directory.
 245 Any .U files in your private U directory will be used in preference to
 246 the one in the public U directory.
 247 For example, one way to force inclusion of any unit is to copy the End.U
 248 file to your .U directory and add the name of the unit you want as
 249 a dependency on the end of the ?MAKE: line.
 250 Certain units can ONLY be forced in this way, namely those of the form
 251 Warn_*.U and Chk_*.U.
 252 You can also customize certain default Configure variables by copying
 253 Myinit.U to your package's private U directory and setting the variables in
 254 that unit.
 255 <span class="paragraph_brs"> <BR><BR> </span>
 256  Now you are ready to run <I><FONT color=#001050>metaconfig</I></FONT><R>. That will create a </R><I><FONT color=#001050>Configure</I></FONT><R>
 257 file, and optionally a </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file (if your sources make any use
 258 of C symbols).
 259 The generated files will automatically be added to your MANIFEST.new
 260 if necessary. Do not forget to update your MANIFEST file though.
 261 <span class="paragraph_brs"> <BR><BR> </span> </R>
 262  In order to create new units, do the following:
 263 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Copy a similar unit to a new .U file.
 264 The name you choose should be the name of a variable generated by the unit,
 265 although this is only a convenience for you, not a requirement.
 266 It should be 12 or less characters to prevent filename chopping.
 267 Actually, it should probably be 10 or less so that those who want to use RCS
 268 can have a .U,v on the end without chopping.
 269 Metaconfig uses the case of the first letter to determine if any variable is
 270 actually produced by this unit, so don't Capitalize your unit
 271 name if it is supposed to produce a shell variable.
 272 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Edit the new .U file to do what you want.
 273 The first ?MAKE: line indicates the dependencies; before the final list
 274 colon all the variables this unit defines, and after the final colon
 275 all the variables (or other units) on which this unit depends.
 276 It is very important that these lists be accurate. If a dependency is
 277 optional and a default value can be used, you should prefix the dependency
 278 with a '+' sign. The corresponding unit will not be loaded to compute the
 279 symbol, unless really required by another unit.
 280 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> To the extent possible, parameterize your unit based on shell
 281 variable defined on ?INIT: lines.
 282 This will move the variable definitions up to the Init.U unit,
 283 where they can be overridden by definitions in Myinit.U, which is
 284 included after Init.U.
 285 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Add the definition of any C symbols desired as ?H: lines.
 286 A line beginning with ?H:?%&lt;: in the .U file will be added to the eventual
 287 config.h file if and only if metaconfig decides that this unit is needed.
 288 The %&lt; stands for the unit's name, which happens to be the name of
 289 the file too (without .U) if you followed the convention.
 290 Always put a comment on each ?H: line in case one of the variable
 291 substitutions earlier on the line starts a comment without finishing it.
 292 Any shell variable starting with d_ may do this, so beware.
 293 If you ommit the ?%&lt;:, then metaconfig will try to intuit the symbol whose
 294 definition is needed prior any inclusion in config.h.
 295 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Add glossary definitions as ?S: lines for shell variables and ?C:
 296 lines for C preprocessor variables.
 297 See a current unit for examples.
 298 It is VERY important to start each entry with a left justified symbol
 299 name, and end each entry with a ?C:. or ?S:. line.&nbsp;&nbsp;The algorithm
 300 that translates C preprocessor symbol entries for the Glossary into
 301 comments for config.h depends on this.
 302 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Make sure the order of all your ? lines is right.&nbsp;&nbsp;The correct order is:
 303 <BR><BR> <!-- --> </DD> </DT></DL> <div class='RS'> <!--  +10-->    <DL><DT> <!--  15--> ?RCS: and ?X:
 304 <DD> basically just comments
 305 </DD> </DT></DL> <DL><DT> <!-- --> ?MAKE:
 306 <DD> metaconfig dependencies
 307 </DD> </DT></DL> <DL><DT> <!-- --> ?Y:
 308 <DD> unit layout directive
 309 </DD> </DT></DL> <DL><DT> <!-- --> ?S:
 310 <DD> glossary shell definitions
 311 </DD> </DT></DL> <DL><DT> <!-- --> ?C:
 312 <DD> glossary C definitions
 313 </DD> </DT></DL> <DL><DT> <!-- --> ?H:
 314 <DD> config.h definitions
 315 </DD> </DT></DL> <DL><DT> <!-- --> ?M:
 316 <DD> confmagic.h definitions
 317 </DD> </DT></DL> <DL><DT> <!-- --> ?W:
 318 <DD> wanted symbols
 319 </DD> </DT></DL> <DL><DT> <!-- --> ?V:
 320 <DD> visible symbols
 321 </DD> </DT></DL> <DL><DT> <!-- --> ?F:
 322 <DD> files created by this unit
 323 </DD> </DT></DL> <DL><DT> <!-- --> ?T:
 324 <DD> temporary shell symbols used
 325 </DD> </DT></DL> <DL><DT> <!-- --> ?D:
 326 <DD> optional dependencies default value
 327 </DD> </DT></DL> <DL><DT> <!-- --> ?O:
 328 <DD> used to mark obsolete units
 329 </DD> </DT></DL> <DL><DT> <!-- --> ?LINT:
 330 <DD> metalint hints
 331 </DD> </DT></DL> <DL><DT> <!-- --> ?INIT:
 332 <DD> shell symbols initializations
 333 </DD> </DT></DL> </div> <!-- --> <span class="paragraph_brs"> <BR><BR> </span>
 334   Here is an example to show the ordering of the lines and the various
 335 formats allowed:
 336 ?RCS: $RCS-Id$
 337 ?RCS: Copyright information
 338 ?RCS: $RCS-Log$
 339 ?X:
 340 ?X: A contrived example
 341 ?X:
 342 ?MAKE:d_one two: three +four Five
 343 ?MAKE: -pick add $@ %&lt;
 344 ?Y:DEFAULT
 345 ?S:d_one:
 346 ?S: First shell symbol, conditionally defines ONE.
 347 ?S:.
 348 ?S:two:
 349 ?S: Second shell symbol, value for TWO.
 350 ?S:.
 351 ?C:ONE:
 352 ?C: First C symbol.
 353 ?C:.
 354 ?C:TWO:
 355 ?C: Second C symbol.
 356 ?C:.
 357 ?H:#$d_one ONE /**/
 358 ?H:#define TWO "$two"
 359 ?H:#$d_one ONE_TWO "$two"
 360 ?H:.
 361 ?M:flip: HAS_FLIP
 362 ?M:#ifndef HAS_FLIP
 363 ?M:#define flip(x) flop(x)
 364 ?M:#endif
 365 ?M:.
 366 ?W:%&lt;:one_two
 367 ?V:p_one p_two:p_three
 368 ?F:file ./ftest !tmp
 369 ?T:tmp var
 370 ?D:two='undef'
 371 ?LINT:change three
 372 ?INIT:two_init='2'
 373 : shell code implementing the unit follows
 374 p_one='one'
 375 p_two='two'
 376 p_three=""
 377 Let me state it one more time: the above unit definition is a <I><FONT color=#001050>fake</I></FONT><R>
 378 one to only show the different possibilities. Such a unit would serve
 379 little purpose anyway... Some more advanced features are not described
 380 here. Please refer to the </R><B>REFERENCE</B><R> section for more complete
 381 information.
 382  </R> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Put the unit into the public or private U directory as appropriate.
 383 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Rerun <I><FONT color=#001050>metaconfig</I></FONT><R>.
 384 </DD> </R></DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Send your unit to ram@acri.fr (Raphael Manfredi) for inclusion
 385 in the master copy, if you think it's of general interest.
 386 <span class="paragraph_brs"> <BR><BR> </span>
 387  In order to add a new program to be located:
 388 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Edit Loc.U, and add the name of the program both to the ?MAKE: line
 389 (between the two colons) and to either loclist or trylist (depending
 390 on whether the program is mandatory or not).
 391 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Rerun metaconfig.
 392 </DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Send your unit to me for inclusion in the master copy, if you think it's
 393 of general interest.
 394 <span class="paragraph_brs"> <BR><BR> </span>
 395  Notes for writing .U files:
 396 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always use "rm -f" because there are systems where rm is interactive by
 397 default.
 398 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Do not use "set -- ..." because '--' does not work with every shell. Use
 399 "set x ...; shift".
 400 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always use echo " " (with a space) because of Eunice systems.
 401 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use only programs that came with V7, so that you know everyone has them.
 402 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use $contains when you want to grep conditionally, since not all
 403 greps return a reasonable status.
 404 Be sure to redirect the output to /dev/null, by using '&gt;/dev/null 2&gt;&1'.
 405 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use "if test" rather than "if [...]" since not every sh knows the
 406 latter construct.
 407 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use the myread script for inputs so that they can do shell escapes
 408 and default evaluation.&nbsp;&nbsp;The general form is
 409 case "$grimble" in
 410 '') dflt=452;;
 411 *) dflt="$grimble";;
 412 esac
 413 rp='How many grimbles do you have?'
 414 . ./myread
 415 grimble="$ans"
 416 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use the getfile script when asking for a file pathname in order to
 417 have optional ~name expansion and sanity checks. See the Getfile.U
 418 unit for a full decription.
 419 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always put a
 420  $startsh
 421 at the top of every generated script that is going to be launched
 422 or sourced by <I><FONT color=#001050>Configure</I></FONT><R>.
 423 </DD> </R></DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Never assume common UNIX-isms like the fact that an object file ends
 424 with a <I><FONT color=#001050>.o</I></FONT><R> and that a library name ends with </R><I><FONT color=#001050>.a</I></FONT><R>.
 425 Use the </R><I><FONT color=#001050>$_o</I></FONT><R> and </R><I><FONT color=#001050>$_a</I></FONT><R> variables instead (see Unix.U).
 426 </DD> </R></DT></DL> <DL><DT> <span class="ip"> *</span> <DD> When doing a compile-link-execute test, always write it like this:
 427 $cc $ccflags $ldflags try.c -o try $libs
 428 because some systems require that linking flags be specified before
 429 the compiled target (with the exception of trailing linking libraries).
 430 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Issue important messages on file descriptor #4, by using '&gt;&4' to redirect
 431 output. Only those messages will appear when the <B>-s</B><R> switch is
 432 given to </R><I><FONT color=#001050>Configure</I></FONT><R> on the command line (silent mode).
 433 </DD> </R></DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always try to determine whether a feature is present in the most
 434 specific way--don't say "if bsd" when you can grep libc.&nbsp;&nbsp;There
 435 are many hybrid systems out there, and each feature should stand
 436 or fall by itself.
 437 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always try to determine whether a feature is present in the most
 438 general way, so that other packages can use your unit.
 439 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> When in doubt, set a default and ask.&nbsp;&nbsp;Don't assume anything.
 440 </DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> If you think the user is wrong, allow for the fact that he may be right.
 441 For instance, he could be running Configure on a different system than
 442 he is going to use the final product on.
 443 <span class="paragraph_brs"> <BR><BR> </span>
 444  Metaconfig reserves the following names in your directory, and if you use such
 445 a name it may get clobbered or have other unforeseen effects:
 446 Configure
 447 Wanted
 448 Obsolete
 449 configure
 450 config_h.SH
 451 confmagic.h
 452 U/*
 453 MANIFEST.new
 454 Additionally, Configure may clobber these names in the directory it is run in:
 455 UU/*
 456 config.sh
 457 config.h
 458 </DD> </DT></DL>
 459
 460
 461 </UL> </LI> <LI> <span class="section">  OPTIONS</span> <BR> <UL> The following options are recognized by <I><FONT color=#001050>metaconfig</I></FONT><R>:
 462 <DL><DT> <!--  15--> <span class="B">  -d</span> <DD> Turn on debug mode. Not really useful unless you are debugging <I><FONT color=#001050>metaconfig</I></FONT><R>
 463 itself.
 464 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -h</span> <DD> Print help message and exit.
 465 </DD> </DT></DL> <DL><DT> <!-- --> <span class="B">  -k</span> <DD> Keep temporary directory, so that you may examine the working files used
 466 by <I><FONT color=#001050>metaconfig</I></FONT><R> to build your </R><I><FONT color=#001050>Configure</I></FONT><R> script. Useful only when
 467 debugging the units.
 468 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -m</span> <DD> Assume lots of memory and swap space. This will speed up symbol lookup in
 469 source files by a significant amount of time, at the expense of memory
 470 consumption...
 471 </DD> </DT></DL> <DL><DT> <!-- --> <span class="B">  -o</span> <DD> Map obsolete symbols on new ones. Use this switch if you still have some
 472 obsolete symbols in your source code and do not want (or cannot) remove
 473 them for now. The obsolete symbols are otherwise ignored, although that
 474 will give you a warning from <I><FONT color=#001050>metaconfig</I></FONT><R>.
 475 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -s</span> <DD> Turn silent mode on.
 476 </DD> </DT></DL> <DL><DT> <!-- --> <span class="B">  -t</span> <DD> Trace symbols as they are found.
 477 </DD> </DT></DL> <DL><DT> <!-- --> <span class="B">  -v</span> <DD> Turn verbose mode on.
 478 </DD> </DT></DL> <DL><DT> <!-- --> <span class="B">  -w</span> <DD> Assume Wanted file is up-to-date. This will skip the time and memory
 479 consuming phase of source code scanning, looking for known symbols.
 480 Use it only when you know your source file have not changed with respect
 481 to the pool of <I><FONT color=#001050>metaconfig</I></FONT><R> symbols used.
 482 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -G</span> <DD> Also provide a GNU <I><FONT color=#001050>configure</I></FONT><R>-like front end to the generated
 483 <span class="I">  Configure</span> </R>script, to be included in the distribution as well. This is only
 484 a wrapper around the
 485 <span class="I">  Configure</span> script naturally, but it lets people familiar with the GNU tool to
 486 not be lost when facing a new distribution.
 487 </DD> </DT></DL> <DL><DT> <!-- --> <B>-L</B><I><FONT color=#001050> dir</I></FONT><R>
 488 <DD> Override default library location. Normally only useful for metaconfig
 489 maintainers to locally use the units being developped instead of the
 490 publicly available ones. The <I><FONT color=#001050>dir</I></FONT><R> specified is the one containing the
 491 units </R><I><FONT color=#001050>U</I></FONT><R> directory.
 492 </DD> </R></DT></DL> </R><DL><DT> <!-- --> <span class="B">  -M</span> <DD> Allow production of a <I><FONT color=#001050>confmagic.h</I></FONT><R> file to automagically remap some
 493 well-known symbols to some other alternative, like </R><I><FONT color=#001050>bcopy</I></FONT><R>() being
 494 remapped transparently to </R><I><FONT color=#001050>memcpy()</I></FONT><R> when not available. This option
 495 is turned on automatically when a </R><I><FONT color=#001050>confmagic.h</I></FONT><R> file exists in the
 496 top-level directory. Simply remove that file if you wish to disable this
 497 option permanently.
 498 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -V</span> <DD> Print version number and exit.
 499 </DD> </DT></DL>
 500
 501
 502 </UL> </LI> <LI> <span class="section">  TUTORIAL</span> <BR> <UL> This (long) section is an introduction to <I><FONT color=#001050>metaconfig</I></FONT><R>, in which we will
 503 learn all the basics. If you already know how to use </R><I><FONT color=#001050>metaconfig</I></FONT><R>, you
 504 may safely skip to the next section.
 505
 506 <span class="SS">  Overview</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 507  Usually when you want to get some source package to compile on a given
 508 platform you have to edit the main Makefile (assuming there is one!),
 509 choose a C compiler, make sure you have the proper libraries, and then
 510 fire the <I><FONT color=#001050>make</I></FONT><R> command. If the package is reasonably well written, it
 511 will compile (without a warning being an option :-). In itself, the last
 512 sentence is a real performance, since given the variety of UNIX platforms
 513 available today and the diversity of flavours, that means the author of the
 514 package has gone into deep trouble to figure out the right choices given
 515 some standard trial, guessing and messing around with system includes and
 516 types.
 517 <span class="paragraph_brs"> <BR><BR> </span> </R>
 518  However, despite all his talent, the author cannot possibly know that
 519 some system has a broken system call, or that some sytem structure lacks
 520 one otherwise standard field, or simply wheter a given include file exists
 521 or not. And I'm not considering the implicit assumptions, like the type
 522 returned by the <I><FONT color=#001050>malloc()</I></FONT><R> function or the presence of the </R><I><FONT color=#001050>rename()</I></FONT><R>
 523 system call to name a few. But that knowledge is necessary to achieve real
 524 portability.
 525 <span class="paragraph_brs"> <BR><BR> </span> </R>
 526  Now let's not abuse ourselves. Using that information requires greater
 527 skills, yet it can lead to more portable programs since it is then
 528 written in a system-independant fashion and relies only on the fact that
 529 some assumption is true or false on a particular system, each assumption
 530 being unrelated with each other. That is to say, we do not say: We're on
 531 a BSD system or we are on a USG system. That's too fuzzy anyway nowadays.
 532 No, we want to say to the source code: this system does not have the
 533 <span class="I">  rename()</span> system call and <I><FONT color=#001050>malloc()</I></FONT><R> returns a </R><I><FONT color=#001050>(void *)</I></FONT><R>
 534 value.
 535 <span class="paragraph_brs"> <BR><BR> </span> </R>
 536  Metaconfig is a tool that will let you do just that, with the additional
 537 benefit of not having to hand-edit the Makefile if all goes well. By
 538 running <I><FONT color=#001050>metaconfig</I></FONT><R>, you create a shell script named </R><I><FONT color=#001050>Configure</I></FONT><R>.
 539 Lots of efforts have been devoted to the Configure script internals to ensure
 540 it will run on 99% of the existing shells available as of this writing.
 541 Configure will probe the target system, asking questions when in doubt and
 542 gather all the answers in one single shell file, which in turn can be used
 543 to automatically generate configured Makefiles and C include files.
 544 <span class="paragraph_brs"> <BR><BR> </span> </R>
 545  There is only a limited (but quite large) set of symbols available for your
 546 shell scripts and C programs. They are all documented in the Glossary file.
 547 All you need to do is learn about them and start using them to address
 548 portability and configuration problems. Then, by running <I><FONT color=#001050>metaconfig</I></FONT><R>,
 549 a suitable Configure script will be generated for your package.
 550 <span class="paragraph_brs"> <BR><BR> </span> </R>
 551  The Configure script is built out several units (more than 300), each
 552 unit being responsible for defining a small number of shell and/or C
 553 symbols. Units are assembled together at the final stage, honoring
 554 the dependency graph (one unit may need the result of several other
 555 units which are then placed before in the script).
 556
 557 <span class="SS">  Symbols</span> <span class="paragraph_brs"> <BR><BR> </span>
 558  Symbols are the most important thing in the <I><FONT color=#001050>metaconfig</I></FONT><R> world. They
 559 are the smallest recognized entity, usually a word, and can be granted
 560 a value at the end of the Configure execution. For instance, the C
 561 pre-processor symbol </R><I><FONT color=#001050>HAS_RENAME</I></FONT><R> is a </R><I><FONT color=#001050>metaconfig</I></FONT><R> symbol that is
 562 guranteed to be defined if, and only if, the </R><I><FONT color=#001050>rename()</I></FONT><R> system call
 563 is present. Likewise, the </R><I><FONT color=#001050>$ranlib</I></FONT><R> shell variable will be set to
 564 either ':' or 'ranlib' depending on whether the call to the </R><I><FONT color=#001050>ranlib</I></FONT><R>
 565 program is needed to order a library file. How this works is not important
 566 for now, what is important is to understand that those symbols are given
 567 a </R><I><FONT color=#001050>life</I></FONT><R> (i.e. a value) upon </R><I><FONT color=#001050>Configure</I></FONT><R> execution.
 568 <span class="paragraph_brs"> <BR><BR> </span> </R>
 569  Using symbols is relatively straightforward. In a C source file, you simply
 570 use the symbol value, as a pre-processor directive (for instance an: <I><FONT color=#001050>#ifdef
 571 HAS_RENAME</I></FONT><R>) or, if the symbol value is a string, directly as you would use
 572 a macro in C. And in a shell file or a Makefile, you may reference a shell
 573 symbol directly.
 574 <span class="paragraph_brs"> <BR><BR> </span> </R>
 575  Actually, I'm lying, because that's not completely as magic as the previous
 576 paragraph could sound. In a C file, you need to include the Configure-produced
 577 <I><FONT color=#001050>config.h</I></FONT><R> file, and you must wrap your shell script or Makefile in a .SH
 578 file and you may reference the shell symbol only in the variable
 579 substitution part of that .SH file. More on this later.
 580
 581 <span class="SS">  Source Files</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 582  Symbols may only appear in a limited set of source files, because
 583 <I><FONT color=#001050>metaconfig</I></FONT><R> will only scan those when looking for known symbols, trying
 584 to figure out which units it will need. You may use C symbols in C source
 585 files, i.e. files with a </R><I><FONT color=#001050>.c</I></FONT><R>, </R><I><FONT color=#001050>.h</I></FONT><R>, </R><I><FONT color=#001050>.y</I></FONT><R> or </R><I><FONT color=#001050>.l</I></FONT><R> extension,
 586 and shell symbols are looked for only in .SH files.
 587 <span class="paragraph_brs"> <BR><BR> </span> </R>
 588  In order to get the value of a symbol, a C file needs to include the special
 589 <I><FONT color=#001050>config.h</I></FONT><R> file, which is produced by </R><I><FONT color=#001050>Configure</I></FONT><R> when C symbols
 590 are present. And .SH files are run through a shell, producing a new file.
 591 However, in the top section of the .SH file, the special </R><I><FONT color=#001050>config.sh</I></FONT><R>
 592 file (also produced by running </R><I><FONT color=#001050>Configure</I></FONT><R>) is sourced, and variable
 593 substitutions apply. Actually, </R><I><FONT color=#001050>config.h</I></FONT><R> is produced by running the
 594 </R><I><FONT color=#001050>metaconfig</I></FONT><R>-produced </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file, again using variable
 595 substitution. So we're going to look at that a little more closely since
 596 this is the heart of the whole </R><I><FONT color=#001050>configuration</I></FONT><R> scheme...
 597
 598 <span class="SS">  Variable Substitution</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 599  There is shell construct called <I><FONT color=#001050>here document</I></FONT><R> which enables a
 600 command to take an input specified within the script itself. That
 601 input is interpreted by the shell as a double-quoted string or a
 602 single quoted string depending on the form of the here document
 603 specification.
 604 <span class="paragraph_brs"> <BR><BR> </span> </R>
 605  To specify a here document, the '&lt;&lt;' token is used, followed by a single
 606 identifier. From then on, the remaining script lines form the input for
 607 the command, until the here document is found on a line by itself.
 608 Shell substitution (including shell variable substitutions) is done
 609 unless the identifier is surrounded by single quotes. For instance:
 610 var='first'
 611 tar='second'
 612 echo "--&gt; first here document:"
 613 cat &lt;&lt;EOM
 614 var='$var'
 615 tar='$tar'
 616 EOM
 617 echo "--&gt; second here document:"
 618 cat &lt;&lt;'EOM'
 619 echo $var
 620 echo $tar
 621 EOM
 622 echo "--&gt; end."
 623 will produce, when run through a shell:
 624 --&gt; first here document:
 625 var='first'
 626 tar='second'
 627 --&gt; second here document:
 628 echo $var
 629 echo $tar
 630 --&gt; end.
 631 The first here document has its content interpreted whilst the second
 632 one is output as-is. Both are useful in a .SH script, as we are about to see.
 633
 634 <span class="SS">  Using .SH Scripts</span> <span class="paragraph_brs"> <BR><BR> </span>
 635  A .SH script is usually produced by running the <I><FONT color=#001050>MakeSH</I></FONT><R> script other
 636 an existing file, transforming </R><I><FONT color=#001050>file</I></FONT><R> into a </R><I><FONT color=#001050>file.SH</I></FONT><R>. Let's take
 637 a single example. Here is a little script (let's call it </R><I><FONT color=#001050>intsize</I></FONT><R>)
 638 which prints a single message, the size of the </R><B>int</B><R> datatype in C.
 639 Unfortunately, it has the value hardwired in it, thusly:
 640 #!/bin/sh
 641 intsize='4'
 642 echo "On this machine, the int type is $intsize bytes"
 643 Let's run </R><I><FONT color=#001050>makeSH</I></FONT><R> on it by typing '</R><I><FONT color=#001050>makeSH intsize</I></FONT><R>'. We get a single
 644 </R><I><FONT color=#001050>intsize.SH</I></FONT><R> file that looks like this:
 645 case $CONFIG in
 646 '')
 647  if test -f config.sh; then TOP=.;
 648  elif test -f ../config.sh; then TOP=..;
 649  elif test -f ../../config.sh; then TOP=../..;
 650  elif test -f ../../../config.sh; then TOP=../../..;
 651  elif test -f ../../../../config.sh; then TOP=../../../..;
 652  else
 653 &nbsp;&nbsp;echo "Can't find config.sh."; exit 1
 654  fi
 655  . $TOP/config.sh
 656  ;;
 657 esac
 658 : This forces SH files to create target in same directory as SH file.
 659 : This is so that make depend always knows where to find SH derivatives.
 660 case "$0" in
 661 */*) cd `expr X$0 : 'X\(.*\)/'` ;;
 662 esac
 663 echo "Extracting intsize (with variable substitutions)"
 664 : This section of the file will have variable substitutions done on it.
 665 : Move anything that needs config subs from !NO!SUBS! section to !GROK!THIS!.
 666 : Protect any dollar signs and backticks that you do not want interpreted
 667 : by putting a backslash in front.&nbsp;&nbsp;You may delete these comments.
 668 $spitshell &gt;intsize &lt;&lt;!GROK!THIS!
 669 $startsh
 670 !GROK!THIS!
 671 <BR>
 672
 673 : In the following dollars and backticks do not need the extra backslash.
 674 $spitshell &gt;&gt;intsize &lt;&lt;'!NO!SUBS!'
 675 intsize='4'
 676 echo "On this machine, the int type is $intsize bytes"
 677 !NO!SUBS!
 678 chmod 755 intsize
 679 $eunicefix intsize
 680 The first part of this script (in the </R><I><FONT color=#001050>case</I></FONT><R> statement) is trying to
 681 locate the </R><I><FONT color=#001050>config.sh</I></FONT><R> file, in order to source it. The </R><I><FONT color=#001050>$CONFIG</I></FONT><R>
 682 variable is false by default, by true when </R><I><FONT color=#001050>config.sh</I></FONT><R> has been sourced
 683 already (which would be the case if this file was executed from within
 684 </R><I><FONT color=#001050>Configure</I></FONT><R> itself, but let's not confuse the issue here).
 685 <span class="paragraph_brs"> <BR><BR> </span> </R>
 686  Once the <I><FONT color=#001050>config.sh</I></FONT><R> file has been sources, all the shell symbols
 687 defined by </R><I><FONT color=#001050>Configure</I></FONT><R> are set. We know reach a second case statement,
 688 used to change the current directory should a path be used to
 689 reach this program (for instance if we said '</R><I><FONT color=#001050>sh ../scripts/intsize.SH</I></FONT><R>',
 690 we would first run '</R><I><FONT color=#001050>cd ../scripts</I></FONT><R>' before continuing). If you do not
 691 understand this, don't worry about it.
 692 <span class="paragraph_brs"> <BR><BR> </span> </R>
 693  Here comes the intersting stuff. This script uses the <I><FONT color=#001050>$spitshell</I></FONT><R>
 694 variable, and it's not something we know about...yet. If you look through
 695 the Glossary file, you will see that this is a variable known by
 696 </R><I><FONT color=#001050>metaconfig</I></FONT><R>. If you make this file part of your distribution (by including
 697 it in the MANIFEST.new file, we'll come back to that later on) and run
 698 </R><I><FONT color=#001050>metaconfig</I></FONT><R>, then the </R><I><FONT color=#001050>Configure</I></FONT><R> script will determine a suitable
 699 value for this variable and it will be set in </R><I><FONT color=#001050>config.sh</I></FONT><R>. Same goes for
 700 </R><I><FONT color=#001050>$startsh</I></FONT><R> and the mysterious </R><I><FONT color=#001050>$eunicefix</I></FONT><R> at the end. On a
 701 reasonable system, the relevant part of </R><I><FONT color=#001050>config.sh</I></FONT><R> would look like this:
 702 spitshell='cat'
 703 startsh='#!/bin/sh'
 704 eunicefix=':'
 705 Ah! We're getting there. Now it looks familiar. We're facing a single
 706 </R><I><FONT color=#001050>cat</I></FONT><R> command whose input comes from a variable-interpolated here
 707 document and whose output is redirected to </R><I><FONT color=#001050>intsize</I></FONT><R>. The value
 708 will be that of </R><I><FONT color=#001050>$startsh</I></FONT><R>, i.e. '#!/bin/sh'. Fine so far.
 709 <span class="paragraph_brs"> <BR><BR> </span> </R>
 710  Then we reach the second here document expansion, to get the remaining of
 711 the script. This time, the here document symbol is surrounded by single
 712 quotes so the contents will be appended verbatim to the <I><FONT color=#001050>intsize</I></FONT><R> file.
 713 So, by running '</R><I><FONT color=#001050>sh intsize.SH</I></FONT><R>', we get the following output:
 714 Extracting intsize (with variable substitutions)
 715 and by looking at the produced intsize file, we see:
 716 #!/bin/sh
 717 intsize='4'
 718 echo "On this machine, the int type is $intsize bytes"
 719 which is exactly what we had at the beginning. So far, it's a no-operation
 720 procedure... But, how marvelous! It so happens (pure coincidence, trust me!),
 721 that </R><I><FONT color=#001050>metaconfig</I></FONT><R> knows about the </R><I><FONT color=#001050>$intsize</I></FONT><R> shell symbol. By moving
 722 the initialization of intsize to the variable-interpolated area of the .SH
 723 script and initializing it with the </R><I><FONT color=#001050>Configure</I></FONT><R>-computed value,
 724 and removing the now useless comments added by </R><I><FONT color=#001050>makeSH</I></FONT><R>, we get:
 725 case $CONFIG in
 726 '')
 727  if test -f config.sh; then TOP=.;
 728  elif test -f ../config.sh; then TOP=..;
 729  elif test -f ../../config.sh; then TOP=../..;
 730  elif test -f ../../../config.sh; then TOP=../../..;
 731  elif test -f ../../../../config.sh; then TOP=../../../..;
 732  else
 733 &nbsp;&nbsp;echo "Can't find config.sh."; exit 1
 734  fi
 735  . $TOP/config.sh
 736  ;;
 737 esac
 738 case "$0" in
 739 */*) cd `expr X$0 : 'X\(.*\)/'` ;;
 740 esac
 741 echo "Extracting intsize (with variable substitutions)"
 742 $spitshell &gt;intsize &lt;&lt;!GROK!THIS!
 743 $startsh
 744 intsize='$intsize'
 745 !GROK!THIS!
 746 <BR>
 747
 748 $spitshell &gt;&gt;intsize &lt;&lt;'!NO!SUBS!'
 749 echo "On this machine, the int type is $intsize bytes"
 750 !NO!SUBS!
 751 chmod 755 intsize
 752 $eunicefix intsize
 753 Of course, running this script through a shell will again output the same
 754 script. But if we run </R><I><FONT color=#001050>Configure</I></FONT><R> on a machine where an </R><B>int</B><R> is
 755 stored as a 64 bits quantity, </R><I><FONT color=#001050>config.sh</I></FONT><R> will set </R><I><FONT color=#001050>intsize</I></FONT><R> to
 756 8 and the </R><I><FONT color=#001050>intsize</I></FONT><R> script will bear the right value and print:
 757 On this machine, the int type is 8 bytes
 758 which is correct. Congratulations! We have just configured a shell script!!
 759
 760 <span class="SS">  Producing config.h</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 761  We can now have a look at the way <I><FONT color=#001050>config.h</I></FONT><R> is produced out of
 762 </R><I><FONT color=#001050>config_h.SH</I></FONT><R>. We know that running </R><I><FONT color=#001050>Configure</I></FONT><R> produces a
 763 </R><I><FONT color=#001050>config.sh</I></FONT><R> script (how exactly this is done is not strictly
 764 relevant here, but for the curious, it's another here document
 765 substitution within </R><I><FONT color=#001050>Configure</I></FONT><R> itself). The </R><I><FONT color=#001050>config_h.SH</I></FONT><R>
 766 itself is built by </R><I><FONT color=#001050>metaconfig</I></FONT><R> at the same time </R><I><FONT color=#001050>Configure</I></FONT><R>
 767 is, provided you make use of at least one C symbol within your sources.
 768 <span class="paragraph_brs"> <BR><BR> </span> </R>
 769  Let's have a look at some random <I><FONT color=#001050>config_h.SH</I></FONT><R> file to see what
 770 really happens:
 771 case $CONFIG in
 772 '')
 773  if test -f config.sh; then TOP=.;
 774  elif test -f ../config.sh; then TOP=..;
 775  elif test -f ../../config.sh; then TOP=../..;
 776  elif test -f ../../../config.sh; then TOP=../../..;
 777  elif test -f ../../../../config.sh; then TOP=../../../..;
 778  else
 779 &nbsp;&nbsp;echo "Can't find config.sh."; exit 1
 780  fi
 781  . $TOP/config.sh
 782  ;;
 783 esac
 784 case "$0" in
 785 */*) cd `expr X$0 : 'X\(.*\)/'` ;;
 786 esac
 787 echo "Extracting config.h (with variable substitutions)"
 788 sed &lt;&lt;!GROK!THIS! &gt;config.h -e 's!^#undef!/#define!' -e 's!^#un-def!#undef!'
 789 /*
 790  * This file was produced by running the config_h.SH script, which
 791  * gets its values from config.sh, which is generally produced by
 792  * running Configure.
 793  *
 794  * Feel free to modify any of this as the need arises.&nbsp;&nbsp;Note, however,
 795  * that running config.h.SH again will wipe out any changes you've made.
 796  * For a more permanent change edit config.sh and rerun config.h.SH.
 797  */
 798 <BR>
 799
 800 /* Configuration time: $cf_time
 801  * Configured by: $cf_by
 802  * Target system: $myuname
 803  */
 804 <BR>
 805
 806 #ifndef _config_h_
 807 #define _config_h_
 808 <BR>
 809
 810 /* bcopy:
 811  * This symbol is maped to memcpy if the bcopy() routine is not
 812  * available to copy strings.
 813  */
 814 /* HAS_BCOPY:
 815  * This symbol is defined if the bcopy() routine is available to
 816  * copy blocks of memory. You should not use this symbol under
 817  * normal circumstances and use bcopy() directly instead, which
 818  * will get mapped to memcpy() if bcopy is not available.
 819  */
 820 #$d_bcopy HAS_BCOPY /**/
 821 #ifndef HAS_BCOPY
 822 #ifdef bcopy
 823 #un-def bcopy
 824 #endif
 825 #define bcopy(s,d,l) memcpy((d),(s),(l))&nbsp;&nbsp;/* mapped to memcpy */
 826 #endif
 827 <BR>
 828
 829 /* HAS_DUP2:
 830  * This symbol, if defined, indicates that the dup2 routine is
 831  * available to duplicate file descriptors.
 832  */
 833 #$d_dup2 HAS_DUP2 /**/
 834 <BR>
 835
 836 /* I_STRING:
 837  * This symbol, if defined, indicates to the C program that it should
 838  * include &lt;string.h&gt; (USG systems) instead of &lt;strings.h&gt; (BSD systems).
 839  */
 840 #$i_string I_STRING&nbsp;&nbsp;/**/
 841 <BR>
 842
 843 #endif
 844 !GROK!THIS!
 845 At the top of the file, we recognize the standard .SH construct that we
 846 have already studied in detail. Next comes the extraction of the file
 847 itself, via a here document with variable substitutions. However, here
 848 we do not use a plain </R><I><FONT color=#001050>cat</I></FONT><R> but a </R><I><FONT color=#001050>sed</I></FONT><R> instead, since we need
 849 to do some further editing on-the-fly. We'll see why later on, so let's
 850 forget about it right now.
 851 <span class="paragraph_brs"> <BR><BR> </span> </R>
 852  We now reach the leading comment, and the file is tagged with the
 853 configuration time, the target system, etc... (those variables coming
 854 from the sourced <I><FONT color=#001050>config.sh</I></FONT><R> file have been set up by </R><I><FONT color=#001050>Configure</I></FONT><R>).
 855 That comment header is followed by a '#ifndef' protection to guard against
 856 multiple inclusions of this file. Then comes the heart of the file...
 857 <span class="paragraph_brs"> <BR><BR> </span> </R>
 858  It helps to know that <I><FONT color=#001050>$d_*</I></FONT><R> and </R><I><FONT color=#001050>$i_*</I></FONT><R> variables are set to
 859 either '</R><I><FONT color=#001050>define</I></FONT><R>' or '</R><I><FONT color=#001050>undef</I></FONT><R>' by </R><I><FONT color=#001050>Configure</I></FONT><R>, depending on
 860 wether a function or an include file is present on the system or not.
 861 That means the:
 862 #$d_bcopy HAS_BCOPY /**/
 863 line will be expanded to either:
 864 #define HAS_BCOPY /**/
 865 if the $d_bcopy variable is set to 'define' or:
 866 #undef HAS_BCOPY /**/
 867 if $d_bcopy was set to 'undef', because the feature was not there. However,
 868 that's not what gets written in the </R><I><FONT color=#001050>config.h</I></FONT><R> file because of the
 869 </R><I><FONT color=#001050>sed</I></FONT><R> filter we have already seen, which will transform the second form
 870 into:
 871 /*#define HAS_BCOPY /**/
 872 That's a handy form for later editing of </R><I><FONT color=#001050>config.h</I></FONT><R> because you only need
 873 to remove the leading '/*' if you want to override </R><I><FONT color=#001050>Configure</I></FONT><R>'s choice.
 874 Likewise, you may add a single '/*' at the beginning of a '#define' line
 875 to avoid the definition of a particular symbol. This is why each symbol
 876 definition is protected by a trailing '/**/', to close the leading
 877 comment opened by '/*' (comments are not nested in C).
 878 <span class="paragraph_brs"> <BR><BR> </span> </R>
 879  Now transforming '#undef' into '/*#define' is nice, but if we want to actually
 880 write a '#undef', we're stuck... unless we write it as '#un-def' and let
 881 <I><FONT color=#001050>sed</I></FONT><R> fix that to '#undef' while producing </R><I><FONT color=#001050>config.h</I></FONT><R>, which is what
 882 is actually done here.
 883 <span class="paragraph_brs"> <BR><BR> </span> </R>
 884  The same kind of reasoning applies to those two lines:
 885 #$d_dup2 HAS_DUP2&nbsp;&nbsp;&nbsp;/**/
 886 #$i_string I_STRING&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/**/
 887 and assuming <I><FONT color=#001050>config.sh</I></FONT><R> defines:
 888 d_dup2='define'
 889 i_string='undef'
 890 we'll get in the produced </R><I><FONT color=#001050>config.h</I></FONT><R>:
 891 #define HAS_DUP2&nbsp;&nbsp;&nbsp;/**/
 892 /*#define I_STRING&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/**/
 893 Clear as running water? Good!
 894 <span class="paragraph_brs"> <BR><BR> </span> </R>
 895  Now it should be obvious that by including <I><FONT color=#001050>config.h</I></FONT><R> in all your
 896 C source files, you get to know what </R><I><FONT color=#001050>Configure</I></FONT><R> has guessed on
 897 your system. In effect, by using those symbols, you are writing
 898 configured C code, since </R><I><FONT color=#001050>metaconfig</I></FONT><R> will know that you need
 899 those symbols and will generate a suitable </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file as
 900 well as all the necessary code in </R><I><FONT color=#001050>Configure</I></FONT><R> to compute a
 901 proper value for them (by assigning values to associated shell variables).
 902
 903 <span class="SS">  Running Metaconfig</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 904  Let's focus on the <I><FONT color=#001050>metaconfig</I></FONT><R> program for a while to understand how
 905 it uses its units and your source code to produce all the needed configuration
 906 files. If you intend to write new units, you should have a good understanding
 907 of the whole scheme.
 908 <span class="paragraph_brs"> <BR><BR> </span> </R>
 909  Assuming your MANIFEST.new file is properly set and lists all the source
 910 files you wish to configure, and that you have run <I><FONT color=#001050>packint</I></FONT><R> in your
 911 root source directory to create a </R><I><FONT color=#001050>.package</I></FONT><R> file, you may run
 912 </R><I><FONT color=#001050>metaconfig</I></FONT><R> and you'll get the following:
 913 $ metaconfig
 914 Locating units...
 915 Extracting dependency lists from 312 units...
 916 Extracting filenames (*.[chyl] and *.SH) from MANIFEST.new...
 917 Building a Wanted file...
 918 Scanning .[chyl] files for symbols...
 919 Scanning .SH files for symbols...
 920 Computing optimal dependency graph...
 921 Building private make file...
 922 Determining loadable units...
 923 Updating make file...
 924 Determining the correct order for the units...
 925 Creating Configure...
 926 Done.
 927 The first phase looks for all the units files (ending with .U) in the public
 928 directory first, then in your private one. If you copy a public file in your
 929 private U directory (i.e. a directory named U at the top level of your package),
 930 it will override the public version. Once it has a list of all the available
 931 units, it parses them and extracts all the ?MAKE: lines to know about the
 932 dependencies and the known shell symbols. It also focuses on the ?H: lines to
 933 learn about the C symbols and which shell symbols needs to be computed to get
 934 a proper value for that C symbol (so we have another level of dependencies
 935 here).
 936 <span class="paragraph_brs"> <BR><BR> </span> </R>
 937  Next, the proper filenames are extracted from the MANIFEST.new files and a
 938 <I><FONT color=#001050>Wanted</I></FONT><R> file is built: that file lists all the C symbols and the shell
 939 symbols needed for that package. We first scan the C-type files for C symbols,
 940 then propagate the dependencies to their associated shell symbols (gathered
 941 from ?H: lines). Next .SH files are scanned and finally all the shell symbols
 942 are known.
 943 <span class="paragraph_brs"> <BR><BR> </span> </R>
 944  A temporary Makefile is built and metaconfig tries to <I><FONT color=#001050>make</I></FONT><R> all the shell
 945 symbols to see what commands (listed on the second ?MAKE: lines) are
 946 executed, and thus which units are really needed. Optional units not otherwise
 947 required are removed and a second Makefile is generated. This time, we know
 948 about all the units and their respective orders, optional units having been
 949 removed and default values computed for their shell symbols. The </R><I><FONT color=#001050>Configure</I></FONT><R>
 950 script can then be generated, along with </R><I><FONT color=#001050>config_h.SH</I></FONT><R>. We're done.
 951
 952 <span class="SS">  Conventions</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 953  Proper conventions needs to be followed to make the whole process sound.
 954 There is a case convention for units and a variable naming convention.
 955 <span class="paragraph_brs"> <BR><BR> </span>
 956  All units should have their first letter lower-cased, unless they are
 957 special units. By special, we mean they do not really define new
 958 shell variables that can be used by the user in his .SH files, but rather
 959 units producing scripts or shell variables that are to be used internally
 960 by the <I><FONT color=#001050>Configure</I></FONT><R> script. Typical examples are the </R><I><FONT color=#001050>Init.U</I></FONT><R>
 961 file which is the main variable initialization, or </R><I><FONT color=#001050>Myread.U</I></FONT><R> which
 962 produces the </R><I><FONT color=#001050>myread</I></FONT><R> script used almost everywhere in </R><I><FONT color=#001050>Configure</I></FONT><R>
 963 when a question is to be asked to the user.
 964 <span class="paragraph_brs"> <BR><BR> </span> </R>
 965  Non-special units then subdivise in two distinct groups: units defining
 966 variables associated to a C symbol and units defining shell variables of
 967 their own. The first group is further divided in variables related to
 968 include files (their name begin with <I><FONT color=#001050>i_</I></FONT><R>) and variables related to
 969 other definitions (name starting with </R><I><FONT color=#001050>d_</I></FONT><R>). The second group have
 970 names standing for itself, for instance </R><I><FONT color=#001050>cc.U</I></FONT><R> defines the </R><I><FONT color=#001050>$cc</I></FONT><R>
 971 shell variable whose value is the C compiler to be used.
 972 <span class="paragraph_brs"> <BR><BR> </span> </R>
 973  Special units sometimes reserve themselves some pre-defined variable and
 974 return "results" in other well-known variables. For instance, the <I><FONT color=#001050>myread</I></FONT><R>
 975 script produced by Myread.U expects the prompt in </R><I><FONT color=#001050>$rp</I></FONT><R>, the default
 976 answer in </R><I><FONT color=#001050>$dflt</I></FONT><R> and places the user answer in </R><I><FONT color=#001050>$ans</I></FONT><R>. This is
 977 not documented in this manual page: you have to go and look at the unit
 978 itself to understand which variables are used and how the unit is to be
 979 used.
 980
 981 <span class="SS">  Using The Glossary</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 982  The Glossary file is automatically produced by the <I><FONT color=#001050>makegloss</I></FONT><R> script,
 983 which extracts the information from ?S:, ?C: and ?MAKE: lines and reformats
 984 them into an alphabetically sorted glossary.
 985 It is important to read the Glossary to know about the symbols you are
 986 allowed to use. However, the Glossary will not tell you how to use them.
 987 Usually, that's up to you.
 988 <span class="paragraph_brs"> <BR><BR> </span> </R>
 989  One day, you will probably write your own units and you will know enough
 990 about <I><FONT color=#001050>metaconfig</I></FONT><R> to do so quickly and efficiently. However, never
 991 forget to properly document your work in the ?S: and ?C: lines, or other
 992 people will not be able to reuse it. Remember about the time where you
 993 had only the Glossary and this manual page to get started.
 994
 995 <span class="SS">  Conclusion</span> </R><span class="paragraph_brs"> <BR><BR> </span>
 996  Now that you know the <I><FONT color=#001050>metaconfig</I></FONT><R> basics, you should read the
 997 </R><I><FONT color=#001050>DESCRIPTION</I></FONT><R> section, then skip to the </R><I><FONT color=#001050>REFERENCE</I></FONT><R> section
 998 to learn about all the gory details such as the allowed syntax for
 999 unit control lines (lines starting with a '?') or the distinct MAKE
1000 commands you are allowed to use.
1001 </UL> </R></LI> <LI> <span class="section">  REFERENCE</span> <BR> <UL> This section documents the internals of <I><FONT color=#001050>metaconfig</I></FONT><R>, basically the
1002 unit syntax, the special units you should know about and the hint files.
1003
1004 <span class="SS">  General Unit Syntax</span> </R><span class="paragraph_brs"> <BR><BR> </span>
1005  A metaconfig unit is divided into two distinct parts. The header section
1006 (lines starting with '?') and a shell section (code to be included in
1007 the <I><FONT color=#001050>Configure</I></FONT><R> script). It is possible to add '?X:' comments anywhere
1008 within the unit, but the other '?' lines (also called </R><I><FONT color=#001050>control lines</I></FONT><R>)
1009 have a strict ordering policy.
1010 <span class="paragraph_brs"> <BR><BR> </span> </R>
1011  If a control line is too long, it
1012 is possible to use a continuation by escaping the final new-line with a
1013 backslash and continuing on the next line (which should then be indented by
1014 spaces or tabs).
1015 <span class="paragraph_brs"> <BR><BR> </span>
1016  The following is a formal description of each of the control lines. Unless
1017 stated otherwise, the order of this presentation is the order to be used
1018 within the unit.
1019 <DL><DT> <!--  5--> ?RCS: <I><FONT color=#001050>free text</I></FONT><R>
1020 <DD> To be used for RCS comments, at the top of the unit.
1021 </DD> </R></DT></DL> <DL><DT> <!-- --> ?X: <I><FONT color=#001050>any text</I></FONT><R>
1022 <DD> General purpose comments. May appear anywhere in the unit but must be left
1023 justfied. For RCS comments, please use the ?RCS: comment form.
1024 </DD> </R></DT></DL> <DL><DT> <!-- --> ?MAKE:<I><FONT color=#001050>symbol list</I></FONT><R>: </R><I><FONT color=#001050>dependency list</I></FONT><R> [</R><I><FONT color=#001050>+optional</I></FONT><R>]
1025 <DD> This is the first dependency line. The first <I><FONT color=#001050>symbol list</I></FONT><R> should list
1026 all the symbols built by this unit (i.e. whose value is computed by the
1027 shell section of the unit). Symbols should be space separated. If a defined
1028 symbol is for internal use only and should&nbsp;&nbsp;not appear in the generated
1029 </R><I><FONT color=#001050>config.sh</I></FONT><R> file, then it should be preceded by a '+' (not to be confused
1030 with optional dependencies defined hereafter).
1031 The second part of the list (after the middle ':') is the unit dependency.
1032 It should list all the needed special units, as well as all the symbols
1033 used by the shell implementation. If a symbol is nedded but its configuration
1034 value is not critical, it can be preceded by a '+', in which case it is
1035 called a conditional dependency: its corresponding unit will be loaded if,
1036 and only if, that symbol is otherwise really wanted; otherwise the default
1037 value will be used.
1038 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?MAKE:<I><FONT color=#001050>tab</I></FONT><R> </R><I><FONT color=#001050>command</I></FONT><R>
1039 <DD> There can be one or more command lines following the initial dependency lines.
1040 Those commands will be executed when the unit is wanted to load them into
1041 <I><FONT color=#001050>Configure</I></FONT><R>. See the paragraph about make commands for more information.
1042 Note that the leading </R><I><FONT color=#001050>tab</I></FONT><R> character is required before the </R><I><FONT color=#001050>command</I></FONT><R>.
1043 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?Y:<I><FONT color=#001050>layout</I></FONT><R>
1044 <DD> Declare a layout directive for this unit. That directive may be one of the
1045 strings <I><FONT color=#001050>top</I></FONT><R>, </R><I><FONT color=#001050>default</I></FONT><R> or </R><I><FONT color=#001050>bottom</I></FONT><R> (case does not matter,
1046 recommended style is to spell them out uppercased). If omitted, </R><I><FONT color=#001050>default</I></FONT><R>
1047 is assumed.
1048 <BR><BR> <!-- --> </R>This directive is only required if you wish to force a unit at the top or
1049 the bottom of the generated <I><FONT color=#001050>Configure</I></FONT><R> script, as unit dependencies
1050 permit it. Important questions may thus be forced at the beginning. Within
1051 the same layout class, units are sorted alphabetically with two special
1052 cases for d_* and i_* units, forced respectively at the top and bottom of
1053 their classes (but these should belong to the default class).
1054 <BR><BR> <!-- --> </R>It you force at the top a unit whose dependencies require all the other
1055 unit to precede it, you achieve nothing interesting. Therefore, that directive
1056 should really be used to increase the priority of some interactive units
1057 that do not depend on many other user-visible symbols, like path-related
1058 questions.
1059 </DD> </R></DT></DL> <DL><DT> <!-- --> ?S:<I><FONT color=#001050>symbol_name</I></FONT><R> [(</R><I><FONT color=#001050>obsolete symbol list</I></FONT><R>)]:
1060 <DD> Introduces a shell symbol. This first line names the symbol, optionally
1061 followed by a list enclosed between parenthesis and giving the obsolete
1062 equivalent. Those obsolete symbols will be remapped to the new
1063 <I><FONT color=#001050>symbol_name</I></FONT><R> if the </R><B>-o</B><R> option is given to </R><I><FONT color=#001050>metaconfig</I></FONT><R>.
1064 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?S:<I><FONT color=#001050>any text, for Glossary</I></FONT><R>
1065 <DD> Basically a comment describing the shell symbol, which will be extracted
1066 by <I><FONT color=#001050>makegloss</I></FONT><R> into the Glossary file.
1067 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?S:.
1068 <DD> Closes the shell symbol comment.
1069 </DD> </DT></DL> <DL><DT> <!-- --> ?C:<I><FONT color=#001050>symbol_name</I></FONT><R> [~ </R><I><FONT color=#001050>alias</I></FONT><R>] [(</R><I><FONT color=#001050>obsolete symbol list</I></FONT><R>)]:
1070 <DD> Introduces a new C symbol. The <I><FONT color=#001050>alias</I></FONT><R> name is the name under which
1071 the C symbol will be controlled, i.e. if the </R><I><FONT color=#001050>alias</I></FONT><R> symbol is wanted,
1072 then that C symbol will be written in the </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file. Usually,
1073 the alias is just '%&lt;' (stands for the unit's name) and there is also
1074 a ?W: line mapping a C symbol to the </R><I><FONT color=#001050>alias</I></FONT><R>. Also the relevant parts
1075 of the ?H: lines are explicitely protected by a '?%&lt;' condition. See
1076 the symbol aliasing paragraph for more details.
1077 The remaining of the line is the optional </R><I><FONT color=#001050>obsolete symbol list</I></FONT><R>,
1078 which lists old equivalents for the new </R><I><FONT color=#001050>symbol_name</I></FONT><R>.
1079 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?C:<I><FONT color=#001050>any text, for Glossary and config_h.SH</I></FONT><R>
1080 <DD> Basically a comment describing the C symbol, which will be extracted
1081 by <I><FONT color=#001050>makegloss</I></FONT><R> into the Glossary file and by </R><I><FONT color=#001050>metaconfig</I></FONT><R> into
1082 the </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file if the symbol is wanted (or if its alias is
1083 wanted when symbol aliasing is used).
1084 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?C:.
1085 <DD> Closes the C symbol comment.
1086 </DD> </DT></DL> <DL><DT> <!-- --> ?H:?<I><FONT color=#001050>symbol</I></FONT><R>:</R><I><FONT color=#001050>config_h.SH stuff</I></FONT><R>
1087 <DD> This is the general inclusion request into <I><FONT color=#001050>config_h.SH</I></FONT><R>. The line is
1088 only written when the guarding </R><I><FONT color=#001050>symbol</I></FONT><R> is really wanted. This general
1089 form is needed when C symbol aliasing was used. Otherwise, if you use one
1090 of the other "standard" forms, the guarding is automatically done by
1091 </R><I><FONT color=#001050>metaconfig</I></FONT><R> itself.
1092 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:#<I><FONT color=#001050>$d_var VAR</I></FONT><R> "</R><I><FONT color=#001050>$var</I></FONT><R>"
1093 <DD> Conditionally defines the <I><FONT color=#001050>VAR</I></FONT><R> C symbol into </R><I><FONT color=#001050>$var</I></FONT><R> when </R><I><FONT color=#001050></I></FONT><R>
1094 is set to '</R><I><FONT color=#001050>define</I></FONT><R>'. Implies a '?</R><I><FONT color=#001050>VAR</I></FONT><R>:' guarding condition, and
1095 </R><I><FONT color=#001050>metaconfig</I></FONT><R> automatically links </R><I><FONT color=#001050>VAR</I></FONT><R> to its two shell variable
1096 dependencies (i.e. both </R><I><FONT color=#001050>$d_var</I></FONT><R> and </R><I><FONT color=#001050>$var</I></FONT><R> will be flagged as
1097 </R><I><FONT color=#001050>wanted</I></FONT><R> if </R><I><FONT color=#001050>VAR</I></FONT><R> is used in C sources).
1098 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:#define <I><FONT color=#001050>VAR</I></FONT><R> [</R><I><FONT color=#001050>optional text</I></FONT><R>]
1099 <DD> Always defines the <I><FONT color=#001050>VAR</I></FONT><R> C symbol to some value. Implies a '?</R><I><FONT color=#001050>VAR</I></FONT><R>:'
1100 guarding condition. An automatic shell dependency is made to the unit itself.
1101 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:#define <I><FONT color=#001050>VAR(x,y,z)</I></FONT><R> </R><I><FONT color=#001050>$var</I></FONT><R>
1102 <DD> Always defines the macro <I><FONT color=#001050>VAR</I></FONT><R> to be the value of the </R><I><FONT color=#001050>$var</I></FONT><R> variable.
1103 It is up to the unit to ensure </R><I><FONT color=#001050>$var</I></FONT><R> holds a&nbsp;&nbsp;sensible value. An
1104 automatic dependency between the C macro </R><I><FONT color=#001050>VAR</I></FONT><R> and the shell variable
1105 is established, and the whole line is guarded by an implicit '?</R><I><FONT color=#001050>VAR</I></FONT><R>:'.
1106 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:#<I><FONT color=#001050>$d_var VAR</I></FONT><R>
1107 <DD> Conditionally defines <I><FONT color=#001050>VAR</I></FONT><R> if </R><I><FONT color=#001050>$d_var</I></FONT><R> is set to '</R><I><FONT color=#001050>define</I></FONT><R>'.
1108 Implies a '?</R><I><FONT color=#001050>VAR</I></FONT><R>:' guarding condition. An automatic shell dependency is
1109 generated towards </R><I><FONT color=#001050>$d_war</I></FONT><R>.
1110 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:#define <I><FONT color=#001050>VAR</I></FONT><R> "</R><I><FONT color=#001050>$var</I></FONT><R>"
1111 <DD> Assigns a configured value to the <I><FONT color=#001050>VAR</I></FONT><R> C symbol. Implies a '?</R><I><FONT color=#001050>VAR</I></FONT><R>:'
1112 gurading condition. An automatic shell dependency is generated to link
1113 </R><I><FONT color=#001050>VAR</I></FONT><R> and </R><I><FONT color=#001050>$var</I></FONT><R>.
1114 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:.
1115 <DD> Closes the <I><FONT color=#001050>config_h.SH</I></FONT><R> inclusion requests.
1116 </DD> </R></DT></DL> <DL><DT> <!-- --> ?M:<I><FONT color=#001050>C symbol</I></FONT><R>: </R><I><FONT color=#001050>C dependencies</I></FONT><R>
1117 <DD> Introduces magic definition concerning the C symbol, for <I><FONT color=#001050>confmagic.h</I></FONT><R>,
1118 and defines the guarding symbol for the remaining ?M: definitions. This
1119 line silently implies '?W:%&lt;:</R><I><FONT color=#001050>C symbol</I></FONT><R>', i.e. the unit will be loaded
1120 into Configure if the C symbol appears within the C sources, whether magic
1121 is used or not. The C dependencies are activated when magic is used, in order
1122 to force their definition in </R><I><FONT color=#001050>config_h.SH</I></FONT><R>. However, if magic is </R><B>not</B><R>
1123 used but the C symbol appears in the source without the needed C dependencies,
1124 you will be warned every time the Wanted file is built, since it may be a
1125 portability issue (and also because the unit is unconditionally loaded into
1126 Configure whenever the C symbol is used, regardless of the other ?C: lines
1127 from the unit).
1128 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?M:<I><FONT color=#001050>cpp defs</I></FONT><R>
1129 <DD> Defines the magic cpp mapping to be introduced in confmagic.h whenever the
1130 concerned symbol is used. There is an implicit '?<I><FONT color=#001050>sym</I></FONT><R>' guarding where
1131 </R><I><FONT color=#001050>sym</I></FONT><R> is the symbol name defined by the leading ?M: line.
1132 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?M:.
1133 <DD> Closes the <I><FONT color=#001050>confmagic.h</I></FONT><R> inclusion request.
1134 </DD> </R></DT></DL> <DL><DT> <!-- --> ?W:<I><FONT color=#001050>shell symbol list</I></FONT><R>:</R><I><FONT color=#001050>C symbol list</I></FONT><R>
1135 <DD> Ties up the destiny of the shell symbols with that of the C symbols: if any
1136 of the C symbols listed is wanted, then all the shell symbols are marked
1137 as wanted. Useful to force inclusion of a unit (shell symbol list set to
1138 '%&lt;') when the presence of some C symbol is detected. The shell symbol list
1139 may be left empty, to benefit from the side effect of C symbol location
1140 within the builtin pre-processor (symbol being <I><FONT color=#001050>defined</I></FONT><R> for that
1141 pre-processor if located in the source). To look for patterns with a space
1142 in them, you need to quote the C symbols within simple quotes, as in
1143 'struct timezone'.
1144 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?V:<I><FONT color=#001050>read-only symbols</I></FONT><R>:</R><I><FONT color=#001050>read-write symbols</I></FONT><R>
1145 <DD> This is a <I><FONT color=#001050>metalint</I></FONT><R> hint and should be used only in special units
1146 exporting some shell variables. The variables before the middle ':'
1147 are exported read-only (changing them will issue a warning), while
1148 other symbols may be freely read and changed.
1149 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?F:<I><FONT color=#001050>files created</I></FONT><R>
1150 <DD> This line serves two purposes: it is a <I><FONT color=#001050>metalint</I></FONT><R> hint, and also
1151 a placeholder for future </R><I><FONT color=#001050>jmake</I></FONT><R> use. It must list three kind of files:
1152 the temporary one which are created for a test, the private UU ones created
1153 in the UU directory for later perusal, and the public ones left in the
1154 root directory of the package. Temporary files must be listed with a
1155 preceding '!' character (meaning "no! they're not re-used later!"), private
1156 UU files should be preceded by a './' (meaning: to use them, say </R><I><FONT color=#001050>./file</I></FONT><R>,
1157 not just </R><I><FONT color=#001050>file</I></FONT><R>), and public ones should be named as-is.
1158 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?T:<I><FONT color=#001050>shell temporaries</I></FONT><R>
1159 <DD> Another <I><FONT color=#001050>metalint</I></FONT><R> hint. This line lists all the shell variables used
1160 as temporaries within the shell section of this unit.
1161 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?D:<I><FONT color=#001050>symbol</I></FONT><R>='</R><I><FONT color=#001050>value</I></FONT><R>'
1162 <DD> Initialization value for symbols used as conditional dependencies. If no
1163 ?D: line is found, then a null value is used instead. The <I><FONT color=#001050>metalint</I></FONT><R>
1164 program will warn you if a symbol is used at least once as a conditional
1165 dependency and does not have a proper ?D: initialization. It's a good
1166 practice to add those lines even for a null initialization since it
1167 emphasizes on the possibly optional nature of a symbol.
1168 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?O:<I><FONT color=#001050>any message you want</I></FONT><R>
1169 <DD> This directive indicates that this unit is obsolete as a whole. Whenever
1170 usage of any of its symbols is made (or indirect usage via dependencies),
1171 the message is output on the screen (on stderr). You can put one ore more
1172 lines, in which case each line will be printed, in order.
1173 </DD> </R></DT></DL> <DL><DT> <!-- --> ?LINT:<I><FONT color=#001050>metalint hints</I></FONT><R>
1174 <DD> See the <I><FONT color=#001050>metalint</I></FONT><R> manual page for an explaination of the distinct
1175 hints that can be used.
1176 </DD> </R></DT></DL> </R><DL><DT> <!-- --> ?INIT:<I><FONT color=#001050>initialization code</I></FONT><R>
1177 <DD> The initialization code specified by this line will be loaded at the top
1178 of the <I><FONT color=#001050>Configure</I></FONT><R> script provided the unit is needed.
1179 </DD> </R></DT></DL> </R>
1180 <span class="SS">  C Symbol Aliasing</span> <span class="paragraph_brs"> <BR><BR> </span>
1181  Sometimes it is not possible to rely on <I><FONT color=#001050>metaconfig</I></FONT><R>'s own default
1182 selection for </R><I><FONT color=#001050>config_h.SH</I></FONT><R> comments and C symbol definition. That's
1183 where aliasing comes into play. Since it's rather tricky to explain, we'll
1184 study an example to understand the underlying mechanism.
1185 <span class="paragraph_brs"> <BR><BR> </span> </R>
1186  The d_const.U unit tries to determine whether or not your C compiler
1187 known about the <I><FONT color=#001050>const</I></FONT><R> keyword. If it doesn't we want to remap
1188 that keyword to a null string, in order to let the program compile.
1189 Moreover, we want to automatically trigger the test when the </R><I><FONT color=#001050>const</I></FONT><R>
1190 word is used.
1191 <span class="paragraph_brs"> <BR><BR> </span> </R>
1192  Here are the relevant parts of the d_const.U unit:
1193 ?MAKE:d_const: cat cc ccflags Setvar
1194 ?MAKE: -pick add $@ %&lt;
1195 ?S:d_const:
1196 ?S: This variable conditionally defines the HASCONST symbol, which
1197 ?S: indicates to the C program that this C compiler knows about the
1198 ?S: const type.
1199 ?S:.
1200 ?C:HASCONST ~ %&lt;:
1201 ?C: This symbol, if defined, indicates that this C compiler knows about
1202 ?C: the const type. There is no need to actually test for that symbol
1203 ?C: within your programs. The mere use of the "const" keyword will
1204 ?C: trigger the necessary tests.
1205 ?C:.
1206 ?H:?%&lt;:#$d_const HASCONST /**/
1207 ?H:?%&lt;:#ifndef HASCONST
1208 ?H:?%&lt;:#define const
1209 ?H:?%&lt;:#endif
1210 ?H:.
1211 ?W:%&lt;:const
1212 ?LINT:set d_const
1213 ?LINT:known const
1214 : check for const keyword
1215 echo " "
1216 echo 'Checking to see if your C compiler knows about "const"...' &gt;&4
1217 /bin/cat &gt;const.c &lt;&lt;'EOCP'
1218 main()
1219 {
1220  const char *foo;
1221 }
1222 EOCP
1223 if $cc -c $ccflags const.c &gt;/dev/null 2&gt;&1 ; then
1224  val="$define"
1225  echo "Yup, it does."
1226 else
1227  val="$undef"
1228  echo "Nope, it doesn't."
1229 fi
1230 set d_const
1231 eval $setvar
1232 First we notice the use of a ?W: line, which basically says: "This unit
1233 is wanted when the <I><FONT color=#001050>const</I></FONT><R> keyword is used in a C file.". In order
1234 to conditionally remap </R><I><FONT color=#001050>const</I></FONT><R> to a null string in </R><I><FONT color=#001050>config.h</I></FONT><R>,
1235 I chose to conditionally define </R><I><FONT color=#001050>HASCONST</I></FONT><R> via </R><I><FONT color=#001050>$d_const</I></FONT><R>.
1236 <span class="paragraph_brs"> <BR><BR> </span> </R>
1237  However, this raises a problem, because the <I><FONT color=#001050>HASCONST</I></FONT><R> symbol is not
1238 going to be used in the sources, only the </R><I><FONT color=#001050>const</I></FONT><R> token is. And the
1239 ?H: line defining </R><I><FONT color=#001050>HASCONST</I></FONT><R> is implicitely guarded by '?HASCONST'.
1240 Therefore, we must add the explicit '?%&lt;' constraint to tell </R><I><FONT color=#001050>metaconfig</I></FONT><R>
1241 that those lines should be included in </R><I><FONT color=#001050>config_h.SH</I></FONT><R> whenever the
1242 '%&lt;' symbol gets wanted (%&lt; refers to the unit's name, here </R><I><FONT color=#001050>d_const</I></FONT><R>).
1243 <span class="paragraph_brs"> <BR><BR> </span> </R>
1244  That's almost perfect, because the ?W: line will want <I><FONT color=#001050>d_const</I></FONT><R> whenever
1245 </R><I><FONT color=#001050>const</I></FONT><R> is used, then the ?H: lines will get included in the
1246 </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file. However, the leading comment (?C: lines) attached to
1247 </R><I><FONT color=#001050>HASCONST</I></FONT><R> is itself also guarded via </R><I><FONT color=#001050>HASCONST</I></FONT><R>, i.e. it has an
1248 implicit '?HASCONST' constraint. Hence the need for </R><I><FONT color=#001050>aliasing</I></FONT><R> the
1249 </R><I><FONT color=#001050>HASCONST</I></FONT><R> symbol to '%&lt;'.
1250 <span class="paragraph_brs"> <BR><BR> </span> </R>
1251  The remaining part of the unit (the shell part) is really straightforward.
1252 It simply tries to compile a sample C program using the <I><FONT color=#001050>const</I></FONT><R> keyword.
1253 If it can, then it will define </R><I><FONT color=#001050>$d_const</I></FONT><R> via the </R><I><FONT color=#001050>$setvar</I></FONT><R>
1254 fonction (defined by the </R><I><FONT color=#001050>Setvar.U</I></FONT><R> unit). See the paragraph about
1255 special units for more details.
1256
1257 <span class="SS">  Make Commands</span> </R><span class="paragraph_brs"> <BR><BR> </span>
1258  On the ?MAKE: command line, you may write a shell command to be executed as-is
1259 or a special <I><FONT color=#001050>-pick</I></FONT><R> command which is trapped by </R><I><FONT color=#001050>metaconfig</I></FONT><R> and
1260 parsed to see what should be done. The leading '-' is only there to prevent
1261 </R><I><FONT color=#001050>make</I></FONT><R> from failing when the command returns a non-zero status -- it's
1262 not really needed since we use '</R><I><FONT color=#001050>make -n</I></FONT><R>' to resolve the dependencies,
1263 but I advise you to keep it in case it becomes mandatory in future versions.
1264 The syntax of the </R><I><FONT color=#001050>pick</I></FONT><R> command is:
1265 -pick </R><I><FONT color=#001050>cmd</I></FONT><R> $@ </R><I><FONT color=#001050>target_file</I></FONT><R>
1266 where </R><I><FONT color=#001050>$@</I></FONT><R> is the standard macro within Makefiles standing for the current
1267 target (the name of the unit being built, with the final .U extension stripped).
1268 The </R><I><FONT color=#001050>cmd</I></FONT><R> part is the actual </R><I><FONT color=#001050>metaconfig</I></FONT><R> command to be run, and the
1269 </R><I><FONT color=#001050>target_file</I></FONT><R> is yet another parameter, whose interpretation depends on
1270 the </R><I><FONT color=#001050>cmd</I></FONT><R> itself. It also has its final .U extension stripped and normally
1271 refers to a unit file, unless it start with './' in which case it references
1272 one of the </R><I><FONT color=#001050>metaconfig</I></FONT><R> control files in the '</R><I><FONT color=#001050>.MT</I></FONT><R> directory.
1273 <span class="paragraph_brs"> <BR><BR> </span> </R>
1274  The available commands are:
1275 <DL><DT> <!--  10--> add
1276 <DD> Adds the <I><FONT color=#001050>target_file</I></FONT><R> to </R><I><FONT color=#001050>Configure</I></FONT><R>.
1277 </DD> </R></DT></DL> <DL><DT> <!-- --> add.Config_sh
1278 <DD> Fills in that part of <I><FONT color=#001050>Configure</I></FONT><R> producing the </R><I><FONT color=#001050>config.sh</I></FONT><R> file.
1279 Only used variables are added, conditional ones (from conditional dependencies)
1280 are skipped.
1281 </DD> </R></DT></DL> <DL><DT> <!-- --> add.Null
1282 <DD> Adds the section initializing all the shell variables used to an empty string.
1283 </DD> </DT></DL> <DL><DT> <!-- --> c_h_weed
1284 <DD> Produces the <I><FONT color=#001050>config_h.SH</I></FONT><R> file. Only the necessary lines are printed.
1285 </DD> </R></DT></DL> <DL><DT> <!-- --> cm_h_weed
1286 <DD> Produces the <I><FONT color=#001050>confmagic.h</I></FONT><R> file. Only the necessary lines are printed.
1287 This command is only enabled when the </R><B>-M</B><R> switch is given, or when a
1288 </R><I><FONT color=#001050>confmagic.h</I></FONT><R> file already exists.
1289 </DD> </R></DT></DL> <DL><DT> <!-- --> close.Config_sh
1290 <DD> Adds the final 'EOT' symbol on a line by itself to end the here document
1291 construct producing the <I><FONT color=#001050>config.sh</I></FONT><R> file.
1292 </DD> </R></DT></DL> <DL><DT> <!-- --> prepend
1293 <DD> Prepends the content of the target to the <I><FONT color=#001050>target_file</I></FONT><R> if that file is
1294 not empty.
1295 </DD> </R></DT></DL> <DL><DT> <!-- --> weed
1296 <DD> Adds the unit to <I><FONT color=#001050>Configure</I></FONT><R> like the </R><I><FONT color=#001050>add</I></FONT><R> command, but make some
1297 additional tests to remove the '?</R><I><FONT color=#001050>symbol</I></FONT><R>' and '%</R><I><FONT color=#001050>symbol</I></FONT><R>' lines
1298 from the </R><I><FONT color=#001050>target_file</I></FONT><R> if the symbol is not wanted or conditionally
1299 wanted. The '%' form is only used internally by </R><I><FONT color=#001050>metaconfig</I></FONT><R> while
1300 producing its own .U files in the '</R><I><FONT color=#001050>.MT</I></FONT><R>' directory.
1301 </DD> </R></DT></DL> <DL><DT> <!-- --> wipe
1302 <DD> Same as <I><FONT color=#001050>add</I></FONT><R> really, but performs an additional macro substitution.
1303 The available macros are described in the </R><I><FONT color=#001050>Hardwired Macros</I></FONT><R> paragraph.
1304 <span class="paragraph_brs"> <BR><BR> </span> </R>
1305  As a side note, <I><FONT color=#001050>metaconfig</I></FONT><R> generates a </R><I><FONT color=#001050>-cond</I></FONT><R> command internally
1306 to deal with conditional dependencies. You should not use it by yourself,
1307 but you will see it if scanning the generated </R><I><FONT color=#001050>Makefile</I></FONT><R> in the </R><I><FONT color=#001050>.MT</I></FONT><R>
1308 directory.
1309 </DD> </R></DT></DL>
1310 <span class="SS">  Hardwired Macros</span> <span class="paragraph_brs"> <BR><BR> </span>
1311  The following macros are recognized by the <I><FONT color=#001050>wipe</I></FONT><R> command and subsituted
1312 before inclusion in </R><I><FONT color=#001050>Configure</I></FONT><R>:
1313 <DL><DT> <!--  10--> &lt;BASEREV&gt;
1314 <DD> The base revision number of the package, derived from <I><FONT color=#001050>.package</I></FONT><R>.
1315 </DD> </R></DT></DL> <DL><DT> <!-- --> &lt;DATE&gt;
1316 <DD> The current date.
1317 </DD> </DT></DL> <DL><DT> <!-- --> &lt;MAINTLOC&gt;
1318 <DD> The e-mail address of the maintainer of this package, derived from
1319 your <I><FONT color=#001050>.package</I></FONT><R>.
1320 </DD> </R></DT></DL> <DL><DT> <!-- --> &lt;PACKAGENAME&gt;
1321 <DD> The name of the package, as derived from your <I><FONT color=#001050>.package</I></FONT><R> file.
1322 </DD> </R></DT></DL> <DL><DT> <!-- --> &lt;PATCHLEVEL&gt;
1323 <DD> The patch level of the <I><FONT color=#001050>metaconfig</I></FONT><R> program.
1324 </DD> </R></DT></DL> <DL><DT> <!-- --> &lt;VERSION&gt;
1325 <DD> The version number of the <I><FONT color=#001050>metaconfig</I></FONT><R> program.
1326 <span class="paragraph_brs"> <BR><BR> </span> </R>
1327  Those macros are mainly used to identify the <I><FONT color=#001050>metaconfig</I></FONT><R> version that
1328 generated a particular </R><I><FONT color=#001050>Configure</I></FONT><R> script and for which package it
1329 was done. The e-mail address of the maintainer is hardwired in the leading
1330 instructions that </R><I><FONT color=#001050>Configure</I></FONT><R> prints when starting.
1331 <span class="paragraph_brs"> <BR><BR> </span> </R>
1332  Recent <I><FONT color=#001050>metaconfig</I></FONT><R> versions understand a much more general syntax
1333 of the form:
1334  &lt;$variable&gt;
1335 which is replaced at Configure-generation time by the value of </R><I><FONT color=#001050>variable</I></FONT><R>
1336 taken from your </R><I><FONT color=#001050>.package</I></FONT><R> file. Eventually, the old hardwired macro
1337 format will disappear, and &lt;$baserev&gt; will replace &lt;BASEREV&gt; in all the
1338 supplied units.
1339 </DD> </R></DT></DL>
1340 <span class="SS">  Special Units</span> <span class="paragraph_brs"> <BR><BR> </span>
1341  The following special units are used to factorize code and provide higher
1342 level functionalities. They either produce a shell script that can be
1343 sourced or a shell variable that can be <I><FONT color=#001050>eval</I></FONT><R>'ed. Parameter passing
1344 is done via well-know variables, either named or anonymous like $1, $2,
1345 etc... (which can be easily set via the shell </R><I><FONT color=#001050>set</I></FONT><R> operator).
1346 When </R><I><FONT color=#001050>Configure</I></FONT><R> executes, it creates and goes into a </R><I><FONT color=#001050>UU</I></FONT><R> directory,
1347 so every produced script lies in there and does not interfere with the
1348 files from your package.
1349 <span class="paragraph_brs"> <BR><BR> </span> </R>
1350  Here are the sepcial units that you should know about, and the way to use
1351 them.
1352 <DL><DT> <!--  5--> Cppsym.U
1353 <DD> This unit produces a shell script called <I><FONT color=#001050>Cppsym</I></FONT><R>, which can be used
1354 to determine whether any symbol in a list is defined by the C preprocessor
1355 or C compiler you have specified.
1356 It can determine the status of any symbol, though the symbols in </R><I><FONT color=#001050></I></FONT><R>
1357 (attribute list) are more easily determined.
1358 </DD> </R></DT></DL> <DL><DT> <!-- --> Csym.U
1359 <DD> This sets the $csym shell variable, used internally by <I><FONT color=#001050>Configure</I></FONT><R> to
1360 check whether a given C symbol is defined or not. A typical use is:
1361 set symbol result [-fva] [previous]
1362 eval $csym
1363 That will set the </R><I><FONT color=#001050>result</I></FONT><R> variable to 'true' if the
1364 function [-f],
1365 variable [-v] or
1366 array [-a]
1367 is defined, 'false' otherwise. If a previous value is given and the </R><B>-r</B><R>
1368 switch was provided to </R><I><FONT color=#001050>Configure</I></FONT><R> (see the </R><I><FONT color=#001050>Configure Options</I></FONT><R>
1369 paragraph), then that value is re-used without questioning.
1370 <BR><BR> <!-- --> </R>The way this computation is done depends on the answer the user gives to
1371 the question <I><FONT color=#001050>Configure</I></FONT><R> will ask about whether it should perform an
1372 <span class="I">  nm</span> </R>extraction or not. If the exctraction was performed, the unit simply looks
1373 through the symbol list, otherwise it performs a compile-link test, unless
1374 <span class="B">  -r</span> was given to reuse the previously computed value, naturally...
1375 </DD> </DT></DL> <DL><DT> <!-- --> End.U
1376 <DD> By copying this unit into your private <I><FONT color=#001050>U</I></FONT><R> directory and appending
1377 dependencies on the ?MAKE: line, you can force a given unit to be loaded
1378 into </R><I><FONT color=#001050>Configure</I></FONT><R> even if it is not otherwise wanted. Some units may
1379 only be forced into </R><I><FONT color=#001050>Configure</I></FONT><R> that way.
1380 </DD> </R></DT></DL> <DL><DT> <!-- --> Filexp.U
1381 <DD> This unit produces a shell script <I><FONT color=#001050>filexp</I></FONT><R> which will expand filenames
1382 beginning with tildes. A typical use is:
1383 exp_name=`./filexp $name`
1384 to assign the expanded file name in </R><I><FONT color=#001050>exp_name</I></FONT><R>.
1385 </DD> </R></DT></DL> <DL><DT> <!-- --> Findhdr.U
1386 <DD> This unit produces a <I><FONT color=#001050>findhdr</I></FONT><R> script which is used to locate the
1387 header files in </R><I><FONT color=#001050>$usrinc</I></FONT><R> or other stranger places using cpp capabilities.
1388 The script is given an include file base name like 'stdio.h' or 'sys/file.h'
1389 and it returns the full path of the inlcude file and a zero status if found,
1390 or an empty string and a non-zero status if the file could not be located.
1391 </DD> </R></DT></DL> <DL><DT> <!-- --> Getfile.U
1392 <DD> This unit produces a bit of shell code that must be sourced in order to get
1393 a file name and make some sanity checks. Optionally, a ~name expansion is
1394 performed.
1395 <BR><BR> <!-- --> To use this unit, <I><FONT color=#001050>$rp</I></FONT><R> and </R><I><FONT color=#001050>$dflt</I></FONT><R> must hold the question and the
1396 default answer, which will be passed as-is to the </R><I><FONT color=#001050>myread</I></FONT><R> script
1397 (see forthcoming </R><I><FONT color=#001050>Myread.U</I></FONT><R>). The </R><I><FONT color=#001050>$fn</I></FONT><R> variable controls the
1398 operation and the result is returned into </R><I><FONT color=#001050>$ans</I></FONT><R>.
1399 <BR><BR> <!-- --> </R>To locate a file or directory, put 'f' or 'd' in <I><FONT color=#001050>f~/</I></FONT><R>. If a '~' appears,
1400 then ~name substitution is allowed. If a '/' appears, only absolute pathnames
1401 are accepted and ~name subsitutions are always expanded before returning.
1402 If '+' is specified, existence checks are skipped. If 'n'
1403 appears within </R><I><FONT color=#001050>$fn</I></FONT><R>, then the user is allowed to answer 'none'.
1404 <BR><BR> <!-- --> </R>Usually, unless you asked for portability, ~name substitution occurs when
1405 requested. However, there are some times you wish to bypass portability and
1406 force the substitution. You may use the 'e' letter (expand) to do that.
1407 <BR><BR> <!-- --> If the special 'l' (locate) type is used, then the <I><FONT color=#001050>$fn</I></FONT><R> variable must
1408 end with a ':', followed by a file basename. If the answer is a directory,
1409 the file basename will be appended before testing for file existence. This
1410 is useful in locate-style questions like this:
1411 dflt='~news/lib'
1412 : no need to specify 'd' or 'f' when 'l' is used
1413 fn='l~:active'
1414 rp='Where is the active file?'
1415 . ./getfile
1416 active="$ans"
1417 <BR><BR> <!-- --> </R>Additionally, the 'p' (path) letter may be used in conjunction with 'l' to
1418 tell <I><FONT color=#001050>getfile</I></FONT><R> that an answer without a '/' in it should be accepted,
1419 assuming that it will be in everyone's PATH at the time this value will be
1420 needed.
1421 <BR><BR> <!-- --> </R>Also useful is the possibility to specify a list of answers that should be
1422 accepted verbatim, bypassing all the checks. This list must be within
1423 parenthesis and items must be comma separated, with no interleaving spaces.
1424 Don't forget to quote the resulting string since parenthesis are meaningful
1425 to the shell. For instance:
1426 dflt='/bin/install'
1427 fn='/fe~(install,./install)'
1428 rp='Use which install program?'
1429 . ./getfile
1430 install="$ans"
1431 would let the user only specify fully qualified paths referring to existing
1432 files, but still allow the special "install" and "./install" answers as-is
1433 (assuming of course something will deal with them specially later on in the
1434 chain since they do not conform with the general expected frame).
1435 <BR><BR> <!-- --> If the answer to the question is 'none', then the existence checks are skipped
1436 and the empty string is returned. Note that since <I><FONT color=#001050>getfile</I></FONT><R> calls
1437 </R><I><FONT color=#001050>myread</I></FONT><R> internally, all the features available with </R><I><FONT color=#001050>myread</I></FONT><R> apply
1438 here to.
1439 <BR><BR> <!-- --> </R>If a completely expanded value is needed (for instance in a Makefile), you
1440 may use the <I><FONT color=#001050>$ansexp</I></FONT><R> variable which is always set up properly
1441 by </R><I><FONT color=#001050>getfile</I></FONT><R>
1442 as the expanded version of </R><I><FONT color=#001050>$ans</I></FONT><R>. Of course, it will not expand ~name if
1443 you did not allow that in the first place in the </R><I><FONT color=#001050>$fn</I></FONT><R> variable.
1444 </DD> </R></DT></DL> <DL><DT> <!-- --> Inhdr.U
1445 <DD> This unit produces the <I><FONT color=#001050>$inhdr</I></FONT><R> shell variable, used internally by
1446 </R><I><FONT color=#001050>Configure</I></FONT><R> to check whether a set of headers exist or not. A typical
1447 use is:
1448 set header i_header [ header2 i_header2 ... ]
1449 eval $inhdr
1450 That will print a message, saying whether the header was found or not and
1451 set the </R><I><FONT color=#001050>i_header</I></FONT><R> variable accordingly. If more than one header
1452 is specified and the first header is not found, we try the next one, until
1453 the list is empty or one is found.
1454 </DD> </R></DT></DL> <DL><DT> <!-- --> Inlibc.U
1455 <DD> This unit produces the <I><FONT color=#001050>$inlibc</I></FONT><R> shell variable, used internally
1456 by </R><I><FONT color=#001050>Configure</I></FONT><R> to check whether a given C function is defined or not.
1457 A typical use is:
1458 set function d_func
1459 eval $inlibc
1460 That will print a message, saying whether the function was found or not
1461 and set </R><I><FONT color=#001050>$d_func</I></FONT><R> accordingly. Internally, it used the </R><I><FONT color=#001050>$csym</I></FONT><R>
1462 routine.
1463 </DD> </R></DT></DL> <DL><DT> <!-- --> Loc.U
1464 <DD> This important unit produces a shell script <I><FONT color=#001050>loc</I></FONT><R> which can be used
1465 to find out where in a list of directories a given file lies. The first
1466 argument specifies the file to be located, the second argument is what
1467 will be returned if the search fails, and the reamining arguments are a
1468 list of directories where the file is to be searched. For instance:
1469 dflt=`./loc sendmail.cf X /usr/lib /var/adm/sendmail /lib`
1470 would set </R><I><FONT color=#001050>$dflt</I></FONT><R> to </R><I><FONT color=#001050>X</I></FONT><R> if no </R><I><FONT color=#001050>sendmail.cf</I></FONT><R> file was found
1471 under the listed directories, or something like </R><I><FONT color=#001050>/usr/lib/sendmail.cf</I></FONT><R>
1472 on some systems. See also </R><I><FONT color=#001050>Getfile.U</I></FONT><R>.
1473 </DD> </R></DT></DL> <DL><DT> <!-- --> MailAuthor.U
1474 <DD> This unit needs to be included on the ?MAKE: line of your own private End.U
1475 to make it into <I><FONT color=#001050>Configure</I></FONT><R>. It offers the user to register himself to
1476 the author, optionally being notified when new patches arrive or receiving
1477 them automatically when issued. You need to install </R><I><FONT color=#001050>mailagent</I></FONT><R> to do
1478 this (at least version 3.0).
1479 </DD> </R></DT></DL> <DL><DT> <!-- --> MailList.U
1480 <DD> This unit needs to be included on the ?MAKE: line of your own private End.U
1481 to make it into <I><FONT color=#001050>Configure</I></FONT><R>. It offers the user to subscribe or
1482 unsubscribe to a mailing list where discussion related to the package are
1483 taking place. You need to run </R><I><FONT color=#001050>packinit</I></FONT><R> and answer the mailing list
1484 related questions to set up the proper variables in your </R><I><FONT color=#001050>.package</I></FONT><R>
1485 before this unit may become operational.
1486 </DD> </R></DT></DL> <DL><DT> <!-- --> Myinit.U
1487 <DD> Copy this unit into your private <I><FONT color=#001050>U</I></FONT><R> directory to add your own default
1488 values to some internal variables. This unit is loaded into </R><I><FONT color=#001050>Configure</I></FONT><R>
1489 after all the default initializations have been done.
1490 </DD> </R></DT></DL> <DL><DT> <!-- --> Myread.U
1491 <DD> This unit produces the <I><FONT color=#001050>myread</I></FONT><R> shell script that must be sourced in
1492 order to do a read. It allows shell escapes, default assignment and
1493 parameter evaluation, as documented in the Instruct.U unit. It also allows
1494 dynamic setting of the </R><B>-d</B><R> option, which will be used for the remaining
1495 of the script execution.
1496 <BR><BR> <!-- --> </R>To use this unit, <I><FONT color=#001050>$rp</I></FONT><R> must hold the question and </R><I><FONT color=#001050>$dflt</I></FONT><R> should
1497 contain the default answer. The question will be printed by the script
1498 itself, and the result is returned in the </R><I><FONT color=#001050>$ans</I></FONT><R> variable.
1499 <BR><BR> <!-- --> </R>Here is a typical usage:
1500 dflt='y'
1501 rp='Question?'
1502 . ./myread
1503 value="$ans"
1504 See the unit itself for more information.
1505 </DD> </DT></DL> <DL><DT> <!-- --> Oldconfig.U
1506 <DD> This unit must be part of your dependency ?MAKE: line when some of your
1507 units tries to reuse an old symbol value. This unit is responsible for
1508 getting the old answers from <I><FONT color=#001050>config.sh</I></FONT><R> or providing useful hints
1509 when running on a given platform for the first time. See the </R><I><FONT color=#001050>Configure
1510 Hints</I></FONT><R> paragraph for more information about hints.
1511 </DD> </R></DT></DL> <DL><DT> <!-- --> Prefixit.U
1512 <DD> The purpose of this unit is to detect changes in the installation prefix
1513 directory to recompute automatically suitable defaults from previous answers.
1514 It relies on the value of the <I><FONT color=#001050>$oldprefix</I></FONT><R> variable which holds the
1515 previous prefix directory when it changed, and is empty otherwise. For instance,
1516 if the prefix was changed from </R><I><FONT color=#001050>/opt</I></FONT><R> to </R><I><FONT color=#001050>/usr/local</I></FONT><R>, then the
1517 previous binary installation directory will be changed from </R><I><FONT color=#001050>/opt/bin</I></FONT><R>
1518 to </R><I><FONT color=#001050>/usr/local/bin</I></FONT><R>, or will remain unchanged if it was, say, </R><I><FONT color=#001050>/bin</I></FONT><R>.
1519 <BR><BR> <!-- --> </R>You need to call <B>set</B><R> before issuing an </R><B>eval</B><R> on </R><I><FONT color=#001050>$prefixit</I></FONT><R>,
1520 such as:
1521 set dflt var [dir]
1522 eval $prefixit
1523 which would set </R><I><FONT color=#001050>$dflt</I></FONT><R> to </R><I><FONT color=#001050>$var</I></FONT><R> or </R><I><FONT color=#001050>$prefix/dir</I></FONT><R> depending
1524 on whether the prefix remained the same or not. If </R><I><FONT color=#001050>dir</I></FONT><R> is the
1525 string </R><I><FONT color=#001050>none</I></FONT><R>, a single space value in </R><I><FONT color=#001050>$dflt</I></FONT><R> is kept as-is, even
1526 when the prefix changes. If </R><I><FONT color=#001050>dir</I></FONT><R> is omitted, then </R><I><FONT color=#001050>$dflt</I></FONT><R> is set
1527 to an empty string if the prefix changed, to </R><I><FONT color=#001050>$var</I></FONT><R> otherwise.
1528 </DD> </R></DT></DL> <DL><DT> <!-- --> Prefixup.U
1529 <DD> The intent of thit unit is similar to that of Prefixit.U, i.e. it helps
1530 fixing the default string to accomodate prefix changes. However, the shell
1531 variable <I><FONT color=#001050>$prefixup</I></FONT><R>, when evaluated, will only restore ~name expansions,
1532 should prefix use such an escape mechanism. Use it as:
1533 set dflt
1534 eval $prefixup
1535 before prompting via </R><I><FONT color=#001050>getfile</I></FONT><R> for instance. If the prefix does not
1536 make use of ~name expanstion, then the above will be a no-op on the </R><I><FONT color=#001050>y</I></FONT><R>
1537 variable, naturally.
1538 </DD> </R></DT></DL> <DL><DT> <!-- --> Typedef.U
1539 <DD> This unit produces the <I><FONT color=#001050>$typedef</I></FONT><R> shell variable, used internally by
1540 </R><I><FONT color=#001050>Configure</I></FONT><R> to check whether a typedef exists or not. A typical
1541 use is:
1542 set typedef val_t default [ includes ]
1543 eval $typedef
1544 This will set the variable </R><I><FONT color=#001050>val_t</I></FONT><R> to the value of </R><I><FONT color=#001050>default</I></FONT><R> if the
1545 typedef was not found among the listed include files, or to </R><I><FONT color=#001050>typedef</I></FONT><R>
1546 if found. If no include files are specified, the unit looks
1547 in </R><I><FONT color=#001050>&lt;sys/types.h&gt;</I></FONT><R> only. If you specifiy some includes, only those are
1548 looked at.
1549 </DD> </R></DT></DL> <DL><DT> <!-- --> Unix.U
1550 <DD> The purpose of this unit is to define some of the most common UNIX-isms
1551 via variables which can be altered from the command line or via proper
1552 hint files. In particular, <I><FONT color=#001050>$_exe</I></FONT><R>, </R><I><FONT color=#001050>$_o</I></FONT><R> and </R><I><FONT color=#001050>$_a</I></FONT><R>
1553 are set. All the units should refer to </R><I><FONT color=#001050>$_o</I></FONT><R> and not to </R><I><FONT color=#001050>.o</I></FONT><R>
1554 directly. The '.' is part of these variables.
1555 </DD> </R></DT></DL> <DL><DT> <!-- --> Setvar.U
1556 <DD> This unit produces the <I><FONT color=#001050></I></FONT><R> variable, which is used internally
1557 by </R><I><FONT color=#001050>Configure</I></FONT><R> to set a </R><I><FONT color=#001050>define</I></FONT><R>/</R><R>undef</R><R> value to a given symbol,
1558 emitting a warning when it suddenly changes from a previous value. For instance:
1559 val="$define"
1560 set d_variable
1561 eval $setvar
1562 If the previous </R><I><FONT color=#001050>$d_variable</I></FONT><R> value was non-null and </R><I><FONT color=#001050>$val</I></FONT><R> is
1563 different, a "whoa" warning is issued.
1564 </DD> </R></DT></DL> <DL><DT> <!-- --> Whoa.U
1565 <DD> This unit produces the <I><FONT color=#001050>whoa</I></FONT><R> script, which emits a warning when the
1566 </R><I><FONT color=#001050>value</I></FONT><R> in variable whose name is </R><I><FONT color=#001050>$var</I></FONT><R> is not the same as
1567 its old previous value held in </R><I><FONT color=#001050>$was</I></FONT><R>. Upon return, </R><I><FONT color=#001050>$td</I></FONT><R> and
1568 </R><I><FONT color=#001050>$tu</I></FONT><R> hold the proper value to </R><I><FONT color=#001050>define</I></FONT><R> or </R><I><FONT color=#001050>undef</I></FONT><R> the variable.
1569 See examples in </R><I><FONT color=#001050>Inlibc.U</I></FONT><R>.
1570 </DD> </R></DT></DL>
1571 <span class="SS">  Builtin Pre-processor</span> <span class="paragraph_brs"> <BR><BR> </span>
1572  Each unit to be included in <I><FONT color=#001050>Configure</I></FONT><R> is ran through a built-in
1573 pre-processor. Pre-processor statements are introduced by the '@' character
1574 ('#' is the shell comment character). It functions merely as the C
1575 pre-processor does but allows for shell and perl escapes. Here are the
1576 available functions:
1577 <DL><DT> <!--  10--> @if <I><FONT color=#001050>expression</I></FONT><R>
1578 <DD> If <I><FONT color=#001050>expression</I></FONT><R> is true, continue loading code until @end, @elsif or @else.
1579 </DD> </R></DT></DL> </R><DL><DT> <!-- --> @elsif <I><FONT color=#001050>expression</I></FONT><R>
1580 <DD> Alternative choice. If <I><FONT color=#001050>expression</I></FONT><R> is true, continue loading code until
1581 @end, another @elsif or @else.
1582 </DD> </R></DT></DL> </R><DL><DT> <!-- --> @else
1583 <DD> Default code to be loaded if the @if <I><FONT color=#001050>expression</I></FONT><R> was false and none
1584 of the optional @elsif matched. Load until @end.
1585 </DD> </R></DT></DL> <DL><DT> <!-- --> @end
1586 <DD> Close the conditional loading statement opened by @if.
1587 </DD> </DT></DL> <DL><DT> <!-- --> @define <I><FONT color=#001050>symbol</I></FONT><R>
1588 <DD> Tells the pre-processor that <I><FONT color=#001050>symbol</I></FONT><R> is defined from now on.
1589 <span class="paragraph_brs"> <BR><BR> </span> </R>
1590  The conditional <I><FONT color=#001050>expression</I></FONT><R> can include symbol names (value is
1591 true if symbol is wanted or defined via </R><I><FONT color=#001050>@define</I></FONT><R> or shell/perl
1592 escapes. Those atoms can be combined using the traditional boolean
1593 operators '!' for negation, '&&' for logical and, and '||' for logical
1594 or.
1595 <span class="paragraph_brs"> <BR><BR> </span> </R>
1596  Text enclosed within single brackets is a shell test, while text between
1597 double brakets is a perl test. Namely the expressions:
1598 { <I><FONT color=#001050>shell text</I></FONT><R> }
1599 {{ </R><I><FONT color=#001050>perl text</I></FONT><R> }}
1600 are translated into:
1601 if </R><I><FONT color=#001050>shell text</I></FONT><R> &gt;/dev/null 2&gt;&1; then exit 0; else exit 1; fi
1602 if (</R><I><FONT color=#001050>perl text</I></FONT><R>) {exit 0;} else {exit 1;}
1603 and the exit status is used in the standard way to get a boolean value,
1604 i.e. 0 is true and everything else is false. Note that only simple
1605 conditions can be expressed in perl, until some complex code can be
1606 loaded within </R><I><FONT color=#001050>metaconfig</I></FONT><R> and executed.
1607 <span class="paragraph_brs"> <BR><BR> </span> </R>
1608  The built-in pre-processor can be used to finely tune some units
1609 (see <I><FONT color=#001050>d_gethname.U</I></FONT><R> for a complex example) depending on the symbols
1610 actually used by the program or the files present in the distribution.
1611 For instance, the </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R> uses a test like:
1612 @if {test -d ../hints}
1613 and </R><I><FONT color=#001050>Configure</I></FONT><R> will contain hint-dependent code only if there is
1614 a </R><I><FONT color=#001050>hints</I></FONT><R> directory in the package's top level directory. Note that
1615 tests are ran from within the '</R><I><FONT color=#001050>.MT</I></FONT><R>' directory, hence the needed
1616 '../' in the test.
1617 <span class="paragraph_brs"> <BR><BR> </span> </R>
1618  The pre-processor can also be used to avoid putting useless code when
1619 a symbol is not defined. Units defining more than one symbol can be
1620 protected that way (since the unit is loaded as a whole) by gathering
1621 symbol-dependent code within an @if/@end pair. For instance:
1622 @if I_TIME || I_SYS_TIME || I_SYS_TIME_KERNEL
1623 need_time_h='true'
1624 @else
1625 need_time_h='false'
1626 @end
1627 will test whether the source code makes any use of one of the three
1628 symbols that control the <I><FONT color=#001050>time.h</I></FONT><R> or </R><I><FONT color=#001050>sys/time.h</I></FONT><R> inclusion
1629 and define the shell symbol accordingly. That gives </R><I><FONT color=#001050>Configure</I></FONT><R>
1630 a feedback on what the sources need and avoid the drawback of having
1631 fixed frozen units.
1632 <span class="paragraph_brs"> <BR><BR> </span> </R>
1633  Via the '?W:' lines, you can get intersting combinations. For instance,
1634 the <I><FONT color=#001050>i_time.U</I></FONT><R> unit needs to know whether the C sources make any
1635 use of the </R><I><FONT color=#001050>struct timezone</I></FONT><R> type. Therefore, the line:
1636 ?W::timezone
1637 is used for its side-effect of defining the symbol </R><I><FONT color=#001050>timezone</I></FONT><R> for
1638 the pre-processor. The unit code can then say:
1639 @if timezone
1640 for s_timezone in '-DS_TIMEZONE' ''; do
1641 @else
1642 s_timezone=''
1643 @end
1644 <BR>
1645
1646 ... code using s_timezone ...
1647 <BR>
1648
1649 @if timezone
1650 done
1651 @end
1652 and have an extra loop trying two successive values for the </R><I><FONT color=#001050>s_timezone</I></FONT><R>
1653 variable, but only if needed.
1654 </DD> </R></DT></DL> </R>
1655 <span class="SS">  Obsolete Symbols</span> <span class="paragraph_brs"> <BR><BR> </span>
1656  Obsolete symbols are preserved to ease the transition with older
1657 <span class="I">  metaconfig</span> units. Unless the <B>-o</B><R> switch is passed to </R><I><FONT color=#001050>metaconfig</I></FONT><R> they will
1658 be ignored. However, an </R><I><FONT color=#001050>Obsolete</I></FONT><R> file will be generated, telling you
1659 which files are making use of those obsolete symbols and what are the new
1660 symbols to be used.
1661 <span class="paragraph_brs"> <BR><BR> </span> </R>
1662  The lifetime for obsolete symbols is one full revision, i.e. they will
1663 be removed when the next base revision is issued (patch upgrades do not
1664 count of course). Therefore, it is wise to translate your sources and
1665 start using the new symbols as soon as possible.
1666
1667 <span class="SS">  Configure Hints</span> <span class="paragraph_brs"> <BR><BR> </span>
1668  It may happen that the internal configuration logic makes the wrong choices.
1669 For instance, on some platform, the <I><FONT color=#001050>vfork()</I></FONT><R> system call is present but
1670 broken, so it should not be used. It is not possible to include that knowledge
1671 in the units themselves, because that might be a temporary problem which the
1672 vendor will eventually fix, or something that was introduced by a new OS
1673 upgrade.
1674 <span class="paragraph_brs"> <BR><BR> </span> </R>
1675  Anyway, for all those tiny little problems that are too system-specific,
1676 <I><FONT color=#001050>metaconfig</I></FONT><R> provides hint files support. To use it, you need to create
1677 a </R><I><FONT color=#001050>hints</I></FONT><R> directory in the package's top level directory, and have it
1678 when you run </R><I><FONT color=#001050>metaconfig</I></FONT><R>. That will load the hint-related part from
1679 </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R>.
1680 <span class="paragraph_brs"> <BR><BR> </span> </R>
1681  From then on, you may pre-set some of the shell variables <I><FONT color=#001050>Configure</I></FONT><R> uses
1682 in an OS-specific .sh file. There is code in </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R> that tries
1683 to guess which hint files are needed by computing a standard name based
1684 on the system OS name, the kernel name, the release number, etc... Since
1685 this information is likely to change rapidly, I'm not documenting it here.
1686 You have to reverse engineer the code from </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R>.
1687 <span class="paragraph_brs"> <BR><BR> </span> </R>
1688  When you first release your package, your hints file directory should be empty.
1689 If the users of your package complain that they have problem with
1690 <I><FONT color=#001050>Configure</I></FONT><R> defaults on a particular system, you have to see whether this
1691 is a platform-specific problem or a general one. In the former case, it's
1692 time to introduce a new hint file, while in the latter, the corresponding
1693 unit should be revised.
1694 <span class="paragraph_brs"> <BR><BR> </span> </R>
1695  For instance, SGI systems are known to have a broken <I><FONT color=#001050>vfork()</I></FONT><R> system
1696 call, as of this writing. And the corresponding hint file name is </R><I><FONT color=#001050>sgi.sh</I></FONT><R>.
1697 So all you need to do is create a </R><I><FONT color=#001050>hints/sgi.sh</I></FONT><R> file in which you write:
1698 d_vfork="$define"
1699 which will always remap </R><I><FONT color=#001050>vfork</I></FONT><R> on </R><I><FONT color=#001050>fork</I></FONT><R> (see </R><I><FONT color=#001050>d_vfork.U</I></FONT><R>). When
1700 running on SGI systems for the first time, </R><I><FONT color=#001050>Configure</I></FONT><R> will detect that
1701 there is an </R><I><FONT color=#001050>hints/sgi.sh</I></FONT><R> file, and that we are on an IRIX machine
1702 (the kernel name is often /irix), therefore it will propose </R><I><FONT color=#001050>sgi</I></FONT><R> as a
1703 possible hint.
1704 If the user accepts it, and since the </R><I><FONT color=#001050>$d_vfork</I></FONT><R> value is modified
1705 via the </R><I><FONT color=#001050>$setvar</I></FONT><R> call, a </R><I><FONT color=#001050>whoa!</I></FONT><R> will be emitted to warn that we
1706 are about to override the value computed by </R><I><FONT color=#001050>Configure</I></FONT><R>.
1707 <span class="paragraph_brs"> <BR><BR> </span> </R>
1708  Note that you don't have to provide <I><FONT color=#001050>all</I></FONT><R> the hints known by
1709 </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R>. If a hint file is missing, it will not be proposed as a
1710 possible choice. The heuristic tests ran to compute the possible hint
1711 candidates are flaky. If you have new values or different tests, please send
1712 them to me...
1713
1714 <span class="SS">  Overriding Choices</span> </R><span class="paragraph_brs"> <BR><BR> </span>
1715  If you create a <I><FONT color=#001050>config.over</I></FONT><R> file in the top level directory,
1716 </R><I><FONT color=#001050>Configure</I></FONT><R> will ask you if you wish to load it to override the default
1717 values. This is done prior creation of the </R><I><FONT color=#001050>config.sh</I></FONT><R> file, so it gives
1718 you a chance to patch the values stored in there.
1719 <span class="paragraph_brs"> <BR><BR> </span> </R>
1720  This is distinct from the hints approach in that it is a local file, which
1721 the user is free to create for his own usage. You should not provide such
1722 a file yourself, but let the user know about this possibility.
1723
1724 <span class="SS">  Configure Options</span> <span class="paragraph_brs"> <BR><BR> </span>
1725  The <I><FONT color=#001050>Configure</I></FONT><R> script may be called with some options specified on the
1726 command line, to slightly modify its behaviour. Here are the allowed options:
1727 <DL><DT> <!--  10--> <span class="B">  -d</span> <DD> Use defaults for all answers.
1728 </DD> </DT></DL> </R><DL><DT> <!-- --> <span class="B">  -e</span> <DD> Go on without questioning past the production of <I><FONT color=#001050>config.sh</I></FONT><R>.
1729 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -f <I><FONT color=#001050>file</I></FONT><R></span> </R><DD> Use the specified file as a default configuration. If this switch is not
1730 used, the configuration is taken from <I><FONT color=#001050>config.sh</I></FONT><R>, when present.
1731 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -h</span> <DD> Print help message and exit.
1732 </DD> </DT></DL> <DL><DT> <!-- --> <span class="B">  -r</span> <DD> Reuse C symbols value if possible. This will skip the costly <I><FONT color=#001050>nm</I></FONT><R>
1733 symbol extraction. If used the first time (with no previous configuration
1734 file), </R><I><FONT color=#001050>Configure</I></FONT><R> will try to compile and link a small program in order
1735 to know about the presence of a symbol, or absence thereof.
1736 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -s</span> <DD> Silent mode. Only strings printed on file descriptor #4 will be seen on
1737 the screen (that's the important messages). It's not possible to completely
1738 turn off any output, but you may use '<I><FONT color=#001050>Configure -ders &gt;/dev/null 2&gt;&1</I></FONT><R>'
1739 to have a full batch run with no output and no user interaction required.
1740 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -D<I><FONT color=#001050> symbol=value</I></FONT><R></span> </R><DD> Pre-defines <I><FONT color=#001050>symbol</I></FONT><R> to bear the specified </R><I><FONT color=#001050>value</I></FONT><R>. It is also
1741 possible to use '</R><B>-D</B><I><FONT color=#001050> symbol</I></FONT><R>' which will use a default value
1742 of 'define'.
1743 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -E</span> <DD> Stop at the end of the configuration questions, after having produced
1744 a <I><FONT color=#001050>config.sh</I></FONT><R>. This will not perform any '</R><I><FONT color=#001050>make depend</I></FONT><R>' or .SH files
1745 extraction.
1746 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -K</span> <DD> Knowledgeable user. When you use this option, you know what you are
1747 doing and therefore the <I><FONT color=#001050>config.sh</I></FONT><R> file will always be handled as if it
1748 was intended to be re-used, even though it might have been generated on
1749 an alien system. It also prevents aborting when </R><I><FONT color=#001050>Configure</I></FONT><R> detects
1750 an unusable C compiler or a wrong set of C flags.
1751 Further shortcuts might be turned on by this option as well in the future.
1752 This option is documented in the </R><I><FONT color=#001050>Configure</I></FONT><R> usage message, to remind
1753 us about its existence, but the given description is hoped to be cryptic
1754 enough. :-)
1755 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -O</span> <DD> Allow values specified via a <B>-D</B><R> or </R><B>-U</B><R> to override settings from
1756 any loaded configuration file. This is not the default behaviour since the
1757 overriding will not be propagated to variables derived from those you are
1758 presently altering. Naturally, without </R><B>-O</B><R>, the setting is only
1759 done when no configuration file is loaded, which is safe since derivative
1760 variables have not been computed yet...
1761 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -S</span> <DD> Perform variable substitution on all the .SH files. You can combine it with the
1762 <B>-f</B><R> switch to propagate any configuration you like.
1763 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -U<I><FONT color=#001050> symbol=</I></FONT><R></span> </R><DD> Pre-sets <I><FONT color=#001050>symbol</I></FONT><R> to bear an empty value. It is also
1764 possible to use '</R><B>-U</B><I><FONT color=#001050> symbol</I></FONT><R>' which will set </R><I><FONT color=#001050>symbol</I></FONT><R> to 'undef'.
1765 </DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B">  -V</span> <DD> Print the version number of the <I><FONT color=#001050>metaconfig</I></FONT><R> that generated this
1766 <span class="I">  Configure</span> </R>script and exit.
1767 </DD> </DT></DL>
1768 <span class="SS">  Running Environment</span> Upon starting, <I><FONT color=#001050>Configure</I></FONT><R> creates a local </R><I><FONT color=#001050>UU</I></FONT><R> directory and runs
1769 from there. The directory is removed when Configure ends, but this means
1770 you must run the script from a place where you can write, i.e. not from
1771 a read-only file system.
1772 <span class="paragraph_brs"> <BR><BR> </span> </R>
1773  You can run <I><FONT color=#001050>Configure</I></FONT><R> remotely though, as in:
1774  ../package/Configure
1775 to configure sources that are not present locally. All the generated files
1776 will be put in the directory where you're running the script from. This magic
1777 is done thanks to the src.U unit, which is setting the </R><I><FONT color=#001050>$src</I></FONT><R>
1778 and </R><I><FONT color=#001050>$rsrc</I></FONT><R> variables to point to the package sources. That path is
1779 full or relative, depending on whether </R><I><FONT color=#001050>Configure</I></FONT><R> was invoked via a
1780 full or relative path.
1781 <span class="paragraph_brs"> <BR><BR> </span> </R>
1782  From within the <I><FONT color=#001050>UU</I></FONT><R> subdirectory, you can use </R><I><FONT color=#001050>$rsrc</I></FONT><R> to access the
1783 source files (units referring to source files link hints shall always use
1784 this mechanism and not assume the file is present in the parent directory).
1785 All the Makefiles should use the $src variable as a pointer to the sources
1786 from the top of the build directory (where </R><I><FONT color=#001050>Configure</I></FONT><R> is run), either
1787 directly or via a VPATH setting.
1788 <span class="paragraph_brs"> <BR><BR> </span> </R>
1789  When running <I><FONT color=#001050>Configure</I></FONT><R> remotely, the .SH files are extracted in the
1790 build directory, not in the source tree. However, it requires some kind of
1791 a </R><I><FONT color=#001050>make</I></FONT><R> support to be able to compile things in a build directory whilst
1792 the sources lie elsewhere.
1793
1794 <span class="SS">  Using Magic Redefinitions</span> </R><span class="paragraph_brs"> <BR><BR> </span>
1795  By making use of the <B>-M</B><R> switch, some magic remappings may take place
1796 within a </R><I><FONT color=#001050>confmagic.h</I></FONT><R> file. That file needs to be included after
1797 </R><I><FONT color=#001050>config.h</I></FONT><R>, of course, but also after all the other needed include files.
1798 Namely:
1799 #include "config.h"
1800 ...
1801 ... </R><I><FONT color=#001050>other inclusions</I></FONT><R> ...
1802 ...
1803 #include "confmagic.h"
1804 Typically, </R><I><FONT color=#001050>confmagic.h</I></FONT><R> will attempt to remap </R><I><FONT color=#001050>bcopy()</I></FONT><R>
1805 on </R><I><FONT color=#001050>memcpy()</I></FONT><R> if no </R><I><FONT color=#001050>bcopy()</I></FONT><R> is available locally, or transform
1806 </R><I><FONT color=#001050>vfork</I></FONT><R> into </R><I><FONT color=#001050>fork</I></FONT><R> when necessary, hence making it useless to
1807 bother about the </R><I><FONT color=#001050>HAS_VFORK</I></FONT><R> symbol.
1808 <span class="paragraph_brs"> <BR><BR> </span> </R>
1809  This configuration magic is documented in the Glossary file.
1810
1811 <span class="SS">  Unit Templates</span> <span class="paragraph_brs"> <BR><BR> </span>
1812  There is a set of unit templates in the <I><FONT color=#001050>metaconfig</I></FONT><R> source directory,
1813 which are intended to be used by a (not yet written) program to quickly
1814 produce new units for various kind of situations. No documentation for this
1815 unfinished project, but I thought I would mention it in the manual page in
1816 case you wish to do it yourself and then contribute it...
1817 </UL> </R></LI> <LI> <span class="section">  AUTHORS</span> <BR> <UL> Larry Wall &lt;lwall@netlabs.com&gt; for version 2.0.
1818 <BR> Harlan Stenn &lt;harlan@mumps.pfcs.com&gt; for important unit extensions.
1819 <BR> Raphael Manfredi &lt;ram@hptnos02.grenoble.hp.com&gt;.
1820 <BR> Many other contributors for the
1821 <I><FONT color=#001050>metaconfig</I></FONT><R> units. See the credit file for a list.
1822 </UL> </R></LI> <LI> <span class="section">  FILES</span> <BR> <UL> <DL><DT> <!--  10--> LIB/dist/mcon/U/*.U
1823 <DD> Public unit files
1824 </DD> </DT></DL> <DL><DT> <!-- --> U/*.U
1825 <DD> Private unit files
1826 </DD> </DT></DL> <DL><DT> <!-- --> LIB/dist/mcon/Glossary
1827 <DD> Glossary file, describing all the metaconfig symbols.
1828 </DD> </DT></DL> <DL><DT> <!-- --> Obsolete
1829 <DD> Lists all the obsolete symbols used by the sources.
1830 </DD> </DT></DL> <DL><DT> <!-- --> Wanted
1831 <DD> Lists all the wanted symbols.
1832 <BR><BR> <!-- --> where LIB is /usr/share/dist.
1833 </DD> </DT></DL> </UL> </LI> <LI> <span class="section">  BUGS</span> <BR> <UL> Units are sometimes included unnecessarily if one of its symbols is
1834 accidentally mentioned, e.g. in a comment.
1835 Better too many units than too few, however.
1836 </UL> </LI> <LI> <span class="section">  SEE ALSO</span> <BR> <UL> <a href="man/1/pat.html">pat(1)</a> , <a href="man/1/makeSH.html">makeSH(1)</a> , <a href="man/1/makedist.html">makedist(1)</a> , <a href="man/1/metalint.html">metalint(1)</a>
1837 </UL> </LI> </UL> </BODY></HTML>
1838 \r
1839                 \r
1840                 </DIV>\r
1841                 </TD>\r
1842         </TR>\r
1843         <TR class="container_bottom">\r
1844                 <TD class="container_bottom">\r
1845                 \r
1846                 <DIV class="bottombaradv">\r
1847                 <script type="text/javascript"><!--\r
1848                 google_ad_client = "pub-2404433452734258";\r
1849                 google_ad_width = 728;\r
1850                 google_ad_height = 90;\r
1851                 google_ad_format = "728x90_as";\r
1852                 google_ad_type = "text_image";\r
1853                 google_ad_channel ="5458575456";\r
1854                 //--></script>\r
1855                 <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>\r
1856                 </DIV>                                          \r
1857                                 \r
1858                 <DIV class="bottombar">Current Users: 17 &copy; 1999-2006 Linux.com.hk <a href=http://Linux.com.hk/>PenguinSoft</a><br/>\r
1859 All trademarks and copyrights on this page are owned by their respective companies.\r
1860 Linux is a trademark of Linus Torvalds.\r
1861 \r
1862 </DIV>\r
1863 \r
1864                 </TD>\r
1865         </TR>\r
1866 </TABLE><!--container-->\r
1867 </DIV><!--container-->\r
1868 </BODY>\r
1869 </HTML>\r