[metaconfig.git] / U / README.dist


		     Perl5 Metaconfig Units

	     Copyright (c) 1996-1998, Andy Dougherty
	     Copyright (c) 1999-2011, H.Merijn Brand
			All rights reserved.

These units are the ones I used to build Configure and config_h.SH
in the Perl5 distribution.

The Configure script and config_h.SH file in the Perl distribution are
generated by a program called metaconfig.  To run metaconfig, you will
need the full dist 3.0 distribution, maintained by Raphael Manfredi.
As of this writing, the current version is dist3.0, patchlevel 70.
Dist version dist-3.0@70.tar.gz is available on CPAN (the Comprehensive
Perl Archive Network) as
<http://www.perl.com/perl/CPAN/authors/id/RAM/dist-3.0@70.tar.gz>.

Instructions:

1.  Unpack the full perl5 sources.  Execute the following command

	chmod +w Configure config_h.SH Porting/Glossary Porting/config*

2.  Unpack the archive containing this file in the perl5 source
    directory.  This will create a directory 'U' under the perl5
    sources.  That directory will contain the metaconfig units for perl5.
    This will also create two files in the perl5 source tree:
    MANIFEST.new and .package.

3.  Apply any patches to perl in the perl_patches/ directory.
    (This may well be empty.)

4.  Obtain and install dist-3.0pl70.

4.  Apply any patches to dist under the dist_patches subdirectory.

5.  From your main perl5 source directory, run packinit to
    regenerate the .package file.  IMPORTANT:  Change the name and
    address of the maintainer to your own name and address.  I don't
    want bug reports intended for you coming to me.

6.  From your main perl5 source directory, run

	metalint (or mlint)

    and repair every failure it reports.

7.  From your main perl5 source directory, run

	metaconfig -m (or mconfig -m)

8.  Edit U/mkglossary and/or U/mkgloss.pl to point to your dist-3.0pl70
    location.  (See comments at the top.)

9.  Run the Porting/mksample script to update the contents of the Porting/
    subdirectory, or run all parts by hand. (see README)

    NB: this script used to be U/mksample replaced by Porting/mksample;
    see Porting/pumpkin.pod instead for current documentation on its
    use.

10. Let me know about any changes, corrections, or enhancements.

Things to watch out for:

1.  Future support of better random number generators should probably
    start with the randfunc.U unit included here.  It's currently
    broken, but well commented and probably a good place to start.

Descriptions:

The units and other related files have been broken up into the following
directories:

acl/
    This is an old patch to begin to detect and use ACL (access
    control list) file protection schemes.

compline/
    These are similar to the standard units, but I have modified them
    to have a more uniform compile command line, usually using the new
    Compile.U unit.  I have submitted these for inclusion into the
    regular dist distribution.  (The ccflags.U unit is actually
    perl-specific since it mentions -DDEBUGGING and -DPOSIX_SOURCE,
    but that's the only place it is perl-specific.)

dist_patches/
    These are patches to dist that must be applied before it is built
    and installed.  I have submitted these for inclusion in the
    regular dist distribution.

modified/
    These are modified versions of the standard units.  Also included in
    this directory are new units that are clearly derived from existing
    units.  I have submitted these for inclusion in the regular dist
    distribution.

perl/
    These are specific to perl.  Some are heavily derived from
    original dist units, and are marked as such.  Others are original.

perl_patches/
    These are patches to the perl source.  This directory
    should ordinarily be empty, but there may have been drift between
    the standard version of perl and the one associated with these
    units.

protos/
    These are units modified to use the new Hasproto.U or Protochk.U
    units to check for prototypes.  I have submitted these for inclusion
    into the regular dist distribution.

target/
    This is the very, very beginning of cross-compiler support.
    It doesn't work yet, and many standard units will need
    modification.

typedefs/
    These are standard units modified to use the modified Typedef.U
    unit to check for typedefs.  (The modified Typdef.U includes a
    function to avoid unnecessary prompts if the typdef being searched
    for exists.)  I have submitted these for inclusion into the
    regular dist distribution.

threads/
    These are specific to threading perl.

Copyright Information:

Unless otherwise indicated, the files contained in this
distribution are:

    Copyright (c) 1996-1998, Andy Dougherty

The following licensing terms apply to all files contained in
this distribution:

You may distribute the files contained in this distribution
under the terms of either

    a) the "Artistic License" which comes with Perl, or

    b) the "Artistic License" which comes with dist, or

    c) the GNU General Public License as published by the Free
    Software Foundation; either version 1, or (at your option) any
    later version (see the file "Copying" that comes with the
    Perl distribution).

