X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=Porting%2Fpumpkin.pod;h=99776b50d2eeafd26eed2e255bd52bd16b1a1f42;hb=d4935d7f25ace6b599fe75f422b41624ca6bf4a6;hp=8736a70994924183984f93aec876823d10d6c777;hpb=67a4fa727c6f261b2e1417d3c6d0a2dfa11e3ebd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/Porting/pumpkin.pod b/Porting/pumpkin.pod index 8736a70..99776b5 100644 --- a/Porting/pumpkin.pod +++ b/Porting/pumpkin.pod @@ -47,63 +47,46 @@ Archives of the list are held at: =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 and F 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 @@ -113,17 +96,12 @@ string C to make clear that the file is not meant for 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 @@ -132,26 +110,6 @@ please inform the guys from the CPAN who are doing indexing and provide the trees of symlinks and the like. They will have to know I 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 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, @@ -236,7 +194,7 @@ emulations, function stubs, build utility wrappers) you may create a separate subdirectory (djgpp, win32) and put the files in there. Remember to update C 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 work for you, you must write a new one. Study the existing ones to see what kind of interface you must supply. @@ -743,6 +701,42 @@ supports dynamic loading, you can also test static loading with 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 @@ -1123,33 +1117,6 @@ 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 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 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 @@ -1273,18 +1240,6 @@ what I came up with off the top of my head. =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 trick -described in F. 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. Tom Tromey @@ -1293,34 +1248,6 @@ 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 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 @@ -1331,47 +1258,6 @@ 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 - /* 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 is essentially arbitrary. The GNU libc -macros are found in . You can include that file instead -of (which itself includes ) if you test for -its existence first. 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 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 @@ -1453,4 +1339,4 @@ All opinions expressed herein are those of the authorZ<>(s). =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 $