This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Updated documentation and README's. Added some locally used
authorH.Merijn Brand <h.m.brand@xs4all.nl>
Sun, 9 Apr 2006 10:59:53 +0000 (10:59 +0000)
committerH.Merijn Brand <h.m.brand@xs4all.nl>
Sun, 9 Apr 2006 10:59:53 +0000 (10:59 +0000)
scripts to the standard distribution. Added the metaconfig
html documentation for a reference to the syntax of all the
.U files.

p4raw-id: //depot/metaconfig@27748

README_U [new file with mode: 0644]
U/Glossary.patch
U/README
U/README.dist
U/ln-all.pl [new file with mode: 0755]
U/mkgloss.pl [new file with mode: 0755]
metaconfig.html [new file with mode: 0644]

diff --git a/README_U b/README_U
new file mode 100644 (file)
index 0000000..9ce7a27
--- /dev/null
+++ b/README_U
@@ -0,0 +1,129 @@
+Line   Description
+======= =======================================================================
+
+?C:    Comments for #defines
+
+?D:    Set default value for variable
+
+       ?D:osname=''
+
+?F:    Defines what files are created by this module
+
+?H:    Defines the part to be included in the generated config_h.SH
+
+       To get #ifdefs in config_h.SH, you'll need strange constructs like
+
+       ?H:?%<:@if USE_SITECUSTOMIZE
+       ?H:?%<:#ifndef USE_SITECUSTOMIZE
+       ?H:?%<:#$usesitecustomize     USE_SITECUSTOMIZE               /**/
+       ?H:?%<:#endif
+       ?H:?%<:@end
+
+?I:    Include
+
+?INIT: ?
+
+?L:    Library
+
+?LINT: tell what is to be expected extern and what is changed
+
+       ?LINT:define fieldn
+       ?LINT:extern CONFIG_H
+       ?LINT:change CONFIG_H
+       ?LINT:use PERL_CONFIG_SH
+
+?M:    Magic
+
+?MAKE: symbol list: dependency list [+optional]
+
+       This is the first dependency line. The first "symbol list"
+       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 "config.sh"
+       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.
+
+?MAKE: <tab> command
+
+       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 "Configure".
+       Note that the leading <tab> character is required before the
+       "command".
+
+?O:    Obsoleted?
+
+?P:    Public
+
+?RCS:  free text
+
+       To be used for RCS comments, at the top of the unit.
+
+?S:    symbol_name (obsolete symbol list)]:
+
+       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 "symbol_name" if the -o option is given to
+       "metaconfig".
+
+?S:    any text, for "Porting/Glossary"
+
+       Basically a comment describing the shell symbol, which will be
+       extracted by "makegloss" into the Glossary file.
+
+?S:    .
+
+       Closes the shell symbol comment.
+
+?T:    What variables are used as temporary variables
+
+?V:    Visible?
+
+       ?V:fieldn
+
+?W:    Wanted
+
+?X:    any text
+
+       General purpose comments. May appear anywhere in the unit but must be
+       left justfied. For RCS comments, please use the ?RCS: comment form.
+
+?Y:    layout
+
+       Declare a layout directive for this unit. That directive may be one
+       of the strings "top", "default" or "bottom" (case does not matter,
+       recommended style is to spell them out uppercased). If omitted,
+       "default" is assumed.
+
+       This directive is only required if you wish to force a unit at the
+       top or the bottom of the generated "Configure" 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).
+
+       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.
+
+       ?Y:TOP
+
+lines can be made conditional (see Config_sh.U)
+
+@if d_portable
+:
+:
+@end
index 0edcb6e..47de461 100644 (file)
@@ -1,6 +1,6 @@
---- Glossary.orig      2003-03-14 12:37:11.000000000 +0200
-+++ Glossary   2003-03-14 12:37:38.000000000 +0200
-@@ -3440,7 +3440,7 @@
+--- Glossary.orig      2006-04-09 12:35:52.000000000 +0200
++++ Glossary   2006-04-09 12:36:00.000000000 +0200
+@@ -3537,7 +3537,7 @@ make_set_make (make.U):
        make_set_make="MAKE=$make"      # if it doesn't.
  
        This uses a comment character to distinguish a
@@ -9,7 +9,7 @@
        from an uncomputed value.
  
  mallocobj (mallocsrc.U):
-@@ -3544,7 +3544,7 @@
+@@ -3654,7 +3654,7 @@ myuname (Oldconfig.U):
        whole thing is then lower-cased.
  
  n (n.U):
@@ -18,7 +18,7 @@
        command to suppress newline.  Otherwise it is null.  Correct usage is
        $echo $n "prompt for a question: $c".
  
-@@ -4053,9 +4053,9 @@
+@@ -4097,9 +4097,9 @@ sh (sh.U):
        /bin/sh, though it's possible that some systems will have /bin/ksh,
        /bin/pdksh, /bin/ash, /bin/bash, or even something such as
        D:/bin/sh.exe.
  
  shar (Loc.U):
        This variable is defined but not used by Configure.
