This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
U/README: Grammatical correction
[metaconfig.git] / 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 thinks 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