=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.
+This section has now been expanded and moved into its own file,
+F<Porting/release_managers_guide.pod>.
-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.
-
-=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.
-
-If you update the subversion number, you may need to change the version
-number near the top of the F<Changes> file.
+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.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
+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
- 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
=head2 make regen_perly
-If perly.y has been edited, it is nessary to run this target to rebuild
+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.
=head2 make regen_all
-This target takes care of the 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
=head2 PPPort
-F<ext/Devel/PPPort/PPPort.pm> needs to be synchronized to include all
+F<cpan/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
else, but the release process is the only place where we can make sure
that no new macros fell through the cracks.
-=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 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".
-
-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.
-
-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 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
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
=head2 Other tests
+=over 4
+
=item gcc -ansi -pedantic
Configure -Dgccansipedantic [ -Dcc=gcc ] will enable (via the cflags script,
=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
=over 4
-=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
=head1 LAST MODIFIED
-$Id: pumpkin.pod,v 1.23 2000/01/13 19:45:13 doughera Released $
+2009-07-08-01 Jesse Vincent