=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
Archives of the list are held at:
- http://www.rosat.mpe-garching.mpg.de/mailing-lists/perl-porters/
+ http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/
=head1 How are Perl Releases Numbered?
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
+In the past it has been observed that pumpkings tend to invent new
naming conventions on the fly. If you are a pumpking, before you
invent a new name for any of the three types of perl distributions,
please inform the guys from the CPAN who are doing indexing and
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.
+In a similar vein, do not create files or directories which differ only
+in case (upper versus lower).
=head2 Seek consensus on major changes
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
=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. The Porting/makerel
-(make release) perl script does now help automate some parts of it.
-
-=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
-the patch pumpkin to anyone unless we have some idea what he or she
-is going to do with it.
+This section has now been expanded and moved into its own file,
+F<Porting/release_managers_guide.pod>.
-=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 run installhtml to check the validity of the pod files
-
-=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.
+I've kept some of the subsections here for now, as they don't direclty
+eleate to building a release any more, but still contain what might be
+useful information - DAPM 7/2009.
=head2 run metaconfig
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
+that comes with Perl's metaconfig units.
+
+Since metaconfig is hard to change, running correction scripts after
+this generation is sometimes needed. Configure gained complexity over
+time, and the order in which config_h.SH is generated can cause havoc
+when compiling perl. Therefor, you need to run Porting/config_h.pl
+after that generation. All that and more is described in the README
+files that come with the metaunits.
+
+Perl's metaconfig units should be available on CPAN. A set of units
+that will work with perl5.9.x is in a file with a name similar to
+F<mc_units-20070423.tgz> under http://www.cpan.org/authors/id/H/HM/HMBRAND/ .
+The mc_units tar file should be unpacked in your main perl source directory.
+Note: those units were for use with 5.9.x. 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.
+Alternatively, do consider if the F<*ish.h> files or the hint 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 -w -MExtUtils::Manifest=fullcheck -e fullcheck
-
-Both commands will also list extra files in the directory that are not
-listed in MANIFEST.
-
-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
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. 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.gnu
- embed.pl
- installperl
- installman
- keywords.pl
- myconfig
- opcode.pl
- perly.fixer
- t/TEST
- t/*/*.t
- *.SH
- vms/ext/Stdio/test.pl
- vms/ext/filespec.t
- 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
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
+to config.sh and then propagate 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.) Vms uses configure.com to generate its own config.sh
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.
-
-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:
-
-Don't forget to regenerate perly_c.diff.
+=head2 make regen_perly
- byacc -d 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
+If perly.y has been edited, it is necessary to run this target to rebuild
+perly.h, perly.act and perly.tab. In fact this target just runs the Perl
+script regen_perly.pl. Note that perly.c is I<not> rebuilt; this is just a
+plain static file now.
-One chunk of lines that often fails begins with
+This target relies on you having Bison installed on your system. Running
+the target will tell you if you haven't got the right version, and if so,
+where to get the right one. Or if you prefer, you could hack
+regen_perly.pl to work with your version of Bison. The important things
+are that the regexes can still extract out the right chunks of the Bison
+output into perly.act and perly.tab, and that the contents of those two
+files, plus perly.h, are functionally equivalent to those produced by the
+supported version of Bison.
- #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
+Note that in the old days, you had to do C<make run_byacc> instead.
=head2 make regen_all
-This target takes care of the PERLYVMS, regen_headers, and regen_pods
-targets.
+This target takes care of the regen_headers target.
+(It used to also call the regen_pods target, but that has been eliminated.)
=head2 make regen_headers
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
backwards-compatibility stubs. There's a lot of XS code out there.
Let's not force people to keep changing it.
-=head2 Changes
+=head2 PPPort
-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 other 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".
+F<ext/Devel-PPPort/PPPort.pm> needs to be synchronized to include all
+new macros added to .h files (normally perl.h and XSUB.h, but others
+as well). Since chances are that when a new macro is added the
+committer will forget to update F<PPPort.pm>, it's the best to diff for
+changes in .h files when making a new release and making sure that
+F<PPPort.pm> contains them all.
+
+The pumpking can delegate the synchronization responsibility to anybody
+else, but the release process is the only place where we can make sure
+that no new macros fell through the cracks.
-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 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.
+The F<pod/perltodo.pod> file contains a roughly-categorized 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 to 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
+can find champions for particular 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
+There are also some more porting-specific L</Todo> items later in this
file.
=head2 OS/2-specific updates
=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>, or
-by running `make regen_all` which will run that script for you.
-
The Perl revision number appears as "perl5" in configure.com.
It is courteous to update that if necessary.
-=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
-
-These steps, with extra checks, are automated by the Porting/makerel
-script.
=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/ . 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
=over 4
-=item CHECK_FORMAT
+=item gcc -ansi -pedantic
+
+Configure -Dgccansipedantic [ -Dcc=gcc ] will enable (via the cflags script,
+not $Config{ccflags}) the gcc strict ANSI C flags -ansi and -pedantic for
+the compilation of the core files on platforms where it knows it can
+do so (like Linux, see cflags.SH for the full list), and on some
+platforms only one (Solaris can do only -pedantic, not -ansi).
+The flag -DPERL_GCC_PEDANTIC also gets added, since gcc does not add
+any internal cpp flag to signify that -pedantic is being used, as it
+does for -ansi (__STRICT_ANSI__).
-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.
+Note that the -ansi and -pedantic are enabled only for version 3 (and
+later) of gcc, since even gcc version 2.95.4 finds lots of seemingly
+false "value computed not used" errors from Perl.
-A more accurate approach is the following commands:
+The -ansi and -pedantic are useful in catching at least the following
+nonportable practices:
=over 4
=item *
-build miniperl with -DCHECK_FORMAT
-
- make clean
- make miniperl OPTIMIZE=-DCHECK_FORMAT >& mini.log
+gcc-specific extensions
=item *
-build a clean miniperl,
-and build everything else from that with -DCHECK_FORMAT
+lvalue casts
- make clean
- make miniperl
- make all OPTIMIZE=-DCHECK_FORMAT >& make.log
-
=item *
-clean up, and print warnings from the log files
+// C++ comments
+
+=item *
- make clean
- perl -nwe 'print if /^\S+:/ and not /^make\b/' \
- mini.log make.log
+enum trailing commas
=back
-(-Wformat support by Robin Barker.)
+The -Dgccansipedantic should be used only when cleaning up the code,
+not for production builds, since otherwise gcc cannot inline certain
+things.
=back
within eval or require. (Fixing these is non-trivial, unfortunately, but
they must be fixed eventually.)
-=head1 Common Gotcha's
+=head1 Common Gotchas
=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
=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
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
+Given that it's already there, you can use it to override distribution modules.
+One way to do that is to add
- sh Configure -Dccflags='-DAPPLLIB_EXP=/my/override'
+ ccflags="$ccflags -DAPPLLIB_EXP=\"/my/override\""
+
+to your config.over file. (You have to be particularly careful to get the
+double quotes in. APPLLIB_EXP must be a valid C string. It might
+actually be easier to just #define it yourself in perl.c.)
-then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB.
+Then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. Perl will
+also search architecture-specific and version-specific subdirectories of
+APPLLIB_EXP.
=head2 Shared libperl.so location
=back
+=head2 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.
+
=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
=back
+=head2 Copyright Issues
+
+The following is based on the consensus of a couple of IPR lawyers,
+but it is of course not a legally binding statement, just a common
+sense summary.
+
+=over 4
+
+=item *
+
+Tacking on copyright statements is unnecessary to begin with because
+of the Berne convention. But assuming you want to go ahead...
+
+=item *
+
+The right form of a copyright statement is
+
+ Copyright (C) Year, Year, ... by Someone
+
+The (C) is not required everywhere but it doesn't hurt and in certain
+jurisdictions it is required, so let's leave it in. (Yes, it's true
+that in some jurisdictions the "(C)" is not legally binding, one should
+use the true ringed-C. But we don't have that character available for
+Perl's source code.)
+
+The years must be listed out separately. Year-Year is not correct.
+Only the years when the piece has changed 'significantly' may be added.
+
+=item *
+
+One cannot give away one's copyright trivially. One can give one's
+copyright away by using public domain, but even that requires a little
+bit more than just saying 'this is in public domain'. (What it
+exactly requires depends on your jurisdiction.) But barring public
+domain, one cannot "transfer" one's copyright to another person or
+entity. In the context of software, it means that contributors cannot
+give away their copyright or "transfer" it to the "owner" of the software.
+
+Also remember that in many cases if you are employed by someone,
+your work may be copyrighted to your employer, even when you are
+contributing on your own time (this all depends on too many things
+to list here). But the bottom line is that you definitely can't give
+away a copyright you may not even have.
+
+What is possible, however, is that the software can simply state
+
+ Copyright (C) Year, Year, ... by Someone and others
+
+and then list the "others" somewhere in the distribution.
+And this is exactly what Perl does. (The "somewhere" is
+AUTHORS and the Changes* files.)
+
+=item *
+
+Split files, merged files, and generated files are problematic.
+The rule of thumb: in split files, copy the copyright years of
+the original file to all the new files; in merged files make
+an union of the copyright years of all the old files; in generated
+files propagate the copyright years of the generating file(s).
+
+=item *
+
+The files of Perl source code distribution do carry a lot of
+copyrights, by various people. (There are many copyrights embedded in
+perl.c, for example.) The most straightforward thing for pumpkings to
+do is to simply update Larry's copyrights at the beginning of the
+*.[hcy], x2p/*.[hcy], *.pl, and README files, and leave all other
+copyrights alone. Doing more than that requires quite a bit of tracking.
+
+=back
+
=head1 AUTHORS
-Original author: Andy Dougherty doughera@lafcol.lafayette.edu .
+Original author: Andy Dougherty doughera@lafayette.edu .
Additions by Chip Salzenberg chip@perl.com and
Tim Bunce Tim.Bunce@ig.co.uk .
=head1 LAST MODIFIED
+27-04-2007 H.Merijn Brand
$Id: pumpkin.pod,v 1.23 2000/01/13 19:45:13 doughera Released $
https://perl5.git.perl.org / perl5.git / blobdiff