perl5.005_03 (stock)

1 files changed, 195 insertions, 52 deletions

diff --git a/gnu/usr.bin/perl/Porting/pumpkin.pod b/gnu/usr.bin/perl/Porting/pumpkin.pod
index 6706c6c3c42..335e49f2733 100644
--- a/gnu/usr.bin/perl/Porting/pumpkin.pod
+++ b/gnu/usr.bin/perl/Porting/pumpkin.pod
@@ -113,6 +113,8 @@ patch' entry in patchlevel.h.
 Watch for announcements of maintenance subversions in
 comp.lang.perl.announce.
 
+The first rule of maintenance work is "First, do no harm."
+
 =head2 Why such a complicated scheme?
 
 Two reasons, really.  At least.
@@ -217,9 +219,16 @@ patch these directly; patch the data files instead.
 
 F<Configure> and F<config_h.SH> are also automatically generated by
 B<metaconfig>.  In general, you should patch the metaconfig units
-instead of patching these files directly.  However, minor changes to
+instead of patching these files directly.  However, very minor changes to
 F<Configure> may be made in between major sync-ups with the metaconfig
-units, which tends to be complicated operations.
+units, which tends to be complicated operations.  But be careful, this
+can quickly spiral out of control.  Running metaconfig is not really
+hard.
+
+Finally, the sample files in the F<Porting/> subdirectory are
+generated automatically by the script F<U/mksample> included 
+with the metaconfig units.  See L<"run metaconfig"> below for
+information on obtaining the metaconfig units.
 
 =head1 How to Make a Distribution
 
@@ -273,16 +282,16 @@ change the appropriate metaconfig units instead, and regenerate Configure.
 
 	metaconfig -m
 
-will regenerate Configure and config_h.SH.  More information on
-obtaining and running metaconfig is in the F<U/README> file that comes
-with Perl's metaconfig units.  Perl's metaconfig units should be
-available the same place you found this file.  On CPAN, look under my
-directory F<authors/id/ANDYD/> for a file such as F<5.003_07-02.U.tar.gz>.
-That file should be unpacked in your main perl source directory.  It
-contains the files needed to run B<metaconfig> to reproduce Perl's
-Configure script.  (Those units are for 5.003_07.  There have been
-changes since then; please contact me if you want more recent
-versions, and I will try to point you in the right direction.)
+will regenerate Configure and config_h.SH.  Much more information
+on obtaining and running metaconfig is in the F<U/README> file
+that comes with Perl's metaconfig units.  Perl's metaconfig units
+should be available on CPAN.  A set of units that will work with
+perl5.005 is in the file F<mc_units-5.005_00-01.tar.gz> under
+http://www.perl.com/CPAN/authors/id/ANDYD/ .  The mc_units tar file
+should be unpacked in your main perl source directory.  Note: those
+units were for use with 5.005.  There may have been changes since then.
+Check for later versions or contact perl5-porters@perl.org to obtain a
+pointer to the current version.
 
 Alternatively, do consider if the F<*ish.h> files might be a better
 place for your changes.
@@ -297,17 +306,7 @@ program for this.  You can also use
 Both commands will also list extra files in the directory that are not
 listed in MANIFEST.
 
-The MANIFEST is normally sorted, with one exception.  Perl includes
-both a F<Configure> script and a F<configure> script.  The
-F<configure> script is a front-end to the main F<Configure>, but
-is there to aid folks who use autoconf-generated F<configure> files
-for other software.  The problem is that F<Configure> and F<configure>
-are the same on case-insensitive file systems, so I deliberately put
-F<configure> first in the MANIFEST so that the extraction of
-F<Configure> will overwrite F<configure> and leave you with the
-correct script.  (The F<configure> script must also have write
-permission for this to work, so it's the only file in the distribution
-I normally have with write permission.)
+The MANIFEST is normally sorted.
 
 If you are using metaconfig to regenerate Configure, then you should note
 that metaconfig actually uses MANIFEST.new, so you want to be sure