Which one to use is your choice.

The units in the "modified" directory have been derived from units
associated with the metaconfig program of Raphael Manfredi's "dist"
distribution.  These units list Raphael Manfredi as the Copyright holder.
dist is distributed under a modified version of the Perl Artistic License.
Clause 7 of this modified license as contained in dist-3.0-pl60 provides:

    7. You may reuse parts of this Package in your own programs, provided
    that you explicitly state where you got them from, in the source code
    (and, left to your courtesy, in the documentation), duplicating
    all the associated copyright notices and disclaimers. Besides
    your changes, if any, must be clearly marked as such. Parts reused
    that way will no longer fall under this license if, and only if,
    the name of your program(s) have no immediate connection with the
    name of the Package itself or its associated programs.  You may then
    apply whatever restrictions you wish on the reused parts or choose
    to place them in the Public Domain--this will apply only within the
    context of your package.

In accordance with this clause, the versions of these units
contained here are made available under the same terms as the
rest of the units.

If you have any questions about the use of these units or about
the differences between these units and the standard versions, please
feel free to ask.

    Andy Dougherty			doughera@lafayette.edu
    Dept. of Physics
    Lafayette College
    Easton, PA  18042-1782
Commit	Line	Data
959f3c4c JH	1
	2	Perl5 Metaconfig Units
	3
	4	Copyright (c) 1996-1998, Andy Dougherty
86b74a81	5	Copyright (c) 1999-2011, H.Merijn Brand
959f3c4c JH	6	All rights reserved.
	7
	8	These units are the ones I used to build Configure and config_h.SH
	9	in the Perl5 distribution.
	10
	11	The Configure script and config_h.SH file in the Perl distribution are
	12	generated by a program called metaconfig. To run metaconfig, you will
	13	need the full dist 3.0 distribution, maintained by Raphael Manfredi.
	14	As of this writing, the current version is dist3.0, patchlevel 70.
	15	Dist version dist-3.0@70.tar.gz is available on CPAN (the Comprehensive
	16	Perl Archive Network) as
	17	<http://www.perl.com/perl/CPAN/authors/id/RAM/dist-3.0@70.tar.gz>.
	18
	19	Instructions:
	20
	21	1. Unpack the full perl5 sources. Execute the following command
	22
	23	chmod +w Configure config_h.SH Porting/Glossary Porting/config*
	24
	25	2. Unpack the archive containing this file in the perl5 source
	26	directory. This will create a directory 'U' under the perl5
	27	sources. That directory will contain the metaconfig units for perl5.
	28	This will also create two files in the perl5 source tree:
	29	MANIFEST.new and .package.
	30
	31	3. Apply any patches to perl in the perl_patches/ directory.
	32	(This may well be empty.)
	33
	34	4. Obtain and install dist-3.0pl70.
	35
	36	4. Apply any patches to dist under the dist_patches subdirectory.
	37
	38	5. From your main perl5 source directory, run packinit to
	39	regenerate the .package file. IMPORTANT: Change the name and
	40	address of the maintainer to your own name and address. I don't
	41	want bug reports intended for you coming to me.
	42
	43	6. From your main perl5 source directory, run
	44
86b74a81	45	metalint (or mlint)
83110c7a MB	46
	47	and repair every failure it reports.
	48
	49	7. From your main perl5 source directory, run
	50
86b74a81	51	metaconfig -m (or mconfig -m)
959f3c4c	52
83110c7a MB	53	8. Edit U/mkglossary and/or U/mkgloss.pl to point to your dist-3.0pl70
83110c7a MB	54	location. (See comments at the top.)
959f3c4c	55
82e3f9e4	56	9. Run the Porting/mksample script to update the contents of the Porting/
83110c7a	57	subdirectory, or run all parts by hand. (see README)
959f3c4c	58
82e3f9e4 DH	59	NB: this script used to be U/mksample replaced by Porting/mksample;
	60	see Porting/pumpkin.pod instead for current documentation on its
	61	use.
	62
