| 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 | \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 (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:?%<: 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 %< 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 ?%<:, 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. 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. 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 $@ %< |
| 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:%<: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 '>/dev/null 2>&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. 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 '>&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. 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. 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 '<<' 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 "--> first here document:" |
| 613 | cat <<EOM |
| 614 | var='$var' |
| 615 | tar='$tar' |
| 616 | EOM |
| 617 | echo "--> second here document:" |
| 618 | cat <<'EOM' |
| 619 | echo $var |
| 620 | echo $tar |
| 621 | EOM |
| 622 | echo "--> end." |
| 623 | will produce, when run through a shell: |
| 624 | --> first here document: |
| 625 | var='first' |
| 626 | tar='second' |
| 627 | --> second here document: |
| 628 | echo $var |
| 629 | echo $tar |
| 630 | --> 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 | 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. You may delete these comments. |
| 668 | $spitshell >intsize <<!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 >>intsize <<'!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 | 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 >intsize <<!GROK!THIS! |
| 743 | $startsh |
| 744 | intsize='$intsize' |
| 745 | !GROK!THIS! |
| 746 | <BR> |
| 747 | |
| 748 | $spitshell >>intsize <<'!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 | 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 <<!GROK!THIS! >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. 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)) /* 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 <string.h> (USG systems) instead of <strings.h> (BSD systems). |
| 839 | */ |
| 840 | #$i_string I_STRING /**/ |
| 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 /**/ |
| 886 | #$i_string I_STRING /**/ |
| 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 /**/ |
| 892 | /*#define I_STRING /**/ |
| 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 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 '%<' (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 '?%<' 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 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:%<:</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 | '%<') 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 $@ %< |
| 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 ~ %<: |
| 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:?%<:#$d_const HASCONST /**/ |
| 1207 | ?H:?%<:#ifndef HASCONST |
| 1208 | ?H:?%<:#define const |
| 1209 | ?H:?%<:#endif |
| 1210 | ?H:. |
| 1211 | ?W:%<: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"...' >&4 |
| 1217 | /bin/cat >const.c <<'EOCP' |
| 1218 | main() |
| 1219 | { |
| 1220 | const char *foo; |
| 1221 | } |
| 1222 | EOCP |
| 1223 | if $cc -c $ccflags const.c >/dev/null 2>&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 '?%<' 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 | '%<' symbol gets wanted (%< 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 '%<'. |
| 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--> <BASEREV> |
| 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> <!-- --> <DATE> |
| 1316 | <DD> The current date. |
| 1317 | </DD> </DT></DL> <DL><DT> <!-- --> <MAINTLOC> |
| 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> <!-- --> <PACKAGENAME> |
| 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> <!-- --> <PATCHLEVEL> |
| 1323 | <DD> The patch level of the <I><FONT color=#001050>metaconfig</I></FONT><R> program. |
| 1324 | </DD> </R></DT></DL> <DL><DT> <!-- --> <VERSION> |
| 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 | <$variable> |
| 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 <$baserev> will replace <BASEREV> 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><sys/types.h></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> >/dev/null 2>&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 >/dev/null 2>&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 <lwall@netlabs.com> for version 2.0. |
| 1818 | <BR> Harlan Stenn <harlan@mumps.pfcs.com> for important unit extensions. |
| 1819 | <BR> Raphael Manfredi <ram@hptnos02.grenoble.hp.com>. |
| 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 © 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 |