=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
- 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
+=head2 make regen_perly
-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 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.
-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>.
+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.
-Some additional notes from Larry on this:
-
-Don't forget to regenerate perly_c.diff.
-
- byacc -d perly.y
- mv y.tab.c perly.c
- patch perly.c <perly_c.diff
- # manually apply any failed hunks
- diff -c perly.c.orig perly.c >perly_c.diff
-
-One chunk of lines that often fails begins with
-
- #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.
-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.
+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.
-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
=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
=over 4
-=item CHECK_FORMAT
-
-If you have gcc, you can test the correct use of printf-style
-arguments. Run C<Configure> with S<-Dccflags='-DCHECK_FORMAT
--Wformat'> (and S<-Dcc=gcc>, if you are not on a system where C<cc>
-is C<gcc>) and run C<make>. The compiler will produce warnings 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.)
-
=item gcc -ansi -pedantic
Configure -Dgccansipedantic [ -Dcc=gcc ] will enable (via the cflags script,
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
=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