83110c7a	63	10. Let me know about any changes, corrections, or enhancements.
959f3c4c JH	64
	65	Things to watch out for:
	66
59bf5d98	67	1. Future support of better random number generators should probably
959f3c4c JH	68	start with the randfunc.U unit included here. It's currently
	69	broken, but well commented and probably a good place to start.
	70
	71	Descriptions:
	72
	73	The units and other related files have been broken up into the following
	74	directories:
	75
	76	acl/
	77	This is an old patch to begin to detect and use ACL (access
	78	control list) file protection schemes.
	79
	80	compline/
	81	These are similar to the standard units, but I have modified them
	82	to have a more uniform compile command line, usually using the new
	83	Compile.U unit. I have submitted these for inclusion into the
	84	regular dist distribution. (The ccflags.U unit is actually
	85	perl-specific since it mentions -DDEBUGGING and -DPOSIX_SOURCE,
	86	but that's the only place it is perl-specific.)
	87
	88	dist_patches/
	89	These are patches to dist that must be applied before it is built
	90	and installed. I have submitted these for inclusion in the
	91	regular dist distribution.
	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	perl/
	100	These are specific to perl. Some are heavily derived from
	101	original dist units, and are marked as such. Others are original.
	102
	103	perl_patches/
	104	These are patches to the perl source. This directory
	105	should ordinarily be empty, but there may have been drift between
	106	the standard version of perl and the one associated with these
	107	units.
	108
	109	protos/
	110	These are units modified to use the new Hasproto.U or Protochk.U
	111	units to check for prototypes. I have submitted these for inclusion
	112	into the regular dist distribution.
	113
	114	target/
	115	This is the very, very beginning of cross-compiler support.
	116	It doesn't work yet, and many standard units will need
	117	modification.
	118
	119	typedefs/
	120	These are standard units modified to use the modified Typedef.U
	121	unit to check for typedefs. (The modified Typdef.U includes a
	122	function to avoid unnecessary prompts if the typdef being searched
	123	for exists.) I have submitted these for inclusion into the
	124	regular dist distribution.
	125
	126	threads/
	127	These are specific to threading perl.
	128
	129	Copyright Information:
	130
	131	Unless otherwise indicated, the files contained in this
132	distribution are:
133
134	Copyright (c) 1996-1998, Andy Dougherty
135
136	The following licensing terms apply to all files contained in
137	this distribution:
138
139	You may distribute the files contained in this distribution
140	under the terms of either
141
142	a) the "Artistic License" which comes with Perl, or
143
144	b) the "Artistic License" which comes with dist, or
145
146	c) the GNU General Public License as published by the Free
147	Software Foundation; either version 1, or (at your option) any
148	later version (see the file "Copying" that comes with the
149	Perl distribution).
150
151	Which one to use is your choice.
152
153	The units in the "modified" directory have been derived from units
154	associated with the metaconfig program of Raphael Manfredi's "dist"
155	distribution. These units list Raphael Manfredi as the Copyright holder.
156	dist is distributed under a modified version of the Perl Artistic License.
157	Clause 7 of this modified license as contained in dist-3.0-pl60 provides:
158
159	7. You may reuse parts of this Package in your own programs, provided
160	that you explicitly state where you got them from, in the source code
161	(and, left to your courtesy, in the documentation), duplicating
162	all the associated copyright notices and disclaimers. Besides
163	your changes, if any, must be clearly marked as such. Parts reused
164	that way will no longer fall under this license if, and only if,
165	the name of your program(s) have no immediate connection with the
166	name of the Package itself or its associated programs. You may then
167	apply whatever restrictions you wish on the reused parts or choose
168	to place them in the Public Domain--this will apply only within the
169	context of your package.
170
171	In accordance with this clause, the versions of these units
172	contained here are made available under the same terms as the
173	rest of the units.
174
175	If you have any questions about the use of these units or about
176	the differences between these units and the standard versions, please
177	feel free to ask.
178
179	Andy Dougherty doughera@lafayette.edu
180	Dept. of Physics
181	Lafayette College
182	Easton, PA 18042-1782