How to create a Configuration script:

     1) Consult the Glossary and write your shell scripts and C programs
	in terms of the symbols that metaconfig knows how to define.  If
	your Glossary is out of date you can rebuild it by saying make gloss.

     2) Copy any .U files that you want to modify to your private U directory
	in the current directory.  Any .U files in your private U directory
	will be used in preference to the standard one.  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.
	For example, you can specify what types of void support your program
	needs--see $defvoidused in voidflags.U.

     3) If you have run metaconfig before in this directory, it created a
	Wanted file.  If you want to reuse this file, use the -w switch with
	metaconfig, and it will skip the scan of your programs for symbols.
	This is useful when you are developing a new unit file for metaconfig,
	and the programs in question haven't really changed.  If you HAVE
	changed the symbols you refer to, do not use the -w switch, and
	a new Wanted file will be created.  Note that you can force inclusion
	of a unit by adding its name to the Wanted file, but if you delete
	the Wanted file you'll lose that info.

     4) Say "metaconfig".  This should eventually produce Configure.

How to add a new unit:

     1) Copy a similar unit to a new .U file.  The name you choose should
	be the name of a variable generated by the unit.  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 variable.

     2) Edit the new .U file to do what you want.  The first ?MAKE: line
	indicates the dependencies; list before the final colon all the
	variables defined, 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.  IMPORTANT: The first symbol after ?MAKE:
	*must* be the name of the file without the .U.

     3) 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.

     4) Add the definition of any C symbols desired as ?H: lines.  A line
	beginning with ?H:?%1: in the .U file will be added to the eventual
	config.h file if and only if metaconfig decides that the first symbol
	on the ?MAKE: line is needed.  The %1 stands for that first symbol,
	which happens to be the name of the file too (without .U).  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.

     5) Add glossary definitions as ?S: lines for shell variables and ?C:
	lines for C preprocessor variables.  Entries are sorted by lines
	that match /[a-zA-Z_]:/ (after the ?[CS]:), so start any continuation
	lines with tabs (after the ?[CS]:).  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 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.

     6) Make sure the order of all your ? lines is right.  The correct order is:

	?RCS: and ?X: lines		-- basically just comments
	?MAKE: lines			-- metaconfig dependencies
	?C: and ?S: lines		-- Glossary definitions
	?H: lines			-- config.h definitions

	?INIT: lines can go anywhere.

     7) Rerun metaconfig.

     8) Send unit to lwall@jpl-devvax.jpl.nasa.gov (Larry Wall) for inclusion
	in the master copy, if you think it's of general interest.

How to add a new program to be located:

     1) 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).

     2) Rerun metaconfig.

     8) Send unit to lwall@jpl-devvax.jpl.nasa.gov (Larry Wall) for inclusion
	in the master copy, if you think it's of general interest.

Notes for writing .U files:

	Always use "rm -f" because there are systems where rm is interactive by
	default.  Files which need to be removed at the end of Configure
	should be added to the rmlist variable.  (rmlist="$rmlist tmpfile")

	Always use echo " " (with a space) because of Eunice systems.

	Use only programs that came with V7, so that you know everyone has
	them.

	Use $contains when you want to grep conditionally, since not all
	greps return a reasonable status.

	Use "if test" rather than "if [...]" since not every sh knows the
	latter construct.

	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? [$dflt]"
		echo $n "$rp $c"
		. myread
		grimble="$ans"

	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.

	When in doubt, set a default and ask.  Don't assume anything.

	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.

Metaconfig reserves the following names in your directory, and if you use such
a name it may get clobbered or have other unforeseen effects:

	.MT/*
	Configure
	Wanted
	UU/*

Additionally, Configure may clobber these names in the directory it is run in:

	UU/*
	config.sh
	config.h
