=head1 NAME
-Pumpkin - Notes on handling the Perl Patch Pumpkin
+Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl
=head1 SYNOPSIS
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/README.html , which automatically points you to a
+http://www.cpan.org/README.html , which automatically points you to a
mirror site "close" to you.
=head2 Perl5-porters mailing list
=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/100000>. 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.
-
-=head2 Subversions
+ print "You've got a new perl\n" if $^V and $^V ge v5.6.0;
-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.)
+You can also require particular version (or later) with:
-These sub-versions can also be used as floating point numbers, so
-you can do things such as
+ use 5.006;
- print "You've got an unstable perl\n" if $] == 5.00303;
+or using the new syntax available only from v5.6 onward:
-You can also require particular version (or later) with
+ use v5.6.0;
- 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 are 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
+always match the regular expression:
- ^perl5\.\d{3}(_[0-4]\d)?\.tar\.gz$
+ ^perl\d+\.(\d+)\.\d+(-MAINT_TRIAL_\d+)\.tar\.gz$
-Developer releases always match
-
- ^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,
If feasible, try to keep filenames 8.3-compliant to humor those poor
souls that get joy from running Perl under such dire limitations.
+There's a script, check83.pl, for keeping your nose 8.3-clean.
=head2 Seek consensus on major changes
line options and possibly existing config.sh and Policy.sh files from
previous Configure runs.
-The extension hints are written Perl (by the time they are used
+The extension hints are written in Perl (by the time they are used
miniperl has been built) and control the building of their respective
extensions. They can be used to for example manipulate compilation
and linking flags.
File::Copy to become aware of your native filesystem syntax and
peculiarities.
+Remember to have a $VERSION in the modules. You can use the
+Porting/checkVERSION.pl script for checking this.
+
=item documentation
If your operating system comes from outside UNIX you almost certainly
A file called F<README.youros> at the top level that explains things
like how to install perl at this platform, where to get any possibly
required additional software, and for example what test suite errors
-to expect, is nice too.
+to expect, is nice too. Such files are in the process of being written
+in pod format and will eventually be renamed F<INSTALL.youros>.
You may also want to write a separate F<.pod> file for your operating
system to tell about existing mailing lists, os-specific modules,
incorporate that feedback quickly (e.g. within 1 week) and send out a
second patch.
+If you update the subversion number, you may need to change the version
+number near the top of the F<Changes> file.
+
=head2 run metaconfig
If you need to make changes to Configure or config_h.SH, it may be best to
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
+http://www.cpan.org/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
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.)
+config_h.SH.) Vms uses configure.com to generate its own config.sh
+and config.h. If you want to add a new variable to config.sh check
+with vms folk how to add it to configure.com too.
XXX]
The Porting/config.sh and Porting/config_H files are provided to
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
+It may also be necessary to update win32/config.?c, 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
started to fix F<perly.fixer> to detect this, but I never completed the
task.
-If C<perly.c> changes, make sure you run C<perl vms/vms_yfix.pl> to
-update the corresponding VMS files. See L<VMS-specific updates>.
+If C<perly.c> or C<perly.h> changes, make sure you run C<perl vms/vms_yfix.pl>
+to update the corresponding VMS files. This could be taken care of by
+the regen_all target in the Unix Makefile. See also
+L<VMS-specific updates>.
Some additional notes from Larry on this:
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
+ diff -c perly.c.orig perly.c >perly_c.diff
One chunk of lines that often fails begins with
Larry
+=head2 make regen_all
+
+This target takes care of the PERLYVMS, regen_headers, and regen_pods
+targets.
+
=head2 make regen_headers
The F<embed.h>, F<keywords.h>, and F<opcode.h> files are all automatically
than answering all the questions and complaints about the failing
command.
+=head2 make regen_pods
+
+Will run `make regen_pods` in the pod directory for indexing.
+
=head2 global.sym, interp.sym and perlio.sym
Make sure these files are up-to-date. Read the comments in these
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,
+source 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.
separately in the patch file (or both). There is no disagreement that
detailed descriptions ought to be easily available somewhere.
+If you update the subversion number in F<patchlevel.h>, you may need
+to change the version number near the top of the F<Changes> file.
+
=head2 Todo
The F<Todo> file contains a roughly-catgorized unordered list of
=head2 VMS-specific updates
If you have changed F<perly.y> or F<perly.c>, then you most probably want
-to update F<vms/perly_{h,c}.vms> by running C<perl vms/vms_yfix.pl>.
+to update F<vms/perly_{h,c}.vms> by running C<perl vms/vms_yfix.pl>, or
+by running `make regen_all` which will run that script for you.
-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".
+The Perl revision number appears as "perl5" in configure.com.
+It is courteous to update that if necessary.
=head2 Making the new distribution
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/ . There are a couple
+http://www.cpan.org/authors/Johan_Vromans/ . There are a couple
of differences between my version and the standard one. I have mine do
a
You can also hand-tweak your config.h to try out different #ifdef
branches.
+=head2 Other tests
+
+=over 4
+
+=item CHECK_FORMAT
+
+To test the correct use of printf-style arguments, C<Configure> with
+S<-Dccflags='-DCHECK_FORMAT -Wformat'> and run C<make>. The compiler
+will produce warning of incorrect use of format arguments. CHECK_FORMAT
+changes perl-defined formats to common formats, so DO NOT USE the executable
+produced by this process.
+
+A more accurate approach is the following commands:
+
+=over 4
+
+=item *
+
+build miniperl with -DCHECK_FORMAT
+
+ make clean
+ make miniperl OPTIMIZE=-DCHECK_FORMAT >& mini.log
+
+=item *
+
+build a clean miniperl,
+and build everything else from that with -DCHECK_FORMAT
+
+ make clean
+ make miniperl
+ make all OPTIMIZE='-DCHECK_FORMAT -Wformat' >& make.log
+
+=item *
+
+clean up, and print warnings from the log files
+
+ make clean
+ perl -nwe 'print if /^\S+:/ and not /^make\b/' \
+ mini.log make.log
+
+=back
+
+(-Wformat support by Robin Barker.)
+
+=back
+
+=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 2
+ ./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
=item Metaconfig worked for me
-My system at the time was Interactive 2.2, a SVR3.2/386 derivative that
+My system at the time was Interactive 2.2, an 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
casual users crazy. Even experienced users will get confused :-). Upon
reflection, I'd say leave libperl.so in $archlib.
+=item 4.
+
+Indentation style: over the years Perl has become a mishmash of
+various indentation styles, but the original "Larry style" can
+probably be restored with (GNU) indent somewhat like this:
+
+ indent -kr -nce -psl -sc
+
+A more ambitious solution would also specify a list of Perl specific
+types with -TSV -TAV -THV .. -TMAGIC -TPerlIO ... but that list would
+be quite ungainly. Also note that GNU indent also doesn't do aligning
+of consecutive assignments, which would truly wreck the layout in
+places like sv.c:Perl_sv_upgrade() or sv.c:Perl_clone_using().
+Similarly nicely aligned &&s, ||s and ==s would not be respected.
+
=back
=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
+http://www.cpan.org/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>
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 ).
+out http://www.cpan.org/CPAN.html ).
=head1 Help Save the World
items that merit consideration. This list isn't exhaustive, it's just
what I came up with off the top of my head.
+=head2 Adding missing library functions to Perl
+
+The perl Configure script automatically determines which headers and
+functions you have available on your system and arranges for them to be
+included in the compilation and linking process. Occasionally, when porting
+perl to an operating system for the first time, you may find that the
+operating system is missing a key function. While perl may still build
+without this function, no perl program will be able to reference the missing
+function. You may be able to write the missing function yourself, or you
+may be able to find the missing function in the distribution files for
+another software package. In this case, you need to instruct the perl
+configure-and-build process to use your function. Perform these steps.
+
+=over 3
+
+=item *
+
+Code and test the function you wish to add. Test it carefully; you will
+have a much easier time debugging your code independently than when it is a
+part of perl.
+
+=item *
+
+Here is an implementation of the POSIX truncate function for an operating
+system (VOS) that does not supply one, but which does supply the ftruncate()
+function.
+
+ /* Beginning of modification history */
+ /* Written 02-01-02 by Nick Ing-Simmons (nick@ing-simmons.net) */
+ /* End of modification history */
+
+ /* VOS doesn't supply a truncate function, so we build one up
+ from the available POSIX functions. */
+
+ #include <fcntl.h>
+ #include <sys/types.h>
+ #include <unistd.h>
+
+ int
+ truncate(const char *path, off_t len)
+ {
+ int fd = open(path,O_WRONLY);
+ int code = -1;
+ if (fd >= 0) {
+ code = ftruncate(fd,len);
+ close(fd);
+ }
+ return code;
+ }
+
+Place this file into a subdirectory that has the same name as the operating
+system. This file is named perl/vos/vos.c
+
+=item *
+
+If your operating system has a hints file (in perl/hints/XXX.sh for an
+operating system named XXX), then start with it. If your operating system
+has no hints file, then create one. You can use a hints file for a similar
+operating system, if one exists, as a template.
+
+=item *
+
+Add lines like the following to your hints file. The first line
+(d_truncate="define") instructs Configure that the truncate() function
+exists. The second line (archobjs="vos.o") instructs the makefiles that the
+perl executable depends on the existence of a file named "vos.o". (Make
+will automatically look for "vos.c" and compile it with the same options as
+the perl source code). The final line ("test -h...") adds a symbolic link
+to the top-level directory so that make can find vos.c. Of course, you
+should use your own operating system name for the source file of extensions,
+not "vos.c".
+
+ # VOS does not have truncate() but we supply one in vos.c
+ d_truncate="define"
+ archobjs="vos.o"
+
+ # Help gmake find vos.c
+ test -h vos.c || ln -s vos/vos.c vos.c
+
+The hints file is a series of shell commands that are run in the top-level
+directory (the "perl" directory). Thus, these commands are simply executed
+by Configure at an appropriate place during its execution.
+
+=item *
+
+At this point, you can run the Configure script and rebuild perl. Carefully
+test the newly-built perl to ensure that normal paths, and error paths,
+behave as you expect.
+
+=back
+
=head2 Good ideas waiting for round tuits
=over 4
=item File locking
Somehow, straighten out, document, and implement lockf(), flock(),
-and/or fcntl() file locking. It's a mess.
+and/or fcntl() file locking. It's a mess. See $d_fcntl_can_lock
+in recent config.sh files though.
=back
https://perl5.git.perl.org / perl5.git / blobdiff