-@@ -4306,7 +4306,7 @@
+@@ -4350,7 +4350,7 @@ spackage (package.U):
  
  spitshell (spitshell.U):
        This variable contains the command necessary to spit out a runnable
 -      shell on this system.  It is either cat or a grep -v for # comments.
 +      shell on this system.  It is either cat or a grep '-v' for # comments.
  
- srand48_r_proto (d_srand48_r.U):
-       This variable encodes the prototype of srand48_r.
+ sPRId64 (quadfio.U):
+       This variable, if defined, contains the string used by stdio to
index 195904e..37e7348 100644 (file)
--- a/U/README
+++ b/U/README
@@ -2,6 +2,7 @@
                     Perl5 Metaconfig Units
 
             Copyright (c) 1996-1998, Andy Dougherty
+            Copyright (c) 1999-2006, H.Merijn Brand
                        All rights reserved.
 
 These units are the ones used to build Configure and config_h.SH
@@ -22,12 +23,21 @@ Glossary.patch
     complain.  This patch silences those warnings.  As new units are
     added and Configure is regenerated, this patch may need more and more
     'fuzz' to be applied.  It should be freshly regenerated every once
-    in a while.
+    in a while. See also mkgloss.pl
+
+ln-all.pl
+    Re-generate the all/ folder
 
 mkglossary
     A script to regenerate Porting/Glossary.  You have to manually
     edit the top of the script to point the location of your metaconfig 
-    units.  It is called automatically by 'mksample'.
+    units.  It is called automatically by 'mksample'. See also mkgloss.pl
+
+mkgloss.pl
+    A perl script that calls U/mkglossary from the perl source tree, sorts
+    the list of symbols, and applies the patch mentioned in Glossary.patch.
+    When called on its own, redirect the output to a temporary file,  and
+    compare that file to Porting/Glossary before applying.
 
 mksample
     A script to regenerate Porting/config.sh and Porting/config.H.
@@ -55,6 +65,10 @@ acl/
     This is an old patch to begin to detect and use ACL (access
     control list) file protection schemes.
 
+all/
+    A folder that conveniently holds symbolic links to all the modules
+    that are used to build the current Configure and config_h.SH.
+
 compline/
     These are similar to the standard units, but I have modified them
     to have a more uniform compile command line, usually using the
index ae0fad4..6317d69 100644 (file)
@@ -2,6 +2,7 @@
                     Perl5 Metaconfig Units
 
             Copyright (c) 1996-1998, Andy Dougherty
+            Copyright (c) 1999-2006, H.Merijn Brand
                        All rights reserved.
 
 These units are the ones I used to build Configure and config_h.SH
@@ -41,15 +42,21 @@ Instructions:
 
 6.  From your main perl5 source directory, run
 
+       metalint
+
+    and repair every failure it reports.
+
+7.  From your main perl5 source directory, run
+
        metaconfig -m
 
-7.  Edit U/mkglossary to point to your dist-3.0pl70 location.
-    (See comments at the top.)
+8.  Edit U/mkglossary and/or U/mkgloss.pl to point to your dist-3.0pl70
+    location.  (See comments at the top.)
 
-8.  Run the U/mksample script to update the contents of the Porting/
-    subdirectory.
+9.  Run the U/mksample script to update the contents of the Porting/
+    subdirectory, or run all parts by hand. (see README)
 
-9.  Let me know about any changes, corrections, or enhancements.
+10. Let me know about any changes, corrections, or enhancements.
 
 Things to watch out for:
 
@@ -60,6 +67,11 @@ Things to watch out for:
     why MPE/iX needed some of the patches, so I may have missed
     something important.  I did try to flag questionable changes in
     the individual units.
+    The Configure as generated in the 5.9.x branch leading towards
+    5.10, is also used exactly as is without changes in the 5.8.x
+    and 5.6.x branches, so do not remove support for features that
+    are availabvle in those branches, but are removed from devel (e.g.
+    perl5005threads).
 
 2.  Future support of better random number generators should probably
     start with the randfunc.U unit included here.  It's currently
