--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">\r
+\r
+\r
+<HTML>\r
+<HEAD>\r
+\r
+\r
+\r
+\r
+\r
+ <base href="http://linux.com.hk:80/penguin/" />\r
+ <TITLE>metaconfig - a Configure script generator
+ Linux Man Page</TITLE>\r
+\r
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">\r
+<META name="GENERATOR" content="IBM WebSphere Studio">\r
+<LINK rel="stylesheet" href="theme/Master.css" type="text/css">\r
+<LINK rel="stylesheet" href="theme/layout.css" type="text/css">\r
+<script type="text/javascript" src="js/common.js"></script>\r
+<!-- google analytics -->\r
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">\r
+</script>\r
+<script type="text/javascript">\r
+_uacct = "UA-90513-1";\r
+urchinTracker();\r
+</script>\r
+</HEAD>\r
+<BODY>\r
+\r
+\r
+\r
+<DIV class="container">\r
+<TABLE class="container">\r
+ <TR class="container_up">\r
+ <TD class="container_up"><!-- topbar -->\r
+ <DIV class="topbar"><A href="index.jsp"> <IMG border="0"\r
+ src="images/logo.png" /> </A> \r
+ <!--topbar ad area-->\r
+ <DIV id="topbaradv"> \r
+ <script type="text/javascript"><!--\r
+ google_ad_client = "pub-2404433452734258"; \r
+ google_ad_width = 468;\r
+ google_ad_height = 60;\r
+ google_ad_format = "468x60_as";\r
+ google_ad_channel ="5458575456"; \r
+ google_ad_type = "text_image"; \r
+ //--></script>\r
+ <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>\r
+ </DIV> \r
+ </DIV>\r
+ <!--- navbar --->\r
+ <CENTER class=navbar><TABLE width="100%" class="navtable">\r
+ <TR align="center" class="navtable">\r
+ <TD class="navtable"><a href=about.jsp class="navtable"> Company</a></TD>\r
+ <TD class="navtable"><a href=products.jsp class="navtable"> Products</a></TD>\r
+ <TD class="navtable"><a href=innovation.jsp class="navtable"> Innovation</a></TD>\r
+ <TD class="navtable"><a href=manpages.jsp class="navtable"> Man pages</a></TD>\r
+ <TD class="navtable"><a href=developer.jsp class="navtable"> Developer</a></TD>\r
+ <TD class="navtable"><a href=mirrors.jsp class="navtable"> Mirrors</a></TD>\r
+ <TD class="navtable"><a href=search.jsp class="navtable"> Search</a></TD>\r
+ </TR>\r
+</TABLE></CENTER>\r
+ <DIV class="sidebar">\r
+ \r
+ <!--sidebar ---> \r
+ \r
+ </DIV>\r
+ <DIV class="bodypart">\r
+ <STYLE>\r
+ DIV.bodypart {\r
+ margin-left:5px;\r
+ }\r
+ </STYLE>\r
+ \r
+ <a href="http://linux.com.hk:80/penguin/man?action=print"><img src='images/printer.gif'></a>\r
+ \r
+ <a href="http://linux.com.hk:80/penguin/man/1/m/" class="mannavlink">back to section</a>\r
+ \r
+ <script type="text/javascript"><!--\r
+ google_ad_client = "pub-2404433452734258";\r
+ google_ad_width = 468;\r
+ google_ad_height = 15;\r
+ google_ad_format = "468x15_0ads_al";\r
+ google_ad_channel ="5458575456";\r
+ google_color_border = "336699";\r
+ google_color_bg = "FFFFFF";\r
+ google_color_link = "0000FF";\r
+ google_color_url = "008000";\r
+ google_color_text = "000000";\r
+ //--></script>\r
+ <script type="text/javascript"\r
+ src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
+ </script> \r
+ \r
+ </br> \r
+ <HTML><HEAD>
+<link rel="stylesheet" type="text/css" href="theme/manpage.css">
+<TITLE>
+METACONFIG (1) manpage
+</TITLE></HEAD><BODY>
+
+<div class='man_header'><div class='man_header_left'>METACONFIG</div>
+<div class='man_header_left'>1</div>
+
+<div class='man_header_right'>Version 3.0 PL70</div>
+</div>
+
+<UL>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<LI> <span class="section"> NAME</span> <BR> <UL> metaconfig - a Configure script generator
+</UL> </LI> <LI> <span class="section"> SYNOPSIS</span> <BR> <UL> <span class="B"> metaconfig</span> [ -<B>dhkmostvwGMV</B><R> ]
+[ -</R><B>L </B><I><FONT color=#001050>dir</I></FONT><R> ]
+</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
+Configure script is, please skip to the <B>TUTORIAL</B><R> section of this
+manual page. If you want a full (formal) description of the way to
+use </R><I><FONT color=#001050>metaconfig</I></FONT><R> and its units, please look at the </R><B>REFERENCE</B><R>
+section. The following is a quick introduction and reference for
+knowledgeable users.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ <span class="B"> Metaconfig</span> operates from set of
+<span class="I"> units</span> which define everything that metaconfig knows about portability.
+Each unit is self-contained, and does not have to be registered anywhere
+other than by inclusion in either the public U directory or your private
+U directory.
+If the dist package (of which metaconfig is a part) is installed in LIB,
+then the public U directory is LIB/dist/mcon/U. On this machine, the
+LIB directory is /usr/share/dist.
+Your private U directory, if you have one,
+is in the top level directory of your package.
+Before you can run <I><FONT color=#001050>metaconfig</I></FONT><R> you must do a several things:
+<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
+<I><FONT color=#001050>packinit</I></FONT><R>.
+This program will ask you about your package and remember what you tell
+it so that all the dist programs can be smart.
+</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
+C programs in terms of the symbols that metaconfig knows how to define.
+You don't need to tell metaconfig which symbols you used, since metaconfig
+will figure that out for you.
+</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
+will depend on values defined by Configure.
+There is a program called <I><FONT color=#001050>makeSH</I></FONT><R> that will help you convert a plain
+script into a script.SH template; some editing will still need to be performed
+on the resulting .SH file to move the variable configuration part in the
+top part of the script (see inline comments generated by </R><I><FONT color=#001050>makeSH</I></FONT><R> within
+your .SH file).
+</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
+files in your package. This file will remain private and will not be
+part of the final distribution.
+The filename should be the first field on each line.
+After some whitespace you can add a short comment describing your file.
+Only source files should be listed in there. The special file
+<I><FONT color=#001050>patchlevel.h</I></FONT><R> (which is handled and maintained by the patching tools --
+see <a href="man/1/pat.html">pat(1)</a> ) should be part of the MANIFEST.new file, but may be
+silently ignored by some tools. As a rule of
+thumb, only files maintained by RCS should be listed in there,
+the </R><I><FONT color=#001050>patchlevel.h</I></FONT><R> file being one important exception.
+</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
+exported version of your MANIFEST.new. That file must be made part of
+the release, i.e. listed in both your MANIFEST.new and MANIFEST itself.
+One of the <I><FONT color=#001050>metaconfig</I></FONT><R> units knows about this file and will force
+Configure to perform a release check, ensuring all the files listed
+there are part of the distribution. The MANIFEST and MANIFEST.new
+files should be distinct, not links.
+</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.
+Any .U files in your private U directory will be used in preference to
+the one in the public U directory.
+For example, one way to force inclusion of any unit is to copy the End.U
+file to your .U directory and add the name of the unit you want as
+a dependency on the end of the ?MAKE: line.
+Certain units can ONLY be forced in this way, namely those of the form
+Warn_*.U and Chk_*.U.
+You can also customize certain default Configure variables by copying
+Myinit.U to your package's private U directory and setting the variables in
+that unit.
+<span class="paragraph_brs"> <BR><BR> </span>
+ 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>
+file, and optionally a </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file (if your sources make any use
+of C symbols).
+The generated files will automatically be added to your MANIFEST.new
+if necessary. Do not forget to update your MANIFEST file though.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ In order to create new units, do the following:
+</DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Copy a similar unit to a new .U file.
+The name you choose should be the name of a variable generated by the unit,
+although this is only a convenience for you, not a requirement.
+It should be 12 or less characters to prevent filename chopping.
+Actually, it should probably be 10 or less so that those who want to use RCS
+can have a .U,v on the end without chopping.
+Metaconfig uses the case of the first letter to determine if any variable is
+actually produced by this unit, so don't Capitalize your unit
+name if it is supposed to produce a shell variable.
+</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.
+The first ?MAKE: line indicates the dependencies; before the final list
+colon all the variables this unit defines, and after the final colon
+all the variables (or other units) on which this unit depends.
+It is very important that these lists be accurate. If a dependency is
+optional and a default value can be used, you should prefix the dependency
+with a '+' sign. The corresponding unit will not be loaded to compute the
+symbol, unless really required by another unit.
+</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
+variable defined on ?INIT: lines.
+This will move the variable definitions up to the Init.U unit,
+where they can be overridden by definitions in Myinit.U, which is
+included after Init.U.
+</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.
+A line beginning with ?H:?%<: in the .U file will be added to the eventual
+config.h file if and only if metaconfig decides that this unit is needed.
+The %< stands for the unit's name, which happens to be the name of
+the file too (without .U) if you followed the convention.
+Always put a comment on each ?H: line in case one of the variable
+substitutions earlier on the line starts a comment without finishing it.
+Any shell variable starting with d_ may do this, so beware.
+If you ommit the ?%<:, then metaconfig will try to intuit the symbol whose
+definition is needed prior any inclusion in config.h.
+</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:
+lines for C preprocessor variables.
+See a current unit for examples.
+It is VERY important to start each entry with a left justified symbol
+name, and end each entry with a ?C:. or ?S:. line. The algorithm
+that translates C preprocessor symbol entries for the Glossary into
+comments for config.h depends on this.
+</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:
+<BR><BR> <!-- --> </DD> </DT></DL> <div class='RS'> <!-- +10--> <DL><DT> <!-- 15--> ?RCS: and ?X:
+<DD> basically just comments
+</DD> </DT></DL> <DL><DT> <!-- --> ?MAKE:
+<DD> metaconfig dependencies
+</DD> </DT></DL> <DL><DT> <!-- --> ?Y:
+<DD> unit layout directive
+</DD> </DT></DL> <DL><DT> <!-- --> ?S:
+<DD> glossary shell definitions
+</DD> </DT></DL> <DL><DT> <!-- --> ?C:
+<DD> glossary C definitions
+</DD> </DT></DL> <DL><DT> <!-- --> ?H:
+<DD> config.h definitions
+</DD> </DT></DL> <DL><DT> <!-- --> ?M:
+<DD> confmagic.h definitions
+</DD> </DT></DL> <DL><DT> <!-- --> ?W:
+<DD> wanted symbols
+</DD> </DT></DL> <DL><DT> <!-- --> ?V:
+<DD> visible symbols
+</DD> </DT></DL> <DL><DT> <!-- --> ?F:
+<DD> files created by this unit
+</DD> </DT></DL> <DL><DT> <!-- --> ?T:
+<DD> temporary shell symbols used
+</DD> </DT></DL> <DL><DT> <!-- --> ?D:
+<DD> optional dependencies default value
+</DD> </DT></DL> <DL><DT> <!-- --> ?O:
+<DD> used to mark obsolete units
+</DD> </DT></DL> <DL><DT> <!-- --> ?LINT:
+<DD> metalint hints
+</DD> </DT></DL> <DL><DT> <!-- --> ?INIT:
+<DD> shell symbols initializations
+</DD> </DT></DL> </div> <!-- --> <span class="paragraph_brs"> <BR><BR> </span>
+ Here is an example to show the ordering of the lines and the various
+formats allowed:
+?RCS: $RCS-Id$
+?RCS: Copyright information
+?RCS: $RCS-Log$
+?X:
+?X: A contrived example
+?X:
+?MAKE:d_one two: three +four Five
+?MAKE: -pick add $@ %<
+?Y:DEFAULT
+?S:d_one:
+?S: First shell symbol, conditionally defines ONE.
+?S:.
+?S:two:
+?S: Second shell symbol, value for TWO.
+?S:.
+?C:ONE:
+?C: First C symbol.
+?C:.
+?C:TWO:
+?C: Second C symbol.
+?C:.
+?H:#$d_one ONE /**/
+?H:#define TWO "$two"
+?H:#$d_one ONE_TWO "$two"
+?H:.
+?M:flip: HAS_FLIP
+?M:#ifndef HAS_FLIP
+?M:#define flip(x) flop(x)
+?M:#endif
+?M:.
+?W:%<:one_two
+?V:p_one p_two:p_three
+?F:file ./ftest !tmp
+?T:tmp var
+?D:two='undef'
+?LINT:change three
+?INIT:two_init='2'
+: shell code implementing the unit follows
+p_one='one'
+p_two='two'
+p_three=""
+Let me state it one more time: the above unit definition is a <I><FONT color=#001050>fake</I></FONT><R>
+one to only show the different possibilities. Such a unit would serve
+little purpose anyway... Some more advanced features are not described
+here. Please refer to the </R><B>REFERENCE</B><R> section for more complete
+information.
+ </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.
+</DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Rerun <I><FONT color=#001050>metaconfig</I></FONT><R>.
+</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
+in the master copy, if you think it's of general interest.
+<span class="paragraph_brs"> <BR><BR> </span>
+ In order to add a new program to be located:
+</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
+(between the two colons) and to either loclist or trylist (depending
+on whether the program is mandatory or not).
+</DD> </DT></DL> <DL><DT> <span class="ip"> <img src="images/bullet.gif"></span> <DD> Rerun metaconfig.
+</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
+of general interest.
+<span class="paragraph_brs"> <BR><BR> </span>
+ Notes for writing .U files:
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always use "rm -f" because there are systems where rm is interactive by
+default.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Do not use "set -- ..." because '--' does not work with every shell. Use
+"set x ...; shift".
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always use echo " " (with a space) because of Eunice systems.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use only programs that came with V7, so that you know everyone has them.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use $contains when you want to grep conditionally, since not all
+greps return a reasonable status.
+Be sure to redirect the output to /dev/null, by using '>/dev/null 2>&1'.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use "if test" rather than "if [...]" since not every sh knows the
+latter construct.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use the myread script for inputs so that they can do shell escapes
+and default evaluation. The general form is
+case "$grimble" in
+'') dflt=452;;
+*) dflt="$grimble";;
+esac
+rp='How many grimbles do you have?'
+. ./myread
+grimble="$ans"
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Use the getfile script when asking for a file pathname in order to
+have optional ~name expansion and sanity checks. See the Getfile.U
+unit for a full decription.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always put a
+ $startsh
+at the top of every generated script that is going to be launched
+or sourced by <I><FONT color=#001050>Configure</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Never assume common UNIX-isms like the fact that an object file ends
+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>.
+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).
+</DD> </R></DT></DL> <DL><DT> <span class="ip"> *</span> <DD> When doing a compile-link-execute test, always write it like this:
+$cc $ccflags $ldflags try.c -o try $libs
+because some systems require that linking flags be specified before
+the compiled target (with the exception of trailing linking libraries).
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Issue important messages on file descriptor #4, by using '>&4' to redirect
+output. Only those messages will appear when the <B>-s</B><R> switch is
+given to </R><I><FONT color=#001050>Configure</I></FONT><R> on the command line (silent mode).
+</DD> </R></DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always try to determine whether a feature is present in the most
+specific way--don't say "if bsd" when you can grep libc. There
+are many hybrid systems out there, and each feature should stand
+or fall by itself.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> Always try to determine whether a feature is present in the most
+general way, so that other packages can use your unit.
+</DD> </DT></DL> <DL><DT> <span class="ip"> *</span> <DD> When in doubt, set a default and ask. Don't assume anything.
+</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.
+For instance, he could be running Configure on a different system than
+he is going to use the final product on.
+<span class="paragraph_brs"> <BR><BR> </span>
+ Metaconfig reserves the following names in your directory, and if you use such
+a name it may get clobbered or have other unforeseen effects:
+Configure
+Wanted
+Obsolete
+configure
+config_h.SH
+confmagic.h
+U/*
+MANIFEST.new
+Additionally, Configure may clobber these names in the directory it is run in:
+UU/*
+config.sh
+config.h
+</DD> </DT></DL>
+
+
+</UL> </LI> <LI> <span class="section"> OPTIONS</span> <BR> <UL> The following options are recognized by <I><FONT color=#001050>metaconfig</I></FONT><R>:
+<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>
+itself.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B"> -h</span> <DD> Print help message and exit.
+</DD> </DT></DL> <DL><DT> <!-- --> <span class="B"> -k</span> <DD> Keep temporary directory, so that you may examine the working files used
+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
+debugging the units.
+</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
+source files by a significant amount of time, at the expense of memory
+consumption...
+</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
+obsolete symbols in your source code and do not want (or cannot) remove
+them for now. The obsolete symbols are otherwise ignored, although that
+will give you a warning from <I><FONT color=#001050>metaconfig</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B"> -s</span> <DD> Turn silent mode on.
+</DD> </DT></DL> <DL><DT> <!-- --> <span class="B"> -t</span> <DD> Trace symbols as they are found.
+</DD> </DT></DL> <DL><DT> <!-- --> <span class="B"> -v</span> <DD> Turn verbose mode on.
+</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
+consuming phase of source code scanning, looking for known symbols.
+Use it only when you know your source file have not changed with respect
+to the pool of <I><FONT color=#001050>metaconfig</I></FONT><R> symbols used.
+</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
+<span class="I"> Configure</span> </R>script, to be included in the distribution as well. This is only
+a wrapper around the
+<span class="I"> Configure</span> script naturally, but it lets people familiar with the GNU tool to
+not be lost when facing a new distribution.
+</DD> </DT></DL> <DL><DT> <!-- --> <B>-L</B><I><FONT color=#001050> dir</I></FONT><R>
+<DD> Override default library location. Normally only useful for metaconfig
+maintainers to locally use the units being developped instead of the
+publicly available ones. The <I><FONT color=#001050>dir</I></FONT><R> specified is the one containing the
+units </R><I><FONT color=#001050>U</I></FONT><R> directory.
+</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
+well-known symbols to some other alternative, like </R><I><FONT color=#001050>bcopy</I></FONT><R>() being
+remapped transparently to </R><I><FONT color=#001050>memcpy()</I></FONT><R> when not available. This option
+is turned on automatically when a </R><I><FONT color=#001050>confmagic.h</I></FONT><R> file exists in the
+top-level directory. Simply remove that file if you wish to disable this
+option permanently.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B"> -V</span> <DD> Print version number and exit.
+</DD> </DT></DL>
+
+
+</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
+learn all the basics. If you already know how to use </R><I><FONT color=#001050>metaconfig</I></FONT><R>, you
+may safely skip to the next section.
+
+<span class="SS"> Overview</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ Usually when you want to get some source package to compile on a given
+platform you have to edit the main Makefile (assuming there is one!),
+choose a C compiler, make sure you have the proper libraries, and then
+fire the <I><FONT color=#001050>make</I></FONT><R> command. If the package is reasonably well written, it
+will compile (without a warning being an option :-). In itself, the last
+sentence is a real performance, since given the variety of UNIX platforms
+available today and the diversity of flavours, that means the author of the
+package has gone into deep trouble to figure out the right choices given
+some standard trial, guessing and messing around with system includes and
+types.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ However, despite all his talent, the author cannot possibly know that
+some system has a broken system call, or that some sytem structure lacks
+one otherwise standard field, or simply wheter a given include file exists
+or not. And I'm not considering the implicit assumptions, like the type
+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>
+system call to name a few. But that knowledge is necessary to achieve real
+portability.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Now let's not abuse ourselves. Using that information requires greater
+skills, yet it can lead to more portable programs since it is then
+written in a system-independant fashion and relies only on the fact that
+some assumption is true or false on a particular system, each assumption
+being unrelated with each other. That is to say, we do not say: We're on
+a BSD system or we are on a USG system. That's too fuzzy anyway nowadays.
+No, we want to say to the source code: this system does not have the
+<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>
+value.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Metaconfig is a tool that will let you do just that, with the additional
+benefit of not having to hand-edit the Makefile if all goes well. By
+running <I><FONT color=#001050>metaconfig</I></FONT><R>, you create a shell script named </R><I><FONT color=#001050>Configure</I></FONT><R>.
+Lots of efforts have been devoted to the Configure script internals to ensure
+it will run on 99% of the existing shells available as of this writing.
+Configure will probe the target system, asking questions when in doubt and
+gather all the answers in one single shell file, which in turn can be used
+to automatically generate configured Makefiles and C include files.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ There is only a limited (but quite large) set of symbols available for your
+shell scripts and C programs. They are all documented in the Glossary file.
+All you need to do is learn about them and start using them to address
+portability and configuration problems. Then, by running <I><FONT color=#001050>metaconfig</I></FONT><R>,
+a suitable Configure script will be generated for your package.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The Configure script is built out several units (more than 300), each
+unit being responsible for defining a small number of shell and/or C
+symbols. Units are assembled together at the final stage, honoring
+the dependency graph (one unit may need the result of several other
+units which are then placed before in the script).
+
+<span class="SS"> Symbols</span> <span class="paragraph_brs"> <BR><BR> </span>
+ Symbols are the most important thing in the <I><FONT color=#001050>metaconfig</I></FONT><R> world. They
+are the smallest recognized entity, usually a word, and can be granted
+a value at the end of the Configure execution. For instance, the C
+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
+guranteed to be defined if, and only if, the </R><I><FONT color=#001050>rename()</I></FONT><R> system call
+is present. Likewise, the </R><I><FONT color=#001050>$ranlib</I></FONT><R> shell variable will be set to
+either ':' or 'ranlib' depending on whether the call to the </R><I><FONT color=#001050>ranlib</I></FONT><R>
+program is needed to order a library file. How this works is not important
+for now, what is important is to understand that those symbols are given
+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.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Using symbols is relatively straightforward. In a C source file, you simply
+use the symbol value, as a pre-processor directive (for instance an: <I><FONT color=#001050>#ifdef
+HAS_RENAME</I></FONT><R>) or, if the symbol value is a string, directly as you would use
+a macro in C. And in a shell file or a Makefile, you may reference a shell
+symbol directly.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Actually, I'm lying, because that's not completely as magic as the previous
+paragraph could sound. In a C file, you need to include the Configure-produced
+<I><FONT color=#001050>config.h</I></FONT><R> file, and you must wrap your shell script or Makefile in a .SH
+file and you may reference the shell symbol only in the variable
+substitution part of that .SH file. More on this later.
+
+<span class="SS"> Source Files</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ Symbols may only appear in a limited set of source files, because
+<I><FONT color=#001050>metaconfig</I></FONT><R> will only scan those when looking for known symbols, trying
+to figure out which units it will need. You may use C symbols in C source
+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,
+and shell symbols are looked for only in .SH files.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ In order to get the value of a symbol, a C file needs to include the special
+<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
+are present. And .SH files are run through a shell, producing a new file.
+However, in the top section of the .SH file, the special </R><I><FONT color=#001050>config.sh</I></FONT><R>
+file (also produced by running </R><I><FONT color=#001050>Configure</I></FONT><R>) is sourced, and variable
+substitutions apply. Actually, </R><I><FONT color=#001050>config.h</I></FONT><R> is produced by running the
+</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
+substitution. So we're going to look at that a little more closely since
+this is the heart of the whole </R><I><FONT color=#001050>configuration</I></FONT><R> scheme...
+
+<span class="SS"> Variable Substitution</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ There is shell construct called <I><FONT color=#001050>here document</I></FONT><R> which enables a
+command to take an input specified within the script itself. That
+input is interpreted by the shell as a double-quoted string or a
+single quoted string depending on the form of the here document
+specification.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ To specify a here document, the '<<' token is used, followed by a single
+identifier. From then on, the remaining script lines form the input for
+the command, until the here document is found on a line by itself.
+Shell substitution (including shell variable substitutions) is done
+unless the identifier is surrounded by single quotes. For instance:
+var='first'
+tar='second'
+echo "--> first here document:"
+cat <<EOM
+var='$var'
+tar='$tar'
+EOM
+echo "--> second here document:"
+cat <<'EOM'
+echo $var
+echo $tar
+EOM
+echo "--> end."
+will produce, when run through a shell:
+--> first here document:
+var='first'
+tar='second'
+--> second here document:
+echo $var
+echo $tar
+--> end.
+The first here document has its content interpreted whilst the second
+one is output as-is. Both are useful in a .SH script, as we are about to see.
+
+<span class="SS"> Using .SH Scripts</span> <span class="paragraph_brs"> <BR><BR> </span>
+ A .SH script is usually produced by running the <I><FONT color=#001050>MakeSH</I></FONT><R> script other
+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
+a single example. Here is a little script (let's call it </R><I><FONT color=#001050>intsize</I></FONT><R>)
+which prints a single message, the size of the </R><B>int</B><R> datatype in C.
+Unfortunately, it has the value hardwired in it, thusly:
+#!/bin/sh
+intsize='4'
+echo "On this machine, the int type is $intsize bytes"
+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
+</R><I><FONT color=#001050>intsize.SH</I></FONT><R> file that looks like this:
+case $CONFIG in
+'')
+ if test -f config.sh; then TOP=.;
+ elif test -f ../config.sh; then TOP=..;
+ elif test -f ../../config.sh; then TOP=../..;
+ elif test -f ../../../config.sh; then TOP=../../..;
+ elif test -f ../../../../config.sh; then TOP=../../../..;
+ else
+ echo "Can't find config.sh."; exit 1
+ fi
+ . $TOP/config.sh
+ ;;
+esac
+: This forces SH files to create target in same directory as SH file.
+: This is so that make depend always knows where to find SH derivatives.
+case "$0" in
+*/*) cd `expr X$0 : 'X\(.*\)/'` ;;
+esac
+echo "Extracting intsize (with variable substitutions)"
+: This section of the file will have variable substitutions done on it.
+: Move anything that needs config subs from !NO!SUBS! section to !GROK!THIS!.
+: Protect any dollar signs and backticks that you do not want interpreted
+: by putting a backslash in front. You may delete these comments.
+$spitshell >intsize <<!GROK!THIS!
+$startsh
+!GROK!THIS!
+<BR>
+
+: In the following dollars and backticks do not need the extra backslash.
+$spitshell >>intsize <<'!NO!SUBS!'
+intsize='4'
+echo "On this machine, the int type is $intsize bytes"
+!NO!SUBS!
+chmod 755 intsize
+$eunicefix intsize
+The first part of this script (in the </R><I><FONT color=#001050>case</I></FONT><R> statement) is trying to
+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>
+variable is false by default, by true when </R><I><FONT color=#001050>config.sh</I></FONT><R> has been sourced
+already (which would be the case if this file was executed from within
+</R><I><FONT color=#001050>Configure</I></FONT><R> itself, but let's not confuse the issue here).
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Once the <I><FONT color=#001050>config.sh</I></FONT><R> file has been sources, all the shell symbols
+defined by </R><I><FONT color=#001050>Configure</I></FONT><R> are set. We know reach a second case statement,
+used to change the current directory should a path be used to
+reach this program (for instance if we said '</R><I><FONT color=#001050>sh ../scripts/intsize.SH</I></FONT><R>',
+we would first run '</R><I><FONT color=#001050>cd ../scripts</I></FONT><R>' before continuing). If you do not
+understand this, don't worry about it.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Here comes the intersting stuff. This script uses the <I><FONT color=#001050>$spitshell</I></FONT><R>
+variable, and it's not something we know about...yet. If you look through
+the Glossary file, you will see that this is a variable known by
+</R><I><FONT color=#001050>metaconfig</I></FONT><R>. If you make this file part of your distribution (by including
+it in the MANIFEST.new file, we'll come back to that later on) and run
+</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
+value for this variable and it will be set in </R><I><FONT color=#001050>config.sh</I></FONT><R>. Same goes for
+</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
+reasonable system, the relevant part of </R><I><FONT color=#001050>config.sh</I></FONT><R> would look like this:
+spitshell='cat'
+startsh='#!/bin/sh'
+eunicefix=':'
+Ah! We're getting there. Now it looks familiar. We're facing a single
+</R><I><FONT color=#001050>cat</I></FONT><R> command whose input comes from a variable-interpolated here
+document and whose output is redirected to </R><I><FONT color=#001050>intsize</I></FONT><R>. The value
+will be that of </R><I><FONT color=#001050>$startsh</I></FONT><R>, i.e. '#!/bin/sh'. Fine so far.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Then we reach the second here document expansion, to get the remaining of
+the script. This time, the here document symbol is surrounded by single
+quotes so the contents will be appended verbatim to the <I><FONT color=#001050>intsize</I></FONT><R> file.
+So, by running '</R><I><FONT color=#001050>sh intsize.SH</I></FONT><R>', we get the following output:
+Extracting intsize (with variable substitutions)
+and by looking at the produced intsize file, we see:
+#!/bin/sh
+intsize='4'
+echo "On this machine, the int type is $intsize bytes"
+which is exactly what we had at the beginning. So far, it's a no-operation
+procedure... But, how marvelous! It so happens (pure coincidence, trust me!),
+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
+the initialization of intsize to the variable-interpolated area of the .SH
+script and initializing it with the </R><I><FONT color=#001050>Configure</I></FONT><R>-computed value,
+and removing the now useless comments added by </R><I><FONT color=#001050>makeSH</I></FONT><R>, we get:
+case $CONFIG in
+'')
+ if test -f config.sh; then TOP=.;
+ elif test -f ../config.sh; then TOP=..;
+ elif test -f ../../config.sh; then TOP=../..;
+ elif test -f ../../../config.sh; then TOP=../../..;
+ elif test -f ../../../../config.sh; then TOP=../../../..;
+ else
+ echo "Can't find config.sh."; exit 1
+ fi
+ . $TOP/config.sh
+ ;;
+esac
+case "$0" in
+*/*) cd `expr X$0 : 'X\(.*\)/'` ;;
+esac
+echo "Extracting intsize (with variable substitutions)"
+$spitshell >intsize <<!GROK!THIS!
+$startsh
+intsize='$intsize'
+!GROK!THIS!
+<BR>
+
+$spitshell >>intsize <<'!NO!SUBS!'
+echo "On this machine, the int type is $intsize bytes"
+!NO!SUBS!
+chmod 755 intsize
+$eunicefix intsize
+Of course, running this script through a shell will again output the same
+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
+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
+8 and the </R><I><FONT color=#001050>intsize</I></FONT><R> script will bear the right value and print:
+On this machine, the int type is 8 bytes
+which is correct. Congratulations! We have just configured a shell script!!
+
+<span class="SS"> Producing config.h</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ We can now have a look at the way <I><FONT color=#001050>config.h</I></FONT><R> is produced out of
+</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
+</R><I><FONT color=#001050>config.sh</I></FONT><R> script (how exactly this is done is not strictly
+relevant here, but for the curious, it's another here document
+substitution within </R><I><FONT color=#001050>Configure</I></FONT><R> itself). The </R><I><FONT color=#001050>config_h.SH</I></FONT><R>
+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>
+is, provided you make use of at least one C symbol within your sources.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Let's have a look at some random <I><FONT color=#001050>config_h.SH</I></FONT><R> file to see what
+really happens:
+case $CONFIG in
+'')
+ if test -f config.sh; then TOP=.;
+ elif test -f ../config.sh; then TOP=..;
+ elif test -f ../../config.sh; then TOP=../..;
+ elif test -f ../../../config.sh; then TOP=../../..;
+ elif test -f ../../../../config.sh; then TOP=../../../..;
+ else
+ echo "Can't find config.sh."; exit 1
+ fi
+ . $TOP/config.sh
+ ;;
+esac
+case "$0" in
+*/*) cd `expr X$0 : 'X\(.*\)/'` ;;
+esac
+echo "Extracting config.h (with variable substitutions)"
+sed <<!GROK!THIS! >config.h -e 's!^#undef!/#define!' -e 's!^#un-def!#undef!'
+/*
+ * This file was produced by running the config_h.SH script, which
+ * gets its values from config.sh, which is generally produced by
+ * running Configure.
+ *
+ * Feel free to modify any of this as the need arises. Note, however,
+ * that running config.h.SH again will wipe out any changes you've made.
+ * For a more permanent change edit config.sh and rerun config.h.SH.
+ */
+<BR>
+
+/* Configuration time: $cf_time
+ * Configured by: $cf_by
+ * Target system: $myuname
+ */
+<BR>
+
+#ifndef _config_h_
+#define _config_h_
+<BR>
+
+/* bcopy:
+ * This symbol is maped to memcpy if the bcopy() routine is not
+ * available to copy strings.
+ */
+/* HAS_BCOPY:
+ * This symbol is defined if the bcopy() routine is available to
+ * copy blocks of memory. You should not use this symbol under
+ * normal circumstances and use bcopy() directly instead, which
+ * will get mapped to memcpy() if bcopy is not available.
+ */
+#$d_bcopy HAS_BCOPY /**/
+#ifndef HAS_BCOPY
+#ifdef bcopy
+#un-def bcopy
+#endif
+#define bcopy(s,d,l) memcpy((d),(s),(l)) /* mapped to memcpy */
+#endif
+<BR>
+
+/* HAS_DUP2:
+ * This symbol, if defined, indicates that the dup2 routine is
+ * available to duplicate file descriptors.
+ */
+#$d_dup2 HAS_DUP2 /**/
+<BR>
+
+/* I_STRING:
+ * This symbol, if defined, indicates to the C program that it should
+ * include <string.h> (USG systems) instead of <strings.h> (BSD systems).
+ */
+#$i_string I_STRING /**/
+<BR>
+
+#endif
+!GROK!THIS!
+At the top of the file, we recognize the standard .SH construct that we
+have already studied in detail. Next comes the extraction of the file
+itself, via a here document with variable substitutions. However, here
+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
+to do some further editing on-the-fly. We'll see why later on, so let's
+forget about it right now.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ We now reach the leading comment, and the file is tagged with the
+configuration time, the target system, etc... (those variables coming
+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>).
+That comment header is followed by a '#ifndef' protection to guard against
+multiple inclusions of this file. Then comes the heart of the file...
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ 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
+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
+wether a function or an include file is present on the system or not.
+That means the:
+#$d_bcopy HAS_BCOPY /**/
+line will be expanded to either:
+#define HAS_BCOPY /**/
+if the $d_bcopy variable is set to 'define' or:
+#undef HAS_BCOPY /**/
+if $d_bcopy was set to 'undef', because the feature was not there. However,
+that's not what gets written in the </R><I><FONT color=#001050>config.h</I></FONT><R> file because of the
+</R><I><FONT color=#001050>sed</I></FONT><R> filter we have already seen, which will transform the second form
+into:
+/*#define HAS_BCOPY /**/
+That's a handy form for later editing of </R><I><FONT color=#001050>config.h</I></FONT><R> because you only need
+to remove the leading '/*' if you want to override </R><I><FONT color=#001050>Configure</I></FONT><R>'s choice.
+Likewise, you may add a single '/*' at the beginning of a '#define' line
+to avoid the definition of a particular symbol. This is why each symbol
+definition is protected by a trailing '/**/', to close the leading
+comment opened by '/*' (comments are not nested in C).
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Now transforming '#undef' into '/*#define' is nice, but if we want to actually
+write a '#undef', we're stuck... unless we write it as '#un-def' and let
+<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
+is actually done here.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The same kind of reasoning applies to those two lines:
+#$d_dup2 HAS_DUP2 /**/
+#$i_string I_STRING /**/
+and assuming <I><FONT color=#001050>config.sh</I></FONT><R> defines:
+d_dup2='define'
+i_string='undef'
+we'll get in the produced </R><I><FONT color=#001050>config.h</I></FONT><R>:
+#define HAS_DUP2 /**/
+/*#define I_STRING /**/
+Clear as running water? Good!
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Now it should be obvious that by including <I><FONT color=#001050>config.h</I></FONT><R> in all your
+C source files, you get to know what </R><I><FONT color=#001050>Configure</I></FONT><R> has guessed on
+your system. In effect, by using those symbols, you are writing
+configured C code, since </R><I><FONT color=#001050>metaconfig</I></FONT><R> will know that you need
+those symbols and will generate a suitable </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file as
+well as all the necessary code in </R><I><FONT color=#001050>Configure</I></FONT><R> to compute a
+proper value for them (by assigning values to associated shell variables).
+
+<span class="SS"> Running Metaconfig</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ Let's focus on the <I><FONT color=#001050>metaconfig</I></FONT><R> program for a while to understand how
+it uses its units and your source code to produce all the needed configuration
+files. If you intend to write new units, you should have a good understanding
+of the whole scheme.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Assuming your MANIFEST.new file is properly set and lists all the source
+files you wish to configure, and that you have run <I><FONT color=#001050>packint</I></FONT><R> in your
+root source directory to create a </R><I><FONT color=#001050>.package</I></FONT><R> file, you may run
+</R><I><FONT color=#001050>metaconfig</I></FONT><R> and you'll get the following:
+$ metaconfig
+Locating units...
+Extracting dependency lists from 312 units...
+Extracting filenames (*.[chyl] and *.SH) from MANIFEST.new...
+Building a Wanted file...
+Scanning .[chyl] files for symbols...
+Scanning .SH files for symbols...
+Computing optimal dependency graph...
+Building private make file...
+Determining loadable units...
+Updating make file...
+Determining the correct order for the units...
+Creating Configure...
+Done.
+The first phase looks for all the units files (ending with .U) in the public
+directory first, then in your private one. If you copy a public file in your
+private U directory (i.e. a directory named U at the top level of your package),
+it will override the public version. Once it has a list of all the available
+units, it parses them and extracts all the ?MAKE: lines to know about the
+dependencies and the known shell symbols. It also focuses on the ?H: lines to
+learn about the C symbols and which shell symbols needs to be computed to get
+a proper value for that C symbol (so we have another level of dependencies
+here).
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Next, the proper filenames are extracted from the MANIFEST.new files and a
+<I><FONT color=#001050>Wanted</I></FONT><R> file is built: that file lists all the C symbols and the shell
+symbols needed for that package. We first scan the C-type files for C symbols,
+then propagate the dependencies to their associated shell symbols (gathered
+from ?H: lines). Next .SH files are scanned and finally all the shell symbols
+are known.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ A temporary Makefile is built and metaconfig tries to <I><FONT color=#001050>make</I></FONT><R> all the shell
+symbols to see what commands (listed on the second ?MAKE: lines) are
+executed, and thus which units are really needed. Optional units not otherwise
+required are removed and a second Makefile is generated. This time, we know
+about all the units and their respective orders, optional units having been
+removed and default values computed for their shell symbols. The </R><I><FONT color=#001050>Configure</I></FONT><R>
+script can then be generated, along with </R><I><FONT color=#001050>config_h.SH</I></FONT><R>. We're done.
+
+<span class="SS"> Conventions</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ Proper conventions needs to be followed to make the whole process sound.
+There is a case convention for units and a variable naming convention.
+<span class="paragraph_brs"> <BR><BR> </span>
+ All units should have their first letter lower-cased, unless they are
+special units. By special, we mean they do not really define new
+shell variables that can be used by the user in his .SH files, but rather
+units producing scripts or shell variables that are to be used internally
+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>
+file which is the main variable initialization, or </R><I><FONT color=#001050>Myread.U</I></FONT><R> which
+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>
+when a question is to be asked to the user.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Non-special units then subdivise in two distinct groups: units defining
+variables associated to a C symbol and units defining shell variables of
+their own. The first group is further divided in variables related to
+include files (their name begin with <I><FONT color=#001050>i_</I></FONT><R>) and variables related to
+other definitions (name starting with </R><I><FONT color=#001050>d_</I></FONT><R>). The second group have
+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>
+shell variable whose value is the C compiler to be used.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Special units sometimes reserve themselves some pre-defined variable and
+return "results" in other well-known variables. For instance, the <I><FONT color=#001050>myread</I></FONT><R>
+script produced by Myread.U expects the prompt in </R><I><FONT color=#001050>$rp</I></FONT><R>, the default
+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
+not documented in this manual page: you have to go and look at the unit
+itself to understand which variables are used and how the unit is to be
+used.
+
+<span class="SS"> Using The Glossary</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ The Glossary file is automatically produced by the <I><FONT color=#001050>makegloss</I></FONT><R> script,
+which extracts the information from ?S:, ?C: and ?MAKE: lines and reformats
+them into an alphabetically sorted glossary.
+It is important to read the Glossary to know about the symbols you are
+allowed to use. However, the Glossary will not tell you how to use them.
+Usually, that's up to you.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ One day, you will probably write your own units and you will know enough
+about <I><FONT color=#001050>metaconfig</I></FONT><R> to do so quickly and efficiently. However, never
+forget to properly document your work in the ?S: and ?C: lines, or other
+people will not be able to reuse it. Remember about the time where you
+had only the Glossary and this manual page to get started.
+
+<span class="SS"> Conclusion</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ Now that you know the <I><FONT color=#001050>metaconfig</I></FONT><R> basics, you should read the
+</R><I><FONT color=#001050>DESCRIPTION</I></FONT><R> section, then skip to the </R><I><FONT color=#001050>REFERENCE</I></FONT><R> section
+to learn about all the gory details such as the allowed syntax for
+unit control lines (lines starting with a '?') or the distinct MAKE
+commands you are allowed to use.
+</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
+unit syntax, the special units you should know about and the hint files.
+
+<span class="SS"> General Unit Syntax</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ A metaconfig unit is divided into two distinct parts. The header section
+(lines starting with '?') and a shell section (code to be included in
+the <I><FONT color=#001050>Configure</I></FONT><R> script). It is possible to add '?X:' comments anywhere
+within the unit, but the other '?' lines (also called </R><I><FONT color=#001050>control lines</I></FONT><R>)
+have a strict ordering policy.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ If a control line is too long, it
+is possible to use a continuation by escaping the final new-line with a
+backslash and continuing on the next line (which should then be indented by
+spaces or tabs).
+<span class="paragraph_brs"> <BR><BR> </span>
+ The following is a formal description of each of the control lines. Unless
+stated otherwise, the order of this presentation is the order to be used
+within the unit.
+<DL><DT> <!-- 5--> ?RCS: <I><FONT color=#001050>free text</I></FONT><R>
+<DD> To be used for RCS comments, at the top of the unit.
+</DD> </R></DT></DL> <DL><DT> <!-- --> ?X: <I><FONT color=#001050>any text</I></FONT><R>
+<DD> General purpose comments. May appear anywhere in the unit but must be left
+justfied. For RCS comments, please use the ?RCS: comment form.
+</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>]
+<DD> This is the first dependency line. The first <I><FONT color=#001050>symbol list</I></FONT><R> should list
+all the symbols built by this unit (i.e. whose value is computed by the
+shell section of the unit). Symbols should be space separated. If a defined
+symbol is for internal use only and should not appear in the generated
+</R><I><FONT color=#001050>config.sh</I></FONT><R> file, then it should be preceded by a '+' (not to be confused
+with optional dependencies defined hereafter).
+The second part of the list (after the middle ':') is the unit dependency.
+It should list all the needed special units, as well as all the symbols
+used by the shell implementation. If a symbol is nedded but its configuration
+value is not critical, it can be preceded by a '+', in which case it is
+called a conditional dependency: its corresponding unit will be loaded if,
+and only if, that symbol is otherwise really wanted; otherwise the default
+value will be used.
+</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>
+<DD> There can be one or more command lines following the initial dependency lines.
+Those commands will be executed when the unit is wanted to load them into
+<I><FONT color=#001050>Configure</I></FONT><R>. See the paragraph about make commands for more information.
+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>.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?Y:<I><FONT color=#001050>layout</I></FONT><R>
+<DD> Declare a layout directive for this unit. That directive may be one of the
+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,
+recommended style is to spell them out uppercased). If omitted, </R><I><FONT color=#001050>default</I></FONT><R>
+is assumed.
+<BR><BR> <!-- --> </R>This directive is only required if you wish to force a unit at the top or
+the bottom of the generated <I><FONT color=#001050>Configure</I></FONT><R> script, as unit dependencies
+permit it. Important questions may thus be forced at the beginning. Within
+the same layout class, units are sorted alphabetically with two special
+cases for d_* and i_* units, forced respectively at the top and bottom of
+their classes (but these should belong to the default class).
+<BR><BR> <!-- --> </R>It you force at the top a unit whose dependencies require all the other
+unit to precede it, you achieve nothing interesting. Therefore, that directive
+should really be used to increase the priority of some interactive units
+that do not depend on many other user-visible symbols, like path-related
+questions.
+</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>)]:
+<DD> Introduces a shell symbol. This first line names the symbol, optionally
+followed by a list enclosed between parenthesis and giving the obsolete
+equivalent. Those obsolete symbols will be remapped to the new
+<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>.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?S:<I><FONT color=#001050>any text, for Glossary</I></FONT><R>
+<DD> Basically a comment describing the shell symbol, which will be extracted
+by <I><FONT color=#001050>makegloss</I></FONT><R> into the Glossary file.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?S:.
+<DD> Closes the shell symbol comment.
+</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>)]:
+<DD> Introduces a new C symbol. The <I><FONT color=#001050>alias</I></FONT><R> name is the name under which
+the C symbol will be controlled, i.e. if the </R><I><FONT color=#001050>alias</I></FONT><R> symbol is wanted,
+then that C symbol will be written in the </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file. Usually,
+the alias is just '%<' (stands for the unit's name) and there is also
+a ?W: line mapping a C symbol to the </R><I><FONT color=#001050>alias</I></FONT><R>. Also the relevant parts
+of the ?H: lines are explicitely protected by a '?%<' condition. See
+the symbol aliasing paragraph for more details.
+The remaining of the line is the optional </R><I><FONT color=#001050>obsolete symbol list</I></FONT><R>,
+which lists old equivalents for the new </R><I><FONT color=#001050>symbol_name</I></FONT><R>.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?C:<I><FONT color=#001050>any text, for Glossary and config_h.SH</I></FONT><R>
+<DD> Basically a comment describing the C symbol, which will be extracted
+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
+the </R><I><FONT color=#001050>config_h.SH</I></FONT><R> file if the symbol is wanted (or if its alias is
+wanted when symbol aliasing is used).
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?C:.
+<DD> Closes the C symbol comment.
+</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>
+<DD> This is the general inclusion request into <I><FONT color=#001050>config_h.SH</I></FONT><R>. The line is
+only written when the guarding </R><I><FONT color=#001050>symbol</I></FONT><R> is really wanted. This general
+form is needed when C symbol aliasing was used. Otherwise, if you use one
+of the other "standard" forms, the guarding is automatically done by
+</R><I><FONT color=#001050>metaconfig</I></FONT><R> itself.
+</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>"
+<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>
+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
+</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
+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
+</R><I><FONT color=#001050>wanted</I></FONT><R> if </R><I><FONT color=#001050>VAR</I></FONT><R> is used in C sources).
+</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>]
+<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>:'
+guarding condition. An automatic shell dependency is made to the unit itself.
+</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>
+<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.
+It is up to the unit to ensure </R><I><FONT color=#001050>$var</I></FONT><R> holds a sensible value. An
+automatic dependency between the C macro </R><I><FONT color=#001050>VAR</I></FONT><R> and the shell variable
+is established, and the whole line is guarded by an implicit '?</R><I><FONT color=#001050>VAR</I></FONT><R>:'.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:#<I><FONT color=#001050>$d_var VAR</I></FONT><R>
+<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>'.
+Implies a '?</R><I><FONT color=#001050>VAR</I></FONT><R>:' guarding condition. An automatic shell dependency is
+generated towards </R><I><FONT color=#001050>$d_war</I></FONT><R>.
+</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>"
+<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>:'
+gurading condition. An automatic shell dependency is generated to link
+</R><I><FONT color=#001050>VAR</I></FONT><R> and </R><I><FONT color=#001050>$var</I></FONT><R>.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?H:.
+<DD> Closes the <I><FONT color=#001050>config_h.SH</I></FONT><R> inclusion requests.
+</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>
+<DD> Introduces magic definition concerning the C symbol, for <I><FONT color=#001050>confmagic.h</I></FONT><R>,
+and defines the guarding symbol for the remaining ?M: definitions. This
+line silently implies '?W:%<:</R><I><FONT color=#001050>C symbol</I></FONT><R>', i.e. the unit will be loaded
+into Configure if the C symbol appears within the C sources, whether magic
+is used or not. The C dependencies are activated when magic is used, in order
+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>
+used but the C symbol appears in the source without the needed C dependencies,
+you will be warned every time the Wanted file is built, since it may be a
+portability issue (and also because the unit is unconditionally loaded into
+Configure whenever the C symbol is used, regardless of the other ?C: lines
+from the unit).
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?M:<I><FONT color=#001050>cpp defs</I></FONT><R>
+<DD> Defines the magic cpp mapping to be introduced in confmagic.h whenever the
+concerned symbol is used. There is an implicit '?<I><FONT color=#001050>sym</I></FONT><R>' guarding where
+</R><I><FONT color=#001050>sym</I></FONT><R> is the symbol name defined by the leading ?M: line.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?M:.
+<DD> Closes the <I><FONT color=#001050>confmagic.h</I></FONT><R> inclusion request.
+</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>
+<DD> Ties up the destiny of the shell symbols with that of the C symbols: if any
+of the C symbols listed is wanted, then all the shell symbols are marked
+as wanted. Useful to force inclusion of a unit (shell symbol list set to
+'%<') when the presence of some C symbol is detected. The shell symbol list
+may be left empty, to benefit from the side effect of C symbol location
+within the builtin pre-processor (symbol being <I><FONT color=#001050>defined</I></FONT><R> for that
+pre-processor if located in the source). To look for patterns with a space
+in them, you need to quote the C symbols within simple quotes, as in
+'struct timezone'.
+</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>
+<DD> This is a <I><FONT color=#001050>metalint</I></FONT><R> hint and should be used only in special units
+exporting some shell variables. The variables before the middle ':'
+are exported read-only (changing them will issue a warning), while
+other symbols may be freely read and changed.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?F:<I><FONT color=#001050>files created</I></FONT><R>
+<DD> This line serves two purposes: it is a <I><FONT color=#001050>metalint</I></FONT><R> hint, and also
+a placeholder for future </R><I><FONT color=#001050>jmake</I></FONT><R> use. It must list three kind of files:
+the temporary one which are created for a test, the private UU ones created
+in the UU directory for later perusal, and the public ones left in the
+root directory of the package. Temporary files must be listed with a
+preceding '!' character (meaning "no! they're not re-used later!"), private
+UU files should be preceded by a './' (meaning: to use them, say </R><I><FONT color=#001050>./file</I></FONT><R>,
+not just </R><I><FONT color=#001050>file</I></FONT><R>), and public ones should be named as-is.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?T:<I><FONT color=#001050>shell temporaries</I></FONT><R>
+<DD> Another <I><FONT color=#001050>metalint</I></FONT><R> hint. This line lists all the shell variables used
+as temporaries within the shell section of this unit.
+</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>'
+<DD> Initialization value for symbols used as conditional dependencies. If no
+?D: line is found, then a null value is used instead. The <I><FONT color=#001050>metalint</I></FONT><R>
+program will warn you if a symbol is used at least once as a conditional
+dependency and does not have a proper ?D: initialization. It's a good
+practice to add those lines even for a null initialization since it
+emphasizes on the possibly optional nature of a symbol.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?O:<I><FONT color=#001050>any message you want</I></FONT><R>
+<DD> This directive indicates that this unit is obsolete as a whole. Whenever
+usage of any of its symbols is made (or indirect usage via dependencies),
+the message is output on the screen (on stderr). You can put one ore more
+lines, in which case each line will be printed, in order.
+</DD> </R></DT></DL> <DL><DT> <!-- --> ?LINT:<I><FONT color=#001050>metalint hints</I></FONT><R>
+<DD> See the <I><FONT color=#001050>metalint</I></FONT><R> manual page for an explaination of the distinct
+hints that can be used.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> ?INIT:<I><FONT color=#001050>initialization code</I></FONT><R>
+<DD> The initialization code specified by this line will be loaded at the top
+of the <I><FONT color=#001050>Configure</I></FONT><R> script provided the unit is needed.
+</DD> </R></DT></DL> </R>
+<span class="SS"> C Symbol Aliasing</span> <span class="paragraph_brs"> <BR><BR> </span>
+ Sometimes it is not possible to rely on <I><FONT color=#001050>metaconfig</I></FONT><R>'s own default
+selection for </R><I><FONT color=#001050>config_h.SH</I></FONT><R> comments and C symbol definition. That's
+where aliasing comes into play. Since it's rather tricky to explain, we'll
+study an example to understand the underlying mechanism.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The d_const.U unit tries to determine whether or not your C compiler
+known about the <I><FONT color=#001050>const</I></FONT><R> keyword. If it doesn't we want to remap
+that keyword to a null string, in order to let the program compile.
+Moreover, we want to automatically trigger the test when the </R><I><FONT color=#001050>const</I></FONT><R>
+word is used.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Here are the relevant parts of the d_const.U unit:
+?MAKE:d_const: cat cc ccflags Setvar
+?MAKE: -pick add $@ %<
+?S:d_const:
+?S: This variable conditionally defines the HASCONST symbol, which
+?S: indicates to the C program that this C compiler knows about the
+?S: const type.
+?S:.
+?C:HASCONST ~ %<:
+?C: This symbol, if defined, indicates that this C compiler knows about
+?C: the const type. There is no need to actually test for that symbol
+?C: within your programs. The mere use of the "const" keyword will
+?C: trigger the necessary tests.
+?C:.
+?H:?%<:#$d_const HASCONST /**/
+?H:?%<:#ifndef HASCONST
+?H:?%<:#define const
+?H:?%<:#endif
+?H:.
+?W:%<:const
+?LINT:set d_const
+?LINT:known const
+: check for const keyword
+echo " "
+echo 'Checking to see if your C compiler knows about "const"...' >&4
+/bin/cat >const.c <<'EOCP'
+main()
+{
+ const char *foo;
+}
+EOCP
+if $cc -c $ccflags const.c >/dev/null 2>&1 ; then
+ val="$define"
+ echo "Yup, it does."
+else
+ val="$undef"
+ echo "Nope, it doesn't."
+fi
+set d_const
+eval $setvar
+First we notice the use of a ?W: line, which basically says: "This unit
+is wanted when the <I><FONT color=#001050>const</I></FONT><R> keyword is used in a C file.". In order
+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>,
+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>.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ However, this raises a problem, because the <I><FONT color=#001050>HASCONST</I></FONT><R> symbol is not
+going to be used in the sources, only the </R><I><FONT color=#001050>const</I></FONT><R> token is. And the
+?H: line defining </R><I><FONT color=#001050>HASCONST</I></FONT><R> is implicitely guarded by '?HASCONST'.
+Therefore, we must add the explicit '?%<' constraint to tell </R><I><FONT color=#001050>metaconfig</I></FONT><R>
+that those lines should be included in </R><I><FONT color=#001050>config_h.SH</I></FONT><R> whenever the
+'%<' symbol gets wanted (%< refers to the unit's name, here </R><I><FONT color=#001050>d_const</I></FONT><R>).
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ That's almost perfect, because the ?W: line will want <I><FONT color=#001050>d_const</I></FONT><R> whenever
+</R><I><FONT color=#001050>const</I></FONT><R> is used, then the ?H: lines will get included in the
+</R><I><FONT color=#001050>config_h.SH</I></FONT><R> file. However, the leading comment (?C: lines) attached to
+</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
+implicit '?HASCONST' constraint. Hence the need for </R><I><FONT color=#001050>aliasing</I></FONT><R> the
+</R><I><FONT color=#001050>HASCONST</I></FONT><R> symbol to '%<'.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The remaining part of the unit (the shell part) is really straightforward.
+It simply tries to compile a sample C program using the <I><FONT color=#001050>const</I></FONT><R> keyword.
+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>
+fonction (defined by the </R><I><FONT color=#001050>Setvar.U</I></FONT><R> unit). See the paragraph about
+special units for more details.
+
+<span class="SS"> Make Commands</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ On the ?MAKE: command line, you may write a shell command to be executed as-is
+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
+parsed to see what should be done. The leading '-' is only there to prevent
+</R><I><FONT color=#001050>make</I></FONT><R> from failing when the command returns a non-zero status -- it's
+not really needed since we use '</R><I><FONT color=#001050>make -n</I></FONT><R>' to resolve the dependencies,
+but I advise you to keep it in case it becomes mandatory in future versions.
+The syntax of the </R><I><FONT color=#001050>pick</I></FONT><R> command is:
+-pick </R><I><FONT color=#001050>cmd</I></FONT><R> $@ </R><I><FONT color=#001050>target_file</I></FONT><R>
+where </R><I><FONT color=#001050>$@</I></FONT><R> is the standard macro within Makefiles standing for the current
+target (the name of the unit being built, with the final .U extension stripped).
+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
+</R><I><FONT color=#001050>target_file</I></FONT><R> is yet another parameter, whose interpretation depends on
+the </R><I><FONT color=#001050>cmd</I></FONT><R> itself. It also has its final .U extension stripped and normally
+refers to a unit file, unless it start with './' in which case it references
+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.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The available commands are:
+<DL><DT> <!-- 10--> add
+<DD> Adds the <I><FONT color=#001050>target_file</I></FONT><R> to </R><I><FONT color=#001050>Configure</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <!-- --> add.Config_sh
+<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.
+Only used variables are added, conditional ones (from conditional dependencies)
+are skipped.
+</DD> </R></DT></DL> <DL><DT> <!-- --> add.Null
+<DD> Adds the section initializing all the shell variables used to an empty string.
+</DD> </DT></DL> <DL><DT> <!-- --> c_h_weed
+<DD> Produces the <I><FONT color=#001050>config_h.SH</I></FONT><R> file. Only the necessary lines are printed.
+</DD> </R></DT></DL> <DL><DT> <!-- --> cm_h_weed
+<DD> Produces the <I><FONT color=#001050>confmagic.h</I></FONT><R> file. Only the necessary lines are printed.
+This command is only enabled when the </R><B>-M</B><R> switch is given, or when a
+</R><I><FONT color=#001050>confmagic.h</I></FONT><R> file already exists.
+</DD> </R></DT></DL> <DL><DT> <!-- --> close.Config_sh
+<DD> Adds the final 'EOT' symbol on a line by itself to end the here document
+construct producing the <I><FONT color=#001050>config.sh</I></FONT><R> file.
+</DD> </R></DT></DL> <DL><DT> <!-- --> prepend
+<DD> Prepends the content of the target to the <I><FONT color=#001050>target_file</I></FONT><R> if that file is
+not empty.
+</DD> </R></DT></DL> <DL><DT> <!-- --> weed
+<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
+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
+from the </R><I><FONT color=#001050>target_file</I></FONT><R> if the symbol is not wanted or conditionally
+wanted. The '%' form is only used internally by </R><I><FONT color=#001050>metaconfig</I></FONT><R> while
+producing its own .U files in the '</R><I><FONT color=#001050>.MT</I></FONT><R>' directory.
+</DD> </R></DT></DL> <DL><DT> <!-- --> wipe
+<DD> Same as <I><FONT color=#001050>add</I></FONT><R> really, but performs an additional macro substitution.
+The available macros are described in the </R><I><FONT color=#001050>Hardwired Macros</I></FONT><R> paragraph.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ 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
+to deal with conditional dependencies. You should not use it by yourself,
+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>
+directory.
+</DD> </R></DT></DL>
+<span class="SS"> Hardwired Macros</span> <span class="paragraph_brs"> <BR><BR> </span>
+ The following macros are recognized by the <I><FONT color=#001050>wipe</I></FONT><R> command and subsituted
+before inclusion in </R><I><FONT color=#001050>Configure</I></FONT><R>:
+<DL><DT> <!-- 10--> <BASEREV>
+<DD> The base revision number of the package, derived from <I><FONT color=#001050>.package</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <DATE>
+<DD> The current date.
+</DD> </DT></DL> <DL><DT> <!-- --> <MAINTLOC>
+<DD> The e-mail address of the maintainer of this package, derived from
+your <I><FONT color=#001050>.package</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <PACKAGENAME>
+<DD> The name of the package, as derived from your <I><FONT color=#001050>.package</I></FONT><R> file.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <PATCHLEVEL>
+<DD> The patch level of the <I><FONT color=#001050>metaconfig</I></FONT><R> program.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <VERSION>
+<DD> The version number of the <I><FONT color=#001050>metaconfig</I></FONT><R> program.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Those macros are mainly used to identify the <I><FONT color=#001050>metaconfig</I></FONT><R> version that
+generated a particular </R><I><FONT color=#001050>Configure</I></FONT><R> script and for which package it
+was done. The e-mail address of the maintainer is hardwired in the leading
+instructions that </R><I><FONT color=#001050>Configure</I></FONT><R> prints when starting.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Recent <I><FONT color=#001050>metaconfig</I></FONT><R> versions understand a much more general syntax
+of the form:
+ <$variable>
+which is replaced at Configure-generation time by the value of </R><I><FONT color=#001050>variable</I></FONT><R>
+taken from your </R><I><FONT color=#001050>.package</I></FONT><R> file. Eventually, the old hardwired macro
+format will disappear, and <$baserev> will replace <BASEREV> in all the
+supplied units.
+</DD> </R></DT></DL>
+<span class="SS"> Special Units</span> <span class="paragraph_brs"> <BR><BR> </span>
+ The following special units are used to factorize code and provide higher
+level functionalities. They either produce a shell script that can be
+sourced or a shell variable that can be <I><FONT color=#001050>eval</I></FONT><R>'ed. Parameter passing
+is done via well-know variables, either named or anonymous like $1, $2,
+etc... (which can be easily set via the shell </R><I><FONT color=#001050>set</I></FONT><R> operator).
+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,
+so every produced script lies in there and does not interfere with the
+files from your package.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Here are the sepcial units that you should know about, and the way to use
+them.
+<DL><DT> <!-- 5--> Cppsym.U
+<DD> This unit produces a shell script called <I><FONT color=#001050>Cppsym</I></FONT><R>, which can be used
+to determine whether any symbol in a list is defined by the C preprocessor
+or C compiler you have specified.
+It can determine the status of any symbol, though the symbols in </R><I><FONT color=#001050></I></FONT><R>
+(attribute list) are more easily determined.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Csym.U
+<DD> This sets the $csym shell variable, used internally by <I><FONT color=#001050>Configure</I></FONT><R> to
+check whether a given C symbol is defined or not. A typical use is:
+set symbol result [-fva] [previous]
+eval $csym
+That will set the </R><I><FONT color=#001050>result</I></FONT><R> variable to 'true' if the
+function [-f],
+variable [-v] or
+array [-a]
+is defined, 'false' otherwise. If a previous value is given and the </R><B>-r</B><R>
+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>
+paragraph), then that value is re-used without questioning.
+<BR><BR> <!-- --> </R>The way this computation is done depends on the answer the user gives to
+the question <I><FONT color=#001050>Configure</I></FONT><R> will ask about whether it should perform an
+<span class="I"> nm</span> </R>extraction or not. If the exctraction was performed, the unit simply looks
+through the symbol list, otherwise it performs a compile-link test, unless
+<span class="B"> -r</span> was given to reuse the previously computed value, naturally...
+</DD> </DT></DL> <DL><DT> <!-- --> End.U
+<DD> By copying this unit into your private <I><FONT color=#001050>U</I></FONT><R> directory and appending
+dependencies on the ?MAKE: line, you can force a given unit to be loaded
+into </R><I><FONT color=#001050>Configure</I></FONT><R> even if it is not otherwise wanted. Some units may
+only be forced into </R><I><FONT color=#001050>Configure</I></FONT><R> that way.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Filexp.U
+<DD> This unit produces a shell script <I><FONT color=#001050>filexp</I></FONT><R> which will expand filenames
+beginning with tildes. A typical use is:
+exp_name=`./filexp $name`
+to assign the expanded file name in </R><I><FONT color=#001050>exp_name</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Findhdr.U
+<DD> This unit produces a <I><FONT color=#001050>findhdr</I></FONT><R> script which is used to locate the
+header files in </R><I><FONT color=#001050>$usrinc</I></FONT><R> or other stranger places using cpp capabilities.
+The script is given an include file base name like 'stdio.h' or 'sys/file.h'
+and it returns the full path of the inlcude file and a zero status if found,
+or an empty string and a non-zero status if the file could not be located.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Getfile.U
+<DD> This unit produces a bit of shell code that must be sourced in order to get
+a file name and make some sanity checks. Optionally, a ~name expansion is
+performed.
+<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
+default answer, which will be passed as-is to the </R><I><FONT color=#001050>myread</I></FONT><R> script
+(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
+operation and the result is returned into </R><I><FONT color=#001050>$ans</I></FONT><R>.
+<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,
+then ~name substitution is allowed. If a '/' appears, only absolute pathnames
+are accepted and ~name subsitutions are always expanded before returning.
+If '+' is specified, existence checks are skipped. If 'n'
+appears within </R><I><FONT color=#001050>$fn</I></FONT><R>, then the user is allowed to answer 'none'.
+<BR><BR> <!-- --> </R>Usually, unless you asked for portability, ~name substitution occurs when
+requested. However, there are some times you wish to bypass portability and
+force the substitution. You may use the 'e' letter (expand) to do that.
+<BR><BR> <!-- --> If the special 'l' (locate) type is used, then the <I><FONT color=#001050>$fn</I></FONT><R> variable must
+end with a ':', followed by a file basename. If the answer is a directory,
+the file basename will be appended before testing for file existence. This
+is useful in locate-style questions like this:
+dflt='~news/lib'
+: no need to specify 'd' or 'f' when 'l' is used
+fn='l~:active'
+rp='Where is the active file?'
+. ./getfile
+active="$ans"
+<BR><BR> <!-- --> </R>Additionally, the 'p' (path) letter may be used in conjunction with 'l' to
+tell <I><FONT color=#001050>getfile</I></FONT><R> that an answer without a '/' in it should be accepted,
+assuming that it will be in everyone's PATH at the time this value will be
+needed.
+<BR><BR> <!-- --> </R>Also useful is the possibility to specify a list of answers that should be
+accepted verbatim, bypassing all the checks. This list must be within
+parenthesis and items must be comma separated, with no interleaving spaces.
+Don't forget to quote the resulting string since parenthesis are meaningful
+to the shell. For instance:
+dflt='/bin/install'
+fn='/fe~(install,./install)'
+rp='Use which install program?'
+. ./getfile
+install="$ans"
+would let the user only specify fully qualified paths referring to existing
+files, but still allow the special "install" and "./install" answers as-is
+(assuming of course something will deal with them specially later on in the
+chain since they do not conform with the general expected frame).
+<BR><BR> <!-- --> If the answer to the question is 'none', then the existence checks are skipped
+and the empty string is returned. Note that since <I><FONT color=#001050>getfile</I></FONT><R> calls
+</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
+here to.
+<BR><BR> <!-- --> </R>If a completely expanded value is needed (for instance in a Makefile), you
+may use the <I><FONT color=#001050>$ansexp</I></FONT><R> variable which is always set up properly
+by </R><I><FONT color=#001050>getfile</I></FONT><R>
+as the expanded version of </R><I><FONT color=#001050>$ans</I></FONT><R>. Of course, it will not expand ~name if
+you did not allow that in the first place in the </R><I><FONT color=#001050>$fn</I></FONT><R> variable.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Inhdr.U
+<DD> This unit produces the <I><FONT color=#001050>$inhdr</I></FONT><R> shell variable, used internally by
+</R><I><FONT color=#001050>Configure</I></FONT><R> to check whether a set of headers exist or not. A typical
+use is:
+set header i_header [ header2 i_header2 ... ]
+eval $inhdr
+That will print a message, saying whether the header was found or not and
+set the </R><I><FONT color=#001050>i_header</I></FONT><R> variable accordingly. If more than one header
+is specified and the first header is not found, we try the next one, until
+the list is empty or one is found.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Inlibc.U
+<DD> This unit produces the <I><FONT color=#001050>$inlibc</I></FONT><R> shell variable, used internally
+by </R><I><FONT color=#001050>Configure</I></FONT><R> to check whether a given C function is defined or not.
+A typical use is:
+set function d_func
+eval $inlibc
+That will print a message, saying whether the function was found or not
+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>
+routine.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Loc.U
+<DD> This important unit produces a shell script <I><FONT color=#001050>loc</I></FONT><R> which can be used
+to find out where in a list of directories a given file lies. The first
+argument specifies the file to be located, the second argument is what
+will be returned if the search fails, and the reamining arguments are a
+list of directories where the file is to be searched. For instance:
+dflt=`./loc sendmail.cf X /usr/lib /var/adm/sendmail /lib`
+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
+under the listed directories, or something like </R><I><FONT color=#001050>/usr/lib/sendmail.cf</I></FONT><R>
+on some systems. See also </R><I><FONT color=#001050>Getfile.U</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <!-- --> MailAuthor.U
+<DD> This unit needs to be included on the ?MAKE: line of your own private End.U
+to make it into <I><FONT color=#001050>Configure</I></FONT><R>. It offers the user to register himself to
+the author, optionally being notified when new patches arrive or receiving
+them automatically when issued. You need to install </R><I><FONT color=#001050>mailagent</I></FONT><R> to do
+this (at least version 3.0).
+</DD> </R></DT></DL> <DL><DT> <!-- --> MailList.U
+<DD> This unit needs to be included on the ?MAKE: line of your own private End.U
+to make it into <I><FONT color=#001050>Configure</I></FONT><R>. It offers the user to subscribe or
+unsubscribe to a mailing list where discussion related to the package are
+taking place. You need to run </R><I><FONT color=#001050>packinit</I></FONT><R> and answer the mailing list
+related questions to set up the proper variables in your </R><I><FONT color=#001050>.package</I></FONT><R>
+before this unit may become operational.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Myinit.U
+<DD> Copy this unit into your private <I><FONT color=#001050>U</I></FONT><R> directory to add your own default
+values to some internal variables. This unit is loaded into </R><I><FONT color=#001050>Configure</I></FONT><R>
+after all the default initializations have been done.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Myread.U
+<DD> This unit produces the <I><FONT color=#001050>myread</I></FONT><R> shell script that must be sourced in
+order to do a read. It allows shell escapes, default assignment and
+parameter evaluation, as documented in the Instruct.U unit. It also allows
+dynamic setting of the </R><B>-d</B><R> option, which will be used for the remaining
+of the script execution.
+<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
+contain the default answer. The question will be printed by the script
+itself, and the result is returned in the </R><I><FONT color=#001050>$ans</I></FONT><R> variable.
+<BR><BR> <!-- --> </R>Here is a typical usage:
+dflt='y'
+rp='Question?'
+. ./myread
+value="$ans"
+See the unit itself for more information.
+</DD> </DT></DL> <DL><DT> <!-- --> Oldconfig.U
+<DD> This unit must be part of your dependency ?MAKE: line when some of your
+units tries to reuse an old symbol value. This unit is responsible for
+getting the old answers from <I><FONT color=#001050>config.sh</I></FONT><R> or providing useful hints
+when running on a given platform for the first time. See the </R><I><FONT color=#001050>Configure
+Hints</I></FONT><R> paragraph for more information about hints.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Prefixit.U
+<DD> The purpose of this unit is to detect changes in the installation prefix
+directory to recompute automatically suitable defaults from previous answers.
+It relies on the value of the <I><FONT color=#001050>$oldprefix</I></FONT><R> variable which holds the
+previous prefix directory when it changed, and is empty otherwise. For instance,
+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
+previous binary installation directory will be changed from </R><I><FONT color=#001050>/opt/bin</I></FONT><R>
+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>.
+<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>,
+such as:
+set dflt var [dir]
+eval $prefixit
+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
+on whether the prefix remained the same or not. If </R><I><FONT color=#001050>dir</I></FONT><R> is the
+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
+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
+to an empty string if the prefix changed, to </R><I><FONT color=#001050>$var</I></FONT><R> otherwise.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Prefixup.U
+<DD> The intent of thit unit is similar to that of Prefixit.U, i.e. it helps
+fixing the default string to accomodate prefix changes. However, the shell
+variable <I><FONT color=#001050>$prefixup</I></FONT><R>, when evaluated, will only restore ~name expansions,
+should prefix use such an escape mechanism. Use it as:
+set dflt
+eval $prefixup
+before prompting via </R><I><FONT color=#001050>getfile</I></FONT><R> for instance. If the prefix does not
+make use of ~name expanstion, then the above will be a no-op on the </R><I><FONT color=#001050>y</I></FONT><R>
+variable, naturally.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Typedef.U
+<DD> This unit produces the <I><FONT color=#001050>$typedef</I></FONT><R> shell variable, used internally by
+</R><I><FONT color=#001050>Configure</I></FONT><R> to check whether a typedef exists or not. A typical
+use is:
+set typedef val_t default [ includes ]
+eval $typedef
+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
+typedef was not found among the listed include files, or to </R><I><FONT color=#001050>typedef</I></FONT><R>
+if found. If no include files are specified, the unit looks
+in </R><I><FONT color=#001050><sys/types.h></I></FONT><R> only. If you specifiy some includes, only those are
+looked at.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Unix.U
+<DD> The purpose of this unit is to define some of the most common UNIX-isms
+via variables which can be altered from the command line or via proper
+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>
+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>
+directly. The '.' is part of these variables.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Setvar.U
+<DD> This unit produces the <I><FONT color=#001050></I></FONT><R> variable, which is used internally
+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,
+emitting a warning when it suddenly changes from a previous value. For instance:
+val="$define"
+set d_variable
+eval $setvar
+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
+different, a "whoa" warning is issued.
+</DD> </R></DT></DL> <DL><DT> <!-- --> Whoa.U
+<DD> This unit produces the <I><FONT color=#001050>whoa</I></FONT><R> script, which emits a warning when the
+</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
+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
+</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.
+See examples in </R><I><FONT color=#001050>Inlibc.U</I></FONT><R>.
+</DD> </R></DT></DL>
+<span class="SS"> Builtin Pre-processor</span> <span class="paragraph_brs"> <BR><BR> </span>
+ Each unit to be included in <I><FONT color=#001050>Configure</I></FONT><R> is ran through a built-in
+pre-processor. Pre-processor statements are introduced by the '@' character
+('#' is the shell comment character). It functions merely as the C
+pre-processor does but allows for shell and perl escapes. Here are the
+available functions:
+<DL><DT> <!-- 10--> @if <I><FONT color=#001050>expression</I></FONT><R>
+<DD> If <I><FONT color=#001050>expression</I></FONT><R> is true, continue loading code until @end, @elsif or @else.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> @elsif <I><FONT color=#001050>expression</I></FONT><R>
+<DD> Alternative choice. If <I><FONT color=#001050>expression</I></FONT><R> is true, continue loading code until
+@end, another @elsif or @else.
+</DD> </R></DT></DL> </R><DL><DT> <!-- --> @else
+<DD> Default code to be loaded if the @if <I><FONT color=#001050>expression</I></FONT><R> was false and none
+of the optional @elsif matched. Load until @end.
+</DD> </R></DT></DL> <DL><DT> <!-- --> @end
+<DD> Close the conditional loading statement opened by @if.
+</DD> </DT></DL> <DL><DT> <!-- --> @define <I><FONT color=#001050>symbol</I></FONT><R>
+<DD> Tells the pre-processor that <I><FONT color=#001050>symbol</I></FONT><R> is defined from now on.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The conditional <I><FONT color=#001050>expression</I></FONT><R> can include symbol names (value is
+true if symbol is wanted or defined via </R><I><FONT color=#001050>@define</I></FONT><R> or shell/perl
+escapes. Those atoms can be combined using the traditional boolean
+operators '!' for negation, '&&' for logical and, and '||' for logical
+or.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Text enclosed within single brackets is a shell test, while text between
+double brakets is a perl test. Namely the expressions:
+{ <I><FONT color=#001050>shell text</I></FONT><R> }
+{{ </R><I><FONT color=#001050>perl text</I></FONT><R> }}
+are translated into:
+if </R><I><FONT color=#001050>shell text</I></FONT><R> >/dev/null 2>&1; then exit 0; else exit 1; fi
+if (</R><I><FONT color=#001050>perl text</I></FONT><R>) {exit 0;} else {exit 1;}
+and the exit status is used in the standard way to get a boolean value,
+i.e. 0 is true and everything else is false. Note that only simple
+conditions can be expressed in perl, until some complex code can be
+loaded within </R><I><FONT color=#001050>metaconfig</I></FONT><R> and executed.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The built-in pre-processor can be used to finely tune some units
+(see <I><FONT color=#001050>d_gethname.U</I></FONT><R> for a complex example) depending on the symbols
+actually used by the program or the files present in the distribution.
+For instance, the </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R> uses a test like:
+@if {test -d ../hints}
+and </R><I><FONT color=#001050>Configure</I></FONT><R> will contain hint-dependent code only if there is
+a </R><I><FONT color=#001050>hints</I></FONT><R> directory in the package's top level directory. Note that
+tests are ran from within the '</R><I><FONT color=#001050>.MT</I></FONT><R>' directory, hence the needed
+'../' in the test.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The pre-processor can also be used to avoid putting useless code when
+a symbol is not defined. Units defining more than one symbol can be
+protected that way (since the unit is loaded as a whole) by gathering
+symbol-dependent code within an @if/@end pair. For instance:
+@if I_TIME || I_SYS_TIME || I_SYS_TIME_KERNEL
+need_time_h='true'
+@else
+need_time_h='false'
+@end
+will test whether the source code makes any use of one of the three
+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
+and define the shell symbol accordingly. That gives </R><I><FONT color=#001050>Configure</I></FONT><R>
+a feedback on what the sources need and avoid the drawback of having
+fixed frozen units.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Via the '?W:' lines, you can get intersting combinations. For instance,
+the <I><FONT color=#001050>i_time.U</I></FONT><R> unit needs to know whether the C sources make any
+use of the </R><I><FONT color=#001050>struct timezone</I></FONT><R> type. Therefore, the line:
+?W::timezone
+is used for its side-effect of defining the symbol </R><I><FONT color=#001050>timezone</I></FONT><R> for
+the pre-processor. The unit code can then say:
+@if timezone
+for s_timezone in '-DS_TIMEZONE' ''; do
+@else
+s_timezone=''
+@end
+<BR>
+
+... code using s_timezone ...
+<BR>
+
+@if timezone
+done
+@end
+and have an extra loop trying two successive values for the </R><I><FONT color=#001050>s_timezone</I></FONT><R>
+variable, but only if needed.
+</DD> </R></DT></DL> </R>
+<span class="SS"> Obsolete Symbols</span> <span class="paragraph_brs"> <BR><BR> </span>
+ Obsolete symbols are preserved to ease the transition with older
+<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
+be ignored. However, an </R><I><FONT color=#001050>Obsolete</I></FONT><R> file will be generated, telling you
+which files are making use of those obsolete symbols and what are the new
+symbols to be used.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ The lifetime for obsolete symbols is one full revision, i.e. they will
+be removed when the next base revision is issued (patch upgrades do not
+count of course). Therefore, it is wise to translate your sources and
+start using the new symbols as soon as possible.
+
+<span class="SS"> Configure Hints</span> <span class="paragraph_brs"> <BR><BR> </span>
+ It may happen that the internal configuration logic makes the wrong choices.
+For instance, on some platform, the <I><FONT color=#001050>vfork()</I></FONT><R> system call is present but
+broken, so it should not be used. It is not possible to include that knowledge
+in the units themselves, because that might be a temporary problem which the
+vendor will eventually fix, or something that was introduced by a new OS
+upgrade.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Anyway, for all those tiny little problems that are too system-specific,
+<I><FONT color=#001050>metaconfig</I></FONT><R> provides hint files support. To use it, you need to create
+a </R><I><FONT color=#001050>hints</I></FONT><R> directory in the package's top level directory, and have it
+when you run </R><I><FONT color=#001050>metaconfig</I></FONT><R>. That will load the hint-related part from
+</R><I><FONT color=#001050>Oldconfig.U</I></FONT><R>.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ From then on, you may pre-set some of the shell variables <I><FONT color=#001050>Configure</I></FONT><R> uses
+in an OS-specific .sh file. There is code in </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R> that tries
+to guess which hint files are needed by computing a standard name based
+on the system OS name, the kernel name, the release number, etc... Since
+this information is likely to change rapidly, I'm not documenting it here.
+You have to reverse engineer the code from </R><I><FONT color=#001050>Oldconfig.U</I></FONT><R>.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ When you first release your package, your hints file directory should be empty.
+If the users of your package complain that they have problem with
+<I><FONT color=#001050>Configure</I></FONT><R> defaults on a particular system, you have to see whether this
+is a platform-specific problem or a general one. In the former case, it's
+time to introduce a new hint file, while in the latter, the corresponding
+unit should be revised.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ For instance, SGI systems are known to have a broken <I><FONT color=#001050>vfork()</I></FONT><R> system
+call, as of this writing. And the corresponding hint file name is </R><I><FONT color=#001050>sgi.sh</I></FONT><R>.
+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:
+d_vfork="$define"
+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
+running on SGI systems for the first time, </R><I><FONT color=#001050>Configure</I></FONT><R> will detect that
+there is an </R><I><FONT color=#001050>hints/sgi.sh</I></FONT><R> file, and that we are on an IRIX machine
+(the kernel name is often /irix), therefore it will propose </R><I><FONT color=#001050>sgi</I></FONT><R> as a
+possible hint.
+If the user accepts it, and since the </R><I><FONT color=#001050>$d_vfork</I></FONT><R> value is modified
+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
+are about to override the value computed by </R><I><FONT color=#001050>Configure</I></FONT><R>.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ Note that you don't have to provide <I><FONT color=#001050>all</I></FONT><R> the hints known by
+</R><I><FONT color=#001050>Oldconfig.U</I></FONT><R>. If a hint file is missing, it will not be proposed as a
+possible choice. The heuristic tests ran to compute the possible hint
+candidates are flaky. If you have new values or different tests, please send
+them to me...
+
+<span class="SS"> Overriding Choices</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ If you create a <I><FONT color=#001050>config.over</I></FONT><R> file in the top level directory,
+</R><I><FONT color=#001050>Configure</I></FONT><R> will ask you if you wish to load it to override the default
+values. This is done prior creation of the </R><I><FONT color=#001050>config.sh</I></FONT><R> file, so it gives
+you a chance to patch the values stored in there.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ This is distinct from the hints approach in that it is a local file, which
+the user is free to create for his own usage. You should not provide such
+a file yourself, but let the user know about this possibility.
+
+<span class="SS"> Configure Options</span> <span class="paragraph_brs"> <BR><BR> </span>
+ The <I><FONT color=#001050>Configure</I></FONT><R> script may be called with some options specified on the
+command line, to slightly modify its behaviour. Here are the allowed options:
+<DL><DT> <!-- 10--> <span class="B"> -d</span> <DD> Use defaults for all answers.
+</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>.
+</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
+used, the configuration is taken from <I><FONT color=#001050>config.sh</I></FONT><R>, when present.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B"> -h</span> <DD> Print help message and exit.
+</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>
+symbol extraction. If used the first time (with no previous configuration
+file), </R><I><FONT color=#001050>Configure</I></FONT><R> will try to compile and link a small program in order
+to know about the presence of a symbol, or absence thereof.
+</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
+the screen (that's the important messages). It's not possible to completely
+turn off any output, but you may use '<I><FONT color=#001050>Configure -ders >/dev/null 2>&1</I></FONT><R>'
+to have a full batch run with no output and no user interaction required.
+</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
+possible to use '</R><B>-D</B><I><FONT color=#001050> symbol</I></FONT><R>' which will use a default value
+of 'define'.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B"> -E</span> <DD> Stop at the end of the configuration questions, after having produced
+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
+extraction.
+</DD> </R></DT></DL> <DL><DT> <!-- --> <span class="B"> -K</span> <DD> Knowledgeable user. When you use this option, you know what you are
+doing and therefore the <I><FONT color=#001050>config.sh</I></FONT><R> file will always be handled as if it
+was intended to be re-used, even though it might have been generated on
+an alien system. It also prevents aborting when </R><I><FONT color=#001050>Configure</I></FONT><R> detects
+an unusable C compiler or a wrong set of C flags.
+Further shortcuts might be turned on by this option as well in the future.
+This option is documented in the </R><I><FONT color=#001050>Configure</I></FONT><R> usage message, to remind
+us about its existence, but the given description is hoped to be cryptic
+enough. :-)
+</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
+any loaded configuration file. This is not the default behaviour since the
+overriding will not be propagated to variables derived from those you are
+presently altering. Naturally, without </R><B>-O</B><R>, the setting is only
+done when no configuration file is loaded, which is safe since derivative
+variables have not been computed yet...
+</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
+<B>-f</B><R> switch to propagate any configuration you like.
+</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
+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'.
+</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
+<span class="I"> Configure</span> </R>script and exit.
+</DD> </DT></DL>
+<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
+from there. The directory is removed when Configure ends, but this means
+you must run the script from a place where you can write, i.e. not from
+a read-only file system.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ You can run <I><FONT color=#001050>Configure</I></FONT><R> remotely though, as in:
+ ../package/Configure
+to configure sources that are not present locally. All the generated files
+will be put in the directory where you're running the script from. This magic
+is done thanks to the src.U unit, which is setting the </R><I><FONT color=#001050>$src</I></FONT><R>
+and </R><I><FONT color=#001050>$rsrc</I></FONT><R> variables to point to the package sources. That path is
+full or relative, depending on whether </R><I><FONT color=#001050>Configure</I></FONT><R> was invoked via a
+full or relative path.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ 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
+source files (units referring to source files link hints shall always use
+this mechanism and not assume the file is present in the parent directory).
+All the Makefiles should use the $src variable as a pointer to the sources
+from the top of the build directory (where </R><I><FONT color=#001050>Configure</I></FONT><R> is run), either
+directly or via a VPATH setting.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ When running <I><FONT color=#001050>Configure</I></FONT><R> remotely, the .SH files are extracted in the
+build directory, not in the source tree. However, it requires some kind of
+a </R><I><FONT color=#001050>make</I></FONT><R> support to be able to compile things in a build directory whilst
+the sources lie elsewhere.
+
+<span class="SS"> Using Magic Redefinitions</span> </R><span class="paragraph_brs"> <BR><BR> </span>
+ By making use of the <B>-M</B><R> switch, some magic remappings may take place
+within a </R><I><FONT color=#001050>confmagic.h</I></FONT><R> file. That file needs to be included after
+</R><I><FONT color=#001050>config.h</I></FONT><R>, of course, but also after all the other needed include files.
+Namely:
+#include "config.h"
+...
+... </R><I><FONT color=#001050>other inclusions</I></FONT><R> ...
+...
+#include "confmagic.h"
+Typically, </R><I><FONT color=#001050>confmagic.h</I></FONT><R> will attempt to remap </R><I><FONT color=#001050>bcopy()</I></FONT><R>
+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
+</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
+bother about the </R><I><FONT color=#001050>HAS_VFORK</I></FONT><R> symbol.
+<span class="paragraph_brs"> <BR><BR> </span> </R>
+ This configuration magic is documented in the Glossary file.
+
+<span class="SS"> Unit Templates</span> <span class="paragraph_brs"> <BR><BR> </span>
+ There is a set of unit templates in the <I><FONT color=#001050>metaconfig</I></FONT><R> source directory,
+which are intended to be used by a (not yet written) program to quickly
+produce new units for various kind of situations. No documentation for this
+unfinished project, but I thought I would mention it in the manual page in
+case you wish to do it yourself and then contribute it...
+</UL> </R></LI> <LI> <span class="section"> AUTHORS</span> <BR> <UL> Larry Wall <lwall@netlabs.com> for version 2.0.
+<BR> Harlan Stenn <harlan@mumps.pfcs.com> for important unit extensions.
+<BR> Raphael Manfredi <ram@hptnos02.grenoble.hp.com>.
+<BR> Many other contributors for the
+<I><FONT color=#001050>metaconfig</I></FONT><R> units. See the credit file for a list.
+</UL> </R></LI> <LI> <span class="section"> FILES</span> <BR> <UL> <DL><DT> <!-- 10--> LIB/dist/mcon/U/*.U
+<DD> Public unit files
+</DD> </DT></DL> <DL><DT> <!-- --> U/*.U
+<DD> Private unit files
+</DD> </DT></DL> <DL><DT> <!-- --> LIB/dist/mcon/Glossary
+<DD> Glossary file, describing all the metaconfig symbols.
+</DD> </DT></DL> <DL><DT> <!-- --> Obsolete
+<DD> Lists all the obsolete symbols used by the sources.
+</DD> </DT></DL> <DL><DT> <!-- --> Wanted
+<DD> Lists all the wanted symbols.
+<BR><BR> <!-- --> where LIB is /usr/share/dist.
+</DD> </DT></DL> </UL> </LI> <LI> <span class="section"> BUGS</span> <BR> <UL> Units are sometimes included unnecessarily if one of its symbols is
+accidentally mentioned, e.g. in a comment.
+Better too many units than too few, however.
+</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>
+</UL> </LI> </UL> </BODY></HTML>
+\r
+ \r
+ </DIV>\r
+ </TD>\r
+ </TR>\r
+ <TR class="container_bottom">\r
+ <TD class="container_bottom">\r
+ \r
+ <DIV class="bottombaradv">\r
+ <script type="text/javascript"><!--\r
+ google_ad_client = "pub-2404433452734258";\r
+ google_ad_width = 728;\r
+ google_ad_height = 90;\r
+ google_ad_format = "728x90_as";\r
+ google_ad_type = "text_image";\r
+ google_ad_channel ="5458575456";\r
+ //--></script>\r
+ <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>\r
+ </DIV> \r
+ \r
+ <DIV class="bottombar">Current Users: 17 © 1999-2006 Linux.com.hk <a href=http://Linux.com.hk/>PenguinSoft</a><br/>\r
+All trademarks and copyrights on this page are owned by their respective companies.\r
+Linux is a trademark of Linus Torvalds.\r
+\r
+</DIV>\r
+\r
+ </TD>\r
+ </TR>\r
+</TABLE><!--container-->\r
+</DIV><!--container-->\r
+</BODY>\r
+</HTML>\r
https://perl5.git.perl.org / metaconfig.git / commitdiff