@@ -320,14 +319,15 @@ learned how to use the full suite of tools in the dist distribution.
 All the tests in the t/ directory ought to be executable.  The
 main makefile used to do a 'chmod t/*/*.t', but that resulted in
 a self-modifying distribution--something some users would strongly
-prefer to avoid.  Probably, the F<t/TEST> script should check for this
-and do the chmod if needed, but it doesn't currently.
+prefer to avoid.  The F<t/TEST> script will check for this
+and do the chmod if needed, but the tests still ought to be
+executable.
 
 In all, the following files should probably be executable:
 
     Configure
     configpm
-    configure
+    configure.gnu
     embed.pl
     installperl
     installman
@@ -340,7 +340,6 @@ In all, the following files should probably be executable:
     *.SH
     vms/ext/Stdio/test.pl
     vms/ext/filespec.t
-    vms/fndvers.com
     x2p/*.SH
 
 Other things ought to be readable, at least :-).
@@ -355,18 +354,43 @@ permissions for system files; something like that might be appropriate.
 =head2 Run Configure
 
 This will build a config.sh and config.h.  You can skip this if you haven't
-changed Configure or config_h.SH at all.
-
-=head2 Update config_H
-
-The config_H file is provided to help those folks who can't run Configure.
-It is important to keep it up-to-date.  If you have changed config_h.SH,
-those changes must be reflected in config_H as well.  (The name config_H was
-chosen to distinguish the file from config.h even on case-insensitive file
-systems.)  Simply edit the existing config_H file; keep the first few
-explanatory lines and then copy your new config.h below.
-
-It may also be necessary to update vms/config.vms and
+changed Configure or config_h.SH at all.  I use the following command
+
+    sh Configure -Dprefix=/opt/perl -Doptimize=-O -Dusethreads \
+	-Dcf_by='yourname' \
+	-Dcf_email='yourname@yourhost.yourplace.com' \
+	-Dperladmin='yourname@yourhost.yourplace.com' \
+	-Dmydomain='.yourplace.com' \
+	-Dmyhostname='yourhost' \
+	-des
+
+=head2 Update Porting/config.sh and Porting/config_H
+
+[XXX 
+This section needs revision.  We're currently working on easing
+the task of keeping the vms, win32, and plan9 config.sh info
+up-to-date.  The plan is to use keep up-to-date 'canned' config.sh
+files in the appropriate subdirectories and then generate 'canned'
+config.h files for vms, win32, etc. from the generic config.sh file.
+This is to ease maintenance.  When Configure gets updated, the parts
+sometimes get scrambled around, and the changes in config_H can
+sometimes be very hard to follow.  config.sh, on the other hand, can
+safely be sorted, so it's easy to track (typically very small) changes
+to config.sh and then propoagate them to a canned 'config.h' by any
+number of means, including a perl script in win32/ or carrying 
+config.sh and config_h.SH to a Unix system and running sh
+config_h.SH.)
+XXX]
+
+The Porting/config.sh and Porting/config_H files are provided to
+help those folks who can't run Configure.  It is important to keep
+them up-to-date.  If you have changed config_h.SH, those changes must
+be reflected in config_H as well.  (The name config_H was chosen to
+distinguish the file from config.h even on case-insensitive file systems.)
+Simply edit the existing config_H file; keep the first few explanatory
+lines and then copy your new config.h below.
+
+It may also be necessary to update win32/config.?c, vms/config.vms and
 plan9/config.plan9, though you should be quite careful in doing so if
 you are not familiar with those systems.  You might want to issue your
 patch with a promise to quickly issue a follow-up that handles those
@@ -389,13 +413,13 @@ task.
 
 Some additional notes from Larry on this:
 
-Don't forget to regenerate perly.c.diff.
+Don't forget to regenerate perly_c.diff.
 
     byacc -d perly.y
     mv y.tab.c perly.c
-    patch perly.c <perly.c.diff
+    patch perly.c <perly_c.diff
     # manually apply any failed hunks
-    diff -c2 perly.c.orig perly.c >perly.c.diff
+    diff -c2 perly.c.orig perly.c >perly_c.diff
 
 One chunk of lines that often fails begins with
 
@@ -467,6 +491,23 @@ ought to go in the Changes file or whether they ought to be available
 separately in the patch file (or both).  There is no disagreement that
 detailed descriptions ought to be easily available somewhere.
 
+=head2 Todo
+
+The F<Todo> file contains a roughly-catgorized unordered list of
+aspects of Perl that could use enhancement, features that could be
+added, areas that could be cleaned up, and so on.  During your term as
+pumpkin-holder, you will probably address some of these issues, and
+perhaps identify others which, while you decide not to address them
+this time around, may be tackled in the future.  Update the file
+reflect the situation as it stands when you hand over the pumpkin.
+
+You might like, early in your pumpkin-holding career, to see if you
+can find champions for partiticular issues on the to-do list: an issue
+owned is an issue more likely to be resolved.
+
+There are also some more porting-specific L<Todo> items later in this
+file.
+
 =head2 OS/2-specific updates
 
 In the os2 directory is F<diff.configure>, a set of OS/2-specific
@@ -1030,6 +1071,62 @@ distribution modules.  If you do
 
 then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB.
 
+=head2 Shared libperl.so location
+
+Why isn't the shared libperl.so installed in /usr/lib/ along
+with "all the other" shared libraries?  Instead, it is installed
+in $archlib, which is typically something like
+
+	/usr/local/lib/perl5/archname/5.00404
+
+and is architecture- and version-specific.
+
+The basic reason why a shared libperl.so gets put in $archlib is so that
+you can have more than one version of perl on the system at the same time,
+and have each refer to its own libperl.so.
+
+Three examples might help.  All of these work now; none would work if you
+put libperl.so in /usr/lib.
+
+=over
+
+=item 1.
+
+Suppose you want to have both threaded and non-threaded perl versions
+around.  Configure will name both perl libraries "libperl.so" (so that
+you can link to them with -lperl).  The perl binaries tell them apart
+by having looking in the appropriate $archlib directories.
+
+=item 2.
+
+Suppose you have perl5.004_04 installed and you want to try to compile
+it again, perhaps with different options or after applying a patch.
+If you already have libperl.so installed in /usr/lib/, then it may be
+either difficult or impossible to get ld.so to find the new libperl.so
+that you're trying to build.  If, instead, libperl.so is tucked away in
+$archlib, then you can always just change $archlib in the current perl
+you're trying to build so that ld.so won't find your old libperl.so.
+(The INSTALL file suggests you do this when building a debugging perl.)
+
+=item 3.
+
+The shared perl library is not a "well-behaved" shared library with
+proper major and minor version numbers, so you can't necessarily
+have perl5.004_04 and perl5.004_05 installed simultaneously.  Suppose
+perl5.004_04 were to install /usr/lib/libperl.so.4.4, and perl5.004_05
+were to install /usr/lib/libperl.so.4.5.  Now, when you try to run
+perl5.004_04, ld.so might try to load libperl.so.4.5, since it has
+the right "major version" number.  If this works at all, it almost
+certainly defeats the reason for keeping perl5.004_04 around.  Worse,
+with development subversions, you certaily can't guarantee that
+libperl.so.4.4 and libperl.so.4.55 will be compatible.
+
+Anyway, all this leads to quite obscure failures that are sure to drive
+casual users crazy.  Even experienced users will get confused :-).  Upon
+reflection, I'd say leave libperl.so in $archlib.
+
+=back
+
 =head1 Upload Your Work to CPAN
 
 You can upload your work to CPAN if you have a CPAN id.  Check out
@@ -1073,12 +1170,23 @@ described in F<INSTALL>.  AFS users also are treated specially.
 We should probably duplicate the metaconfig prefix stuff for an
 install prefix.
 
-=item Configure -Dsrcdir=/blah/blah
+=item Configure -Dsrc=/blah/blah
 
 We should be able to emulate B<configure --srcdir>.  Tom Tromey
 tromey@creche.cygnus.com has submitted some patches to
-the dist-users mailing list along these lines.  Eventually, they ought
-to get folded back into the main distribution.
+the dist-users mailing list along these lines.  They have been folded
+back into the main distribution, but various parts of the perl
+Configure/build/install process still assume src='.'.
+
+=item Directory for vendor-supplied modules?
+
+If a vendor supplies perl, but wants to leave $siteperl and $sitearch
+for the local user to use, where should the vendor put vendor-supplied
+modules (such as Tk.so?)  If the vendor puts them in $archlib, then
+they need to be updated each time the perl version is updated.
+Perhaps we need a set of libries $vendorperl and $vendorarch that
+track $apiversion (like the $sitexxx directories do) rather than
+just $version (like the main perl directory).
 
 =item Hint file fixes
 
@@ -1090,6 +1198,47 @@ Configure so that most of them aren't needed.
 Some of the hint file information (particularly dynamic loading stuff)
 ought to be fed back into the main metaconfig distribution.
 
+=item Catch GNU Libc "Stub" functions
+
+Some functions (such as lchown()) are present in libc, but are
+unimplmented.  That is, they always fail and set errno=ENOSYS.
+
+Thomas Bushnell provided the following sample code and the explanation
+that follows:
+
+    /* System header to define __stub macros and hopefully few prototypes,
+	which can conflict with char FOO(); below.  */
+    #include <assert.h>
+    /* Override any gcc2 internal prototype to avoid an error.  */
+    /* We use char because int might match the return type of a gcc2
+	builtin and then its argument prototype would still apply.  */
+    char FOO();
+
+    int main() {
+
+    /* The GNU C library defines this for functions which it implements
+	to always fail with ENOSYS.  Some functions are actually named
+	something starting with __ and the normal name is an alias.  */
+    #if defined (__stub_FOO) || defined (__stub___FOO)
+    choke me
+    #else
+    FOO();
+    #endif
+
+    ; return 0; }
+
+The choice of <assert.h> is essentially arbitrary.  The GNU libc
+macros are found in <gnu/stubs.h>.  You can include that file instead
+of <assert.h> (which itself includes <gnu/stubs.h>) if you test for
+its existence first.  <assert.h> is assumed to exist on every system,
+which is why it's used here.  Any GNU libc header file will include
+the stubs macros.  If either __stub_NAME or __stub___NAME is defined,
+then the function doesn't actually exist.  Tests using <assert.h> work
+on every system around.
+
+The declaration of FOO is there to override builtin prototypes for
+ANSI C functions.
+
 =back
 
 =head2 Probably good ideas waiting for round tuits
@@ -1135,12 +1284,6 @@ Get some of the Macintosh stuff folded back into the main distribution.
 Maybe include a replacement function that doesn't lose data in rare
 cases of coercion between string and numerical values.
 
-=item long long
-
-Can we support C<long long> on systems where C<long long> is larger
-than what we've been using for C<IV>?  What if you can't C<sprintf>
-a C<long long>?
-
 =item Improve makedepend
 
 The current makedepend process is clunky and annoyingly slow, but it
@@ -1177,4 +1320,4 @@ All opinions expressed herein are those of the authorZ<>(s).
 
 =head1 LAST MODIFIED
 
-$Id: pumpkin.pod,v 1.13 1997/08/28 18:26:40 doughera Released $
+$Id: pumpkin.pod,v 1.22 1998/07/22 16:33:55 doughera Released $