diff --git a/U/ln-all.pl b/U/ln-all.pl
new file mode 100755 (executable)
index 0000000..bf3ff96
--- /dev/null
@@ -0,0 +1,526 @@
+#!/pro/bin/perl
+
+# (c)'06 H.Merijn Brand [ 09 Apr 2006 ]
+
+# Small script to regenerate the links in U/all, that should
+# represent all the modules used in the current Configure
+# except the default dist libs
+
+use strict;
+use warnings;
+
+use File::Copy;
+
+my $meta = "/pro/3gl/CPAN/metaconfig";
+my $perl = "/pro/3gl/CPAN/perl-current";
+# the files that metaconfig might (probably will) overwrite:
+my @safe = qw( Configure config_h.SH );
+
+chdir $meta or die "no $meta";
+mkdir  "U/all";        # Ignore error if already exists
+chdir  "U/all";
+unlink <*.U >;
+
+for (@safe) {
+    unlink $_;
+    copy "$perl/$_", $_;
+    }
+
+@ARGV = ("metaconfig -v -m 2>&1 |");
+while (<>) {
+    s{^\s+$perl/U}{} or next;
+    chomp;
+    (my $f = $_) =~ s{.*/}{};
+    symlink "../$_", $f;
+    }
+
+for (qw( Configure config_h.SH )) {
+    unlink "$perl/$_";
+    move $_, "$perl/$_";
+    }
+
+__END__
+The list of files that were linked before I started this script:
+U/all/abortsig.U
+U/all/alignbytes.U
+U/all/ansi2knr.U
+U/all/archlib.U
+U/all/archname.U
+U/all/atolf.U
+U/all/atoll.U
+U/all/bincompat3.U
+U/all/bincompat5005.U
+U/all/bin.U
+U/all/bitpbyte.U
+U/all/byteorder.U
+U/all/ccflags.U
+U/all/cc.U
+U/all/cf_email.U
+U/all/cf_who.U
+U/all/charorder.U
+U/all/charsize.U
+U/all/Checkcc.U
+U/all/Compile.U
+U/all/Config_h.U
+U/all/Config_sh.U
+U/all/cppstdin.U
+U/all/cpp_stuff.U
+U/all/Cppsym.U
+U/all/Csym.U
+U/all/d_access.U
+U/all/d_accessx.U
+U/all/d_asctime_r.U
+U/all/d_attribut.U
+U/all/dbm64.U
+U/all/d_builtin.U
+U/all/d_casti32.U
+U/all/d_castneg.U
+U/all/d_class.U
+U/all/d_clearenv.U
+U/all/d_clock_getres.U
+U/all/d_clock_gettime.U
+U/all/d_clock_settime.U
+U/all/d_closedir.U
+U/all/d_cmsghdr_s.U
+U/all/d_crypt_r.U
+U/all/d_csh.U
+U/all/d_ctime_r.U
+U/all/d_dirfd.U
+U/all/d_dirname_r.U
+U/all/d_dlsymun.U
+U/all/d_drand48proto.U
+U/all/d_drand48_r.U
+U/all/d_eaccess.U
+U/all/d_endgrent_r.U
+U/all/d_endgrent.U
+U/all/d_endhent.U
+U/all/d_endnent.U
+U/all/d_endpent.U
+U/all/d_endpwent_r.U
+U/all/d_endpwent.U
+U/all/d_endsent.U
+U/all/d_endspent.U
+U/all/d_eofpipe.U
+U/all/Devel.U
+U/all/devtype.U
+U/all/d_fchdir.U
+U/all/d_fcntl_can_lock.U
+U/all/d_fd_set.U
+U/all/d_finitel.U
+U/all/d_finite.U
+U/all/d_flexfnam.U
+U/all/d_fpclassify.U
+U/all/d_fp_class_l.U
+U/all/d_fp_classl.U
+U/all/d_fp_class.U
+U/all/d_fpclass.U
+U/all/d_fpos64_t.U
+U/all/d_frexpl.U
+U/all/d_fs_data_s.U
+U/all/d_fseeko.U
+U/all/d_fstatfs.U
+U/all/d_fsync.U
+U/all/d_ftello.U
+U/all/d_futimes.U
+U/all/d__fwalk.U
+U/all/d_gconvert.U
+U/all/d_getcwd.U
+U/all/d_getespwnam.U
+U/all/d_getfsstat.U
+U/all/d_getgrent_r.U
+U/all/d_getgrent.U
+U/all/d_getgrgid_r.U
+U/all/d_getgrnam_r.U
+U/all/d_gethbyad.U
+U/all/d_gethbynm.U
+U/all/d_gethent.U
+U/all/d_gethname.U
+U/all/d_gethostprotos.U
+U/all/d_getitimer.U
+U/all/d_getlogin_r.U
+U/all/d_getmntent_r.U
+U/all/d_getmntent.U
+U/all/d_getmntinfo_r.U
+U/all/d_getmnt.U
+U/all/d_getnbyad.U
+U/all/d_getnbynm.U
+U/all/d_getnent.U
+U/all/d_getnetprotos.U
+U/all/d_getpagsz.U
+U/all/d_getpent.U
+U/all/d_getpgrp.U
+U/all/d_getprotby.U
+U/all/d_getprotoprotos.U
+U/all/d_getprpwnam.U
+U/all/d_getpwent_r.U
+U/all/d_getpwent.U
+U/all/d_getpwnam_r.U
+U/all/d_getpwuid_r.U
+U/all/d_getrlimit.U
+U/all/d_getsent.U
+U/all/d_getservprotos.U
+U/all/d_getspent_r.U
+U/all/d_getspent.U
+U/all/d_getspnam_r.U
+U/all/d_getspnam.U
+U/all/d_getsrvby.U
+U/all/d_gmtime_r.U
+U/all/d_gnulibc.U
+U/all/d_hasmntopt.U
+U/all/d_htonl.U
+U/all/d_iconv.U
+U/all/d_int64_t.U
+U/all/d_iovec_s.U
+U/all/d_isascii.U
+U/all/d_isfinite.U
+U/all/d_isinf.U
+U/all/d_isnanl.U
+U/all/d_isnan.U
+U/all/d_keepsig.U
+U/all/d_lchmod.U
+U/all/d_lchown.U
+U/all/d_ldbl_dig.U
+U/all/dlext.U
+U/all/d_libm_lib_version.U
+U/all/d_llseek.U
+U/all/d_localtime_r.U
+U/all/d_longdbl.U
+U/all/d_longlong.U
+U/all/d_lseekproto.U
+U/all/dlsrc.U
+U/all/d_lutimes.U
+U/all/d_madvise.U
+U/all/d_malloc_size.U
+U/all/d_memchr.U
+U/all/d_mkdtemp.U
+U/all/d_mknod.U
+U/all/d_mkstemps.U
+U/all/d_mkstemp.U
+U/all/d_mmap.U
+U/all/d_modfl.U
+U/all/d_mprotect.U
+U/all/d_mq_close.U
+U/all/d_mq_getattr.U
+U/all/d_mq_notify.U
+U/all/d_mq_open.U
+U/all/d_mq_receive.U
+U/all/d_mq_send.U
+U/all/d_mq_setattr.U
+U/all/d_mq_unlink.U
+U/all/d_msghdr_s.U
+U/all/d_msg.U
+U/all/d_nanosleep.U
+U/all/d_NOFILE.U
+U/all/d_off64_t.U
+U/all/d_open3.U
+U/all/doublesize.U
+U/all/d_portable.U
+U/all/d_posix_clock.U
+U/all/d_posix_mq.U
+U/all/d_posix_sched.U
+U/all/d_posix_sem.U
+U/all/d_posix_shm.U
+U/all/d_posix_timer.U
+U/all/d_printfed.U
+U/all/d_pthrattrj.U
+U/all/d_pthreadj.U
+U/all/d_pthread_y.U
+U/all/d_qgcvt.U
+U/all/d_random_r.U
+U/all/d_rand_r.U
+U/all/d_readdir_r.U
+U/all/d_readv.U
+U/all/d_recvmsg.U
+U/all/d_safebcpy.U
+U/all/d_safemcpy.U
+U/all/d_sanemcmp.U
+U/all/d_sbrkproto.U
+U/all/d_scannl.U
+U/all/d_sched_getparam.U
+U/all/d_sched_getscheduler.U
+U/all/d_sched_gpmax.U
+U/all/d_sched_gpmin.U
+U/all/d_sched_rrgi.U
+U/all/d_sched_setparam.U
+U/all/d_sched_setscheduler.U
+U/all/d_sem_close.U
+U/all/d_sem_destroy.U
+U/all/d_sem_getvalue.U
+U/all/d_sem_init.U
+U/all/d_sem_open.U
+U/all/d_sem_post.U
+U/all/d_sem_trywait.U
+U/all/d_sem.U
+U/all/d_sem_unlink.U
+U/all/d_sem_wait.U
+U/all/d_sendmsg.U
+U/all/d_setgrent_r.U
+U/all/d_setgrent.U
+U/all/d_setgrps.U
+U/all/d_sethent.U
+U/all/d_setitimer.U
+U/all/d_setnent.U
+U/all/d_setpent.U
+U/all/d_setpgrp.U
+U/all/d_setproctitle.U
+U/all/d_setpwent_r.U
+U/all/d_setpwent.U
+U/all/d_setrlimit.U
+U/all/d_setsent.U
+U/all/d_setspent.U
+U/all/d_setvbuf.U
+U/all/d_sfio.U
+U/all/d_sgndchr.U
+U/all/d_shm_open.U
+U/all/d_shm.U
+U/all/d_shm_unlink.U
+U/all/d_sigaction.U
+U/all/d_sigqueue.U
+U/all/d_sigsetjmp.U
+U/all/d_sigtimedwait.U
+U/all/d_sigwaitinfo.U
+U/all/d_sigwait.U
+U/all/d_sitecustomize.U
+U/all/d_snprintf.U
+U/all/d_socket.U
+U/all/d_socklen_t.U
+U/all/d_socks5_init.U
+U/all/d_sprintf_len.U
+U/all/d_sqrtl.U
+U/all/d_srand48_r.U
+U/all/d_srandom_r.U
+U/all/d_statblks.U
+U/all/d_statfs3.U
+U/all/d_statfs4.U
+U/all/d_statfs_f_flags.U
+U/all/d_statfs_s.U
+U/all/d_statfs.U
+U/all/d_statvfs.U
+U/all/d_stdstdio.U
+U/all/d_strerror_r.U
+U/all/d_strerror.U
+U/all/d_strtold.U
+U/all/d_strtoll.U
+U/all/d_strtoq.U
+U/all/d_strtoull.U
+U/all/d_strtoul.U
+U/all/d_strtouq.U
+U/all/d_telldirproto.U
+U/all/d_timer_create.U
+U/all/d_timer_delete.U
+U/all/d_timer_getoverrun.U
+U/all/d_timer_gettime.U
+U/all/d_timer_settime.U
+U/all/d_times.U
+U/all/d_time.U
+U/all/d_tmpnam_r.U
+U/all/d_ualarm.U
+U/all/d_union_semun.U
+U/all/d_unorderedl.U
+U/all/d_unordered.U
+U/all/d_unsetenv.U
+U/all/d_ustat.U
+U/all/d_utimes.U
+U/all/d_vfork.U
+U/all/d_voidsig.U
+U/all/d_vprintf.U
+U/all/d_wifstat.U
+U/all/d_writev.U
+U/all/ebcdic.U
+U/all/End.U
+U/all/errnolist.U
+U/all/Extensions.U
+U/all/Extractall.U
+U/all/Extract.U
+U/all/fflushall.U
+U/all/Findhdr.U
+U/all/Finish.U
+U/all/floatsize.U
+U/all/fpossize.U
+U/all/fpostype.U
+U/all/fpu.U
+U/all/gccvers.U
+U/all/Getfile.U
+U/all/gidf.U
+U/all/gidsign.U
+U/all/gidsize.U
+U/all/gidtype.U
+U/all/groupstype.U
+U/all/Guess.U
+U/all/Hasfield.U
+U/all/Hasproto.U
+U/all/Hasstruct.U
+U/all/Head.U
+U/all/html1dir.U
+U/all/html3dir.U
+U/all/i_db.U
+U/all/i_fp_class.U
+U/all/i_grp.U
+U/all/i_iconv.U
+U/all/i_ieeefp.U
+U/all/i_inttypes.U
+U/all/i_libutil.U
+U/all/i_machcthr.U
+U/all/i_malloc.U
+U/all/i_mntent.U
+U/all/i_mqueue.U
+U/all/inc_version_list.U
+U/all/i_netdb.U
+U/all/i_netinettcp.U
+U/all/Inhdr.U
+U/all/i_nlist.U
+U/all/inotype.U
+U/all/installprefix.U
+U/all/installstyle.U
+U/all/Instruct.U
+U/all/instubperl.U
+U/all/intsize.U
+U/all/i_poll.U
+U/all/i_prot.U
+U/all/i_pthread.U
+U/all/i_pwd.U
+U/all/i_sched.U
+U/all/i_semaphore.U
+U/all/i_shadow.U
+U/all/i_socks.U
+U/all/issymlink.U
+U/all/i_sunmath.U
+U/all/i_sysaccess.U
+U/all/i_syslog.U
+U/all/i_sysmman.U
+U/all/i_sysmode.U
+U/all/i_sysmount.U
+U/all/i_sysrusage.U
+U/all/i_syssecrt.U
+U/all/i_sysstatfs.U
+U/all/i_sysstatvfs.U
+U/all/i_sysuio.U
+U/all/i_sysutsname.U
+U/all/i_sysvfs.U
+U/all/i_time.U
+U/all/i_ulimit.U
+U/all/i_ustat.U
+U/all/libc.U
+U/all/libnlist.U
+U/all/libperl.U
+U/all/libpth.U
+U/all/libs.U
+U/all/lib.U
+U/all/lns.U
+U/all/localarch.U
+U/all/locallib.U
+U/all/Loc_ar.U
+U/all/Loc.U
+U/all/longdblfio.U
+U/all/lseektype.U
+U/all/mad.U
+U/all/mallocsrc.U
+U/all/man1dir.U
+U/all/man3dir.U
+U/all/mandirstyle.U
+U/all/mandirs.U
+U/all/Mksymlinks.U
+U/all/models.U
+U/all/modetype.U
+U/all/multiarch.U
+U/all/myhostname.U
+U/all/Myinit.U
+U/all/Myread.U
+U/all/nblock_io.U
+U/all/need_va_copy.U
+U/all/netdbtype.U
+U/all/nis.U
+U/all/oldarchlib.U
+U/all/Oldconfig.U
+U/all/Oldsym.U
+U/all/Options.U
+U/all/orderlib.U
+U/all/otherlibdirs.U
+U/all/pager.U
+U/all/patchlevel.U
+U/all/perl5.U
+U/all/perladmin.U
+U/all/perlpath.U
+U/all/perlxvf.U
+U/all/perlxv.U
+U/all/pidsign.U
+U/all/pidsize.U
+U/all/pidtype.U
+U/all/prefix.U
+U/all/privlib.U
+U/all/Protochk.U
+U/all/ptrsize.U
+U/all/quadfio.U
+U/all/quadtype.U
+U/all/randbits.U
+U/all/randfunc.U
+U/all/sbrksmart.U
+U/all/scriptdir.U
+U/all/selectminbits.U
+U/all/selecttype.U
+U/all/Setprefixvar.U
+U/all/Signal.U
+U/all/sig_name.U
+U/all/sitearch.U
+U/all/sitebin.U
+U/all/sitehtml1dir.U
+U/all/sitehtml1.U
+U/all/sitehtml3dir.U
+U/all/sitehtml3.U
+U/all/sitelib.U
+U/all/siteman1dir.U
+U/all/siteman1.U
+U/all/siteman3dir.U
+U/all/siteman3.U
+U/all/siteprefix.U
+U/all/sitescriptdir.U
+U/all/sitescript.U
+U/all/sizesize.U
+U/all/sizetype.U
+U/all/sockopt.U
+U/all/socksizetype.U
+U/all/so.U
+U/all/spitshell.U
+U/all/src.U
+U/all/ssizesize.U
+U/all/ssizetype.U
+U/all/startperl.U
+U/all/stdchar.U
+U/all/stdio64.U
+U/all/stdio_streams.U
+U/all/sunscanf.U
+U/all/trnl.U
+U/all/Tr.U
+U/all/Typedef.U
+U/all/uidf.U
+U/all/uidsign.U
+U/all/uidsize.U
+U/all/uidtype.U
+U/all/Unix.U
+U/all/use64bits.U
+U/all/uselfs.U
+U/all/uselongdbl.U
+U/all/uselonglong.U
+U/all/usemorebits.U
+U/all/usemultiplicity.U
+U/all/usenm.U
+U/all/useperlio.U
+U/all/usesocks.U
+U/all/usethreads.U
+U/all/usrinc.U
+U/all/vendorarch.U
+U/all/vendorbin.U
+U/all/vendorhtml1dir.U
+U/all/vendorhtml1.U
+U/all/vendorhtml3dir.U
+U/all/vendorhtml3.U
+U/all/vendorlib.U
+U/all/vendorman1dir.U
+U/all/vendorman1.U
+U/all/vendorman3dir.U
+U/all/vendorman3.U
+U/all/vendorprefix.U
+U/all/vendorscript.U
+U/all/versiononly.U
+U/all/voidflags.U
+U/all/xs_apiversion.U
diff --git a/U/mkgloss.pl b/U/mkgloss.pl
new file mode 100755 (executable)
index 0000000..81b5d5a
--- /dev/null
@@ -0,0 +1,32 @@
+#!/pro/bin/perl
+
+# (c)'06 H.Merijn Brand [ 09 Apr 2006 ]
+
+# This script combines the output of mkglossary, with the suggested
+# patches (see README), and sorts the list
+
+use strict;
+use warnings;
+
+@ARGV = ("U/mkglossary |");
+$/ = undef;
+my @g = split m{(?<=\n\n)(?=\S)}, <>, -1;
+
+print splice @g, 0, 2;
+for (sort { lc $a cmp lc $b } @g) {
+    if (m/^make_set_make /) {
+       s/Configure -D option/Configure '-D' option/;
+       }
+    if (m/^n /) {
+       s/contains the -n flag/contains the '-n' flag/;
+       }
+    if (m/^sh /) {
+       s/set sh with a -D$/set sh with a '-D'/m;
+       s{with -O -Dsh=/bin/whatever -Dstartsh=whatever}
+        {with '-O -Dsh=/bin/whatever -Dstartsh=whatever'};
+       }
+    if (m/^spitshell /) {
+       s/cat or a grep -v for # comments/cat or a grep '-v' for # comments/;
+       }
+    print;
+    }
diff --git a/metaconfig.html b/metaconfig.html
new file mode 100644 (file)
index 0000000..fd4c7a3
--- /dev/null
@@ -0,0 +1,1869 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">\r
+\r
+\r
+<HTML>\r
+<HEAD>\r
+\r
+\r
+\r
+\r
+\r
+       <base href="http://linux.com.hk:80/penguin/" />\r
+       <TITLE>metaconfig - a Configure script generator
+ Linux Man Page</TITLE>\r
+\r
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">\r
+<META name="GENERATOR" content="IBM WebSphere Studio">\r
+<LINK rel="stylesheet" href="theme/Master.css" type="text/css">\r
+<LINK rel="stylesheet" href="theme/layout.css" type="text/css">\r
+<script type="text/javascript" src="js/common.js"></script>\r
+<!-- google analytics -->\r
+<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">\r
+</script>\r
+<script type="text/javascript">\r
+_uacct = "UA-90513-1";\r
+urchinTracker();\r
+</script>\r
+</HEAD>\r
+<BODY>\r
+\r
+\r
+\r
+<DIV class="container">\r
+<TABLE class="container">\r
+       <TR class="container_up">\r
+               <TD class="container_up"><!-- topbar -->\r
+               <DIV class="topbar"><A href="index.jsp"> <IMG border="0"\r
+                       src="images/logo.png" /> </A> \r
+                       <!--topbar ad area-->\r
+               <DIV id="topbaradv">                            \r
+        <script type="text/javascript"><!--\r
+                        google_ad_client = "pub-2404433452734258";  \r
+                        google_ad_width = 468;\r
+                        google_ad_height = 60;\r
+                        google_ad_format = "468x60_as";\r
+                        google_ad_channel ="5458575456"; \r
+                        google_ad_type = "text_image";  \r
+        //--></script>\r
+        <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>\r
+        </DIV>                 \r
+               </DIV>\r
+               <!--- navbar --->\r
+               <CENTER class=navbar><TABLE width="100%" class="navtable">\r
+       <TR align="center" class="navtable">\r
+               <TD class="navtable"><a href=about.jsp class="navtable"> Company</a></TD>\r
+               <TD class="navtable"><a href=products.jsp class="navtable"> Products</a></TD>\r
+               <TD class="navtable"><a href=innovation.jsp class="navtable"> Innovation</a></TD>\r
+               <TD class="navtable"><a href=manpages.jsp class="navtable"> Man pages</a></TD>\r
+               <TD class="navtable"><a href=developer.jsp class="navtable"> Developer</a></TD>\r
+               <TD class="navtable"><a href=mirrors.jsp class="navtable"> Mirrors</a></TD>\r
+               <TD class="navtable"><a href=search.jsp class="navtable"> Search</a></TD>\r
+       </TR>\r
+</TABLE></CENTER>\r
+               <DIV  class="sidebar">\r
+               \r
+               <!--sidebar ---> \r
+               \r
+               </DIV>\r
+               <DIV class="bodypart">\r
+               <STYLE>\r
+               DIV.bodypart {\r
+                       margin-left:5px;\r
+               }\r
+               </STYLE>\r
+               \r
+               <a href="http://linux.com.hk:80/penguin/man?action=print"><img src='images/printer.gif'></a>\r
+                       &nbsp;\r
+               <a href="http://linux.com.hk:80/penguin/man/1/m/" class="mannavlink">back to section</a>\r
+               \r
+               <script type="text/javascript"><!--\r
+               google_ad_client = "pub-2404433452734258";\r
+               google_ad_width = 468;\r
+               google_ad_height = 15;\r
+               google_ad_format = "468x15_0ads_al";\r
+               google_ad_channel ="5458575456";\r
+               google_color_border = "336699";\r
+               google_color_bg = "FFFFFF";\r
+               google_color_link = "0000FF";\r
+               google_color_url = "008000";\r
+               google_color_text = "000000";\r
+               //--></script>\r
+               <script type="text/javascript"\r
+                 src="http://pagead2.googlesyndication.com/pagead/show_ads.js">\r
+               </script>               \r
+               \r
+               </br>           \r
+               <HTML><HEAD>
+<link rel="stylesheet" type="text/css" href="theme/manpage.css">
+<TITLE>
+METACONFIG &nbsp;&nbsp;(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:?%&lt;: 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 %&lt; 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 ?%&lt;:, 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.&nbsp;&nbsp;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.&nbsp;&nbsp;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 $@ %&lt;
+?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:%&lt;: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 '&gt;/dev/null 2&gt;&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.&nbsp;&nbsp;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 '&gt;&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.&nbsp;&nbsp;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.&nbsp;&nbsp;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 '&lt;&lt;' 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 "--&gt; first here document:"
+cat &lt;&lt;EOM
+var='$var'
+tar='$tar'
+EOM
+echo "--&gt; second here document:"
+cat &lt;&lt;'EOM'
+echo $var
+echo $tar
+EOM
+echo "--&gt; end."
+will produce, when run through a shell:
+--&gt; first here document:
+var='first'
+tar='second'
+--&gt; second here document:
+echo $var
+echo $tar
+--&gt; 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
+&nbsp;&nbsp;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.&nbsp;&nbsp;You may delete these comments.
+$spitshell &gt;intsize &lt;&lt;!GROK!THIS!
+$startsh
+!GROK!THIS!
+<BR>
+
+: In the following dollars and backticks do not need the extra backslash.
+$spitshell &gt;&gt;intsize &lt;&lt;'!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
+&nbsp;&nbsp;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 &gt;intsize &lt;&lt;!GROK!THIS!
+$startsh
+intsize='$intsize'
+!GROK!THIS!
+<BR>
+
+$spitshell &gt;&gt;intsize &lt;&lt;'!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
+&nbsp;&nbsp;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 &lt;&lt;!GROK!THIS! &gt;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.&nbsp;&nbsp;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))&nbsp;&nbsp;/* 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 &lt;string.h&gt; (USG systems) instead of &lt;strings.h&gt; (BSD systems).
+ */
+#$i_string I_STRING&nbsp;&nbsp;/**/
+<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&nbsp;&nbsp;&nbsp;/**/
+#$i_string I_STRING&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/**/
+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&nbsp;&nbsp;&nbsp;/**/
+/*#define I_STRING&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/**/
+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&nbsp;&nbsp;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 '%&lt;' (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 '?%&lt;' 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&nbsp;&nbsp;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:%&lt;:</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
+'%&lt;') 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 $@ %&lt;
+?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 ~ %&lt;:
+?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:?%&lt;:#$d_const HASCONST /**/
+?H:?%&lt;:#ifndef HASCONST
+?H:?%&lt;:#define const
+?H:?%&lt;:#endif
+?H:.
+?W:%&lt;:const
+?LINT:set d_const
+?LINT:known const
+: check for const keyword
+echo " "
+echo 'Checking to see if your C compiler knows about "const"...' &gt;&4
+/bin/cat &gt;const.c &lt;&lt;'EOCP'
+main()
+{
+ const char *foo;
+}
+EOCP
+if $cc -c $ccflags const.c &gt;/dev/null 2&gt;&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 '?%&lt;' 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
+'%&lt;' symbol gets wanted (%&lt; 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 '%&lt;'.
+<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--> &lt;BASEREV&gt;
+<DD> The base revision number of the package, derived from <I><FONT color=#001050>.package</I></FONT><R>.
+</DD> </R></DT></DL> <DL><DT> <!-- --> &lt;DATE&gt;
+<DD> The current date.
+</DD> </DT></DL> <DL><DT> <!-- --> &lt;MAINTLOC&gt;
+<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> <!-- --> &lt;PACKAGENAME&gt;
+<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> <!-- --> &lt;PATCHLEVEL&gt;
+<DD> The patch level of the <I><FONT color=#001050>metaconfig</I></FONT><R> program.
+</DD> </R></DT></DL> <DL><DT> <!-- --> &lt;VERSION&gt;
+<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:
+ &lt;$variable&gt;
+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 &lt;$baserev&gt; will replace &lt;BASEREV&gt; 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>&lt;sys/types.h&gt;</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> &gt;/dev/null 2&gt;&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 &gt;/dev/null 2&gt;&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 &lt;lwall@netlabs.com&gt; for version 2.0.
+<BR> Harlan Stenn &lt;harlan@mumps.pfcs.com&gt; for important unit extensions.
+<BR> Raphael Manfredi &lt;ram@hptnos02.grenoble.hp.com&gt;.
+<BR> Many other contributors for the
+<I><FONT color=#001050>metaconfig</I></FONT><R> units. See the credit file for a list.
+</UL> </R></LI> <LI> <span class="section">  FILES</span> <BR> <UL> <DL><DT> <!--  10--> LIB/dist/mcon/U/*.U
+<DD> Public unit files
+</DD> </DT></DL> <DL><DT> <!-- --> U/*.U
+<DD> Private unit files
+</DD> </DT></DL> <DL><DT> <!-- --> LIB/dist/mcon/Glossary
+<DD> Glossary file, describing all the metaconfig symbols.
+</DD> </DT></DL> <DL><DT> <!-- --> Obsolete
+<DD> Lists all the obsolete symbols used by the sources.
+</DD> </DT></DL> <DL><DT> <!-- --> Wanted
+<DD> Lists all the wanted symbols.
+<BR><BR> <!-- --> where LIB is /usr/share/dist.
+</DD> </DT></DL> </UL> </LI> <LI> <span class="section">  BUGS</span> <BR> <UL> Units are sometimes included unnecessarily if one of its symbols is
+accidentally mentioned, e.g. in a comment.
+Better too many units than too few, however.
+</UL> </LI> <LI> <span class="section">  SEE ALSO</span> <BR> <UL> <a href="man/1/pat.html">pat(1)</a> , <a href="man/1/makeSH.html">makeSH(1)</a> , <a href="man/1/makedist.html">makedist(1)</a> , <a href="man/1/metalint.html">metalint(1)</a> 
+</UL> </LI> </UL> </BODY></HTML>
+\r
+               \r
+               </DIV>\r
+               </TD>\r
+       </TR>\r
+       <TR class="container_bottom">\r
+               <TD class="container_bottom">\r
+               \r
+               <DIV class="bottombaradv">\r
+               <script type="text/javascript"><!--\r
+               google_ad_client = "pub-2404433452734258";\r
+               google_ad_width = 728;\r
+               google_ad_height = 90;\r
+               google_ad_format = "728x90_as";\r
+               google_ad_type = "text_image";\r
+               google_ad_channel ="5458575456";\r
+               //--></script>\r
+               <script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js"></script>\r
+               </DIV>                                          \r
+                               \r
+               <DIV class="bottombar">Current Users: 17 &copy; 1999-2006 Linux.com.hk <a href=http://Linux.com.hk/>PenguinSoft</a><br/>\r
+All trademarks and copyrights on this page are owned by their respective companies.\r
+Linux is a trademark of Linus Torvalds.\r
+\r
+</DIV>\r
+\r
+               </TD>\r
+       </TR>\r
+</TABLE><!--container-->\r
+</DIV><!--container-->\r
+</BODY>\r
+</HTML>\r