U/README

   1
   2                      Perl5 Metaconfig Units
   3
   4              Copyright (c) 1996-1998, Andy Dougherty
   5              Copyright (c) 1999-2011, H.Merijn Brand
   6                         All rights reserved.
   7
   8 These units are the ones used to build Configure and config_h.SH
   9 in the Perl5 distribution.
  10
  11 metaconfig will first look in its standard locations (specified when you
  12 installed dist).  It will then recurse through the 'U' subdirectory
  13 and find any additional "private" units.  Private units override
  14 standard ones supplied with metaconfig.
  15
  16 Files in this directory:
  17
  18 README
  19     This file.
  20
  21 Glossary.patch
  22     The standard dist units contain some strings that make pod2man
  23     complain.  This patch silences those warnings.  As new units are
  24     added and Configure is regenerated, this patch may need more and more
  25     'fuzz' to be applied.  It should be freshly regenerated every once
  26     in a while. See also mkgloss.pl
  27
  28 ln-all.pl
  29     Re-generate the all/ folder
  30
  31 mkglossary
  32     A script to regenerate Porting/Glossary.  You have to manually
  33     edit the top of the script to point the location of your metaconfig
  34     units.  It is called automatically by 'mksample'. See also mkgloss.pl
  35
  36 mkgloss.pl
  37     A perl script that calls U/mkglossary from the perl source tree, sorts
  38     the list of symbols, and applies the patch mentioned in Glossary.patch.
  39     When called on its own, redirect the output to a temporary file,  and
  40     compare that file to Porting/Glossary before applying.
  41
  42 mksample
  43     A script to regenerate Porting/config.sh and Porting/config.H.
  44     It also calls mkglossary, if necessary.
  45
  46 Subdirectories:
  47
  48 The units and other related files have been broken up into the following
  49 directories.
  50
  51 a_dvisory/
  52     These are units that have to go first in the generated config_h.SH.
  53     A word of explanation:  Configure and config_h.SH are generated from 'Units'
  54     (the *.U files).  Files indicate dependencies (using make(1)), and
  55     Configure is built to follow those dependencies.  However, config_h.SH
  56     is simply built by putting all the units in alphabetical order and
  57     extracting the relevant lines.  (This could be fixed, I suppose, but
  58     it wasn't trivial the one time I looked.)
  59     The a_dvisory/ directory, then, is a place to put units that need
  60     to be early in config_h.SH.  (Most units are self-contained
  61     and ought to be able to go anywhere.  However, some things, like
  62     byteorder, need to have the #defines from multiarch available.)
  63
  64 acl/
  65     This is an old patch to begin to detect and use ACL (access
  66     control list) file protection schemes.
  67
  68 all/
  69     A folder that conveniently holds symbolic links to all the modules
  70     that are used to build the current Configure and config_h.SH.
  71
  72 compline/
  73     These are similar to the standard units, but I have modified them
  74     to have a more uniform compile command line, usually using the
  75     new Compile.U unit.  (The ccflags.U unit is perl-specific since it
  76     mentions -DDEBUGGING and -DPOSIX_SOURCE, but that's the only place
  77     it is perl-specific.)
  78
  79 dist_patches/
  80     These are patches to dist that must be applied before it is built
  81     and installed.  I have submitted these for inclusion in the
  82     regular dist distribution.  They have already been applied
  83     to the ../dist-3.0at70b directory.
  84
  85 ebcdic/
  86     These are units that had to be specially modified to work under
  87     either EBCDIC or ASCII.
  88
  89 installdirs/
  90     These are units to handle perl's installation directories and
  91     related issues.
  92
  93 modified/
  94     These are modified versions of the standard units.  Also included in
  95     this directory are new units that are clearly derived from existing
  96     units.  I have submitted these for inclusion in the regular dist
  97     distribution.
  98
  99 nullified/
 100     These are null units that replace units in the standard
 101     distribution.  Typically they are there because some part of the
 102     perl source accidentally uses a symbol that metaconfig means we
 103     want the corresponding unit.
 104
 105 perl/
 106     These are specific to perl.  Some are heavily derived from
 107     original dist units, and are marked as such.  Others are original.
 108
 109 perl_patches/
 110     These are patches to the perl source.  This directory
 111     should ordinarily be empty, but there may have been drift between
 112     the standard version of perl and the one associated with these
 113     units.
 114
 115 protos/
 116     These are units modified to use the new Hasproto.U or Protochk.U
 117     units to check for prototypes.
 118
 119 threads/
 120     These are specific to threading perl.
 121
 122 typedefs/
 123     These are standard units modified to use the modified Typedef.U
 124     unit to check for typedefs.  (The modified Typdef.U includes a
 125     function to avoid unnecessary prompts if the typdef being searched
 126     for exists.)
 127
 128
 129 Where appropriate, I submitted these units for inclusion into the
 130 regular dist distribution.  However, since dist is no longer actively
 131 maintained, and the alternative is for *me* to actively maintain it,
 132 the units just sit here.
 133
 134 Copyright Information:
 135
 136 Unless otherwise indicated, the files contained in this
 137 distribution are:
 138
 139     Copyright (c) 1996-1998, Andy Dougherty
 140
 141 The following licensing terms apply to all files contained in
 142 this distribution:
 143
 144 You may distribute the files contained in this distribution
 145 under the terms of either
 146
 147     a) the "Artistic License" which comes with Perl, or
 148
 149     b) the "Artistic License" which comes with dist, or
 150
 151     c) the GNU General Public License as published by the Free
 152     Software Foundation; either version 1, or (at your option) any
 153     later version (see the file "Copying" that comes with the
 154     Perl distribution).
 155
 156 Which one to use is your choice.
 157
 158 The units in the "modified" directory have been derived from units
 159 associated with the metaconfig program of Raphael Manfredi's "dist"
 160 distribution.  These units list Raphael Manfredi as the Copyright holder.
 161 dist is distributed under a modified version of the Perl Artistic License.
 162 Clause 7 of this modified license as contained in dist-3.0-pl60 provides:
 163
 164     7. You may reuse parts of this Package in your own programs, provided
 165     that you explicitly state where you got them from, in the source code
 166     (and, left to your courtesy, in the documentation), duplicating
 167     all the associated copyright notices and disclaimers. Besides
 168     your changes, if any, must be clearly marked as such. Parts reused
 169     that way will no longer fall under this license if, and only if,
 170     the name of your program(s) have no immediate connection with the
 171     name of the Package itself or its associated programs.  You may then
 172     apply whatever restrictions you wish on the reused parts or choose
 173     to place them in the Public Domain--this will apply only within the
 174     context of your package.
 175
 176 In accordance with this clause, the versions of these units
 177 contained here are made available under the same terms as the
 178 rest of the units.
 179
 180 If you have any questions about the use of these units or about
 181 the differences between these units and the standard versions, please
 182 feel free to ask.
 183
 184     Andy Dougherty                      doughera@lafayette.edu
 185     Dept. of Physics
 186     Lafayette College
 187     Easton, PA  18042-1782