1870 lines
114 KiB
HTML
1870 lines
114 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
|
|
<HTML>
|
|
<HEAD>
|
|
|
|
|
|
|
|
|
|
|
|
<base href="http://linux.com.hk:80/penguin/" />
|
|
<TITLE>metaconfig - a Configure script generator
|
|
Linux Man Page</TITLE>
|
|
|
|
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<META name="GENERATOR" content="IBM WebSphere Studio">
|
|
<LINK rel="stylesheet" href="theme/Master.css" type="text/css">
|
|
<LINK rel="stylesheet" href="theme/layout.css" type="text/css">
|
|
<script type="text/javascript" src="js/common.js"></script>
|
|
<!-- google analytics -->
|
|
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
|
|
</script>
|
|
<script type="text/javascript">
|
|
_uacct = "UA-90513-1";
|
|
urchinTracker();
|
|
</script>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
|
|
|
|
<DIV class="container">
|
|
<TABLE class="container">
|
|
<TR class="container_up">
|
|
<TD class="container_up"><!-- topbar -->
|
|
<DIV class="topbar"><A href="index.jsp"> <IMG border="0"
|
|
src="images/logo.png" /> </A>
|
|
<!--topbar ad area-->
|
|
<DIV id="topbaradv">
|
|
<script type="text/javascript"><!--
|
|
google_ad_client = "pub-2404433452734258";
|
|
google_ad_width = 468;
|
|
google_ad_height = 60;
|
|
google_ad_format = "468x60_as";
|
|
google_ad_channel ="5458575456";
|
|
google_ad_type = "text_image";
|
|
//--></script>
|
|
<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>
|
|
</DIV>
|
|
</DIV>
|
|
<!--- navbar --->
|
|
<CENTER class=navbar><TABLE width="100%" class="navtable">
|
|
<TR align="center" class="navtable">
|
|
<TD class="navtable"><a href=about.jsp class="navtable"> Company</a></TD>
|
|
<TD class="navtable"><a href=products.jsp class="navtable"> Products</a></TD>
|
|
<TD class="navtable"><a href=innovation.jsp class="navtable"> Innovation</a></TD>
|
|
<TD class="navtable"><a href=manpages.jsp class="navtable"> Man pages</a></TD>
|
|
<TD class="navtable"><a href=developer.jsp class="navtable"> Developer</a></TD>
|
|
<TD class="navtable"><a href=mirrors.jsp class="navtable"> Mirrors</a></TD>
|
|
<TD class="navtable"><a href=search.jsp class="navtable"> Search</a></TD>
|
|
</TR>
|
|
</TABLE></CENTER>
|
|
<DIV class="sidebar">
|
|
|
|
<!--sidebar --->
|
|
|
|
</DIV>
|
|
<DIV class="bodypart">
|
|
<STYLE>
|
|
DIV.bodypart {
|
|
margin-left:5px;
|
|
}
|
|
</STYLE>
|
|
|
|
<a href="http://linux.com.hk:80/penguin/man?action=print"><img src='images/printer.gif'></a>
|
|
|
|
<a href="http://linux.com.hk:80/penguin/man/1/m/" class="mannavlink">back to section</a>
|
|
|
|
<script type="text/javascript"><!--
|
|
google_ad_client = "pub-2404433452734258";
|
|
google_ad_width = 468;
|
|
google_ad_height = 15;
|
|
google_ad_format = "468x15_0ads_al";
|
|
google_ad_channel ="5458575456";
|
|
google_color_border = "336699";
|
|
google_color_bg = "FFFFFF";
|
|
google_color_link = "0000FF";
|
|
google_color_url = "008000";
|
|
google_color_text = "000000";
|
|
//--></script>
|
|
<script type="text/javascript"
|
|
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
|
|
</script>
|
|
|
|
</br>
|
|
<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>
|
|
|
|
|
|
</DIV>
|
|
</TD>
|
|
</TR>
|
|
<TR class="container_bottom">
|
|
<TD class="container_bottom">
|
|
|
|
<DIV class="bottombaradv">
|
|
<script type="text/javascript"><!--
|
|
google_ad_client = "pub-2404433452734258";
|
|
google_ad_width = 728;
|
|
google_ad_height = 90;
|
|
google_ad_format = "728x90_as";
|
|
google_ad_type = "text_image";
|
|
google_ad_channel ="5458575456";
|
|
//--></script>
|
|
<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>
|
|
</DIV>
|
|
|
|
<DIV class="bottombar">Current Users: 17 © 1999-2006 Linux.com.hk <a href=http://Linux.com.hk/>PenguinSoft</a><br/>
|
|
All trademarks and copyrights on this page are owned by their respective companies.
|
|
Linux is a trademark of Linus Torvalds.
|
|
|
|
</DIV>
|
|
|
|
</TD>
|
|
</TR>
|
|
</TABLE><!--container-->
|
|
</DIV><!--container-->
|
|
</BODY>
|
|
</HTML>
|