perl5.git.perl.org Git - metaconfig.git/blame_incremental

... / ...

Commit	Line	Data
	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