=head1 How are Perl Releases Numbered?
-Perl version numbers are floating point numbers, such as 5.004.
-(Observations about the imprecision of floating point numbers for
-representing reality probably have more relevance than you might
-imagine :-) The major version number is 5 and the '004' is the
-patchlevel. (Questions such as whether or not '004' is really a minor
-version number can safely be ignored.:)
+Beginning with v5.6.0, even versions will stand for maintenance releases
+and odd versions for development releases, i.e., v5.6.x for maintenance
+releases, and v5.7.x for development releases. Before v5.6.0, subversions
+_01 through _49 were reserved for bug-fix maintenance releases, and
+subversions _50 through _99 for unstable development versions.
-The version number is available as the magic variable $],
-and can be used in comparisons, e.g.
+For example, in v5.6.1, the revision number is 5, the version is 6,
+and 1 is the subversion.
- print "You've got an old perl\n" if $] < 5.002;
+For compatibility with the older numbering scheme the composite floating
+point version number continues to be available as the magic variable $],
+and amounts to C<$revision + $version/1000 + $subversion/1000000>. This
+can still be used in comparisons.
-You can also require particular version (or later) with
+ print "You've got an old perl\n" if $] < 5.005_03;
- use 5.002;
+In addition, the version is also available as a string in $^V.
-At some point in the future, we may need to decide what to call the
-next big revision. In the .package file used by metaconfig to
-generate Configure, there are two variables that might be relevant:
-$baserev=5.0 and $package=perl5. At various times, I have suggested
-we might change them to $baserev=5.1 and $package=perl5.1 if want
-to signify a fairly major update. Or, we might want to jump to perl6.
-Let's worry about that problem when we get there.
+ print "You've got a new perl\n" if $^V and $^V ge v5.6.0;
-=head2 Subversions
+You can also require particular version (or later) with:
-In addition, there usually are sub-versions available. Sub-versions
-are numbered with sub-version numbers. For example, version 5.003_04
-is the 4'th developer version built on top of 5.003. It might include
-the _01, _02, and _03 changes, but it also might not. Sub-versions are
-allowed to be subversive. (But see the next section for recent
-changes.)
+ use 5.006;
-These sub-versions can also be used as floating point numbers, so
-you can do things such as
+or using the new syntax available only from v5.6 onward:
- print "You've got an unstable perl\n" if $] == 5.00303;
+ use v5.6.0;
-You can also require particular version (or later) with
-
- use 5.003_03; # the "_" is optional
+At some point in the future, we may need to decide what to call the
+next big revision. In the .package file used by metaconfig to
+generate Configure, there are two variables that might be relevant:
+$baserev=5 and $package=perl5.
-Sub-versions produced by the members of perl5-porters are usually
+Perl releases produced by the members of perl5-porters are usually
available on CPAN in the F<src/5.0/maint> and F<src/5.0/devel>
directories.
=head2 Maintenance and Development Subversions
-Starting with version 5.004, subversions _01 through _49 is reserved
-for bug-fix maintenance releases, and subversions _50 through _99 for
-unstable development versions.
-
-The separate bug-fix track is being established to allow us an easy
-way to distribute important bug fixes without waiting for the
-developers to untangle all the other problems in the current
-developer's release. The first rule of maintenance work is "First, do
-no harm."
+The first rule of maintenance work is "First, do no harm."
Trial releases of bug-fix maintenance releases are announced on
perl5-porters. Trial releases use the new subversion number (to avoid
public consumption.
In general, the names of official distribution files for the public
-always match the regular expression
-
- ^perl5\.\d{3}(_[0-4]\d)?\.tar\.gz$
+always match the regular expression:
-Developer releases always match
+ ^perl\d+\.(\d+)\.\d+(-MAINT_TRIAL_\d+)\.tar\.gz$
- ^perl5\.\d{3}(_[5-9]\d)?\.tar\.gz$
-
-And the trial versions for a new maintainance release match
-
- ^perl5\.\d{3}(_[0-4]\d)-MAINT_TRIAL_\d+\.tar\.gz$
+C<$1> in the pattern is always an even number for maintenance
+versions, and odd for developer releases.
In the past it has been observed that pumkings tend to invent new
naming conventions on the fly. If you are a pumpking, before you
provide the trees of symlinks and the like. They will have to know
I<in advance> what you decide.
-=head2 Why such a complicated scheme?
-
-Two reasons, really. At least.
-
-First, we need some way to identify and release collections of patches
-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,
separate subdirectory (djgpp, win32) and put the files in there.
Remember to update C<MANIFEST> when you add files.
-If your system support dynamic loading but none of the existing
+If your system supports dynamic loading but none of the existing
methods at F<ext/DynaLoader/dl_*.xs> work for you, you must write
a new one. Study the existing ones to see what kind of interface
you must supply.
You can also hand-tweak your config.h to try out different #ifdef
branches.
+=head1 Running Purify
+
+Purify is a commercial tool that is helpful in identifying memory
+overruns, wild pointers, memory leaks and other such badness. Perl
+must be compiled in a specific way for optimal testing with Purify.
+
+Use the following commands to test perl with Purify:
+
+ sh Configure -des -Doptimize=-g -Uusemymalloc -Dusemultiplicity \
+ -Accflags=-DPURIFY
+ setenv PURIFYOPTIONS "-chain-length=25"
+ make all pureperl
+ cd t
+ ln -s ../pureperl perl
+ setenv PERL_DESTRUCT_LEVEL 5
+ ./perl TEST
+
+Disabling Perl's malloc allows Purify to monitor allocations and leaks
+more closely; using Perl's malloc will make Purify report most leaks
+in the "potential" leaks category. Enabling the multiplicity option
+allows perl to clean up thoroughly when the interpreter shuts down, which
+reduces the number of bogus leak reports from Purify. The -DPURIFY
+enables any Purify-specific debugging code in the sources.
+
+Purify outputs messages in "Viewer" windows by default. If you don't have
+a windowing environment or if you simply want the Purify output to
+unobtrusively go to a log file instead of to the interactive window,
+use the following options instead:
+
+ setenv PURIFYOPTIONS "-chain-length=25 -windows=no -log-file=perl.log \
+ -append-logfile=yes"
+
+The only currently known leaks happen when there are compile-time errors
+within eval or require. (Fixing these is non-trivial, unfortunately, but
+they must be fixed eventually.)
+
=head1 Common Gotcha's
=over 4
=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
=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 -Dsrc=/blah/blah
We should be able to emulate B<configure --srcdir>. Tom Tromey
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 the default $archlib,
-then they need to be updated each time the perl version is updated.
-Perhaps we need a set of libries $vendorlib and $vendorarch that
-track $apiversion (like the $sitexxx directories do) rather than just
-$version (like the main perl directory).
-
-An alternative (and perhaps even better) plan might be for the vendor
-to select non-default $privlib and $archlib directories, perhaps using
-$apiversion instead of $version (or even just /usr/lib/perl5 with no
-version stuff at all), and put modules into those directories (with perl
-Makefile.PL INSTALLDIRS=perl). This would be fine unless the vendor
-wanted to support different versions of perl installed at the same time.
-(How many vendors *really* want to do that?)
-
-=item Separate directories for Perl-supplied and add-on man pages
-
-Man pages supplied with the perl distribution proper ought to go in
-an appropriate man directory. Perhaps man pages supplied with add-on
-modules ought to (at least optionally) go into a $siteman[1-9] directory.
-For example, suppose that $privlib is /usr/lib/perl5 and $man1dir
-is /usr/man/man1. Also, suppose $sitelib is /usr/local/lib/perl5.
-In this situation, it might make sense for man pages to go into
-/usr/local/lib/man/man1.
-
=item Hint file fixes
Various hint files work around Configure problems. We ought to fix
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
=head1 LAST MODIFIED
-$Id: pumpkin.pod,v 1.22 1998/07/22 16:33:55 doughera Released $
+$Id: pumpkin.pod,v 1.23 2000/01/13 19:45:13 doughera Released $