[inseparable changes from patch from perl5.003_27 to perl5.003_28]

 CORE LANGUAGE CHANGES

Subject: Don't let C<sub foo;> undefine &foo
From: Chip Salzenberg <chip@perl.com>
Files: op.c

Subject: Make code, doc agree on $ENV{PATH} and `cmd`
From: Chip Salzenberg <chip@perl.com>
Files: pod/perlsec.pod pp_sys.c

Subject: Optimize keys() and values() in void context
From: Chip Salzenberg <chip@perl.com>
Files: doop.c op.c

 CORE PORTABILITY

Subject: VMS patches post _27
Date: Thu, 20 Feb 1997 01:58:46 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: MANIFEST dosish.h hv.c lib/ExtUtils/MM_VMS.pm lib/ExtUtils/xsubpp perl.c perlsdio.h pod/perldelta.pod pod/perlvar.pod t/op/closure.t unixish.h vms/Makefile vms/descrip.mms vms/ext/filespec.t vms/genconfig.pl vms/vms.c vms/vmsish.h

    private-msgid: <01IFMEMPN1IU0057E2@hmivax.humgen.upenn.edu>

Subject: Re: OS/2 patch for _27
Date: Thu, 20 Feb 1997 19:24:16 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: INSTALL README.os2 lib/Test/Harness.pm os2/Changes os2/OS2/PrfDB/t/os2_prfdb.t os2/os2.c os2/os2ish.h os2/perl2cmd.pl perl.c pod/perldelta.pod t/TEST t/harness t/op/magic.t
Msg-ID: <199702210024.TAA03174@monk.mps.ohio-state.edu>

    (applied based on p5p patch as commit 833d3f255ed68b969f062cec63d33f853ed9237c)

 DOCUMENTATION

Subject: INSTALL updates since _26
Date: Tue, 18 Feb 1997 16:00:08 -0500 (EST)
From: Andy Dougherty <doughera@fractal.phys.lafayette.edu>
Files: INSTALL
Msg-ID: <Pine.SOL.3.95q.970218155815.2014F-100000@fractal.lafayette.e

    (applied based on p5p patch as commit a8247d96fd6167a3b920e63aedee5592cd6e29a7)

Subject: Document "$$0" change
From: Chip Salzenberg <chip@perl.com>
Files: pod/perldelta.pod

Subject: Don't recommend impossible //o for C<$x =~ $y>
From: Chip Salzenberg <chip@perl.com>
Files: pod/perlop.pod

Subject: Correct doc that claimed that <FH> was never false
From: Chip Salzenberg <chip@perl.com>
Files: pod/perldelta.pod pod/perlop.pod

Subject: Document C<$?> vs. $SIG{CHLD}
From: Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
Files: pod/perlvar.pod

Subject: Add pumpkin.pod
From: Chip Salzenberg <chip@perl.com>
Files: MANIFEST Porting/pumpkin.pod

Subject: Don't say "associat*ve arr*y"
From: Chip Salzenberg <chip@perl.com>
Files: MANIFEST gv.h hv.c lib/Env.pm lib/overload.pm opcode.pl pod/perl.pod pod/perldelta.pod pod/perldiag.pod pod/perlfunc.pod pod/perlguts.pod pod/perlmod.pod pod/perltie.pod pod/perltoc.pod pod/perltrap.pod x2p/a2p.pod

 OTHER CORE CHANGES

Subject: Fix a typo
From: Chip Salzenberg <chip@perl.com>
Files: pp_sys.c

Subject: Fix perl_call_sv(..., G_NOARGS)
From: Chip Salzenberg <chip@perl.com>
Files: perl.c

Subject: Fix SIGSEGV when cloning sub with complex expression
From: Chip Salzenberg <chip@perl.com>
Files: op.c

1 files changed, 1122 insertions, 0 deletions

diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod
new file mode 100644
index 0000000000..3744548fc5
--- /dev/null
+++ b/Porting/pumpkin.pod
@@ -0,0 +1,1122 @@
+=head1 NAME
+
+Pumpkin - Notes on handling the Perl Patch Pumpkin
+
+=head1 SYNOPSIS
+
+There is no simple synopsis, yet.
+
+=head1 DESCRIPTION
+
+This document attempts to begin to describe some of the
+considerations involved in patching and maintaining perl.
+
+This document is still under construction, and still subject to
+significant changes.  Still, I hope parts of it will be useful,
+so I'm releasing it even though it's not done.
+
+For the most part, it's a collection of anecdotal information that
+already assumes some familiarity with the Perl sources.  I really need
+an introductory section that describes the organization of the sources
+and all the various auxiliary files that are part of the distribution.
+
+=head1 Where Do I Get Perl Sources and Related Material?
+
+The Comprehensive Perl Archive Network (or CPAN) is the place to go.
+There are many mirrors, but the easiest thing to use is probably
+http://www.perl.com/CPAN, which automatically points you to a
+mirror site "close" to you.
+
+=head2 Perl5-porters mailing list
+
+The mailing list perl5-porters@perl.org
+is the main group working with the development of perl.  If you're
+interested in all the latest developments, you should definitely
+subscribe.  The list is high volume, but generally has a
+fairly low noise level.
+
+Subscribe by sending the message (in the body of your letter)
+
+	subscribe perl5-porters
+
+to perl5-porters-request@perl.org .
+
+=head1 How are Perl Releases Numbered?
+
+Perl version numbers are floating point numbers, such as 5.004.  The
+major version number is 5, the minor version is '0', and '03' is the
+patchlevel.  The version number is available as the magic variable $],
+and can be used in comparisons, e.g.
+
+	print "You've got an old perl\n" if $] < 5.002;
+
+(Observations about the imprecision of floating point numbers for
+representing reality probably have more relevance than you might
+imagine :-)
+
+You can also require particular version (or later) with
+
+	use 5.002;
+
+=head2 Subversions
+
+In addition, there may be "developer" sub-versions available.  These
+are not official releases.  They may contain unstable experimental
+features, and are subject to rapid change.  Such developer
+sub-versions are numbered with sub-version numbers.  For example,
+version 5.004_04 is the 4'th developer version built on top of
+5.004.  It might include the _01, _02, and _03 changes, but it
+also might not.  Sub-versions are allowed to be subversive.
+
+These sub-versions can also be used as floating point numbers, so
+you can do things such as
+
+	print "You've got an unstable perl\n" if $] == 5.00403;
+
+You can also require particular version (or later) with
+
+	use 5.004_03;    # the "_" is optional
+
+Sub-versions produced by the members of perl5-porters are usually
+available on CPAN in the F<src/5.0/unsupported> directory.
+
+=head2 Why such a complicated scheme?
+
+Two reasons, really.  At least.
+
+First, we need some way to identify releases that are known to
+have new features that need testing and exploration.  The
+subversion scheme does that nicely while fitting into the
+C<use 5.004;> mold.
+
+Second, since most of the folks who help maintain perl do so on a
+free-time voluntary basis, perl development does not proceed at a
+precise pace, though it always seems to be moving ahead quickly.
+We needed some way to pass around the "patch pumpkin" to allow
+different people chances to work on different aspects of the
+distribution without getting in each other's way.  It wouldn't be
+constructive to have multiple people working on incompatible
+implementations of the same idea.  Instead what was needed was
+some kind of "baton" or "token" to pass around so everyone knew
+whose turn was next.
+
+=head2 Why is it called the patch pumpkin?
+
+Chip Salzenberg gets credit for that, with a nod to his cow orker,
+David Croy.  We had passed around various names (baton, token, hot
+potato) but none caught on.  Then, Chip asked:
+
+[begin quote]
+
+   Who has the patch pumpkin?
+
+To explain:  David Croy once told me once that at a previous job,
+there was one tape drive and multiple systems that used it for backups.
+But instead of some high-tech exclusion software, they used a low-tech
+method to prevent multiple simultaneous backups: a stuffed pumpkin.
+No one was allowed to make backups unless they had the "backup pumpkin".
+
+[end quote]
+
+The name has stuck.
+
+=head1 Philosophical Issues in Patching Perl
+
+There are no absolute rules, but there are some general guidelines I
+have tried to follow as I apply patches to the perl sources.
+(This section is still under construction.)
+
+=head2 Solve problems as generally as possible
+
+(I still have to think of a good example here.)
+
+=head2 Seek consensus on major changes
+
+If you are making big changes, don't do it in secret.  Discuss the
+ideas in advance on perl5-porters.
+
+=head2 Keep the documentation up-to-date
+
+If your changes may affect how users use perl, then check to be sure
+that the documentation is in sync with your changes.  Be sure to
+check all the files F<pod/*.pod> and also the F<INSTALL> document.
+
+Consider writing the appropriate documentation first and then
+implementing it to correspond to the documentation.
+
+=head2 Avoid machine-specific #ifdef's
+
+To the extent reasonable, try to avoid machine-specific #ifdef's in
+the sources.  Instead, use feature-specific #ifdef's.  The reason is
+that the machine-specific #ifdef's may not be valid across major
+releases of the operating system.  Further, the feature-specific tests
+may help out folks on another platform who have the same problem.
+
+=head2 Allow for lots of testing
+
+We should never release a main version without testing it as a
+subversion first.
+
+=head2 Automate generatation of derivative files
+
+The F<embed.h>, F<keywords.h>, F<opcode.h>, and F<perltoc.pod> files
+are all automatically generated by perl scripts.  In general, don't
+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
+F<Configure> may be made in between major sync-ups with the metaconfig
+units, which tends to be complicated operations.
+
+=head1 How to Make a Distribution
+
+There really ought to be a 'make dist' target, but there isn't.
+The 'dist' suite of tools also contains a number of tools that I haven't
+learned how to use yet.  Some of them may make this all a bit easier.
+
+Here are the steps I go through to prepare a patch & distribution.
+
+Lots of it could doubtless be automated but isn't.
+
+=head2 Announce your intentions
+
+First, you should volunteer out loud to take the patch pumpkin.  It's
+generally counter-productive to have multiple people working in secret
+on the same thing.
+
+At the same time, announce what you plan to do with the patch pumpkin,
+to allow folks a chance to object or suggest alternatives, or do it for
+you.  Naturally, the patch pumpkin holder ought to incorporate various
+bug fixes and documentation improvements that are posted while he or
+she has the pumpkin, but there might also be larger issues at stake.
+
+One of the precepts of the subversion idea is that we shouldn't give
+it to anyone unless we have some idea what you're going to do with
+it.
+
+=head2 refresh pod/perltoc.pod
+
+Presumably, you have done a full C<make> in your working source
+directory.  Before you C<make spotless> (if you do), and if you have
+changed any documentation in any module or pod file, change to the
+F<pod> directory and run C<make toc>.
+
+=head2 update patchlevel.h
+
+Don't be shy about using the subversion number, even for a relatively
+modest patch.  We've never even come close to using all 99 subversions,
+and it's better to have a distinctive number for your patch.  If you
+need feedback on your patch, go ahead and issue it and promise to
+incorporate that feedback quickly (e.g. within 1 week) and send out a
+second patch.
+
+=head2 run metaconfig
+
+If you need to make changes to Configure or config_h.SH, it may be best to
+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<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.
+
+Alternatively, do consider if the F<*ish.h> files might be a better
+place for your changes.
+
+=head2 MANIFEST
+
+Make sure the MANIFEST is up-to-date.  You can use dist's B<manicheck>
+program for this.  You can also use
+
+    perl -MExtUtils::Manifest -e fullcheck
+
+to do half the job.  This will make sure everything listed in MANIFEST
+is included in the distribution.  dist's B<manicheck> command 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.)
+
+If you are using metaconfig to regenerate Configure, then you should note
+that metaconfig actually uses MANIFEST.new, so you want to be sure
+MANIFEST.new is up-to-date too.  I haven't found the MANIFEST/MANIFEST.new
+distinction particularly useful, but that's probably because I still haven't
+learned how to use the full suite of tools in the dist distribution.
+
+=head2 Check permissions
+
+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.
+
+In all, the following files should probably be executable:
+
+    Configure
+    configpm
+    configure
+    embed.pl
+    installperl
+    installman
+    keywords.pl
+    lib/splain
+    myconfig
+    opcode.pl
+    perly.fixer
+    t/TEST
+    t/*/*.t
+    *.SH
+    vms/ext/Stdio/test.pl
+    vms/ext/filespec.t
+    vms/fndvers.com
+    x2p/*.SH
+
+Other things ought to be readable, at least :-).
+
+Probably, the permissions for the files could be encoded in MANIFEST
+somehow, but I'm reluctant to change MANIFEST itself because that
+could break old scripts that use MANIFEST.
+
+I seem to recall that some SVR3 systems kept some sort of file that listed
+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
+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
+directories.
+
+=head2 make run_byacc
+
+If you have byacc-1.8.2 (available from CPAN), and if there have been
+changes to F<perly.y>, you can regenerate the F<perly.c> file.  The
+run_byacc makefile target does this by running byacc and then applying
+some patches so that byacc dynamically allocates space, rather than
+having fixed limits.  This patch is handled by the F<perly.fixer>
+script.  Depending on the nature of the changes to F<perly.y>, you may
+or may not have to hand-edit the patch to apply correctly.  If you do,
+you should include the edited patch in the new distribution.  If you
+have byacc-1.9, the patch won't apply cleanly.  Changes to the printf
+output statements mean the patch won't apply cleanly.  Long ago I
+started to fix F<perly.fixer> to detect this, but I never completed the
+task.
+
+Some additional notes from Larry on this:
+
+Don't forget to regenerate perly.c.diff.
+
+    byacc perly.y
+    mv y.tab.c perly.c
+    patch perly.c <perly.c.diff
+    # manually apply any failed hunks
+    diff -c2 perly.c.orig perly.c >perly.c.diff
+
+One chunk of lines that often fails begins with
+
+    #line 29 "perly.y"
+
+and ends one line before
+
+    #define YYERRCODE 256
+
+This only happens when you add or remove a token type.  I suppose this
+could be automated, but it doesn't happen very often nowadays.
+
+Larry
+
+=head2 make regen_headers
+
+The F<embed.h>, F<keywords.h>, and F<opcode.h> files are all automatically
+generated by perl scripts.  Since the user isn't guaranteed to have a
+working perl, we can't require the user to generate them.  Hence you have
+to, if you're making a distribution.
+
+I used to include rules like the following in the makefile:
+
+    # The following three header files are generated automatically
+    # The correct versions should be already supplied with the perl kit,
+    # in case you don't have perl or 'sh' available.
+    # The - is to ignore error return codes in case you have the source
+    # installed read-only or you don't have perl yet.
+    keywords.h: keywords.pl
+	    @echo "Don't worry if this fails."
+	    - perl keywords.pl
+
+
+However, I got lots of mail consisting of people worrying because the
+command failed.  I eventually decided that I would save myself time
+and effort by manually running C<make regen_headers> myself rather
+than answering all the questions and complaints about the failing
+command.
+
+=head2 global.sym and interp.sym
+
+Make sure these files are up-to-date.  Read the comments in these
+files and in perl_exp.SH to see what to do.
+
+=head2 Binary compatibility
+
+If you do change F<global.sym> or F<interp.sym>, think carefully about
+what you are doing.  To the extent reasonable, we'd like to maintain
+souce and binary compatibility with older releases of perl.  That way,
+extensions built under one version of perl will continue to work with
+new versions of perl.
+
+Of course, some incompatible changes may well be necessary.  I'm just
+suggesting that we not make any such changes without thinking carefully
+about them first.  If possible, we should provide
+backwards-compatibility stubs.  There's a lot of XS code out there.
+Let's not force people to keep changing it.
+
+=head2 Changes
+
+Be sure to update the F<Changes> file.  Try to include both an overall
+summary as well as detailed descriptions of the changes.  Your
+audience will include bother developers and users, so describe
+user-visible changes (if any) in terms they will understand, not in
+code like "initialize foo variable in bar function".
+
+There are differing opinions on whether the detailed descriptions
+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 OS/2-specific updates
+
+In the os2 directory is F<diff.configure>, a set of OS/2-specific
+diffs against B<Configure>.  If you make changes to Configure, you may
+want to consider regenerating this diff file to save trouble for the
+OS/2 maintainer.
+
+=head2 VMS-specific updates
+
+If you have changed F<perly.y>, then you may want to update
+F<vms/perly_{h,c}.vms> by running C<perl vms/vms_yfix.pl>.
+
+The Perl version number appears in several places under F<vms>.
+It is courteous to update these versions.  For example, if you are
+making 5.004_42, replace "5.00441" with "5.00442".
+
+=head2 Making the new distribution
+
+Suppose, for example, that you want to make version 5.004_08.  Then you can
+do something like the following
+
+	mkdir ../perl5.004_08
+	awk '{print $1}' MANIFEST | cpio -pdm ../perl5.004_08
+	cd ../
+	tar cf perl5.004_08.tar perl5.004_08
+	gzip --best perl5.004_08.tar
+
+=head2 Making a new patch
+
+I find the F<makepatch> utility quite handy for making patches.
+You can obtain it from any CPAN archive under
+http://www.perl.com/CPAN/authors/Johan_Vromans/.  The only
+difference between my version and the standard one is that I have mine
+do a
+
+	# Print a reassuring "End of Patch" note so people won't
+	# wonder if their mailer truncated patches.
+	print "\n\nEnd of Patch.\n";
+
+at the end.  That's because I used to get questions from people asking if
+their mail was truncated.
+
+Here's how I generate a new patch.  I'll use the hypothetical
+5.004_07 to 5.004_08 patch as an example.
+
+	# unpack perl5.004_07/
+	gzip -d -c perl5.004_07.tar.gz | tar -xof -
+	# unpack perl5.004_08/
+	gzip -d -c perl5.004_08.tar.gz | tar -xof -
+	makepatch perl5.004_07 perl5.004_08 > perl5.004_08.pat
+
+Makepatch will automatically generate appropriate B<rm> commands to remove
+deleted files.  Unfortunately, it will not correctly set permissions
+for newly created files, so you may have to do so manually.  For example,
+patch 5.003_04 created a new test F<t/op/gv.t> which needs to be executable,
+so at the top of the patch, I inserted the following lines:
+
+	# Make a new test
+	touch t/op/gv.t
+	chmod +x t/opt/gv.t
+
+Now, of course, my patch is now wrong because makepatch didn't know I
+was going to do that command, and it patched against /dev/null.
+
+So, what I do is sort out all such shell commands that need to be in the
+patch (including possible mv-ing of files, if needed) and put that in the
+shell commands at the top of the patch.  Next, I delete all the patch parts
+of perl5.004_08.pat, leaving just the shell commands.  Then, I do the
+following:
+
+	cd perl5.003_07
+	sh ../perl5.003_08.pat
+	cd ..
+	makepatch perl5.003_07 perl5.003_08 >> perl5.003_08.pat
+
+(Note the append to preserve my shell commands.)
+Now, my patch will line up with what the end users are going to do.
+
+=head2 Testing your patch
+
+It seems obvious, but be sure to test your patch.  That is, verify that
+it produces exactly the same thing as your full distribution.
+
+	rm -rf perl5.003_07
+	gzip -d -c perl5.003_07.tar.gz | tar -xf -
+	cd perl5.003_07
+	sh ../perl5.003_08.pat
+	patch -p1 -N < ../perl5.003_08.pat
+	cd ..
+	gdiff -r perl5.003_07 perl5.003_08
+
+where B<gdiff> is GNU diff.  Other diff's may also do recursive checking.
+
+=head2 More testing
+
+Again, it's obvious, but you should test your new version as widely as you
+can.  You can be sure you'll hear about it quickly if your version doesn't
+work on both ANSI and pre-ANSI compilers, and on common systems such as
+SunOS 4.1.[34], Solaris, and Linux.
+
+If your changes include conditional code, try to test the different
+branches as thoroughly as you can.  For example, if your system
+supports dynamic loading, you can also test static loading with
+
+	sh Configure -Uusedl
+
+You can also hand-tweak your config.h to try out different #ifdef
+branches.
+
+=head1 Common Gotcha's
+
+=over 4
+
+=item #elif
+
+The '#elif' preprocessor directive is not understood on all systems.
+Specifically, I know that Pyramids don't understand it.  Thus instead of the
+simple
+
+	#if defined(I_FOO)
+	#  include <foo.h>
+	#elif defined(I_BAR)
+	#  include <bar.h>
+	#else
+	#  include <fubar.h>
+	#endif
+
+You have to do the more Byzantine
+
+	#if defined(I_FOO)
+	#  include <foo.h>
+	#else
+	#  if defined(I_BAR)
+	#    include <bar.h>
+	#  else
+	#    include <fubar.h>
+	#  endif
+	#endif
+
+Incidentally, whitespace between the leading '#' and the preprocessor
+command is not guaranteed, but is very portable and you may use it freely.
+I think it makes things a bit more readable, especially once things get
+rather deeply nested.  I also think that things should almost never get
+too deeply nested,  so it ought to be a moot point :-)
+
+=item Probably Prefer POSIX
+
+It's often the case that you'll need to choose whether to do
+something the BSD-ish way or the POSIX-ish way.  It's usually not
+a big problem when the two systems use different names for similar
+functions, such as memcmp() and bcmp().  The perl.h header file
+handles these by appropriate #defines, selecting the POSIX mem*()
+functions if available, but falling back on the b*() functions, if
+need be.
+
+More serious is the case where some brilliant person decided to
+use the same function name but give it a different meaning or
+calling sequence :-).  getpgrp() and setpgrp() come to mind.
+These are a real problem on systems that aim for conformance to
+one standard (e.g. POSIX), but still try to support the other way
+of doing things (e.g. BSD).  My general advice (still not really
+implemented in the source) is to do something like the following.
+Suppose there are two alternative versions, fooPOSIX() and
+fooBSD().
+
+    #ifdef HAS_FOOPOSIX
+	/* use fooPOSIX(); */
+    #else
+    #  ifdef HAS_FOOBSD
+	/* try to emulate fooPOSIX() with fooBSD();
+	   perhaps with the following:  */
+    #    define fooPOSIX fooBSD
+    #  else
+    #  /* Uh, oh.  We have to supply our own. */
+    #    define fooPOSIX Perl_fooPOSIX
+    #  endif
+    #endif
+
+=item Think positively
+
+If you need to add an #ifdef test, it is usually easier to follow if you
+think positively, e.g.
+
+	#ifdef HAS_NEATO_FEATURE
+	    /* use neato feature */
+	#else
+	    /* use some fallback mechanism */
+	#endif
+
+rather than the more impenetrable
+
+	#ifndef MISSING_NEATO_FEATURE
+	    /* Not missing it, so we must have it, so use it */
+	#else
+	    /* Are missing it, so fall back on something else. */
+	#endif
+
+Of course for this toy example, there's not much difference.  But when
+the #ifdef's start spanning a couple of screen fulls, and the #else's
+are marked something like
+
+	#else /* !MISSING_NEATO_FEATURE */
+
+I find it easy to get lost.
+
+=item Providing Missing Functions -- Problem
+
+Not all systems have all the neat functions you might want or need, so
+you might decide to be helpful and provide an emulation.  This is
+sound in theory and very kind of you, but please be careful about what
+you name the function.  Let me use the C<pause()> function as an
+illustration.
+
+Perl5.003 has the following in F<perl.h>
+
+    #ifndef HAS_PAUSE
+    #define pause() sleep((32767<<16)+32767)
+    #endif
+
+Configure sets HAS_PAUSE if the system has the pause() function, so
+this #define only kicks in if the pause() function is missing.
+Nice idea, right?
+
+Unfortunately, some systems apparently have a prototype for pause()
+in F<unistd.h>, but don't actually have the function in the library.
+(Or maybe they do have it in a library we're not using.)
+
+Thus, the compiler sees something like
+
+    extern int pause(void);
+    /* . . . */
+    #define pause() sleep((32767<<16)+32767)
+
+and dies with an error message.  (Some compilers don't mind this;
+others apparently do.)
+
+To work around this, 5.003_03 and later have the following in perl.h:
+
+    /* Some unistd.h's give a prototype for pause() even though
+       HAS_PAUSE ends up undefined.  This causes the #define
+       below to be rejected by the compiler.  Sigh.
+    */
+    #ifdef HAS_PAUSE
+    #  define Pause	pause
+    #else
+    #  define Pause() sleep((32767<<16)+32767)
+    #endif
+
+This works.
+
+The curious reader may wonder why I didn't do the following in
+F<util.c> instead:
+
+    #ifndef HAS_PAUSE
+    void pause()
+    {
+    sleep((32767<<16)+32767);
+    }
+    #endif
+
+That is, since the function is missing, just provide it.
+Then things would probably be been alright, it would seem.
+
+Well, almost.  It could be made to work.  The problem arises from the
+conflicting needs of dynamic loading and namespace protection.
+
+For dynamic loading to work on AIX (and VMS) we need to provide a list
+of symbols to be exported.  This is done by the script F<perl_exp.SH>,
+which reads F<global.sym> and F<interp.sym>.  Thus, the C<pause>
+symbol would have to be added to F<global.sym>  So far, so good.
+
+On the other hand, one of the goals of Perl5 is to make it easy to
+either extend or embed perl and link it with other libraries.  This
+means we have to be careful to keep the visible namespace "clean".
+That is, we don't want perl's global variables to conflict with
+those in the other application library.  Although this work is still
+in progress, the way it is currently done is via the F<embed.h> file.
+This file is built from the F<global.sym> and F<interp.sym> files,
+since those files already list the globally visible symbols.  If we
+had added C<pause> to global.sym, then F<embed.h> would contain the
+line
+
+    #define pause	Perl_pause
+
+and calls to C<pause> in the perl sources would now point to
+C<Perl_pause>.  Now, when B<ld> is run to build the F<perl> executable,
+it will go looking for C<perl_pause>, which probably won't exist in any
+of the standard libraries.  Thus the build of perl will fail.
+
+Those systems where C<HAS_PAUSE> is not defined would be ok, however,
+since they would get a C<Perl_pause> function in util.c.  The rest of
+the world would be in trouble.
+
+And yes, this scenario has happened.  On SCO, the function C<chsize>
+is available.  (I think it's in F<-lx>, the Xenix compatibility
+library.)  Since the perl4 days (and possibly before), Perl has
+included a C<chsize> function that gets called something akin to
+
+    #ifndef HAS_CHSIZE
+    I32 chsize(fd, length)
+    /*  . . . */
+    #endif
+
+When 5.003 added
+
+    #define chsize	Perl_chsize
+
+to F<embed.h>, the compile started failing on SCO systems.
+
+The "fix" is to give the function a different name.  The one
+implemented in 5.003_05 isn't optimal, but here's what was done:
+
+    #ifdef HAS_CHSIZE
+    # ifdef my_chsize  /* Probably #defined to Perl_my_chsize in embed.h */
+    #   undef my_chsize
+    # endif
+    # define my_chsize chsize
+    #endif
+
+My explanatory comment in patch 5.003_05 said:
+
+     Undef and then re-define my_chsize from Perl_my_chsize to
+     just plain chsize if this system HAS_CHSIZE.  This probably only
+     applies to SCO.  This shows the perils of having internal
+     functions with the same name as external library functions :-).
+
+Now, we can safely put C<my_chsize> in F<global.sym>, export it, and
+hide it with F<embed.h>.
+
+To be consistent with what I did for C<pause>, I probably should have
+called the new function C<Chsize>, rather than C<my_chsize>.
+However, the perl sources are quite inconsistent on this (Consider
+New, Mymalloc, and Myremalloc, to name just a few.)
+
+There is a problem with this fix, however, in that C<Perl_chsize>
+was available as a F<libperl.a> library function in 5.003, but it
+isn't available any more (as of 5.003_07).  This means that we've
+broken binary compatibility.  This is not good.
+
+=item Providing missing functions -- some ideas
+
+We currently don't have a standard way of handling such missing
+function names.  Right now, I'm effectively thinking aloud about a
+solution.  Some day, I'll try to formally propose a solution.
+
+Part of the problem is that we want to have some functions listed as
+exported but not have their names mangled by embed.h or possibly
+conflict with names in standard system headers.  We actually already
+have such a list at the end of F<perl_exp.SH> (though that list is
+out-of-date):
+
+    # extra globals not included above.
+    cat <<END >> perl.exp
+    perl_init_ext
+    perl_init_fold
+    perl_init_i18nl14n
+    perl_alloc
+    perl_construct
+    perl_destruct
+    perl_free
+    perl_parse
+    perl_run
+    perl_get_sv
+    perl_get_av
+    perl_get_hv
+    perl_get_cv
+    perl_call_argv
+    perl_call_pv
+    perl_call_method
+    perl_call_sv
+    perl_requirepv
+    safecalloc
+    safemalloc
+    saferealloc
+    safefree
+
+This still needs much thought, but I'm inclined to think that one
+possible solution is to prefix all such functions with C<perl_> in the
+source and list them along with the other C<perl_*> functions in
+F<perl_exp.SH>.
+
+Thus, for C<chsize>, we'd do something like the following:
+
+    /* in perl.h */
+    #ifdef HAS_CHSIZE
+    #  define perl_chsize chsize
+    #endif
+
+then in some file (e.g. F<util.c> or F<doio.c>) do
+
+    #ifndef HAS_CHSIZE
+    I32 perl_chsize(fd, length)
+    /* implement the function here . . . */
+    #endif
+
+Alternatively, we could just always use C<chsize> everywhere and move
+C<chsize> from F<global.sym> to the end of F<perl_exp.SH>.  That would
+probably be fine as long as our C<chsize> function agreed with all the
+C<chsize> function prototypes in the various systems we'll be using.
+As long as the prototypes in actual use don't vary that much, this is
+probably a good alternative.  (As a counter-example, note how Configure
+and perl have to go through hoops to find and use get Malloc_t and
+Free_t for C<malloc> and C<free>.)
+
+At the moment, this latter option is what I tend to prefer.
+
+=item All the world's a VAX
+
+Sorry, showing my age:-).  Still, all the world is not BSD 4.[34],
+SVR4, or POSIX.  Be aware that SVR3-derived systems are still quite
+common (do you have any idea how many systems run SCO?)  If you don't
+have a bunch of v7 manuals handy, the metaconfig units (by default
+installed in F</usr/local/lib/dist/U>) are a good resource to look at
+for portability.
+
+=back
+
+=head1 Miscellaneous Topics
+
+=head2 Autoconf
+
+Why does perl use a metaconfig-generated Configure script instead of an
+autoconf-generated configure script?
+
+Metaconfig and autoconf are two tools with very similar purposes.
+Metaconfig is actually the older of the two, and was originally written
+by Larry Wall, while autoconf is probably now used in a wider variety of
+packages.  The autoconf info file discusses the history of autoconf and
+how it came to be.  The curious reader is referred there for further
+information.
+
+Overall, both tools are quite good, I think, and the choice of which one
+to use could be argued either way.  In March, 1994, when I was just
+starting to work on Configure support for Perl5, I considered both
+autoconf and metaconfig, and eventually decided to use metaconfig for the
+following reasons:
+
+=over 4
+
+=item Compatibility with Perl4
+
+Perl4 used metaconfig, so many of the #ifdef's were already set up for
+metaconfig.  Of course metaconfig had evolved some since Perl4's days,
+but not so much that it posed any serious problems.
+
+=item Metaconfig worked for me
+
+My system at the time was Interactive 2.2, a SVR3.2/386 derivative that
+also had some POSIX support.  Metaconfig-generated Configure scripts
+worked fine for me on that system.  On the other hand, autoconf-generated
+scripts usually didn't.  (They did come quite close, though, in some
+cases.)  At the time, I actually fetched a large number of GNU packages
+and checked.  Not a single one configured and compiled correctly
+out-of-the-box with the system's cc compiler.
+
+=item Configure can be interactive
+
+With both autoconf and metaconfig, if the script works, everything is
+fine.  However, one of my main problems with autoconf-generated scripts
+was that if it guessed wrong about something, it could be B<very> hard to
+go back and fix it.  For example, autoconf always insisted on passing the
+-Xp flag to cc (to turn on POSIX behavior), even when that wasn't what I
+wanted or needed for that package.  There was no way short of editing the
+configure script to turn this off.  You couldn't just edit the resulting
+Makefile at the end because the -Xp flag influenced a number of other
+configure tests.
+
+Metaconfig's Configure scripts, on the other hand, can be interactive.
+Thus if Configure is guessing things incorrectly, you can go back and fix
+them.  This isn't as important now as it was when we were actively
+developing Configure support for new features such as dynamic loading,
+but it's still useful occasionally.
+
+=item GPL
+
+At the time, autoconf-generated scripts were covered under the GNU Public
+License, and hence weren't suitable for inclusion with Perl, which has a
+different licensing policy.  (Autoconf's licensing has since changed.)
+
+=item Modularity
+
+Metaconfig builds up Configure from a collection of discrete pieces
+called "units".  You can override the standard behavior by supplying your
+own unit.  With autoconf, you have to patch the standard files instead.
+I find the metaconfig "unit" method easier to work with.  Others
+may find metaconfig's units clumsy to work with.
+
+=back
+
+=head2 @INC search order
+
+By default, the list of perl library directories in @INC is the
+following:
+
+    $archlib
+    $privlib
+    $sitearch
+    $sitelib
+
+Specifically, on my Solaris/x86 system, I run
+B<sh Configure -Dprefix=/opt/perl> and I have the following
+directories:
+
+    /opt/perl/lib/i86pc-solaris/5.00307
+    /opt/perl/lib
+    /opt/perl/lib/site_perl/i86pc-solaris
+    /opt/perl/lib/site_perl
+
+That is, perl's directories come first, followed by the site-specific
+directories.
+
+The site libraries come second to support the usage of extensions
+across perl versions.  Read the relevant section in F<INSTALL> for
+more information.  If we ever make $sitearch version-specific, this
+topic could be revisited.
+
+=head2 Why isn't there a directory to override Perl's library?
+
+Mainly because no one's gotten around to making one.  Note that
+"making one"  involves changing perl.c, Configure, config_h.SH (and
+associated files, see above), and I<documenting> it all in the
+INSTALL file.
+
+Apparently, most folks who want to override one of the standard library
+files simply do it by overwriting the standard library files.
+
+=head2 APPLLIB
+
+In the perl.c sources, you'll find an undocumented APPLLIB_EXP
+variable, sort of like PRIVLIB_EXP and ARCHLIB_EXP (which are
+documented in config_h.SH).  Here's what APPLLIB_EXP is for, from
+a mail message from Larry:
+
+    The main intent of APPLLIB_EXP is for folks who want to send out a
+    version of Perl embedded in their product.  They would set the symbol
+    to be the name of the library containing the files needed to run or to
+    support their particular application.  This works at the "override"
+    level to make sure they get their own versions of any library code that
+    they absolutely must have configuration control over.
+
+    As such, I don't see any conflict with a sysadmin using it for a
+    override-ish sort of thing, when installing a generic Perl.  It should
+    probably have been named something to do with overriding though.  Since
+    it's undocumented we could still change it...  :-)
+
+Given that it's already there, you can use it to override
+distribution modules.  If you do
+
+	sh Configure -Dccflags='-DAPPLLIB_EXP=/my/override'
+
+then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB.
+
+=head1 Upload Your Work to CPAN
+
+You can upload your work to CPAN if you have a CPAN id.  Check out
+http://www.perl.com/CPAN/modules/04pause.html for information on
+_PAUSE_, the Perl Author's Upload Server.
+
+I typically upload both the patch file, e.g. F<perl5.004_08.pat.gz>
+and the full tar file, e.g. F<perl5.004_08.tar.gz>.
+
+If you want your patch to appear in the F<src/5.0/unsupported>
+directory on CPAN, send e-mail to the CPAN master librarian.  (Check
+out http://www.perl.com/CPAN/CPAN.html).
+
+=head1 Help Save the World
+
+You should definitely announce your patch on the perl5-porters list.
+You should also consider announcing your patch on
+comp.lang.perl.announce, though you should make it quite clear that a
+subversion is not a production release, and be prepared to deal with
+people who will not read your disclaimer.
+
+=head1 Todo
+
+Here, in no particular order, are some Configure and build-related
+items that merit consideration.  This list isn't exhaustive, it's just
+what I came up with off the top of my head.
+
+=head2 Good ideas waiting for round tuits
+
+=over 4
+
+=item installprefix
+
+I think we ought to support
+
+    Configure -Dinstallprefix=/blah/blah
+
+Currently, we support B<-Dprefix=/blah/blah>, but the changing the install
+location has to be handled by something like the F<config.over> trick
+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
+
+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.
+
+=item Hint file fixes
+
+Various hint files work around Configure problems.  We ought to fix
+Configure so that most of them aren't needed.
+
+=item Hint file information
+
+Some of the hint file information (particularly dynamic loading stuff)
+ought to be fed back into the main metaconfig distribution.
+
+=back
+
+=head2 Probably good ideas waiting for round tuits
+
+=over 4
+
+=item GNU configure --options
+
+I've received sensible suggestions for --exec_prefix and other
+GNU configure --options.  It's not always obvious exactly what is
+intended, but this merits investigation.
+
+=item make clean
+
+Currently, B<make clean> isn't all that useful, though
+B<make realclean> and B<make distclean> are.  This needs a bit of
+thought and documentation before it gets cleaned up.
+
+=item Try gcc if cc fails
+
+Currently, we just give up.
+
+=item bypassing safe*alloc wrappers
+
+On some systems, it may be safe to call the system malloc directly
+without going through the util.c safe* layers.  (Such systems would
+accept free(0), for example.)  This might be a time-saver for systems
+that already have a good malloc.  (Recent Linux libc's apparently have
+a nice malloc that is well-tuned for the system.)
+
+=back
+
+=head2 Vague possibilities
+
+=over 4
+
+=item Win95, WinNT, and Win32 support
+
+We need to get something into the distribution for 32-bit Windows.
+I'm tired of all the private e-mail questions I get, and I'm saddened
+that so many folks keep trying to reinvent the same wheel.
+
+=item MacPerl
+
+Get some of the Macintosh stuff folded back into the main
+distribution.
+
+=item gconvert replacement
+
+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
+works for most folks.  Alas, it assumes that there is a filename
+$firstmakefile that the B<make> command will try to use before it uses
+F<Makefile>.  Such may not be the case for all B<make> commands,
+particularly those on non-Unix systems.
+
+Probably some variant of the BSD F<.depend> file will be useful.
+We ought to check how other packages do this, if they do it at all.
+We could probably pre-generate the dependencies (with the exception of
+malloc.o, which could probably be determined at F<Makefile.SH>
+extraction time.
+
+=item GNU Makefile standard targets
+
+GNU software generally has standardized Makefile targets.  Unless we
+have good reason to do otherwise, I see no reason not to support them.
+
+=item File locking
+
+Somehow, straighten out, document, and implement lockf(), flock(),
+and/or fcntl() file locking.  It's a mess.
+
+=back
+
+=head1 AUTHOR
+
+Andy Dougherty <doughera@lafcol.lafayette.edu>.
+
+Additions by Chip Salzenberg <chip@atlantic.net>.
+
+All opinions expressed herein are those of the authorZ<>(s).
+
+=head1 LAST MODIFIED
+
+$Id: pumpkin.pod,v 1.8 1997/02/18 18:19:20 chip Released $