Commit | Line | Data |
---|---|---|
83110c7a MB |
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 |